Balances

Query wallet balances in real-time to display accurate fund information to your users.

For real-time balance change notifications, use Webhooks.

Get Wallet Balance

Retrieve the current balance for a specific wallet.

Quick Example

Response:

{
  "walletId": "wal_abc123",
  "network": "polygon",
  "balances": [
    {
      "currency": "USDC",
      "amount": "1250.50",
      "decimals": 6
    },
    {
      "currency": "USDT",
      "amount": "0.00",
      "decimals": 6
    }
  ],
  "lastUpdated": "2024-01-15T10:30:00Z"
}

Request Parameters

Parameter	Type	Required	Description
`walletId`	string	Yes	Wallet ID in the URL path (e.g., `wal_abc123`)

Response Fields

Field	Type	Description
`walletId`	string	Unique wallet identifier
`network`	string	Network the wallet is on (e.g., `polygon`, `ethereum`)
`balances[]`	array	Array of token balances in the wallet
`balances[].currency`	string	Currency/token symbol (e.g., `USDC`, `USDT`)
`balances[].amount`	string	Balance amount (decimal string)
`balances[].decimals`	number	Token decimals (e.g., 6 for USDC)
`lastUpdated`	string	ISO timestamp of last balance update

Get Customer Balances

Retrieve all wallet balances for a customer across all networks.

Quick Example

Response:

{
  "customerId": "cus_abc123",
  "totalBalance": {
    "amount": "2500.75",
    "currency": "USD"
  },
  "wallets": [
    {
      "walletId": "wal_poly_001",
      "network": "polygon",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "balances": [
        {
          "currency": "USDC",
          "amount": "1250.50"
        }
      ]
    },
    {
      "walletId": "wal_eth_002",
      "network": "ethereum",
      "address": "0x9876543210987654321098765432109876543210",
      "balances": [
        {
          "currency": "USDC",
          "amount": "1250.25"
        }
      ]
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
`customerId`	string	Yes	Customer ID in the URL path (e.g., `cus_abc123`)

Response Fields

Field	Type	Description
`customerId`	string	Customer ID from the request
`totalBalance`	object	Total balance across all wallets (converted to base currency)
`totalBalance.amount`	string	Total balance amount
`totalBalance.currency`	string	Base currency (e.g., `USD`)
`wallets[]`	array	Array of wallets owned by the customer
`wallets[].walletId`	string	Unique wallet identifier
`wallets[].network`	string	Network the wallet is on
`wallets[].address`	string	Wallet address on the network
`wallets[].balances[]`	array	Token balances in this wallet
`wallets[].balances[].currency`	string	Currency/token symbol
`wallets[].balances[].amount`	string	Balance amount

Language Examples

Best Practices

Balance Consistency: Balances may have a slight delay (a few seconds) after transactions complete due to blockchain confirmation times.

Caching: Balance queries can be cached for short periods (30-60 seconds) to reduce API calls. Use webhooks for real-time updates.

Balances

Balances

Get Wallet Balance

Quick Example

Request Parameters

Response Fields

Get Customer Balances

Quick Example

Request Parameters

Response Fields

Language Examples

Best Practices

See Also

On this page