x402 · agentic payments
x402 payments: get paid by AI agents
The next customers of your API won’t have a credit card. They’ll have a wallet. Your SpendTheBits @handle is an x402-payable endpoint: AI agents pay you in USDC over plain HTTP — no invoices, no accounts, no custodian. Price a resource once; get paid every time a machine wants it.
How a payment happens
One HTTP round trip, one on-chain settlement
The agent asks, you quote
An agent requests your resource and receives HTTP 402 Payment Required with a machine-readable price: amount, asset (USDC), and where to pay — your @handle's endpoint.
The agent signs, gas-free
It signs an EIP-3009 USDC transfer authorization off-chain — no gas token needed — and retries the same request with the payment attached.
Verified, served, settled
The payment verifies and settles on-chain to addresses only your keys control. The agent gets the resource; you got paid, machine-to-machine, with no invoice and no custodian.
GET /@stbclaudeprod/proof/ HTTP/1.1
Host: x402.spendthebits.com
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 JSON>
{ "x402Version": 2, "accepts": [
{ "scheme": "exact", "network": "eip155:8453", "amount": "10000",
"asset": "0x8335…2913" /* USDC on Base */, "payTo": "0xBe5c…9D30" },
{ "scheme": "exact", "network": "eip155:137", … }, /* Polygon */
{ "scheme": "exact", "network": "eip155:42161", … }, /* Arbitrum */
{ "scheme": "exact", "network": "solana:5eyk…vdp", … } /* Solana */ ] }
GET /@stbclaudeprod/proof/ HTTP/1.1
Host: x402.spendthebits.com
PAYMENT-SIGNATURE: <base64 JSON: accepted + signed EIP-3009 authorization>
HTTP/1.1 200 OK — 1.4 s after the first request
PAYMENT-RESPONSE: { "success": true, "network": "eip155:8453",
"transaction": "0x71f4c1dc…f10b3" } — 0.01 USDC settled on Base, 2 Sep 2026For client developers
Pay a handle with a stock x402 client
A regular x402 client can pay any SpendTheBits handle, and it needs no lookup first. A handle URL is a standard x402 resource: the unpaid request returns the price, token, network and seller address, the client signs a USDC authorization, and the retry returns the resource with a settlement receipt. We ran the stock @x402/fetch and Python x402 clients against a live handle, and neither needed a line of SpendTheBits-specific code.
TypeScript
npm install @x402/fetch @x402/evm viemimport { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.BUYER_KEY);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
// the network you hold USDC on — eip155:8453 is Base
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});
const res = await pay("https://x402.spendthebits.com/@stbclaudeprod/proof/");
console.log(res.status, await res.text());
console.log(decodePaymentResponseHeader(res.headers.get("PAYMENT-RESPONSE")));Python
pip install "x402[evm,requests]"import os
from eth_account import Account
from x402.client import x402ClientSync
from x402.http.clients.requests import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
client = x402ClientSync()
signer = EthAccountSigner(Account.from_key(os.environ["BUYER_KEY"]))
register_exact_evm_client(client, signer, networks="eip155:8453") # Base
r = x402_requests(client).get("https://x402.spendthebits.com/@stbclaudeprod/proof/")
print(r.status_code, r.text, r.headers.get("PAYMENT-RESPONSE"))curl (read the quote)
no wallet neededcurl -s -D - -o /dev/null https://x402.spendthebits.com/@stbclaudeprod/proof/ \
| awk 'tolower($1)=="payment-required:" {print $2}' | tr -d '\r' | base64 -d- Lookup or API key
- None. The 402 carries everything a client needs.
- Gas
- None. The payment is a signed EIP-3009 authorization.
- Network
- Register the one you hold USDC on. A handle quotes several and a stock client signs the first it supports.
- Browsers
- Supported. The endpoints send CORS headers and expose the payment headers.
For buying agents
Buy a gift card over x402
Every gift card in the SpendTheBits store is an x402 resource. An agent that holds USDC on Base can buy a real Amazon, Tim Hortons or Starbucks card with a stock x402 client, and the card lands in its owner’s app, in the owner’s name. The money goes from the agent to a per-order contract that can only forward it to the card provider or refund the agent. We never hold it.
https://x402.spendthebits.com/@stb/cards/<country>/<brand>/<amount>/
usa amazon-com 25
GET /@stb/cards/usa/amazon-com/25/ → 402 quote fee (a few cents)
PAYMENT-SIGNATURE: <signed> → 201 { order_id, total_usdc, pay_url, status_url, claim_token }
POST <pay_url> PAYMENT-SIGNATURE: <signed> → 200 the order, paid to its forwarder contract
GET <status_url> X-Claim-Token: <token> → awaiting_payment → processing → completed (about 5 minutes)Lock the price
Request the card URL. The 402 quotes a small fee; paying it creates the order at the provider's exact price and returns the total, a pay link, a status link and a claim token. The total includes the card, a small service fee and the bridge fee ceiling.
Pay the order
Pay the total to the order's forwarder contract on Base. Its terms are fixed in its address: forward to the card provider before the deadline, pay the quoted fee, or refund the agent. A second payment is refunded, never burned.
Poll, then it is in the app
Poll the status link with the claim token. The USDC is bridged to the provider in about a minute and the card is issued a few minutes later. It appears in the owner's orders, tagged with the agent's name, code behind the device unlock.
- Who can buy
- Any agent key registered under Agent budgets in the app, with gift cards switched on by its owner. An unknown key is refused before any payment.
- Limits
- The owner sets a per-card and a monthly limit. Over a limit, the store asks the owner instead: one tap on the phone approves it. The store itself caps agent orders per card.
- Client cap
- Stock clients refuse payments above about a dollar by default. Set your client's per-payment cap above the card's total, e.g. spendControls: { maxAmountPerPayment: "$30" } in @x402/fetch.
- Referrals
- Add ?ref=@handle to the card URL. The referrer's share of the service fee goes to an ownerless, immutable split contract on Base, which pays it out on-chain once about $0.50 has built up there, or 24 hours after the oldest unpaid share, whichever comes first. It is not paid in the purchase transaction itself.
- Card codes
- Never in the HTTP response by default. If the owner allows it for one agent, the code is served once, from a separate reveal link, and never again.
- Gifting
- Coming: a card sent to another SpendTheBits @handle, issued in the recipient's name. Not live yet; the store refuses a recipient today.
Built in the open
Proven on Circle’s Arc
We built and demonstrated these agentic payment flows on Arc, Circle’s stablecoin-native blockchain, as part of Circle’s developer program — end to end, from the 402 challenge to on-chain USDC settlement.
Read the Arc build write-up (PDF)Why an @handle beats an API key
An API key gates access; an @handle gets you paid. It’s human-readable, it resolves to addresses your device derived, it doubles as a Lightning address for Bitcoin — and every payment to it is final, on-chain, and yours.
Further reading
Insights on agent payments
- x402 on Arc: agent payments with final settlement
Discover how x402 on Arc enables automated software tools to settle payments in real time with absolute finality and low costs.
- AI agent payments in production: an agent bought a gift card over x402, with no custodian
How AI agent payments work without a custodian: an agent bought a real gift card over x402, paid in USDC, through a contract that only forwards or refunds.
- What is x402? The x402 protocol for AI agent payments
Discover the x402 protocol, an open standard built on HTTP 402 that enables seamless, account-free payments for software and autonomous AI agents.
- x402 Payments in Production: What It Costs to Get Paid by an AI Agent
x402 payments measured in production: 1.4 s from HTTP 402 to settled USDC on Base, who pays gas, what the facilitator charges, and how replays are refused.
- How to monetize an API with x402 without custody
Learn how to monetize an API natively using the open-source x402 protocol, stateless HTTP headers, and non-custodial wallets.
- EIP-3009 transferWithAuthorization explained
Learn how EIP-3009 transferWithAuthorization enables gasless stablecoin payments with random nonces and why the x402 standard uses it.
Questions & answers
Agent payments: common questions
What is the x402 protocol?+
x402 is an open payment protocol built on HTTP's 402 Payment Required status code. A server quotes a price in a machine-readable header; the client — typically an AI agent — signs a stablecoin payment authorization and retries the request with it attached. Once the payment verifies, the resource is served. It turns any URL into something an agent can pay.
Can AI agents pay me on SpendTheBits?+
Yes. Your @handle doubles as a public x402-payable endpoint. You attach a USDC price to a resource — an API route, a dataset, a report — and any x402-capable agent can pay it and get the resource in one round trip, with settlement verified on-chain.
Can a regular x402 client pay a SpendTheBits handle?+
Yes, and no lookup is needed first. A handle URL is a standard x402 resource: an unpaid request answers 402 Payment Required with the price, the token, the network and the seller's address as one x402 v2 quote in the standard PAYMENT-REQUIRED header, repeated identically in the body. Stock clients such as @x402/fetch and the Python x402 package read that quote, sign and retry with no SpendTheBits-specific code. Runnable examples are on GitHub at github.com/jkambo1986-collab/x402-handle-examples.
Do agents pay gas fees when they pay me?+
No. Payments use EIP-3009 transfer authorizations: the agent signs an off-chain authorization and the settlement layer submits it, so the paying agent needs USDC but not native gas tokens.
What is USDC on Arc?+
Arc is Circle's purpose-built blockchain for stablecoin finance, where USDC acts as the native asset. SpendTheBits built and demonstrated x402 payment flows on Arc during Circle's developer program — see our hackathon write-up linked on this page.
Can an AI agent buy a gift card over x402?+
Yes. Every gift card in the SpendTheBits store is an x402 resource with a URL of the form x402.spendthebits.com/@stb/cards/<country>/<brand>/<amount>/. The agent pays a small quote fee to lock the provider's exact price, then pays the order to a per-order contract that can only forward the money to the card provider or refund the agent. The card is issued in the agent owner's name and appears in their SpendTheBits orders; the agent never receives the card code unless the owner allows it.
Does SpendTheBits hold the money agents pay me?+
Never. Settlements pay on-chain addresses that only your device's keys control — the same fully non-custodial model as the rest of the app. A small service fee, under 1%, applies on settled payments and is disclosed up front.
Claim your @handle before the agents come knocking.