x402 Buyer

x402 Buyer API

Base URL: https://ai.cryptoapis.io/x402/buyer. Authenticated with a Crypto APIs key that has the X402_BUYER feature. The buyer service manages an agent wallet and produces the payment payload your client signs locally — it never holds your key.

Wallet lifecycle

POST /wallets — register an agent wallet. Body: { blockchain, network (CAIP-2, e.g. "eip155:8453"), address } (or xpub for HD derivation on supported families). Returns { walletId, address, type }. The walletId is the buyer-service record id, not the chain address — pass this to /authorize and the SDKs.
GET /wallets — list your registered wallets (resolve a fresh walletId here rather than hard-coding one; the list is per-API-key).
GET /wallets/:id — fetch one wallet.
PATCH /wallets/:id — update limits (spending caps) and the allowedNetworks / allowedDomains allowlists.
GET /wallets/:id/history — payment history for the wallet.

Authorizing a payment

POST /authorize takes the merchant's PaymentRequirements and your walletId, checks wallet policy, and returns the exact payload to sign locally (EIP-712 TransferWithAuthorization on EVM; the family-appropriate transaction elsewhere). There is deliberately no /sign endpoint — signing happens on your side. A gated response carries an actionable reason (e.g. wallet_not_found, family_not_yet_supported, dependency_unavailable) rather than an opaque error.

Spending policy

A wallet carries optional perTxLimit / dailyLimit / monthlyLimit caps (atomic-unit strings; omit for no cap), settable at create or via PATCH. All three are enforced at /authorize. A wallet created with no limits receives conservative default safety caps so it is never unlimited by accident. The buyer budget is advisory; the facilitator remains the hard settlement gate.

Signing locally

Sign the /authorize payload with any standard EIP-712 tool (viem/ethers) or the Crypto APIs @cryptoapis-io/offline-signer, then retry the merchant call with the signed payment. The x402-buyer-sdk wraps register → authorize → sign → retry for you.

Was this page helpful?

Yes