The x402 guide for AI agents (and the humans configuring them)
Everything an agent needs to pay for an API on its own: what x402 is, why the wallet-per-service model breaks down, the three ways to pay, and a copy-paste walkthrough. {{ t_services }} services graded · {{ t_callable }} callable through the gateway · re-probed every 6 hours.
What x402 is, in two sentences
x402 is an open payment protocol that lets a client pay for a single HTTP request with USDC instead of signing up for an account and managing an API key — the server answers an unpaid request with HTTP 402 Payment Required and a machine-readable price, the client pays, and the same request succeeds. It is backed by the Linux Foundation with Visa, Stripe, Google, and AWS involved, and the catalog of services that speak it is growing fast.
The wallet problem
x402 solves the signup problem but hands you a new one. To pay services directly, your agent needs a funded crypto wallet, has to sign a payment for every call, and only reaches services whose challenge matches the exact x402 wire dialect its client library speaks. There are two dialects in the wild (an older v1 and a newer v2), and the official v2 client refuses v1 challenges outright — so a service your agent technically has money for can still be uncallable. Multiply that by a catalog of services, each with its own price, quirks, and failure modes, and "let the agent pay for things" turns into wallet plumbing.
Graded exists to remove that plumbing. It is a quality index — every discoverable x402 service is probed every six hours and graded A–F on whether an agent can actually pay it and parse the result — and a gateway: one endpoint, one prepaid balance, and the gateway fronts each upstream payment in whichever dialect the service speaks.
Three ways to pay
Pick based on whether you want to run a wallet at all.
1 · Your own wallet, direct
Keep a funded USDC-on-Base wallet and pay each service directly with an x402 client. Maximum control, no middleman markup — but you carry the wallet, sign every call, handle both wire dialects yourself, and get no quality signal before you spend. Good if you already run wallet infrastructure and call a small, known set of services.
2 · Gateway credits, funded with USDC
Create a gateway account, pay 0.10 USDC per pack (on Base) to the x402-gated top-up route, and it credits your balance 1:1. Your agent then calls any passing service through one endpoint; the gateway fronts the upstream payment in both dialects and meters your credits. One balance instead of a wallet per API — but you still hold USDC.
3 · Gateway credits, funded with a card
Same balance, no crypto at all. Top up by credit card through Stripe Checkout in packs of $5, $10, or $20, credited 1:1. This is the path for an agent whose operator has a card but no wallet — and the card's email doubles as a key-recovery handle. Card top-ups are live.
Agent self-onboarding, step by step
An agent can complete every step below on its own — account creation needs no email and no human. Replace gwk_YOUR_KEY with the key you get in step 1 and SERVICE_ID with an id from the catalog.
Connect over MCP
The gateway is a live MCP server at https://graded.sh/mcp. Drop this into your MCP client config and the agent gets tools to list, inspect, and call services:
MCP config
{{ codeMcp }}
1. Create an account
Free, no email. The response contains your secret gwk_ key — it is shown once, so store it.
{{ codeCreate }}
2. Discover the graded catalog
Listing, filtering, and full service detail are free and need no key. Filter by grade and to only services callable through the gateway:
{{ codeList }}
3. Top up your balance
Fund with USDC over the x402 top-up (any x402 v2 client works), or with a card — no wallet required:
{{ codeTopup }}
4. Call any passing service
The gateway pays the upstream x402 price from its own wallet and deducts your prepaid credits. A failed call is refunded automatically.
{{ codeCall }}
Check your balance and history
{{ codeAccount }}
FAQ, honestly
What does it cost to call a service?
The upstream service's own x402 price plus a 25% markup, with a $0.005 floor per successful call. That markup is the whole business model. Discovery — listing, search, grades, service detail — is free and needs no account.
What happens if a call fails?
You are only charged for successful calls. If the upstream call fails or returns free, the charge is refunded to your balance automatically. The gateway carries the risk of a payment that settles upstream but fails to return.
Do I need a crypto wallet?
No. Fund with a card through Stripe ($5 / $10 / $20 packs) and never touch crypto, or top up with USDC on Base (0.10 per pack) if you prefer. Either way the agent holds one balance instead of a wallet per API.
Is my key recoverable if I lose it?
The gwk_ key is shown exactly once — store it. If you top up by card, Stripe collects your email and it is attached to the account as a recovery handle. Without a stored key and without a card-attached email, the account cannot be recovered.
Which services can I call through the gateway?
Any service graded D or better whose challenge states a parseable Base-USDC price at or under $0.25 per call — the gateway's per-call ceiling. Higher-priced or broken services stay listed and graded, just not callable through us. See the methodology for the full rubric.
Ready to wire it up? Create an account, browse the graded index, or read who runs this. Machine clients can read the raw catalog at /v1/services and the payment contract at /.well-known/x402.