📖 Referência Completa do Ledger (Saldo, Extrato e Comprovante)
Esta página é a referência de contrato para consulta de saldo, ativos e movimentações — cobre GET /ledger/balance, GET /users/consolidated-balance, GET /users/assets, GET /users/wallets, GET /ledger/statement, GET /ledger/statement/export e GET /ledger/transactions/{id}.
Saldo
curl https://api.dexkey.finance/v1/ledger/balance \
-H "Authorization: Bearer $JWT"Aceita ?currency=BTC para retornar só uma moeda. Sem o filtro, retorna todas (BRL, BRT, BTC, ETH, USDT, USDC).
Saldo Consolidado (Numa Única Moeda de Exibição)
Útil pra mostrar "quanto o usuário tem, no total" numa única moeda (BRL ou USD), somando todos os ativos:
curl "https://api.dexkey.finance/v1/users/consolidated-balance?displayCurrency=BRL" \
-H "Authorization: Bearer $JWT"{
"displayCurrency": "BRL",
"totalBalance": 1500.35,
"assets": [
{ "symbol": "BTC", "name": "Bitcoin", "amount": 0.001, "price": 500000, "value": 500 },
{ "symbol": "BRT", "name": "Real Tokenizado", "amount": 1000.35, "price": 1, "value": 1000.35 }
]
}Ativos Agregados (Por Símbolo, Todas as Carteiras/Redes)
Diferente do saldo consolidado (uma moeda de exibição), este endpoint soma cada ativo pelo próprio símbolo nativo, e detalha em quais carteiras/redes ele está distribuído:
curl https://api.dexkey.finance/v1/users/assets \
-H "Authorization: Bearer $JWT"{
"assets": [
{
"symbol": "USDT",
"name": "Tether USD",
"amount": 28.004431,
"brlPrice": 5.73, "brlValue": 160.48,
"usdPrice": 1.0, "usdValue": 28.0,
"list": [
{ "amount": 27.12, "blockchain": "polygon", "network": "mainnet", "networkCode": "ERC-20", "walletAddress": "0xf0b1..." },
{ "amount": 0.88, "blockchain": "tron", "network": "mainnet", "networkCode": "TRC-20", "walletAddress": "TXy..." }
]
}
]
}503 se o provedor de carteiras estiver indisponível.
Lista de Carteiras (Paginada)
curl "https://api.dexkey.finance/v1/users/wallets?page=1&limit=10" \
-H "Authorization: Bearer $JWT"{
"totalItems": 3,
"totalPages": 1,
"limit": 10,
"page": 1,
"items": [
{
"id": "wallet-id-abc123",
"network": "mainnet",
"blockchain": "bitcoin",
"address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"createdAt": "2026-01-10T10:00:00.000Z",
"updatedAt": "2026-01-10T10:00:00.000Z",
"assets": []
}
]
}Diferente de GET /users/wallets-status (que só diz se as carteiras já foram criadas — ver Quickstart), este endpoint lista as carteiras de fato, uma por blockchain/rede.
Consultar Status de Depósito/Saque Cripto
Diferente do Pix (que tem GET /pix/deposit/{id}/status dedicado), não existe um endpoint de status separado para depósito/saque cripto. Use o id da transação retornado por POST /ledger/crypto/withdraw (campo ledgerTransactionId na resposta) em:
curl https://api.dexkey.finance/v1/ledger/transactions/{id} \
-H "Authorization: Bearer $JWT"Isso retorna o comprovante completo — inclui status (PENDING/COMPLETED/FAILED/REVERSED) e, para operações cripto, operationDetails.blockchainHash quando disponível.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CRYPTO_WITHDRAW",
"status": "COMPLETED",
"amount": "1000000",
"amountFormatted": "0.01000000 BTC",
"currency": "BTC",
"description": "Saque de BTC",
"createdAt": "2026-07-14T10:00:00.000Z",
"completedAt": "2026-07-14T10:05:00.000Z",
"fees": {
"totalFee": "700", "totalFeeFormatted": "0.00000700 BTC",
"platformFee": "500", "platformFeeFormatted": "0.00000500 BTC",
"participantFee": "200", "participantFeeFormatted": "0.00000200 BTC",
"netAmount": "999300", "netAmountFormatted": "0.00999300 BTC"
},
"operationDetails": {
"toAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493...",
"blockchainHash": "0xabc123...",
"network": "bitcoin"
},
"entries": [
{ "id": "...", "accountCode": "...", "amount": "-1000000", "amountFormatted": "-0.01000000 BTC", "type": "DEBIT" }
]
}O mesmo endpoint serve de comprovante genérico pra qualquer tipo de transação (Pix, transferência interna, swap) — o conteúdo de operationDetails/counterparty/pendingTransfer varia conforme o type.
Extrato — GET /ledger/statement
curl "https://api.dexkey.finance/v1/ledger/statement?page=1&limit=50" \
-H "Authorization: Bearer $JWT"Filtros
|
Query param |
Descrição |
|---|---|
|
|
|
|
|
Paginação |
Tipos de Transação e Seus Campos Específicos
Cada item de data[] tem um formato base (id, type, status, amount, currency,amountFormatted, createdAt, description, entries) mais campos exclusivos por tipo:
|
Tipo |
Campos específicos |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
sem campos extras |
Não existem tipos CRYPTO_IN/SWAP_IN/SWAP_OUT — um swap é uma única transação do tipo CRYPTO_SWAP, com as duas pernas (moeda de origem debitada, moeda de destino creditada) dentro do mesmo array entries, não duas transações separadas.
Exemplos Reais por Tipo
Transferência interna enviada:
{
"type": "TRANSFER_INTERNAL",
"amount": "-2001",
"amountFormatted": "-R$ 20,01",
"description": "Transferência enviada para Fulano",
"network": "polygon",
"recipient": { "id": "...", "name": "Fulano", "email": "...", "phone": "..." }
}Pix recebido (BRT_MINT):
{
"type": "BRT_MINT",
"amount": "1000",
"amountFormatted": "R$ 10,00",
"description": "Pix Recebido",
"pixMetadata": { "pixEventId": "E00416968...", "qrCodeId": "...", "endToEndId": "E00416968..." }
}Depósito cripto confirmado:
{
"type": "CRYPTO_DEPOSIT",
"amount": "1000000",
"amountFormatted": "0.01000000 BTC",
"currency": "BTC",
"description": "Depósito de BTC",
"network": "bitcoin"
}Saque cripto:
{
"type": "CRYPTO_WITHDRAW",
"amount": "-10060000",
"amountFormatted": "-10.06 USDT",
"description": "Saque de USDT",
"network": "tron"
}Swap entre moedas (uma transação, duas pernas em entries):
{
"type": "CRYPTO_SWAP",
"amount": "-1000",
"amountFormatted": "-R$ 10,00",
"description": "Conversão: -R$ 10,00 -> 1.944314 USDT",
"entries": [
{ "amount": "1944314", "amountFormatted": "1.944314 USDT", "type": "CREDIT" },
{ "amount": "-1000", "amountFormatted": "-R$ 10,00", "type": "DEBIT" }
],
"fromCurrency": "BRT", "toCurrency": "USDT",
"fromNetwork": "polygon", "toNetwork": "ethereum"
}Estorno (REVERSAL):
{
"type": "REVERSAL",
"amount": "5055000",
"amountFormatted": "5.055 USDT",
"description": "Transação",
"entries": [{ "amount": "5055000", "amountFormatted": "5.055 USDT", "type": "CREDIT" }]
}
Sumário (summary)
GET /ledger/statement retorna também um objeto summary com totalCredits,totalDebits e balance/balanceFormatted do período filtrado. Quando o resultado tem uma única moeda, balance é numérico. Quando tem múltiplas moedas, balance = "0" e balanceFormatted = "-" — não há conversão cross-currency automática nesse campo.
Exportação em CSV
curl "https://api.dexkey.finance/v1/ledger/statement/export?startDate=2026-07-01&endDate=2026-07-31" \
-H "Authorization: Bearer $JWT" -o extrato.csvColunas: Data, Horário, ID, Hash, Tipo, Moeda Origem, Valor Origem, Moeda Destino, Valor Destino, Taxa, Status.
Exemplos Completos — Saque Pix vs. Saque USDT
Saque Pix de R$ 100,00 (resposta de POST /pix/withdraw):
{
"operationId": "pixwdmpbdrp6w28gpxyzv",
"status": "PENDING",
"amount": 10000,
"amountFormatted": "R$ 100,00",
"ledgerTransactionId": "01234567-89ab-cdef-0123-456789abcdef",
"fees": {
"totalDebited": 10070,
"platformFee": 50,
"participantFee": 20,
"totalFee": 70,
"totalDebitedFormatted": "R$ 100,70",
"totalFeeFormatted": "R$ 0,70"
},
"balance": { "before": 20000, "after": 9930, "beforeFormatted": "R$ 200,00", "afterFormatted": "R$ 99,30" }
}Total debitado do saldo: R$ 100,70 (R$ 100,00 solicitado + R$ 0,70 de taxa).
Saque de 50 USDT (comprovante via GET /ledger/transactions/{id} depois de POST /ledger/crypto/withdraw):
{
"type": "CRYPTO_WITHDRAW",
"status": "PENDING",
"amount": "50051000",
"amountFormatted": "50.051000 USDT",
"currency": "USDT",
"fees": {
"totalFee": "51000", "totalFeeFormatted": "0.051000 USDT",
"netAmount": "50000000", "netAmountFormatted": "50.000000 USDT"
}
}Confirmado em ledger.service.ts (cryptoWithdraw()): o valor debitado do saldo é sempre amount solicitado + fee (mesmo princípio do Pix — a taxa é somada, nunca descontada do valor que você pediu para sacar). Use fees.totalFee para saber exatamente quanto foi cobrado, e fees.netAmount para conferir o valor que efetivamente saiu na rede.
