Referência da API

Posições e ordens

Acompanhamento do que a automação fez: posições abertas, proteção (stop/alvo) e ordens.

GET/v1/users/:externalUserId/execution-statusPosições e proteção GET/v1/users/:externalUserId/positionsPosições na corretora GET/v1/users/:externalUserId/intentsOrdens do cliente POST/v1/orders/prepareOrdem manual: preparar (opcional)POST/v1/orders/executeOrdem manual: executar (opcional)GET/v1/orders/:intentIdOrdem manual: consultar POST/v1/orders/:intentId/reconcileOrdem manual: reconciliar

GET/v1/users/:externalUserId/execution-status

Posições e proteção

Tela do cliente

Posições abertas com o estado da proteção (PROTECTED, PROTECTION_DEGRADED, PROVIDER_ACCESS_LOST, UNKNOWN) e o acesso à corretora. Por posição: positionId, providerId, symbol, side, quantity, entryPrice, leverage, protection { status, stopLossPrice, takeProfitPrice, reason }, openedAt.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/execution-status" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "PARCEIRO_A",
  "requestId": "req_muyn0wfr_nfy59n5p",
  "providers": [],
  "positions": []
}

GET/v1/users/:externalUserId/positions

Posições na corretora

Tela do cliente

Posições lidas direto na corretora.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema

Query string

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora

Erros comuns

422CREDENTIALS_MISSINGcorretora não conectada

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/positions?providerId=BINANCE" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "providerId": "BINANCE",
  "positions": [],
  "requestId": "req_example"
}

GET/v1/users/:externalUserId/intents

Ordens do cliente

Tela do cliente

Ordens/intenções: intentId, type, providerId, symbol, side, quantity, status, executedQuantity, executedPrice, errorCode, createdAt, finalizedAt.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema

Query string

statusOPEN | ALLopcional
padrão OPEN
limit1–200opcional
padrão 50

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/intents?status=ALL" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "PARCEIRO_A",
  "requestId": "req_muyn0weo_ujzpc78n",
  "intents": []
}

POST/v1/orders/prepare

Ordem manual: preparar (opcional)

Rotina do servidorIdempotency-Key obrigatório

NÃO é necessária para a automação: as entradas vêm da estratégia FINAUTON. Use só se o seu produto tiver ordem manual, combinado com o FINAUTON. Preparar valida a ordem (contrato, risco, cobrança, prontidão) e devolve a intenção SEM enviar nada à corretora.

Fluxo: preparar → executar (mesmo corpo e mesmo intentId) → consultar → reconciliar se o status vier UNCERTAIN.

Abertura REAL só com orderType LIMIT e price (ordem a mercado para abrir é recusada). Fechar/reduzir: reduceOnly true ou type CLOSE_POSITION.

Envie intentId (8–64 caracteres) gerado por você: ele torna a ordem idempotente na corretora. Repetir a mesma ação = mesmo intentId e mesma Idempotency-Key.

Conta no limite de ordens do parceiro (ordersPerMinute) → 429 RATE_LIMITED.

Corpo (JSON)

externalUserIdstring (1–120)obrigatório
cliente dono da conta na corretora
typeOPEN_POSITION | PLACE_ORDER | CLOSE_POSITION | CANCEL_ORDER | CANCEL_ALL_ORDERS | UPDATE_ORDER | SET_LEVERAGE | SET_MARGIN_MODE | SET_STOP_LOSS | SET_TAKE_PROFITobrigatório
o que fazer
providerIdBINANCE | HYPERLIQUIDobrigatório
corretora (do seu contrato)
intentIdstring (8–64)condicional
recomendado — id seu e único por ação; torna a ordem idempotente na corretora
symbolstringcondicional
obrigatório em ordens — ex.: BTCUSDT
sideBUY | SELLcondicional
obrigatório em ordens — BUY = comprar/long; SELL = vender/short
orderTypeLIMIT | MARKET | STOP_MARKET | TAKE_PROFIT_MARKETcondicional
obrigatório em ordens — abertura REAL: só LIMIT
quantitynúmero > 0condicional
envie quantity OU notionalUsd — quantidade no ativo
notionalUsdnúmero > 0condicional
envie quantity OU notionalUsd — tamanho em USD (alternativa a quantity)
pricenúmero > 0condicional
obrigatório em LIMIT — preço limite
triggerPricenúmero > 0condicional
obrigatório em STOP_MARKET/TAKE_PROFIT_MARKET — preço de disparo
timeInForceGTC | IOC | FOK | POST_ONLYopcional
validade da ordem
leverageinteiro 1–125opcional
limitada pelo contrato
marginModeISOLATED | CROSSopcional
tipo de margem
reduceOnlybooleanopcional
true = só reduz/fecha posição
stopLossPricenúmero > 0 | nullopcional
stop desta ordem
takeProfits[{ price, share }]opcional
alvos; share = fração da posição (0–1)
portionnúmero 0–1opcional
fração a fechar (CLOSE_POSITION)
orderIdstringcondicional
obrigatório em CANCEL_ORDER/UPDATE_ORDER — ordem na corretora
positionSideBUY | SELLopcional
lado da posição (SET_STOP_LOSS / SET_TAKE_PROFIT)

