Referência da API

Conexão da corretora

O cliente conecta a corretora na página HOSPEDADA da FINAUTON. Seu app só cria a sessão, abre o link e acompanha o resultado — nunca vê chave de API, seed ou assinatura.

GET/v1/users/:externalUserId/providersCorretoras do cliente POST/v1/users/:externalUserId/connect-sessionsCriar sessão de conexão GET/v1/users/:externalUserId/connect-sessions/:sessionIdAcompanhar a conexão GET/v1/users/:externalUserId/accountsContas conectadas POST/v1/users/:externalUserId/accounts/:provider/testTestar conexão DELETE/v1/users/:externalUserId/accounts/:providerDesconectar corretora GET/v1/users/:externalUserId/accountSaldo na corretora

GET/v1/users/:externalUserId/providers

Corretoras do cliente

Tela do cliente

Por corretora: tipo de conexão (API_KEY na Binance, AGENT_WALLET na Hyperliquid), estado (NOT_CONNECTED, CONNECT_PENDING, CONNECTED, ACCESS_LOST, RECOVERING, REVOKED), permissões, se pode abrir novas entradas, situação comercial e, na Hyperliquid, a taxa de builder do contrato. approvedByUser é true/false/null; null significa consulta inconclusiva. approvalStatus distingue APPROVED, REQUIRED, UNKNOWN e NOT_CONNECTED. Conexão do Agent não prova aprovação Builder nem cobrança em fill.

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/providers" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "PARCEIRO_A",
  "requestId": "req_muyn0w6o_ii9qbt4s",
  "providers": [
    {
      "providerId": "BINANCE",
      "name": "Binance",
      "rollout": "PILOT",
      "connectionScheme": "API_KEY",
      "connectionFlow": "HOSTED",
      "connection": "NOT_CONNECTED",
      "permissions": null,
      "eligibleForNewEntries": true,
      "commercial": {
        "allowed": true,
        "state": "ACTIVE",
        "reasonCode": "B2B_CONTRACT_ACTIVE",
        "graceUntil": null,
        "source": "B2B_CONTRACT"
      },
      "builder": null
    },
    {
      "providerId": "HYPERLIQUID",
      "name": "Hyperliquid",
      "rollout": "PILOT",
      "connectionScheme": "AGENT_WALLET",
      "connectionFlow": "HOSTED",
      "connection": "NOT_CONNECTED",
      "permissions": null,
      "eligibleForNewEntries": true,
      "commercial": {
        "allowed": true,
        "state": "ACTIVE",
        "reasonCode": "B2B_CONTRACT_ACTIVE",
        "graceUntil": null,
        "source": "B2B_CONTRACT"
      },
      "builder": {
        "required": true,
        "feeTenthsBps": 20,
        "approvalRequiredFromWallet": true,
        "approvedByUser": null,
        "approvalStatus": "NOT_CONNECTED",
        "approvedMaxFeeTenthsBps": null
      }
    }
  ]
}

POST/v1/users/:externalUserId/connect-sessions

Criar sessão de conexão

Tela do cliente

Cria um link de uso único (15 minutos) para a página FINAUTON. Abra o connectUrl para o cliente (redirect, nova aba ou webview).

Não grave nem registre o connectUrl em log: o token vai no fragmento #t=.

Uma nova sessão cancela a pendente do mesmo cliente + corretora.

Binance: o cliente cola a chave de API (Futures ligado, saque DESLIGADO, IP liberado conforme a página). Hyperliquid: conecta a carteira, autoriza a carteira-agente (opera, não saca) e aprova a taxa de builder do contrato. approvedByUser é true/false/null; null significa consulta inconclusiva. approvalStatus distingue APPROVED, REQUIRED, UNKNOWN e NOT_CONNECTED. Conexão do Agent não prova aprovação Builder nem cobrança em fill.

Parâmetros de caminho

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

Corpo (JSON)

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora
returnUrlstring httpsopcional
botão "Voltar ao app"; precisa ser de uma origem registrada no seu contrato
purposeCONNECT | BUILDER_APPROVALopcional
BUILDER_APPROVAL = pedir nova aprovação da taxa de builder (Hyperliquid já conectada)

Erros comuns

403RETURN_URL_NOT_ALLOWEDorigem do returnUrl não registrada
403PROVIDER_NOT_GRANTEDcorretora fora do contrato
403CLIENT_SUSPENDEDcliente suspenso

Requisição

curl -X POST "$FIN_API/v1/users/cli-1001/connect-sessions" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "providerId": "BINANCE",
    "returnUrl": "https://app.parceiro.example/conta"
  }'

Resposta201

{
  "sessionId": "6ac6be4f91c7c1927cc1ba87",
  "externalUserId": "cli-1001",
  "providerId": "BINANCE",
  "scheme": "API_KEY",
  "purpose": "CONNECT",
  "status": "PENDING",
  "failureCode": null,
  "opened": false,
  "expiresAt": "2026-10-07T22:04:03.862Z",
  "completedAt": null,
  "connectUrl": "https://app.finauton.com/connect#t=<token-uso-unico>",
  "requestId": "req_muyn3wt6_tp05bazo"
}

GET/v1/users/:externalUserId/connect-sessions/:sessionId

Acompanhar a conexão

Tela do cliente

status: PENDING, CONNECTED, FAILED, EXPIRED, CANCELLED; opened diz se o cliente abriu o link; failureCode explica a falha. Consulte a cada 3–5 s enquanto PENDING, ou use os eventos provider.connected / provider.connect_failed.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
sessionIdstringobrigatório
da criação da sessão

