x402 autonomous top-up

x402 top-up is the programmatic version of the crypto wallet flow: the same order machinery, but driven by code instead of a browser dialog. This page is the human-readable overview; the full protocol reference (endpoints, challenge schema, error codes) lives in x402 protocol.

The four calls

1. Create an order — authenticated with your API key (or an agent key):

curl -X POST https://linkex.ai/api/user/topup/x402/orders \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 5}'

The response contains an x402 v2 challenge: network, token contract, atomic amount, recipient (payTo), and a 10-minute expiry.

2. Sign it with any x402 v2-capable wallet:

   • Binance Agentic Wallet (baw x402-payment preview / sign)
   • @linkexai/agent-sdk (buildX402PaymentPayload for EVM, buildSvmPaymentPayload for Solana)
   • Coinbase x402 tooling, or your own EIP-3009 / Permit2 / Solana signer

3. Submit the signed payload — note this endpoint is public; the signature itself is the authorization:

curl -X POST https://linkex.ai/api/x402/pay/ORDER_ID \
  -H "Content-Type: application/json" \
  -d @signed-payload.json

4. Confirm — the response reports settled (credited now) or credit_pending (credited after on-chain confirmation). Verify with:

curl https://linkex.ai/api/user/self/balance \
  -H "Authorization: Bearer sk-YOUR_KEY"

Why use an agent key for this

Creating orders with a plain account key works, but an agent key adds guardrails: the order is bound to the agent wallet, and per-call / daily / total spend caps are enforced at settlement time (SPEND_CAP_EXCEEDED). That means a runaway agent cannot drain the funding wallet beyond the caps you set. See Agent credentials.

Keeping an agent funded

• Semi-automatic (browser): the console's Keep Funded page polls the balance and prompts you to sign a top-up when it drops below a threshold.
• Fully autonomous: run the funding loop in your own runtime with @linkexai/agent-sdk, or the linkex/funder Docker image — poll GET /api/user/self/balance, create an order when low, sign, submit.