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 clienteVer no app modelo: Conectar corretora ↗

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.

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": "TENANT_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": 10,
        "approvalRequiredFromWallet": true
      }
    }
  ]
}

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

Criar sessão de conexão

Tela do clienteVer no app modelo: Conectar corretora ↗

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.

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 tenant
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 clienteVer no app modelo: Conectar corretora ↗

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".

Parâmetros de caminho

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

Erros comuns

422API_NOT_CONFIGUREDcorretora não conectada

Requisição

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

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"

GET/v1/users/:externalUserId/account

Saldo na corretora

Tela do clienteVer no app modelo: Conectar corretora ↗

Saldo/conta lidos na corretora (somente leitura).

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/account?providerId=BINANCE" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"