Crypto Wallets

Todos os endpoints exigem Authorization: Bearer <token> e são escopados pelo tenant (clientId) resolvido do OAuth.

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
}

Field	Type	Required	Description
network	string	Yes	Família de chain: EVM | BTC | TRON | SOLANA | XRPL
userId	string	No	Referência do usuário no seu sistema (isola a carteira dentro do tenant)
isForwardPayment	integer	No	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"
}

Field	Type	Required	Description
network	string	Yes	Família de chain: EVM | BTC | TRON | SOLANA | XRPL
reference	string	No	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 Parameters:

Parameter	Type	Required	Description
network	string	No	Filtra por família de chain
status	string	No	Filtra por status
limit	integer	No	Tamanho da página
offset	integer	No	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 Parameters:

Parameter	Type	Required	Description
network	string	Yes	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
tokenAddress	string	No	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 Parameters:

Parameter	Type	Required	Description
network	string	Yes	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
page	integer	No	Página (0-based)
pageSize	integer	No	Tamanho da página (default 50)
tokenAddress	string	No	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
}

Field	Type	Required	Description
network	string	Yes	Rede específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
fromAddress	string	Yes	Endereço de origem
to	string	Yes	Endereço de destino
amount	string	Yes	Valor (decimal em string)
tokenAddress	string	No	Contrato do token (transferência de token)
decimals	integer	No	Decimais do token

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.