Referência da API

Risco

O cliente define os limites de risco por corretora. Fluxo: prévia (não grava) → mostrar alertas → cliente confirma → gravar com o aceite. Gravar setup REAL exige a corretora já conectada.

GET/v1/users/:externalUserId/setupSetup atual POST/v1/users/:externalUserId/setup/previewPrévia do setup PUT/v1/users/:externalUserId/setupGravar setup PUT/v1/users/:externalUserId/riskAtualizar só os limites

GET/v1/users/:externalUserId/setup

Setup atual

Tela do clienteVer no app modelo: Risco e estratégia ↗

Setup da corretora. setupStatus.issues lista o que falta para ligar, campo a campo, com mensagem pronta para a tela.

Cliente novo: mode "PAPER", enabled false (padrão interno) até gravar o setup REAL.

Parâmetros de caminho

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

Query string

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora

Requisição

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

Resposta200

{
  "externalUserId": "cli-1001",
  "providerId": "BINANCE",
  "mode": "PAPER",
  "enabled": false,
  "market": "FUTURES",
  "leverage": 2,
  "marginType": "ISOLATED",
  "orderSizeUsd": 5,
  "sizingStatus": "AVAILABLE",
  "maxConcurrentTrades": 3,
  "maxMarginPerTradeUsd": 5,
  "allowedSymbols": [],
  "allowMemecoins": false,
  "autoStopLoss": true,
  "autoTakeProfit": true,
  "autoBreakEven": true,
  "maxAdverseEntryPercent": 0.15,
  "quoteCurrency": null,
  "capitalBase": null,
  "maxLossPerTrade": null,
  "entryTimeoutMinutes": null,
  "allowedStrategies": [
    "FUTURES_MAIN_V1"
  ],
  "setupStatus": {
    "status": "SETUP_INCOMPLETE",
    "issues": [
      {
        "code": "CAPITAL_BASE_REQUIRED",
        "field": "capitalBase",
        "message": "Defina o capital base (valor maior que zero)."
      },
      {
        "code": "MAX_LOSS_REQUIRED",
        "field": "maxLossPerTrade",
        "message": "Defina a perda máxima por operação (maior que zero)."
      },
      {
        "code": "ENTRY_TIMEOUT_REQUIRED",
        "field": "entryTimeoutMinutes",
        "message": "Defina o tempo máximo de uma entrada pendente (1–1440 minutos)."
      }
    ]
  },
  "risk": {
    "maxDailyLossUsd": 1.5,
    "maxOpenNotionalUsd": 30,
    "maxSameDirection": 2,
    "haltedToday": false
  },
  "safety": {
    "policyVersion": "2026-10-05.1",
    "fingerprint": "849d46a1ab2fbe753c262109c41309716c6813c0d0dd44445070811b5dd2281d",
    "required": false,
    "acknowledged": true,
    "flags": []
  },
  "apiConfigured": false,
  "requestId": "req_muyn0w4r_ss9gkaoj"
}

POST/v1/users/:externalUserId/setup/preview

Prévia do setup

Tela do clienteVer no app modelo: Risco e estratégia ↗

NÃO grava nada. Valida contra os limites do contrato e devolve os alertas da combinação (safety.flags) e o fingerprint. Se safety.required for true e acknowledged false, o cliente precisa confirmar os alertas antes de gravar. Funciona antes de conectar a corretora.

Parâmetros de caminho

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

Corpo (JSON)

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora
mode"REAL"obrigatório
PAPER não é oferecido no B2B (PAPER_NOT_GRANTED)
enabledbooleanobrigatório
liga o setup
leverageinteiro 1–125obrigatório
alavancagem; limitada pelo contrato
orderSizeUsdnúmero ≥ 1obrigatório
tamanho por operação
maxConcurrentTradesinteiro 1–20obrigatório
operações simultâneas; limitada pelo contrato
maxMarginPerTradeUsdnúmero ≥ 0obrigatório
margem máxima por operação; limitada pelo contrato
maxDailyLossUsdnúmero ≥ 0obrigatório
perda máxima diária; atingiu → sem novas entradas até o dia seguinte (UTC)
capitalBasenúmero > 0para ligar
capital base
maxLossPerTradenúmero > 0para ligar
perda máxima por operação
entryTimeoutMinutesinteiro 1–1440para ligar
tempo máximo de uma entrada pendente
marginTypeISOLATED | CROSSEDopcional
tipo de margem
allowedSymbolsstring[]opcional
ativos permitidos, ex.: ["BTCUSDT"]
autoStopLoss · autoTakeProfit · autoBreakEvenbooleanopcional
proteções automáticas
allowMemecoinsbooleanopcional
maxOpenNotionalUsd · maxSameDirection · maxAdverseEntryPercentnúmeroopcional
limites adicionais

Erros comuns

422RISK_ENVELOPE_EXCEEDEDacima do contrato, ex.: "Alavancagem acima do limite do parceiro (50 > 5)."
403PAPER_NOT_GRANTEDmode PAPER

Requisição

