For AI agents · x402 buyers

AI agent gift cards over x402

An AI agent can buy a real gift card with USDC over x402. It requests a card URL, pays a small quote fee to lock the exact price, then pays the order to a per-order contract on Base. About five minutes later the card is in its owner’s SpendTheBits app, in the owner’s name. The owner sets the limits, can be asked first, and keeps the code unless they choose to share it.

The card URL

Every card is an x402 resource

No catalogue call and no SpendTheBits-specific lookup: the URL names the card. The free storefront above it lists countries, brands and amounts as JSON for agents and as a page for people. A payable URL never redirects, with or without its trailing slash.

https://x402.spendthebits.com/@stb/cards/                       countries (free)
https://x402.spendthebits.com/@stb/cards/usa/?q=amazon          brands + amount URLs (free)
https://x402.spendthebits.com/@stb/cards/usa/amazon-com/25/     the card: 402 = quote fee

GET  /@stb/cards/usa/amazon-com/25/           → 402  quote fee; body.card.indicative_total_usd
     PAYMENT-SIGNATURE: <signed>              → 201  { order_id, total_usdc, pay_url, status_url, claim_token }
POST <pay_url>   PAYMENT-SIGNATURE: <signed>  → 200  paid to the order's forwarder contract
GET  <status_url>   X-Claim-Token: <token>    → awaiting_payment → processing → completed

How an agent buys a card

1.Register the agent's key in the SpendTheBits app and switch gift cards on for it.
Agents → create an agent (its key is made on the phone, never from your recovery phrase) → Gift cards: per-card limit, monthly limit, optional brand list, Ask me first. Fund it with only what it may spend.
2.GET the card URL. The unpaid 402 is the quote fee, and its body carries the card's indicative total.
Nothing is created at the card provider by an unpaid request, so browsing and pricing are free.
3.Pay the quote fee with any stock x402 client.
The paid response is the exact quote: total, pay link, status link, pay-by time and a claim token.
4.Pay the order before the pay-by time.
One 'exact' USDC payment on Base to the order's own forwarder contract. Raise your client's per-payment cap above the total first.
5.Poll the status link with the claim token until the order reads completed.
About five minutes. The card appears in the owner's orders, tagged with the agent's name.

Limits, approvals and codes

What an agent can buy: Real gift cards from the SpendTheBits store: Amazon, Starbucks, Tim Hortons and hundreds more, redeemable in the USA and Canada. Fixed-value cards come in their listed amounts; variable cards take any amount between their bounds.
Who the card is for: Always the agent's owner, in the owner's name, in the owner's app. An agent cannot put a different name on a card; one that tries is refused.
Who can buy: A key registered under Agents in the owner's app, with gift cards switched on for it. Any other key is refused at verification, before any payment settles.
Owner limits: A per-card limit, a monthly limit and an optional brand list, set per agent in the app. The store also caps every agent order per card; the storefront publishes the live value as max_card_usd.
Ask first: With Ask me first on (the default), an over-limit or unlisted-brand request becomes a question on the owner's phone instead of a refusal. The agent reads awaiting_owner and must not pay; the owner approves with Face ID and pays it, or declines.
Card codes: Hidden from the agent by default. The status link never carries a code. If the owner allows codes for one agent, a separate reveal link serves each code once and never again.
The money: Paid to a per-order contract whose terms are fixed in its address: forward to the card provider before the deadline, pay the quoted service fee, or refund the payer. Past the deadline it refunds in full. SpendTheBits never holds it.
Price: The provider's price plus a small service fee, all in the quote before you pay. The provider's spread is a larger share of a small card, so compare the total with the face value.

Referrals: add ?ref=@handle to a card URL. The referrer’s share of the service fee goes to an ownerless, immutable split contract, which pays it out on-chain once about $0.50 has built up or 24 hours have passed, whichever comes first. Gifting a card to another @handle is built but not live; the store refuses a recipient today.

Proof, not a mock-up

A real purchase on mainnet, 20 September 2026

An unmodified @x402/fetch client with an agent key from the owner’s Agents screen bought a $10 Amazon.com card. About 4.5 minutes from the first payment to a completed card, and the agent never saw the code. Every step below is a public transaction on Base (times UTC).

Time	Step	Transaction
19:04:01	Quote fee paid (a few cents)	0x265b368e…2254
19:04:03	Order paid: 11.224455 USDC to the per-order forwarder	0x5494ea30…05de
19:04:15	Forwarder deployed = forwarded: USDC burned through Circle CCTP to the card provider	0xd5aecb29…1b89
~19:05	Minted on Ethereum to the provider's deposit address, about 50 s after payment	—
19:08:28	Card issued: completed, in the owner's app	—

The forwarder, 0x9f27…F4b1, did not exist when the agent paid it. Its address was computed from its terms; deploying it was the forward. Read the press release and the full write-up.

Examples and the MCP server

Runnable examples

buy-gift-card.mjs prices and buys a card with the stock client and polls the status link without ever printing a code; gift-card-status.mjs reads an order with its claim token. Both set the client’s per-payment cap on purpose.

x402-handle-examples on GitHub

MCP server (in testing)

A first-party MCP server gives an assistant six tools: search, price, quote, buy, order status and a one-time code reveal. It pays with the same stock x402 client, keeps the claim token out of the model’s context and holds its own spending cap. It is built and tested, not published yet.

Owner setup, step by step with screenshots: how to let your AI agent buy a gift card. Selling rather than buying? Get paid by AI agents.

Questions & answers

Agent gift cards: common questions

Can an AI agent buy a gift card with USDC?

Yes. Every card in the SpendTheBits store is an x402 resource at x402.spendthebits.com/@stb/cards/<country>/<brand>/<amount>/. A stock x402 client pays a small quote fee to lock the exact price, then pays the order in USDC on Base to a per-order contract. The card is issued to the agent's owner and appears in their SpendTheBits app about five minutes later.

Does the agent see the gift card code?

Not by default. The status link never includes a code. An owner can allow codes for one agent; then a separate reveal link serves each code exactly once.

What happens when the agent asks for a card above the owner's limit?

With Ask me first on, the owner gets a notification naming the agent, brand, amount and total, and approves or declines with one tap. The agent's status reads awaiting_owner and it must not pay. With Ask me first off, the request is refused before anything is charged.

Why does my x402 client refuse to pay for the card?

Stock clients cap each payment at about one dollar by default. Raise the cap above the card's total, for example spendControls.maxAmountPerPayment in @x402/fetch. The card URL's 402 body carries a spend_controls_hint with the number to use.

Who holds the money while the card is being issued?

Nobody. The order is paid to a per-order forwarder contract with no owner. It can only forward the USDC to the card provider before the deadline, pay the quoted service fee, or refund the payer.

Is there an MCP server for gift cards?

A first-party MCP server with search, price, quote, buy and status tools is built and in testing. It is not published yet. Until it is, any stock x402 client works, and runnable examples are on GitHub.