Onboarding

This guide walks through using the gateway as a client: add credit with USDC (x402), create an API key (SIWE), then call the chat completion API.

What You Need

• A wallet private key for signing (testnet for staging gateways)
• USDC on the chain the gateway expects (often Base Sepolia for staging)
• The gateway base URL (HTTPS origin, no path). The hosted gateway is https://agent-router.gaib.cloud
• Node.js if you use the official example script

Base Sepolia Test USDC

For https://agent-router.gaib.cloud (staging), payments use Base Sepolia with this test USDC token:

0xB5080336118e55bc5D5Cf5f37771dB5C392FC48D

The contract exposes a mint function that anyone can call on testnet, so you can obtain spendable balance without a faucet. The staging script can mint for you when SKIP_MINT is not set.

WARNING

This is a testnet-only asset with no real value. Production gateways use real USDC on another network. Always use the accepts payload from a 402 response as the source of truth for asset, network, and amounts.

End-to-End Flow

Step	What Happens
1. Top up	POST /v1/topup with { "amount": <usd> }. The server responds with 402 and payment instructions. Sign and complete payment per x402, then retry.
2. API key	POST /v1/auth/keys with a SIWE message and signature. Response includes a secret API key (store it safely).
3. Inference	POST /v1/chat/completions with Authorization: Bearer <api_key> and a chat-style JSON body.

Model IDs are provider-qualified: openrouter/..., gemini/..., kimi/..., minimax/..., or local/....

Example Automation Script

The repo includes a TypeScript script that runs all three steps:

set -a && source .env && set +a && \
GATEWAY_URL=https://agent-router.gaib.cloud \
SKIP_MINT=1 \
npx tsx scripts/stg-topup-and-inference.ts

Environment Variables

Variable	Purpose
TEST_PK	Required. Hex-encoded private key for the wallet.
GATEWAY_URL	Base URL of the gateway.
SKIP_MINT	Set to 1 to skip testnet USDC minting.
TOPUP_AMOUNT_USD	Top-up amount in USD (minimum 1).
MODEL	Chat model id (default: a gemini/... model).
X402_CLIENT_NETWORK	CAIP-2 network for payment (e.g. eip155:84532).

SIWE Message Alignment

The SIWE message must match what the server verifies:

• domain -- hostname of the gateway (e.g. agent-router.gaib.cloud)
• uri -- the auth endpoint (e.g. https://agent-router.gaib.cloud/v1/auth/keys)
• chainId -- must match the gateway's chain

If key creation fails with 4xx, confirm you're using the same public HTTPS host the gateway presents.

After Onboarding

Inference requests are billed against your wallet balance. Send chat completion requests with your Bearer token until limits or balance apply.