Crypto Wallets

Todos los endpoints requieren Authorization: Bearer <token> y están acotados al tenant (clientId) resuelto desde OAuth.

Visión general

La API de Crypto Wallets permite generar billeteras blockchain custodiadas, recibir depósitos, transferir y consultar saldo e historial onchain.

La creación de billetera es por familia de chain: EVM, BTC, TRON, SOLANA, XRPL — una billetera EVM (una sola dirección) sirve para ETHEREUM, POLYGON y BSC. Para saldo, historial y transferencia se indica la red específica (ETHEREUM, POLYGON, BSC, BITCOIN, TRON, SOLANA, XRPL), ya que los tokens viven por red.

Flujos principales:

1. Crear billetera (POST /v1/crypto/wallets) o una dirección de checkout (POST /v1/crypto/checkout/address, forward wallet con barrido automático).
2. Recibir un depósito — el proveedor notifica vía webhook; el evento crypto-cash-in se reenvía a tu webhook registrado.
3. Consultar saldo (/balance) e historial (/history).
4. Transferir / cash-out (POST /v1/crypto/transfer).

---

POST /v1/crypto/wallets

Crea una billetera custodiada para la familia de chain indicada y la registra bajo el 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	Familia de chain: EVM | BTC | TRON | SOLANA | XRPL
userId	string	No	Referencia de tu usuario (aísla la billetera dentro del tenant)
isForwardPayment	integer	No	1 crea una forward wallet (checkout) que barre los fondos recibidos

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

Crea una dirección de depósito de checkout (forward wallet). Los fondos recibidos se barren automáticamente a la billetera maestra y disparan el webhook crypto-cash-in.

Request Body:

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

Field	Type	Required	Description
network	string	Yes	Familia de chain: EVM | BTC | TRON | SOLANA | XRPL
reference	string	No	Tu referencia (ej.: id del pedido)

Response 200 OK:

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

---

GET /v1/crypto/wallets

Lista las billeteras del tenant.

Query Parameters:

Parameter	Type	Required	Description
network	string	No	Filtra por familia de chain
status	string	No	Filtra por estado
limit	integer	No	Tamaño de página
offset	integer	No	Desplazamiento

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 y de tokens de una billetera.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Red específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
tokenAddress	string	No	Dirección del contrato del token (filtra el 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

Historial de transacciones onchain de una billetera.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Red específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
page	integer	No	Página (0-based)
pageSize	integer	No	Tamaño de 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

Envía una transferencia onchain desde una billetera (cash-out).

Request Body:

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

Field	Type	Required	Description
network	string	Yes	Red específica: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
fromAddress	string	Yes	Dirección de origen
to	string	Yes	Dirección de destino
amount	string	Yes	Monto (decimal en string)
tokenAddress	string	No	Contrato del token (transferencia de token)
decimals	integer	No	Decimales del token

Response 200 OK:

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

---

Depósitos (webhook)

Los depósitos recibidos en las billeteras se entregan a tu webhook como el evento crypto-cash-in. Registra tu webhook y consulta el modelo de datos en la sección Webhooks.