# checkout402

> Hosted checkouts that machines can pay. One URL per checkout, two faces: a
> human gets a pay page, an agent gets an HTTP 402 with a machine-readable
> price and pays via x402 (signed USDC authorization) in one round trip.
> Non-custodial: funds settle on-chain straight to the seller's own wallet
> through an immutable splitter. Fee: 0.5% of price (min $0.005), charged on
> top, printed inside every 402.

## Buy (no account, no API key — the payment is the login)

1. GET https://api.checkout402.com/c/<checkout_id> with `Accept: application/json` → HTTP 402.
   Body: `accepts[]` (per network: `maxAmountRequired` in atomic USDC,
   `payTo`, `extra.providerAmount` + `extra.feeAmount` = the visible split),
   plus `endpoint` describing what you get (title, description,
   optional input_schema / output_schema / examples / freshness / coverage /
   source / constraints). Inspect BEFORE paying — quote_checkout on MCP does
   the same with no spend.
   PARAMETERISED endpoints: if `endpoint.input_schema` is present, supply your
   inputs at prepare time — POST https://api.checkout402.com/c/<id>/prepare {"payer": …,
   "params": {…}} — and send the same `params` inside the X-PAYMENT envelope.
   They are folded into the signed `resource`, so ONE payment buys ONE query:
   different params are a different signature and a separate purchase. Params
   that don't match `input_schema` are rejected BEFORE you sign.

   One checkout, possibly several rails — the SAME dollar price on each. Pick
   whichever `accepts[]` entry you can pay; how you sign depends on the family:

   - EVM (`eip155:*`, USDC on Base): `payTo` is the immutable SPLITTER contract.
     Sign an EIP-3009 ReceiveWithAuthorization for the exact total. Either build
     it yourself, or POST https://api.checkout402.com/c/<checkout_id>/prepare {"payer": <your
     address>} for the exact EIP-712 typed data (the server signs nothing and
     holds no key).
   - SVM (`solana:*`, SPL USDC): program-less, so there is NO splitter and
     `payTo` names the seller. Build ONE transaction containing exactly TWO
     `transfer_checked` instructions — `extra.providerAmount` to the seller's
     ATA and `extra.feeAmount` to `extra.feeRecipient`'s ATA — sign it as the
     payer, leave the fee-payer slot empty, and send
     `{"transaction": <base64>, "payer": <your pubkey>}`. The relayer co-signs
     as fee payer, so you need no SOL.
3. Retry the same URL (or POST https://api.checkout402.com/c/<checkout_id>/pay) with header
   `X-PAYMENT: base64url({"network": <caip2>, "payload": {…signed…}})`
   → HTTP 200 with `fulfillment` (the goods) and `receipt` (on-chain tx).
4. Retries are safe: re-presenting the SAME X-PAYMENT after a settled payment
   redelivers the goods (`replayed: true`) and never charges twice.
5. Receipts: GET https://api.checkout402.com/r/<receipt_id> (JSON or HTML).

Buyer library: `pay402` (Python + JS) — `pay(url, private_key=…, max_usd=…)`
does the whole loop with a spend ceiling. Test-mode checkouts settle with no
chain and no funds: `pay(url, test_payer="0xYourAddress")`.

## Sell (agents welcome — no email needed)

1. POST https://api.checkout402.com/auth/wallet/challenge {"address": <wallet>, "network":
   <caip2>} → challenge message.
2. Sign it with the wallet, POST https://api.checkout402.com/auth/wallet/verify → an API key
   (`c402_live_…`). The signing wallet is registered as your verified payout
   address. Re-signing later mints a fresh key (key recovery).
3. Create a checkout (same primitive four ways):
   - Web: https://api.checkout402.com/create (relay-first, under two minutes)
   - REST: POST https://api.checkout402.com/v1/checkouts with Bearer key
   - MCP: create_checkout tool at https://api.checkout402.com/mcp (best for bulk from a repo)
   - CLI: `c402 checkouts create --title … --price … --pay-to …` (stdlib-only,
     `--json` on every command; `c402 login --wallet <key>` needs no email)
   Core fields: title, description, price_usd, pay_to, fulfillment.
   For an API: fulfillment="relay", origin_url="https://…". Optional offer
   fields (input_schema, output_schema, example_input, example_output,
   freshness, coverage, source, constraints) make unpaid inspect useful —
   ask the seller to approve commercial claims before publishing.
   → {"url": "https://api.checkout402.com/c/chk_…"} — share that URL.
4. Keys are scoped (read_only < payments < full) and moded: a `c402_test_…`
   key drives everything but cannot move real money.
5. Profile: GET https://api.checkout402.com/auth/me returns your full profile; PATCH the same
   path to change name, bio, slug (your public handle), website_url, avatar_url,
   profile_type, social_links. Empty string clears a field; omitted leaves it.
6. Webhooks: POST https://api.checkout402.com/v1/webhooks {"url": …} → `checkout.paid` events,
   HMAC-signed (`X-Checkout402-Signature: t=<unix>,v1=<hmac of "{t}.{body}">`).

## MCP

Seller tools (create_checkout, list_checkouts, get_checkout, list_receipts,
get_receipt, create_webhook) at https://api.checkout402.com/mcp — JSON-RPC 2.0, streamable HTTP,
`Authorization: Bearer c402_…`. `tools/list` needs no auth.

## Machine endpoints

- https://api.checkout402.com/           self-describing JSON map (request with Accept: application/json)
- https://api.checkout402.com/openapi.json
- https://api.checkout402.com/docs       Swagger UI
- https://api.checkout402.com/create     one-page seller create (relay-first)
- https://api.checkout402.com/demo       mints a fresh test-mode checkout and redirects to it (rate-limited)

Networks: USDC on Base (eip155:8453) at launch. Every 402 lists what the
checkout actually accepts — never advertised beyond what is configured.