Requisição

curl -X GET "$FIN_API/v1/users/cli-1001/connect-sessions/6ac6be4f91c7c1927cc1ba87" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "sessionId": "6ac6be4f91c7c1927cc1ba87",
  "externalUserId": "cli-1001",
  "providerId": "BINANCE",
  "scheme": "API_KEY",
  "purpose": "CONNECT",
  "status": "PENDING",
  "failureCode": null,
  "opened": false,
  "expiresAt": "2026-10-07T22:04:03.862Z",
  "completedAt": null,
  "requestId": "req_muyn3wuu_sxnq857h"
}

GET/v1/users/:externalUserId/accounts

Contas conectadas

Rotina do servidor

Contas por corretora, sem segredo: configured, status, permissões (canRead, canFutures, canWithdraw) e dica da conta.

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/accounts" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "accounts": [
    {
      "providerId": "BINANCE",
      "scheme": "API_KEY",
      "configured": false,
      "status": "NOT_CONNECTED",
      "permissions": {
        "canRead": false,
        "canFutures": false,
        "canWithdraw": false
      },
      "accountHint": null,
      "updatedAt": null,
      "revokedAt": null
    }
  ],
  "requestId": "req_muyn0w8y_2m1jc66q"
}

POST/v1/users/:externalUserId/accounts/:provider/test

Testar conexão

Tela do cliente

Testa a conexão já guardada (somente leitura). Devolve success, latencyMs e permissions. Bom para um botão "Testar conexão".

Teste bem-sucedido também atualiza as permissões mostradas em /providers e /accounts (as permissões reais da chave). Falha responde 400 com success:false e error, sem mudar nada.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
providerBINANCE | HYPERLIQUIDobrigatório
corretora

Erros comuns

400API_NOT_CONFIGUREDcorretora não conectada
403PROVIDER_NOT_GRANTEDcorretora fora do contrato

Requisição

curl -X POST "$FIN_API/v1/users/cli-1001/accounts/BINANCE/test" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "tenantId": "PARCEIRO_A",
  "requestId": "req_mv0a1b2c_tst0001",
  "providerId": "BINANCE",
  "success": true,
  "error": null,
  "latencyMs": 184,
  "permissions": {
    "canRead": true,
    "canFutures": true,
    "canWithdraw": false
  }
}

DELETE/v1/users/:externalUserId/accounts/:provider

Desconectar corretora

Tela do cliente

Revoga a conexão no FINAUTON: bloqueia novas entradas nessa corretora; histórico preservado. Gera o evento provider.disconnected.

Parâmetros de caminho

externalUserIdstring (1–120)obrigatório
id do cliente no SEU sistema
providerBINANCE | HYPERLIQUIDobrigatório
corretora

Requisição

curl -X DELETE "$FIN_API/v1/users/cli-1001/accounts/BINANCE" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "externalUserId": "cli-1001",
  "account": {
    "providerId": "BINANCE",
    "scheme": "API_KEY",
    "configured": false,
    "status": "REVOKED",
    "capabilities": [
      "PERP_TRADING",
      "LEVERAGE",
      "STOP_LOSS",
      "TAKE_PROFIT"
    ],
    "permissions": {
      "canRead": true,
      "canFutures": true,
      "canWithdraw": false
    },
    "accountHint": "ab12…9f",
    "updatedAt": "2026-10-10T20:15:02.000Z",
    "revokedAt": "2026-10-10T20:15:02.000Z",
    "secretRetainedForReconciliation": false
  },
  "requestId": "req_mv0a1b2c_del0001"
}

Com posição aberta nessa corretora, secretRetainedForReconciliation vem true: o FINAUTON mantém o acesso só para proteger e encerrar o que está aberto.

GET/v1/users/:externalUserId/account

Saldo na corretora

Tela do cliente

Saldo/conta lidos na corretora (somente leitura).

Lê a corretora na hora (não é cache). Mostre balances[].free como disponível e total como saldo com margem; usdValue pode vir null quando o ativo não tem cotação em USD.

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
403PROVIDER_NOT_ALLOWEDcorretora fora do contrato
503PROVIDER_DOWNcorretora indisponível; tente de novo

Requisição

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

Resposta200

{
  "providerId": "BINANCE",
  "balances": [
    {
      "asset": "USDT",
      "free": 182.4,
      "total": 230.15,
      "usdValue": 230.15
    }
  ],
  "positions": [
    {
      "symbol": "SOLUSDT",
      "side": "SHORT",
      "quantity": 0.34,
      "entryPrice": 109.67,
      "markPrice": 108.9,
      "unrealizedPnlUsd": 0.26,
      "unrealizedPnlPercent": 0.7,
      "leverage": 3,
      "marginMode": "ISOLATED",
      "liquidationPrice": 141.2,
      "providerId": "BINANCE"
    }
  ],
  "orders": [
    {
      "orderId": "8389765512",
      "clientOrderId": "fin-stop-1001",
      "symbol": "SOLUSDT",
      "side": "BUY",
      "type": "STOP_MARKET",
      "status": "NEW",
      "quantity": 0.34,
      "filledQuantity": 0,
      "price": null,
      "averagePrice": null,
      "triggerPrice": 111.44,
      "reduceOnly": true,
      "timeInForce": "GTC",
      "createdAt": "2026-10-09T14:05:14.000Z",
      "providerId": "BINANCE"
    }
  ],
  "requestId": "req_mv0a1b2c_acc0001"
}