Wallet Balances

POST /api/v1/pay/balances

Query user multi-chain wallet balances — after the user connects their wallet, the frontend sends addresses for each chain, and the backend concurrently queries and returns balances. Used by the checkout page to determine which tokens have sufficient balance.

Each chain has a 5-second timeout and won't block others.

Request

{
  "wallets": {
    "base": "0xAbc123...",
    "eth": "0xAbc123...",
    "arb": "0xAbc123...",
    "ton": "UQBxxx...",
    "solana": "5xYzW..."
  }
}

Field	Type	Description
`wallets`	`Record<string, string>`	Wallet addresses per chain (blockchain → address)

Response

{
  "balances": [
    {
      "blockchain": "base",
      "address": "0xAbc123...",
      "tokens": [
        {
          "symbol": "USDC",
          "decimals": 6,
          "balance": "25500000",
          "balance_formatted": "25.5",
          "balance_usd": "25.50",
          "price_usd": 1.0
        },
        {
          "symbol": "ETH",
          "decimals": 18,
          "balance": "50000000000000000",
          "balance_formatted": "0.05",
          "balance_usd": "125.00",
          "price_usd": 2500.0
        }
      ]
    },
    {
      "blockchain": "ton",
      "address": "UQBxxx...",
      "tokens": [
        {
          "symbol": "TON",
          "decimals": 9,
          "balance": "5000000000",
          "balance_formatted": "5.0",
          "balance_usd": "15.00",
          "price_usd": 3.0
        }
      ]
    }
  ]
}

Field	Type	Description
`balance`	`string`	Raw balance (smallest unit)
`balance_formatted`	`string`	Formatted balance (human-readable)
`balance_usd`	`string?`	USD valuation
`price_usd`	`f64?`	Token unit price

Chains that fail to query or time out are skipped.