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

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

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.