Crypto Wallets

Todos os endpoints exigem Authorization: Bearer <token> e o header x-client-id: <seu Client_ID> — o tenant id é o mesmo valor do Client_ID do OAuth (detalhes); sem ele a chamada falha com 400 MISSING_CLIENT_ID. As carteiras são escopadas ao seu tenant.

Visão geral

A API de Crypto Wallets permite gerar carteiras blockchain custodiais, receber depósitos, transferir, e consultar saldo e histórico onchain.

A criação de carteira é por família de chain: EVM, BTC, TRON, SOLANA, XRPL — uma carteira EVM (um único endereço) atende ETHEREUM, POLYGON e BSC. Já em saldo, histórico e transferência você informa a rede específica (ETHEREUM, POLYGON, BSC, BITCOIN, TRON, SOLANA, XRPL), pois os tokens vivem por rede.

Fluxos principais:

1. Criar carteira (POST /v1/crypto/wallets) ou endereço de checkout (POST /v1/crypto/checkout/address, forward wallet que faz varredura automática).
2. Receber depósito — o provedor notifica via webhook; o evento crypto-cash-in é reentregue ao seu webhook registrado.
3. Consultar saldo (/balance) e histórico (/history).
4. Transferir / saque (POST /v1/crypto/transfer).

---

POST /v1/crypto/wallets

Cria uma carteira custodial para a família de chain informada e a registra sob o tenant.

Headers:

Header	Value
Authorization	Bearer <token>
Content-Type	application/json

Request Body:

{
  "network": "EVM",
  "userId": "user-123",
  "isForwardPayment": 0
}

Campo	Tipo	Obrigatório	Descrição
network	string	Sim	Família de chain: EVM | BTC | TRON | SOLANA | XRPL
userId	string	Não	Referência do usuário no seu sistema (isola a carteira dentro do tenant)
isForwardPayment	integer	Não	1 cria uma forward wallet (checkout) que varre os fundos recebidos

Response 200 OK:

{
  "message": "Wallet created",
  "data": {
    "walletId": "a1b2c3d4-0000-0000-0000-000000000000",
    "address": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
    "network": "EVM",
    "coin": "EVM",
    "isForwardPayment": 0
  }
}

---

POST /v1/crypto/checkout/address

Cria um endereço de depósito de checkout (forward wallet). Os fundos recebidos são varridos automaticamente para a carteira mestre e disparam o webhook crypto-cash-in.

Request Body:

{
  "network": "EVM",
  "reference": "order-9911"
}

Campo	Tipo	Obrigatório	Descrição
network	string	Sim	Família de chain: EVM | BTC | TRON | SOLANA | XRPL
reference	string	Não	Sua referência (ex.: id do pedido)

Response 200 OK:

{
  "message": "Checkout address created",
  "data": {
    "address": "0x1122334455667788990011223344556677889900",
    "network": "EVM",
    "reference": "order-9911"
  }
}

---

GET /v1/crypto/wallets

Lista as carteiras do tenant.

Query params:

Param	Tipo	Obrigatório	Descrição
network	string	Não	Filtra por família de chain
status	string	Não	Filtra por status
limit	integer	Não	Tamanho da página
offset	integer	Não	Deslocamento

Response 200 OK:

{
  "message": "Success",
  "data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000000",
      "clientId": "tenant-1",
      "network": "EVM",
      "address": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
      "coin": "EVM",
      "status": "ACTIVE",
      "isForwardPayment": 0,
      "createdAt": "2026-06-06T12:00:00.000Z"
    }
  ]
}

---

GET /v1/crypto/wallets/{address}/balance

Saldo nativo e de tokens de uma carteira.

Query params:

Param	Tipo	Obrigatório	Descrição
network	string	Sim	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
tokenAddress	string	Não	Endereço do contrato do token (filtra o saldo)

Response 200 OK:

{
  "message": "Success",
  "data": [
    {
      "address": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
      "asset": "MATIC",
      "decimals": 18,
      "balance": "12.5",
      "type": "native"
    },
    {
      "address": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
      "asset": "USDT",
      "decimals": 6,
      "balance": "1000.00",
      "tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
    }
  ]
}

---

GET /v1/crypto/wallets/{address}/history

Histórico de transações onchain de uma carteira.

Query params:

Param	Tipo	Obrigatório	Descrição
network	string	Sim	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
page	integer	Não	Página (0-based)
pageSize	integer	Não	Tamanho da página (default 50)
tokenAddress	string	Não	Filtra por contrato de token

Response 200 OK:

{
  "message": "Success",
  "data": [
    {
      "chain": "polygon-mainnet",
      "hash": "0xabc123...",
      "address": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
      "blockNumber": 58123456,
      "amount": "1000.00",
      "transactionSubtype": "incoming",
      "counterAddress": "0x4444...",
      "timestamp": 1749200000000
    }
  ]
}

---

POST /v1/crypto/transfer

Submete uma transferência onchain a partir de uma carteira (cash-out).

Request Body:

{
  "network": "POLYGON",
  "fromAddress": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432",
  "to": "0x4444555566667777888899990000aaaabbbbcccc",
  "amount": "10.5",
  "tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "decimals": 6
}

Campo	Tipo	Obrigatório	Descrição
network	string	Sim	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
fromAddress	string	Sim	Endereço de origem
to	string	Sim	Endereço de destino
amount	string	Sim	Valor (decimal em string)
tokenAddress	string	Não	Contrato do token (transferência de token)
decimals	integer	Não	Decimais do token
networkId	string	Não	Rede específica dentro da família (EVM), quando aplicável
currency	string	Não	Código da moeda/token XRPL (transferência de token na XRPL)
issuer	string	Não	Endereço emissor do token XRPL (transferência de token na XRPL)

Response 200 OK:

{
  "message": "Success",
  "data": {
    "txHash": "0xabc123..."
  }
}

---

Depósitos (webhook)

Os depósitos recebidos nas carteiras são entregues ao seu webhook como o evento crypto-cash-in. Registre seu webhook e veja o modelo de dados na seção Webhooks.