Top up (x402)
Fund your balance with USDC or USDT using the x402 payment protocol.
Top-up uses the x402 protocol. You pay a stablecoin on-chain, and the gateway credits your balance after verifying the payment. USDC (ERC-3009) and USDT (Permit2) are accepted on Base and Arbitrum.
It's a two-step flow: the first request returns payment requirements, the second carries the signed payment.
Step 1 — Discover payment requirements
curl -X POST https://agent-router.gaib.ai/v1/topup \
-H "Content-Type: application/json" \
-d '{"amount": 5}'The server responds with HTTP 402 and an accepts array describing how to pay:
{
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"maxAmountRequired": "5000000",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0x...",
"extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" }
}
]
}Always use the accepts array from the live 402 response as the source of truth — the offered assets, networks, and transfer methods can vary by deployment.
Step 2 — Sign and resend
Sign the payment and resend with the X-Payment header. The easiest way is the @x402/fetch interceptor:
import { withPaymentInterceptor } from '@x402/fetch'
const fetchWithPayment = withPaymentInterceptor(fetch, walletClient)
const res = await fetchWithPayment('https://agent-router.gaib.ai/v1/topup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: 5 }),
})
const { balance_usdc, credited_usdc } = await res.json()
// balance_usdc: total balance in micro-USDC| Field | Type | Description |
|---|---|---|
amount | number | USD amount, minimum $1 |
See the full Top Up API reference for response fields.