Crypto Wallets

All endpoints require Authorization: Bearer <token> and are scoped to the tenant (clientId) resolved from OAuth.

Overview

The Crypto Wallets API lets you generate custodial blockchain wallets, receive deposits, transfer, and query onchain balance and history.

Wallet creation is by chain family: EVM, BTC, TRON, SOLANA, XRPL — a single EVM wallet (one address) serves ETHEREUM, POLYGON and BSC. For balance, history and transfer you pass the specific network (ETHEREUM, POLYGON, BSC, BITCOIN, TRON, SOLANA, XRPL), since tokens live per network.

Main flows:

1. Create a wallet (POST /v1/crypto/wallets) or a checkout address (POST /v1/crypto/checkout/address, a forward wallet that auto-sweeps).
2. Receive a deposit — the provider notifies via webhook; the crypto-cash-in event is re-delivered to your registered webhook.
3. Query balance (/balance) and history (/history).
4. Transfer / cash-out (POST /v1/crypto/transfer).

---

POST /v1/crypto/wallets

Creates a custodial wallet for the given chain family and registers it under the 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	Chain family: EVM | BTC | TRON | SOLANA | XRPL
userId	string	No	Your user reference (isolates the wallet within the tenant)
isForwardPayment	integer	No	1 creates a forward (checkout) wallet that sweeps received funds

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

Creates a checkout deposit address (forward wallet). Received funds are auto-swept to the master wallet and trigger the crypto-cash-in webhook.

Request Body:

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

Field	Type	Required	Description
network	string	Yes	Chain family: EVM | BTC | TRON | SOLANA | XRPL
reference	string	No	Your reference (e.g. order id)

Response 200 OK:

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

---

GET /v1/crypto/wallets

Lists the tenant's wallets.

Query Parameters:

Parameter	Type	Required	Description
network	string	No	Filter by chain family
status	string	No	Filter by status
limit	integer	No	Page size
offset	integer	No	Offset

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

Native and token balances of a wallet.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Specific network: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
tokenAddress	string	No	Token contract address (filters the balance)

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

Onchain transaction history of a wallet.

Query Parameters:

Parameter	Type	Required	Description
network	string	Yes	Specific network: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
page	integer	No	Page (0-based)
pageSize	integer	No	Page size (default 50)
tokenAddress	string	No	Filter by token contract

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

Submits an onchain transfer from a wallet (cash-out).

Request Body:

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

Field	Type	Required	Description
network	string	Yes	Specific network: ETHEREUM | POLYGON | BSC | BITCOIN | TRON | SOLANA | XRPL
fromAddress	string	Yes	Source address
to	string	Yes	Destination address
amount	string	Yes	Amount (decimal string)
tokenAddress	string	No	Token contract (token transfer)
decimals	integer	No	Token decimals

Response 200 OK:

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

---

Deposits (webhook)

Deposits received on the wallets are delivered to your webhook as the crypto-cash-in event. Register your webhook and see the data model in the Webhooks section.