Erros comuns

400VALIDATION_ERRORcampo ausente ou inválido
403PROVIDER_NOT_ALLOWEDcorretora fora do contrato
422RISK_ENVELOPE_EXCEEDEDacima do limite do contrato
422CREDENTIALS_MISSINGcorretora não conectada
403B2B_ACCESS_SUSPENDEDcliente/contrato suspenso (abertura negada; fechar continua possível)
429RATE_LIMITEDlimite de ordens por minuto do parceiro

Requisição

curl -X POST "$FIN_API/v1/orders/prepare" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: orders-prepare-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalUserId": "cli-1001",
    "type": "OPEN_POSITION",
    "providerId": "BINANCE",
    "intentId": "ord-cli-1001-0001",
    "symbol": "BTCUSDT",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": 0.001,
    "price": 62000,
    "timeInForce": "GTC",
    "leverage": 3,
    "marginMode": "ISOLATED",
    "stopLossPrice": 60800,
    "takeProfits": [
      {
        "price": 63500,
        "share": 0.5
      },
      {
        "price": 64500,
        "share": 0.5
      }
    ]
  }'

Resposta200

{
  "intent": {
    "intentId": "ord-cli-1001-0001",
    "providerId": "BINANCE",
    "type": "OPEN_POSITION",
    "symbol": "BTCUSDT",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": 0.001,
    "price": 62000,
    "leverage": 3,
    "reduceOnly": false,
    "status": "PREPARED"
  },
  "requestId": "req_mv0a1b2c_ord0001"
}

POST/v1/orders/execute

Ordem manual: executar (opcional)

Rotina do servidorIdempotency-Key obrigatório

ENVIA a ordem REAL à corretora do cliente, com as mesmas checagens do preparar. Mesmo corpo do preparar. A resposta traz o resultado da corretora; se status vier UNCERTAIN, não reenvie: consulte e reconcilie.

Movimenta dinheiro real: use só com autorização do cliente e do FINAUTON.

status: FILLED · PARTIALLY_FILLED · ACCEPTED (na corretora, aguardando) · NOT_FILLED · REJECTED · FAILED · UNCERTAIN (enviada sem confirmação) · DUPLICATE (mesmo intentId já executado).

A proteção (stop e alvos) segue o setup do cliente; stopLossPrice e takeProfits no corpo definem a proteção desta ordem quando permitido pelo setup.

Corpo (JSON)

externalUserIdstring (1–120)obrigatório
cliente dono da conta na corretora
typeOPEN_POSITION | PLACE_ORDER | CLOSE_POSITION | CANCEL_ORDER | CANCEL_ALL_ORDERS | UPDATE_ORDER | SET_LEVERAGE | SET_MARGIN_MODE | SET_STOP_LOSS | SET_TAKE_PROFITobrigatório
o que fazer
providerIdBINANCE | HYPERLIQUIDobrigatório
corretora (do seu contrato)
intentIdstring (8–64)condicional
recomendado — id seu e único por ação; torna a ordem idempotente na corretora
symbolstringcondicional
obrigatório em ordens — ex.: BTCUSDT
sideBUY | SELLcondicional
obrigatório em ordens — BUY = comprar/long; SELL = vender/short
orderTypeLIMIT | MARKET | STOP_MARKET | TAKE_PROFIT_MARKETcondicional
obrigatório em ordens — abertura REAL: só LIMIT
quantitynúmero > 0condicional
envie quantity OU notionalUsd — quantidade no ativo
notionalUsdnúmero > 0condicional
envie quantity OU notionalUsd — tamanho em USD (alternativa a quantity)
pricenúmero > 0condicional
obrigatório em LIMIT — preço limite
triggerPricenúmero > 0condicional
obrigatório em STOP_MARKET/TAKE_PROFIT_MARKET — preço de disparo
timeInForceGTC | IOC | FOK | POST_ONLYopcional
validade da ordem
leverageinteiro 1–125opcional
limitada pelo contrato
marginModeISOLATED | CROSSopcional
tipo de margem
reduceOnlybooleanopcional
true = só reduz/fecha posição
stopLossPricenúmero > 0 | nullopcional
stop desta ordem
takeProfits[{ price, share }]opcional
alvos; share = fração da posição (0–1)
portionnúmero 0–1opcional
fração a fechar (CLOSE_POSITION)
orderIdstringcondicional
obrigatório em CANCEL_ORDER/UPDATE_ORDER — ordem na corretora
positionSideBUY | SELLopcional
lado da posição (SET_STOP_LOSS / SET_TAKE_PROFIT)