curl -X POST "$FIN_API/v1/users/cli-1001/setup/preview" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "providerId": "BINANCE",
    "mode": "REAL",
    "enabled": true,
    "leverage": 3,
    "orderSizeUsd": 10,
    "maxConcurrentTrades": 1,
    "maxMarginPerTradeUsd": 10,
    "maxDailyLossUsd": 10,
    "capitalBase": 100,
    "maxLossPerTrade": 2,
    "entryTimeoutMinutes": 30
  }'

Resposta200

{
  "externalUserId": "cli-1001",
  "providerId": "BINANCE",
  "safety": {
    "policyVersion": "2026-10-05.1",
    "fingerprint": "18ed74468f4bf6542a7353ea2749cb0ad2f524523c47cc021c16bc740bf70391",
    "required": true,
    "acknowledged": false,
    "flags": []
  },
  "requestId": "req_muyn0wq4_amphkip7"
}

PUT/v1/users/:externalUserId/setup

Gravar setup

Tela do clienteIdempotency-Key obrigatórioVer no app modelo: Risco e estratégia ↗

Grava o setup COMPLETO (não é remendo: envie todos os campos). Com alertas exigidos, inclua riskAcknowledgement com o fingerprint da prévia e os códigos de safety.flags. Resposta: o setup gravado (mesmo formato do GET).

Parâmetros de caminho

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

Corpo (JSON)

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora
mode"REAL"obrigatório
PAPER não é oferecido no B2B (PAPER_NOT_GRANTED)
enabledbooleanobrigatório
liga o setup
leverageinteiro 1–125obrigatório
alavancagem; limitada pelo contrato
orderSizeUsdnúmero ≥ 1obrigatório
tamanho por operação
maxConcurrentTradesinteiro 1–20obrigatório
operações simultâneas; limitada pelo contrato
maxMarginPerTradeUsdnúmero ≥ 0obrigatório
margem máxima por operação; limitada pelo contrato
maxDailyLossUsdnúmero ≥ 0obrigatório
perda máxima diária; atingiu → sem novas entradas até o dia seguinte (UTC)
capitalBasenúmero > 0para ligar
capital base
maxLossPerTradenúmero > 0para ligar
perda máxima por operação
entryTimeoutMinutesinteiro 1–1440para ligar
tempo máximo de uma entrada pendente
marginTypeISOLATED | CROSSEDopcional
tipo de margem
allowedSymbolsstring[]opcional
ativos permitidos, ex.: ["BTCUSDT"]
autoStopLoss · autoTakeProfit · autoBreakEvenbooleanopcional
proteções automáticas
allowMemecoinsbooleanopcional
maxOpenNotionalUsd · maxSameDirection · maxAdverseEntryPercentnúmeroopcional
limites adicionais
riskAcknowledgement{ fingerprint, codes[] }condicional
aceite dos alertas da prévia (só no PUT, quando safety.required)

Erros comuns

422RISK_ACK_REQUIREDfaltou confirmar os alertas → refaça a prévia e peça a confirmação
422API_NOT_CONFIGUREDcorretora ainda não conectada → "Conecte a corretora antes de ativar"
422RISK_ENVELOPE_EXCEEDEDacima do limite do contrato (o limite vem na mensagem)
400SETUP_INCOMPLETEfaltam campos para ligar → setupStatus.issues
403PAPER_NOT_GRANTEDuse mode "REAL"
422DAILY_LOSS_HALTtrava diária atingida; volta no dia seguinte (UTC)

Requisição

curl -X PUT "$FIN_API/v1/users/cli-1001/setup" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: put-setup-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "providerId": "BINANCE",
    "mode": "REAL",
    "enabled": true,
    "leverage": 3,
    "orderSizeUsd": 10,
    "maxConcurrentTrades": 1,
    "maxMarginPerTradeUsd": 10,
    "maxDailyLossUsd": 10,
    "capitalBase": 100,
    "maxLossPerTrade": 2,
    "entryTimeoutMinutes": 30,
    "riskAcknowledgement": {
      "fingerprint": "18ed74468f4bf6542a7353ea2749cb0ad2f524523c47cc021c16bc740bf70391",
      "codes": []
    }
  }'

PUT/v1/users/:externalUserId/risk

Atualizar só os limites

Tela do clienteIdempotency-Key obrigatório

Atualiza só os limites de risco, sem mexer em alavancagem, tamanho ou ligado. Resposta: o setup atualizado.

Parâmetros de caminho

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

Corpo (JSON)

providerIdBINANCE | HYPERLIQUIDobrigatório
corretora
maxConcurrentTradesinteiro 1–20obrigatório
maxMarginPerTradeUsdnúmero ≥ 0obrigatório
maxDailyLossUsdnúmero ≥ 0obrigatório
demais campos opcionais do setup—opcional
capitalBase, maxLossPerTrade, allowedSymbols…

Requisição

curl -X PUT "$FIN_API/v1/users/cli-1001/risk" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: put-risk-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "providerId": "BINANCE",
    "maxConcurrentTrades": 1,
    "maxMarginPerTradeUsd": 10,
    "maxDailyLossUsd": 10
  }'