Assets & Balances

Read the public token catalog (no auth), your off-chain balances, ledger history, and optional convert / transfer operations. Balance endpoints require authentication.

Signed endpoints on this page

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
  }
}

Balance convert (overview)

Convert moves off-chain balance from one allowed token to another inside the same app. Nothing is sent on-chain.

Recommended flow:

1. Estimate — POST /api/v1/balances/convert/estimate (quote only; no balance change)
2. Convert — POST /api/v1/balances/convert (applies the same quote rules and updates balances)

Rules that apply to both endpoints

How the quote is calculated

rate            = FX rate from peggedFrom → peggedTo   (or 1 if same peg)
effectiveRate   = rate × (1 − markupPercentage / 100)  (or 1 if same peg)
toAmount        = amount × effectiveRate

Example (cross peg): convert 100 USDT (USD) → XSGD (SGD), market rate 1.35, markup 1%:

• rate = 1.35
• effectiveRate = 1.35 × (1 − 0.01) = 1.3365
• toAmount = 100 × 1.3365 = 133.65
• Ledger: debit 100 from USDT, credit 133.65 to XSGD

Estimate Convert

POST /api/v1/balances/convert/estimate

Returns a conversion quote without changing balances. Use this to show the user how much they will receive before calling convert.

Does not check whether you have enough activeBalance (insufficient balance is only enforced on convert).

Request body

{
  "from": "usdt-ethereum",
  "to": "xsgd-ethereum",
  "amount": 100
}

Response 200

{
  "data": {
    "from": "usdt-ethereum",
    "to": "xsgd-ethereum",
    "amount": 100,
    "toAmount": 133.65,
    "rate": 1.35,
    "effectiveRate": 1.3365,
    "markupPercentage": 1,
    "peggedFrom": "USD",
    "peggedTo": "SGD",
    "fxProvider": "frankfurter",
    "samePeg": false
  }
}

Response data fields (quote object)

Same-peg example

{
  "from": "usdt-ethereum",
  "to": "usdc-ethereum",
  "amount": 50
}

{
  "data": {
    "from": "usdt-ethereum",
    "to": "usdc-ethereum",
    "amount": 50,
    "toAmount": 50,
    "rate": 1,
    "effectiveRate": 1,
    "markupPercentage": 0,
    "peggedFrom": "USD",
    "peggedTo": "USD",
    "fxProvider": "",
    "samePeg": true
  }
}

Errors (estimate)

Convert Balance

POST /api/v1/balances/convert

Applies a conversion using the same quote rules as Estimate Convert:

• Debits amount from the source token’s off-chain activeBalance
• Credits toAmount to the destination token’s off-chain activeBalance
• Records the conversion (rate, markup, pegs, balances after)

Request body is identical to estimate. Unlike estimate, convert requires sufficient source activeBalance.

Request body

{
  "from": "usdt-ethereum",
  "to": "xsgd-ethereum",
  "amount": 100
}

Response 200

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "usdt-ethereum",
    "to": "xsgd-ethereum",
    "amount": 100,
    "toAmount": 133.65,
    "rate": 1.35,
    "effectiveRate": 1.3365,
    "markupPercentage": 1,
    "peggedFrom": "USD",
    "peggedTo": "SGD",
    "fxProvider": "frankfurter",
    "samePeg": false,
    "fromBalance": {
      "tokenCode": "usdt-ethereum",
      "network": "ethereum",
      "networkType": "evm",
      "chainId": 1,
      "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "symbol": "USDT",
      "decimals": 6,
      "pendingBalance": 0,
      "activeBalance": 0,
      "withholdBalance": 0
    },
    "toBalance": {
      "tokenCode": "xsgd-ethereum",
      "network": "ethereum",
      "networkType": "evm",
      "chainId": 1,
      "tokenAddress": "0x…",
      "symbol": "XSGD",
      "decimals": 6,
      "pendingBalance": 0,
      "activeBalance": 133.65,
      "withholdBalance": 0
    }
  }
}

Response data fields

Quote fields (from … samePeg) match the estimate quote object.

Asset object (fromBalance / toBalance)

Same shape as List Assets:

walletId is omitted for per_app.

Example (before → after, cross peg)

Start: USDT activeBalance = 100, XSGD = 0. Convert 100 USDT → XSGD at effective rate 1.3365:

Errors (convert)

Same as estimate errors, plus:

Transfer Balance

Move off-chain activeBalance from your app to another app under the same client account (same Panel user). Both apps may be per_app or per_wallet; wallet fields apply when needed.

POST /api/v1/balances/transfer

Request body

{
  "destinationAppId": "4f83980c-c764-4b5d-9c0c-82e301ad6e45",
  "amount": 10,
  "token": "usdt-ethereum",
  "sourceWalletId": "5326036c-50c3-4d63-8150-69cb253542e3",
  "walletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response 200