Checkout Options

POST /api/v1/pay/checkout-options

Aggregation endpoint — returns all available payment options at once after the user connects their wallet. Combines tokens + balances + batch-quote so the frontend can render directly.

Flow

Concurrently query balances across all chains
Find tokens with balance > 0
Concurrently fetch quotes for those tokens
Determine if balance is sufficient, sort results (sufficient first, direct first, fastest settlement first)

Request

{
  "wallets": {
    "base": "0xAbc123...",
    "eth": "0xAbc123...",
    "arb": "0xAbc123...",
    "ton": "UQBxxx..."
  },
  "settle_chain": "eip155:8453",
  "settle_token": "USDC",
  "settle_amount": "10000000"
}

Field	Type	Description
`wallets`	`Record<string, string>`	Wallet addresses per chain (blockchain → address)
`settle_chain`	`string`	Settlement chain (CAIP-2 format, e.g. `eip155:8453`)
`settle_token`	`string`	Settlement token (e.g. `USDC`)
`settle_amount`	`string`	Settlement amount (smallest unit, USDC 6 decimals = 10 USDC → `10000000`)

Response

{
  "settle_chain": "eip155:8453",
  "settle_token": "USDC",
  "settle_amount": "10000000",
  "options": [
    {
      "blockchain": "base",
      "token": "USDC",
      "chain_name": "Base",
      "is_direct": true,
      "balance": "25.5",
      "balance_usd": "25.50",
      "pay_amount": "10000000",
      "pay_amount_formatted": null,
      "pay_amount_usd": null,
      "sufficient": true,
      "estimated_time": 5,
      "method": "Direct",
      "logo": "https://...",
      "chain_logo": "https://...",
      "error": null,
      "min_amount_usd": null
    },
    {
      "blockchain": "eth",
      "token": "ETH",
      "chain_name": "Ethereum",
      "is_direct": false,
      "balance": "0.5",
      "balance_usd": "1250.00",
      "pay_amount": "4200000000000000",
      "pay_amount_formatted": "0.0042",
      "pay_amount_usd": "10.50",
      "sufficient": true,
      "estimated_time": 120,
      "method": "CrossChain",
      "logo": "https://...",
      "chain_logo": "https://...",
      "error": null,
      "min_amount_usd": 5.0
    }
  ]
}

CheckoutOption Fields

Field	Type	Description
`blockchain`	`string`	Chain identifier
`token`	`string`	Token symbol
`is_direct`	`bool`	Whether it is a direct chain (same-chain transfer)
`balance`	`string`	User balance (formatted)
`balance_usd`	`string?`	Balance USD valuation
`pay_amount`	`string?`	Amount to pay (smallest unit)
`pay_amount_formatted`	`string?`	Amount to pay (human-readable, available for cross-chain)
`sufficient`	`bool`	Whether the balance is sufficient
`estimated_time`	`u32?`	Estimated settlement time in seconds
`method`	`"Direct" \| "CrossChain"`	Payment method
`error`	`string?`	Quote failure reason
`min_amount_usd`	`f64?`	Minimum amount for this route (USD)