💵 Referência de Taxas (Fees)

Esta página cobre como consultar taxas antes e depois de uma operação: GET /fees/preview, GET /fees/history, GET /fees/transactions/{transactionId}, GET /fees/catalog e GET /fees/catalog/{feeType}.

Escopo — leia antes de integrar: estes endpoints resolvem a taxa pela identidade dona do token. Para o usuário final (JWT de sessão ou API key pessoal), funcionam plenamente sobre os dados dele. Para uma credencial de participante, apenas GET /fees/preview foi desenhado para consultar em nome de um usuário vinculado (via parâmetro userId) — history, transactions/{id} e catalog sempre resolvem pela identidade do token, e uma credencial de participante não corresponde a nenhum usuário real, então não use esses três com token de participante (o catálogo, por exemplo, cairia para as taxas globais em vez das do seu contrato). Se você precisa reconciliar taxas por usuário como participante, use GET /participant/users/{userId}/transactions (ver Portal de Leitura sobre Seus Usuários — rollout gradual), que já traz totalFee/participantFee/netAmount por transação.

1. Preview — Simular Taxa Antes de Confirmar

curl "https://api.dexkey.finance/v1/fees/preview?feeType=PIX_WITHDRAW&currency=BRL&channel=PIX&amount=1000.00" \
  -H "Authorization: Bearer $JWT"

Query param	Obrigatório	Descrição
`feeType`	sim	`PIX_DEPOSIT`, `PIX_WITHDRAW`, `CRYPTO_DEPOSIT`, `CRYPTO_WITHDRAW`, `SWAP`, `TRANSFER`
`currency`	sim	Código ISO 4217 ou símbolo cripto
`channel`	sim	`PIX`, `BLOCKCHAIN` ou `INTERNAL`
`amount`	sim	Valor em unidades da moeda (string, ex: `"1000.00"`)
`network`	não	Rede blockchain, obrigatório pra moedas multi-rede (ex: BRT)
`userId`	não	Simula a taxa para outro usuário. Uso normal: omitido (usa o próprio token). Credencial de participante: pode informar o `userId` de um usuário vinculado — é o único caso em que token de participante funciona aqui.
`skipBalanceCheck`	não	Pula a validação de saldo (útil pra exibir preview sem saldo suficiente ainda)

{
  "feeType": "PIX_WITHDRAW",
  "currency": "BRL",
  "channel": "PIX",
  "grossAmount": "100000",
  "platformFee": { "fixed": "200", "fixedFormatted": "R$ 2,00", "percentage": "300", "percentageFormatted": "R$ 3,00", "total": "500", "totalFormatted": "R$ 5,00" },
  "participantFee": { "fixed": "100", "fixedFormatted": "R$ 1,00", "percentage": "100", "percentageFormatted": "R$ 1,00", "total": "200", "totalFormatted": "R$ 2,00" },
  "totalFee": "700",
  "totalFeeFormatted": "R$ 7,00",
  "grossAmountFormatted": "R$ 1.000,00",
  "netAmountFormatted": "R$ 993,00",
  "netAmount": "99300",
  "effectiveRate": "0.7",
  "disclaimer": "Fees locked at operation start"
}

403 se userId pertencer a outro usuário/fora do escopo do seu participante. 422 (FEE_INSUFFICIENT_BALANCE) se o saldo não cobrir valor + taxa em operações de saída, a menos que skipBalanceCheck=true.

2. Histórico de Taxas

curl "https://api.dexkey.finance/v1/fees/history?limit=20&offset=0" \
  -H "Authorization: Bearer $JWT"

Filtros opcionais: feeType, currency, limit (1-100), offset. Retorna as taxas do próprio usuário do token, mais recentes primeiro.

{
  "data": [
    {
      "id": "550e8400-...",
      "transactionId": "660e8400-...",
      "feeType": "PIX_WITHDRAW",
      "currency": "BRL",
      "channel": "PIX",
      "transactionAmount": "1000.00",
      "totalFee": "7.00",
      "platformFee": "5.00",
      "participantFee": "2.00",
      "netAmount": "993.00",
      "isReversed": false,
      "createdAt": "2026-02-20T10:30:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 150, "hasMore": true }
}

3. Detalhe de uma Taxa

curl https://api.dexkey.finance/v1/fees/transactions/{transactionId} \
  -H "Authorization: Bearer $JWT"

Mesmo formato de um item de history acima. 404 se a taxa não existir ou não pertencer ao usuário do token.

4. Catálogo de Taxas Vigentes ("Tabela do Contrato")

curl "https://api.dexkey.finance/v1/fees/catalog?channel=BLOCKCHAIN,INTERNAL" \
  -H "Authorization: Bearer $JWT"

Retorna um item por (tipo, canal, moeda) com o total efetivo (plataforma + participante/usuário já somados) e o breakdown de origem:

{
  "channels": ["BLOCKCHAIN", "INTERNAL"],
  "items": [
    {
      "feeType": "TRANSFER",
      "channel": "INTERNAL",
      "currency": "BRL",
      "displayLabel": "Transferência interna",
      "isExempt": false,
      "fixedAmount": "1.50",
      "percentageRate": "0.3",
      "displayValue": "R$ 1,50",
      "displayRate": "0,30%",
      "effectiveFrom": "2026-01-01T00:00:00.000Z",
      "breakdown": {
        "platform": { "fixedAmount": "1.50", "percentageRate": "0.3" },
        "participant": null,
        "user": null,
        "overridePlatform": false,
        "overrideReason": null
      }
    }
  ]
}

GET /fees/catalog/{feeType}?channel=...&currency=... retorna o mesmo item, individual, mais um bloco about com textos editoriais (whenApplied, whoPays, whoReceives,conversion).

Os valores de fixedAmount/percentageRate neste exemplo vêm do seed de desenvolvimento — não use como a taxa real do seu contrato. Consulte GET /fees/catalog autenticado com o JWT de um usuário real vinculado a você para ver as taxas efetivamente configuradas.

Regras Gerais

Cobrança: a taxa é cobrada no ato da operação, como lançamento próprio no ledger (nunca descontada silenciosamente do valor principal) — ver fees em cada transação no Referência Completa do Ledger.
Moeda da taxa: sempre a mesma moeda da operação (uma transferência em BTC gera taxa em BTC, não em BRL).
Arredondamento: Banker's Rounding (ROUND_HALF_EVEN) — ex. 2,45 arredonda pra 2,4, não 2,5. Padrão do mercado financeiro brasileiro (ABNT NBR 5891), evita viés sistemático de arredondamento sempre pra cima.
Spread do Swap: padrão de 1% (100 bps), com piso de 0,1% (10 bps) e teto de 5% (500 bps), configurável por par de moedas.
Valor mínimo do Swap: existe um piso por par de moedas (retorna 422 se abaixo dele) — o valor exato não é público nesta versão da doc; use POST /swap/quote para descobrir na prática (retorna 422 se o valor for baixo demais).
Estorno de taxa: se uma operação falha depois de cobrar a taxa, a reversão (REVERSAL) inclui a taxa — o usuário é reembolsado integralmente, incluindo o valor da taxa (FeeTransaction.isReversed = true).

🔗 Cobranças / Links de Pagamento (Receive Requests)

🔔 Eventos Assíncronos (Webhooks)