AI agent checkout: from wallet authorization to x402 delivery
Updated 2026-11-20
An authorized AI agent can purchase an eligible automatic-fulfillment product by following six bounded steps: check service readiness, sign in with the payer wallet, create one idempotent order, validate the HTTP 402 terms, sign the exact BSC USDT payment, and poll that same order until delivery. Login proves wallet control but never grants permission to spend.
Before the agent starts
- Use a dedicated BSC wallet authorized by its owner, with only the necessary USDT and a small amount of BNB for any required token-approval gas.
- Configure an expected recipient and a strict per-order spending limit outside the model prompt.
- Read the current agent instructions, OpenAPI specification, and live catalog.
Step 1: check readiness and the live product
Request GET /api/health and require the payment readiness signal described in the API. Read GET /api/catalog, then the checkout options for the selected product. Never rely on a cached product ID, stock value, price, or option from an old answer.
Step 2: prove the payer identity
Request an authentication challenge for the wallet, sign the exact returned message with personal_sign, and exchange it for a short-lived session. Send the session in the Authorization header. The wallet that owns the session must also be the payer; a login message is not a token approval or payment signature.
Step 3: create exactly one order
Submit the product and option with a stable idempotency key. If the request times out, retry with the same key and identical body. Save the returned order ID. Creating a quote does not charge the wallet, but changing the key can create another order.
Step 4: validate the HTTP 402 requirement
The payment endpoint returns HTTP 402 and a PAYMENT-REQUIRED value. Compare its chain, USDT contract, recipient, amount, deadline, resource, and order binding against local policy. Stop if any field differs from the expected values or exceeds the owner-approved spending limit.
Step 5: sign and resubmit
On BSC, this integration uses Permit2 with a fresh nonce and an order-bound witness. If a token allowance is required, it is a separate on-chain transaction that uses BNB gas. Base64 encode the x402 v2 payload, place it in PAYMENT-SIGNATURE, and retry the same payment endpoint with the same authenticated wallet.
Step 6: wait for delivery without paying twice
Settlement and fulfillment are separate. Poll the original order no more frequently than the documented interval. States such as payment confirmation, processing, review, or attention required are not instructions to create a replacement charge. Retrieve delivery only after the order says delivered.
Operational safety rules
- Keep private keys inside the wallet environment; never include them in prompts, logs, URLs, or support messages.
- Do not log bearer sessions, recovery credentials, payment signatures, or delivered content.
- Reject cross-order signature reuse and keep the original order ID for reconciliation.
- After a restart or session expiry, sign in again with the same wallet to recover its orders.
For payment-field details, continue with the English x402 guide. The JavaScript example is available at agent-client.mjs.
Frequently asked questions
Does an agent need the owner’s main-wallet private key?
No. Use a dedicated, owner-authorized wallet with a limited balance and spending policy. The private key stays inside the wallet environment.
Can a timed-out create-order request be retried?
Yes, but only with the same idempotency key and identical request body. This allows the server to return the original order instead of creating another one.
Should the agent pay again when fulfillment is slow?
No. Payment and fulfillment are separate. Check the original order and preserve its ID; do not create a replacement charge while it is confirming or processing.
Can a different wallet submit the payment?
No. The authenticated order owner and the payment signer must be the same authorized wallet in this flow.