Erros comuns

400VALIDATION_ERRORcampo ausente ou inválido
403PROVIDER_NOT_ALLOWEDcorretora fora do contrato
422RISK_ENVELOPE_EXCEEDEDacima do limite do contrato
422CREDENTIALS_MISSINGcorretora não conectada
403B2B_ACCESS_SUSPENDEDcliente/contrato suspenso (abertura negada; fechar continua possível)
429RATE_LIMITEDlimite de ordens por minuto do parceiro
409ACCOUNT_BUSYoutra entrada da mesma conta em andamento; tente de novo em instantes
503PROVIDER_DOWNcorretora indisponível; consulte a intenção antes de repetir

Requisição

curl -X POST "$FIN_API/v1/orders/execute" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: orders-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalUserId": "cli-1001",
    "type": "OPEN_POSITION",
    "providerId": "BINANCE",
    "intentId": "ord-cli-1001-0001",
    "symbol": "BTCUSDT",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": 0.001,
    "price": 62000,
    "timeInForce": "GTC",
    "leverage": 3,
    "marginMode": "ISOLATED",
    "stopLossPrice": 60800,
    "takeProfits": [
      {
        "price": 63500,
        "share": 0.5
      },
      {
        "price": 64500,
        "share": 0.5
      }
    ]
  }'

Resposta200

{
  "execution": {
    "status": "ACCEPTED",
    "intentId": "ord-cli-1001-0001",
    "providerId": "BINANCE",
    "orderId": "8389765590",
    "clientOrderId": "ord-cli-1001-0001",
    "filledQuantity": 0,
    "averagePrice": null,
    "requestedPrice": 62000,
    "feeUsd": null,
    "builderFeeUsd": null,
    "latencyMs": 212
  },
  "requestId": "req_mv0a1b2c_ord0002"
}

GET/v1/orders/:intentId

Ordem manual: consultar

Rotina do servidor

Estado da intenção no FINAUTON (sem chamar a corretora): status, ordem na corretora, quantidade e preço executados, erro.

Parâmetros de caminho

intentIdstring (8–64)obrigatório
o intentId enviado no preparar/executar

Query string

externalUserIdstring (1–120)obrigatório
cliente dono da ordem
providerIdBINANCE | HYPERLIQUIDobrigatório
corretora

Erros comuns

404NOT_FOUNDintenção inexistente ou de outro cliente/parceiro

Requisição

curl -X GET "$FIN_API/v1/orders/INTENT_ID?externalUserId=cli-1001&providerId=BINANCE" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "intentId": "ord-cli-1001-0001",
  "providerId": "BINANCE",
  "status": "FILLED",
  "orderId": "8389765590",
  "clientOrderId": "ord-cli-1001-0001",
  "executedQuantity": 0.001,
  "executedPrice": 61994.5,
  "errorCode": null,
  "errorMessage": null,
  "reconciledAt": null,
  "requestId": "req_mv0a1b2c_ord0003"
}

POST/v1/orders/:intentId/reconcile

Ordem manual: reconciliar

Rotina do servidorIdempotency-Key obrigatório

Confere com a corretora as intenções incertas da conta (UNCERTAIN) e posições/ordens sem registro, e devolve o estado final da intenção pedida. Não reenvia ordem.

Parâmetros de caminho

intentIdstring (8–64)obrigatório
intenção a acompanhar

Corpo (JSON)

externalUserIdstring (1–120)obrigatório
cliente dono da ordem
providerIdBINANCE | HYPERLIQUIDobrigatório
corretora

Erros comuns

404NOT_FOUNDintenção inexistente ou de outro cliente/parceiro
503PROVIDER_DOWNcorretora indisponível; tente mais tarde

Requisição

curl -X POST "$FIN_API/v1/orders/INTENT_ID/reconcile" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: orders-reconcile-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalUserId": "cli-1001",
    "providerId": "BINANCE"
  }'

Resposta200

{
  "reconciliation": {
    "scanned": 1,
    "resolved": 1,
    "stillUncertain": 0,
    "orphanPositions": 0,
    "orphanOrders": 0,
    "details": []
  },
  "intent": {
    "intentId": "ord-cli-1001-0001",
    "providerId": "BINANCE",
    "status": "FILLED",
    "orderId": "8389765590",
    "clientOrderId": "ord-cli-1001-0001",
    "executedQuantity": 0.001,
    "executedPrice": 61994.5,
    "errorCode": null,
    "errorMessage": null,
    "reconciledAt": "2026-10-10T20:31:07.000Z"
  },
  "requestId": "req_mv0a1b2c_ord0004"
}