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/executeOrdem manual (opcional)

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

Posições e proteção

Tela do clienteVer no app modelo: Operação ↗

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": "TENANT_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"

GET/v1/users/:externalUserId/intents

Ordens do cliente

Tela do clienteVer no app modelo: Operação ↗

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": "TENANT_A",
  "requestId": "req_muyn0weo_ujzpc78n",
  "intents": []
}

POST/v1/orders/execute

Ordem manual (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. Família: POST /v1/orders/prepare, POST /v1/orders/execute, GET /v1/orders/:intentId?externalUserId=&providerId=, POST /v1/orders/:intentId/reconcile. Desligada no app modelo.

Requisição

curl -X POST "$FIN_API/v1/orders/execute" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: orders-cli-1001-$(uuidgen)"