Assets & Transactions

Read the public token catalog (no auth), your off-chain balances per token, and your ledger history. Balance and history endpoints require authentication.

Balance type: Everything on this page except List Allowed Tokens is off-chain — your app's ledger balance at Xellar, not a live blockchain read. See Understanding Balances.

For per_app (default), there is one row per token. For per_wallet, there is one row per token and deposit walletId.

List Allowed Tokens (Public)

Returns every active allowed token and its active network. No authentication. Use this to populate token/network pickers for invoices, withdraws, and listen flows.

The payload is catalog data only: token id, code, symbol, decimals, contract address, and network id/code/type/chainId. It does not include RPC URLs, credentials, or other infrastructure fields.

GET /api/v1/tokens

Query Parameters

Response 200

{
  "data": [
    {
      "id": "tok_abc123",
      "tokenCode": "usdt-ethereum",
      "symbol": "USDT",
      "decimals": 6,
      "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "network": {
        "id": "net_abc123",
        "code": "ethereum",
        "type": "evm",
        "chainId": 1
      }
    }
  ]
}

Inactive tokens and tokens on inactive networks are omitted.

Off-Chain Balance Fields

Each token asset has three balance buckets:

latestBalance in transaction history is also off-chain — it is a snapshot of activeBalance after each ledger entry.

List Assets

GET /api/v1/assets

Returns off-chain balances per token.

Query Parameters

Response 200

{
  "data": {
    "items": [
      {
        "tokenCode": "USDT",
        "network": "ethereum",
        "networkType": "evm",
        "chainId": 1,
        "tokenAddress": "0x...",
        "symbol": "USDT",
        "decimals": 6,
        "walletId": "wal_1",
        "pendingBalance": 0,
        "activeBalance": 100.5,
        "withholdBalance": 0
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 20
  }
}

walletId is present on per_wallet apps and omitted on per_app.

Get Asset by Token Code

GET /api/v1/assets/:tokenCode → { "data": { /* single asset */ } }

Optional query walletId — required to pick a single row when the app is per_wallet and the token has balances on more than one wallet.

Returns off-chain balance for one token. Response fields match List Assets.

List Transaction History

GET /api/v1/transaction-histories

Returns your off-chain ledger — credits and debits that changed your balance over time.

Query Parameters

Response 200

{
  "data": {
    "items": [
      {
        "id": "txn_abc123",
        "tokenCode": "USDT",
        "network": "ethereum",
        "symbol": "USDT",
        "method": "credit",
        "transactionType": "deposit",
        "amount": 100,
        "latestBalance": 100.5,
        "referenceType": "invoice",
        "referenceId": "inv_abc123",
        "createdAt": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 20,
    "page": 1,
    "limit": 20
  }
}