MCP tools#

JSON-RPC 2.0 over streamable HTTP at https://api.checkout402.com/mcp.

Authorization: Bearer c402_live_...

tools/list needs no auth — a host can see what's on offer before anyone connects. Everything that touches your account does.

Setup for Claude specifically: Connect Claude.

Seller tools#

create_checkout#

The one that matters. Same object as POST /v1/checkouts.

Returns the checkout including its url — the thing to share.

Mode is not an argument. With a c402_ key the key decides. Over an OAuth connection (Claude, and anything else without a key) it creates an unarmed checkout — every face rehearses, so an agent working through a repo can mint a dozen without any of them arriving able to take real money. go_live is the one deliberate step that arms one, and an agent should ask before calling it.

The result carries url and test_url — the same id with /test appended. The test face settles simulated forever, armed or not.

max_deliveries is still accepted as an old name for calls, but the schema no longer advertises it: two names for one number is a question with only one right answer.

reusable is not advertised either, and defaults to true. A checkout an agent creates is a published product — an API, a tool, a payload — and a product is not spent by its first buyer. One-shot is the invoice case: still reachable by passing reusable: false, but not a question worth stopping a create for, and not the axis a seller means when they say "single". That axis is calls — one call, or a package of them.

go_live#

Arm an unarmed checkout for real money. Takes checkout_id.

Arms in place — same id, same URL. Nothing new is minted: the link already shared is the one that now takes real payments. The URL in a script, a README or a colleague's terminal is safe for a different reason than before — the rehearsal address is the same checkout's /test face, which can never be armed, and the response says so: it returns the checkout (same id) plus a rehearsal block naming where rehearsals continue.

Idempotent: calling it twice returns the same checkout, unchanged the second time.

get_content · update_content#

The mini CMS, for agents. get_content returns a gated article as the seller wrote it — paid body, teaser, the whole declaration (owner only). update_content edits it in place: payload is the article text, content replaces the whole declaration, so read first, change one field, send it all back. Same id, same URL; edits are live for the next read, including readers already holding passes. An ordinary checkout's payload is refused — goods a buyer was quoted stay frozen.

Fix the typo in the second paragraph of my latest article and tighten the teaser.

get_content_snippet#

The block the seller pastes where the paid body used to be: the free teaser, Google's paywalled-content JSON-LD, and a plain link to the payable URL. Static HTML, so a crawler that never runs JavaScript still finds a price where the content is missing and can buy instead of leaving empty-handed.

Returns snippet, gate_url, teaser, jsonld and price_usd. Read-only: it creates nothing and costs nothing to call twice.

issue_content_grant#

Let a reader you have already authenticated read a gated article without paying: your subscribers, your staff, a comped reader. You decide who is entitled; this mints the pass.

list_mcp_tools#

Ask the seller's own MCP server which tools it advertises. {origin_url}, plus the same optional origin_auth_* fields, returns {origin_url, tools: [{name, description, input_schema}]}.

Call it before create_checkout with fulfillment: "mcp". Nothing is stored — it is not a catalogue. It exists because a guessed tool name creates a checkout that takes the money and then fails on a tool the server never had, and the only person who can discover that is a buyer who already paid.

Then either sell the whole server for one price and let the buyer name the tool at call time, or set mcp_tool to sell exactly one. The pin is checked on every call rather than by the payment signature, because a package key is a bearer token presented with unsigned query parameters.

list_checkouts · get_checkout#

Yours, and one in detail. get_checkout takes checkout_id.

list_receipts · get_receipt#

Payments received. A receipt carries the payer, the split, tx_hash and the delivery outcome.

create_webhook#

{url} → registration plus the signing secret, shown once.

Also on the server#

whoami (which account, test or live), get_analytics, get_payout_history, list_awaiting_fulfilment and mark_fulfilled (the webhook-mode pair), and get_embed_settings · set_embed_settings (the frame-origin allowlist, so standing up an embedding site never has to leave the MCP flow). tools/list is always the authority on what exists.

Schedule tools#

list_schedules (filter by checkout_id, status), get_schedule (every period with its date, window, status and receipt, plus paid_through and next_charge_at) and cancel_schedule (stop a series you sell; what settled stays settled). See the recurring guide.

Escrow tools#

The whole lifecycle, without leaving MCP.

Spending tools#

The rail an agent buys with: a wallet checkout402 generates and holds the key to, so a connected agent can pay an x402 challenge without holding crypto. Real money moves, so a live connection is required; a test key is refused.

Two tools are deliberately absent. There is no create tool: minting a custodial wallet is done by a person at the dashboard. There is no reveal tool, ever: an MCP connection is exactly the credential that spends, and the credential that spends must not be the credential that exfiltrates. Getting money out is the dashboard's Reveal private key, and nothing else. See the spending wallets guide.

Buyer tools#

Buyer tools need no account and no key — a buyer holds a wallet, not one of our credentials. quote_checkout, pay_test_checkout, report_checkout and the buyer-side escrow actions all run unauthenticated; where an on-chain action results, the escrow contract authorises by msg.sender, so the tool reveals nothing and produces a transaction only the right wallet can use.

quote_checkout#

Read any checkout's price and offer card without paying. Takes a checkout URL or id; returns the total, the fee, and what you'd be buying.

Use it before deciding. It spends nothing. A …/test URL is quoted as the rehearsal face — testnet rails, simulated settlement — and either way the answer names where the rehearsal lives.

report_checkout#

Say a checkout failed you — the agent-native half of the abuse/failure channel. Buyers here are overwhelmingly agents with no account and no inbox; this is their recourse, and reports reach the seller's dashboard and checkout402's own review.

pay_test_checkout#

Rehearse any checkout end to end — on its test face, always. Whatever URL you pass (live face, /test face, armed or not), the payment settles simulated on /c/{id}/test: no funds, no key, no signature. Exists so an agent can prove the whole loop — challenge, settle, receipt, goods — before real money is involved. Rehearsals never consume the sale.

URLs on any of the three faces are accepted — /c/, /e/ and /x/ — because all three are addresses we publish. Rehearsing a gated article also returns grant, grant_scope and grant_expires_in: the pass is the product there, so a rehearsal that returned only the body would not be rehearsing the thing being sold.

Calling it directly#

curl -X POST https://api.checkout402.com/mcp \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $C402_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"create_checkout","arguments":{
         "title":"Financials","price_usd":"0.10","pay_to":"0x..."}}}'

The transport is a plain JSON-RPC POST: one request object in, one JSON object back. There is no SSE stream, no GET /mcp and no session header, so the accept header changes nothing and a bare curl is a complete client.

Notifications are the exception — notifications/* messages carry no id and get an empty 202 rather than a result.

OAuth#

For hosts that connect on a user's behalf:

Every tool here is a thin wrapper over the REST API in the API reference. Nothing is reachable through MCP that isn't reachable with curl.