Referência da API

Saúde e contrato

Verificar a credencial, ler o seu contrato e o consumo da API. Cada parceiro tem um contrato único, definido pelo FINAUTON no cadastro (corretoras, estratégias, limites de risco, cobrança e origens de retorno). Na API ele aparece como um tenant com o mesmo id do parceiro — você só lê, não precisa configurar nada.

GET/v1/healthSaúde da API GET/v1/tenantsLer o contrato GET/v1/tenants/:tenantIdLer o contrato pelo id PUT/v1/tenants/:tenantId/restrictionsRestringir o contrato GET/v1/usageConsumo da API

GET/v1/health

Saúde da API

Rotina do servidor

Confirma que a API está no ar e que a credencial é válida. Mostra se a execução REAL de cada corretora já está homologada (ENABLED) ou não (NOT_VALIDATED).

Erros comuns

401B2B_CREDENTIAL_INVALIDcredencial ausente, errada ou revogada

Requisição

curl -X GET "$FIN_API/v1/health" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "api": "UP",
  "providers": [
    {
      "providerId": "BINANCE",
      "status": "AVAILABLE",
      "realExecution": "ENABLED"
    },
    {
      "providerId": "HYPERLIQUID",
      "status": "AVAILABLE",
      "realExecution": "ENABLED"
    }
  ],
  "requestId": "req_muyn0vq4_1odbkqy3"
}

GET/v1/tenants

Ler o contrato

Backoffice do parceiro

Seu contrato: o que foi concedido (grants), suas restrições, origens de retorno registradas e a cobrança vigente (mensalidade por cliente, % de performance, período, carry). Use para montar as opções das telas — por exemplo, quais corretoras oferecer. A lista traz um item (o tenant com o id do seu parceiro).

Requisição

curl -X GET "$FIN_API/v1/tenants" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "tenants": [
    {
      "tenantId": "PARCEIRO_A",
      "name": "Parceiro A",
      "status": "ACTIVE",
      "grants": {
        "providers": [
          "BINANCE",
          "HYPERLIQUID"
        ],
        "strategies": [
          "FUTURES_MAIN_V1"
        ],
        "capabilities": []
      },
      "partnerRestrictions": null,
      "returnUrlOrigins": [
        "https://app.parceiro.example"
      ],
      "contract": {
        "version": 1,
        "suspended": false,
        "subscriptionMonthlyUsd": 30,
        "currency": "USDT",
        "performanceFeePercent": 0.2,
        "performancePeriod": "MONTHLY",
        "carryPolicy": "CARRY"
      },
      "clients": 7
    }
  ],
  "requestId": "req_muyn0vrf_wnfdfsns"
}

GET/v1/tenants/:tenantId

Ler o contrato pelo id

Backoffice do parceiro

O mesmo conteúdo de um item de /v1/tenants, dentro de { tenant }.

Parâmetros de caminho

tenantIdstringobrigatório
id do contrato (igual ao id do seu parceiro)

Erros comuns

404NOT_FOUNDid inexistente ou de outro parceiro

Requisição

curl -X GET "$FIN_API/v1/tenants/PARCEIRO_A" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "tenant": {
    "tenantId": "PARCEIRO_A",
    "name": "Parceiro A",
    "status": "ACTIVE",
    "grants": {
      "providers": [
        "BINANCE",
        "HYPERLIQUID"
      ],
      "strategies": [
        "FUTURES_MAIN_V1"
      ],
      "capabilities": []
    },
    "partnerRestrictions": null,
    "returnUrlOrigins": [
      "https://app.parceiro.example"
    ],
    "contract": {
      "version": 1,
      "suspended": false,
      "subscriptionMonthlyUsd": 30,
      "currency": "USDT",
      "performanceFeePercent": 0.2,
      "performancePeriod": "MONTHLY",
      "carryPolicy": "CARRY"
    },
    "clients": 7
  },
  "requestId": "req_muyn6fxq_8xlbemkj"
}

PUT/v1/tenants/:tenantId/restrictions

Restringir o contrato

Backoffice do parceiro

Restringe o seu contrato DENTRO do que foi concedido (nunca amplia). null remove a restrição. Opcional: use só se quiser oferecer menos do que o FINAUTON concedeu.

Reduzir o envelope abaixo do setup de um cliente bloqueia novas entradas dele (OUTSIDE_ENVELOPE) até ele reduzir o setup. Nada é alterado automaticamente.

Parâmetros de caminho

tenantIdstringobrigatório
id do contrato (igual ao id do seu parceiro)

Corpo (JSON)

providersstring[] | nullopcional
subconjunto das corretoras concedidas
strategiesstring[] | nullopcional
subconjunto das estratégias concedidas
envelopeobjeto | nullopcional
maxLeverage, maxMarginPerTradeUsd, maxConcurrentTrades, maxDailyLossUsd (≤ recebido)
reasonstring (3–500)obrigatório
motivo

Erros comuns

403GRANT_ESCALATIONpedido fora do concedido
403RISK_ENVELOPE_EXCEEDEDenvelope acima do recebido

Requisição

curl -X PUT "$FIN_API/v1/tenants/PARCEIRO_A/restrictions" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "providers": [
      "BINANCE"
    ],
    "envelope": {
      "maxLeverage": 3
    },
    "reason": "Lançamento só com Binance"
  }'

Resposta200

{
  "tenant": {
    "tenantId": "PARCEIRO_A",
    "name": "Parceiro A",
    "status": "ACTIVE",
    "grants": {
      "providers": [
        "BINANCE",
        "HYPERLIQUID"
      ],
      "strategies": [
        "FUTURES_MAIN_V1"
      ],
      "capabilities": [
        "PERP_TRADING"
      ]
    },
    "partnerRestrictions": {
      "providers": [
        "BINANCE"
      ],
      "strategies": null,
      "riskEnvelope": {
        "maxLeverage": 3
      }
    },
    "returnUrlOrigins": [
      "https://app.parceiro.example"
    ],
    "contract": {
      "version": 1,
      "suspended": false,
      "subscriptionMonthlyUsd": 30,
      "currency": "USDT",
      "performanceFeePercent": 0.2,
      "performancePeriod": "WEEKLY",
      "carryPolicy": "NO_CARRY"
    },
    "clients": 3
  },
  "requestId": "req_mv0a1b2c_res0001"
}

GET/v1/usage

Consumo da API

Backoffice do parceiro

Consumo da sua credencial na última hora e os limites por minuto (requestsPerMinute, ordersPerMinute).

Requisição

curl -X GET "$FIN_API/v1/usage" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"

Resposta200

{
  "window": {
    "from": "2026-10-07T20:46:42.732Z",
    "minutes": 60
  },
  "totals": {
    "requests": 730,
    "orders": 0
  },
  "limits": {
    "requestsPerMinute": 120,
    "ordersPerMinute": 30
  },
  "buckets": [
    {
      "window": "2026-10-07T20:47:00.000Z",
      "kind": "REQUEST",
      "count": 71
    }
  ],
  "requestId": "req_muyn0vwh_fuyxxv6m"
}