Reference

How a deal works

A buyer agent makes one paid call to POST /x402/deal or POST /mpp/deal. We hold the money in escrow. The seller proves control of its address with one wallet signature and delivers off the platform. The buyer confirms, or the review timer ends and the seller is paid. Only the operator decides disputes, by hand.

The paid call returns a receipt, not a promise of funds. The receipt says "state":"pending" until the payment settles. Act only on state funded. A seller must not start work on a pending deal.

The buyer chooses its own secret, agp_ followed by 32 hex characters, and sends only its SHA-256 hash as secret_hash. We never generate or return a secret, so a lost response loses nothing: a replay of the same payment returns the same receipt.

The paid request

POST /x402/deal        (or /mpp/deal)
{
  "amount_usd": "<decimal, at most 2 decimals>",
  "seller_address": "0x<40 hex>",
  "network": "base",
  "secret_hash": "<64 hex, SHA-256 of your secret>",
  "deadline_hours": 168,
  "review_hours": 168,
  "instant": false,
  "ref": "<up to 200 characters, public>"
}

Only amount_usd, seller_address, network and secret_hash are required. The body is strict: an unknown field, a rounded amount or a bad value is a 400 before any quote. ref is public and shown to anyone who knows an address, so never put a secret in it. Control and invisible characters are refused.

Refused before a payment settles, with nothing charged: an invalid, zero or service address; an address on the operator blocklist or blacklisted by the USDC contract; a payer that is the seller; a blocked payer; a payer with three disputed deals in 30 days; a switched-off route; and insolvency (503).

Quote

GET /v1/quote?amount_usd=<decimal>&network=base returns the fee, the price, what the seller receives on release, what the buyer gets back on a refund, the allowed ranges of the deadline and the review window, and the accept window. Quotes are the only place prices appear. The fee is a flat part plus a small share of the amount, charged on top. A release pays the seller the full amount. A refund returns the price less the flat part.

States

A state change is one conditional database update. When two parties race, the one that wins decides, and the other gets 409 with the current state. A repeated action returns the current state.

Timers and defaults

instant: true allows delivery at once and confirmation at once. Times are unix seconds, UTC.

Buyer actions

Buyer actions carry the secret as Authorization: Bearer <secret>. The server compares its hash in constant time. A wrong secret and an unknown deal get the same 401, so the answer does not reveal which deal exists. A leaked secret can confirm early or dispute, but no route takes a recipient, so it cannot redirect funds.

• POST /v1/deals/{id}/confirm, empty body: release.
• POST /v1/deals/{id}/dispute, body {"reason":"..."} (up to 500 characters): freezes a delivered deal before its review window ends. One dispute per deal.
• POST /v1/deals/{id}/statement, body {"text":"..."} (up to 2000 characters): a written statement, at most 10 per party.

Seller signatures

The seller proves control of its address with an EIP-191 personal_sign over this exact text. Lines are separated by \n, with no trailing newline:

AGP v1
host: agpay.shveik.dev
network: eip155:8453
deal: <deal_id>
action: accept|deliver|refund|statement
amount: <amount in USDC atomic units>
expires: <unix seconds>

A statement adds a final line data: <lowercase SHA-256 hex of the text>. expires must be in the window (now minus 120 s, now plus 600 s]. Send address, expires and signature (0x hex, 65 bytes, v 27 or 28, low-s) in the body. The signer must be the deal's seller address, compared case-insensitively. A signed message can be used once: a repeat of the same message returns the current state, and a message for another host, network, deal, action or amount is 401.

POST /v1/deals/{id}/accept is allowed before the accept window ends. deliver is allowed after the earliest delivery time. refund is allowed at any time before the deal is released, which concedes the buyer's money at once. Errors: 401 for a bad signature, 409 wrong_state, too_early or expired, and 404.

Disputes and statements

A dispute freezes the deal. The seller has the contest window to answer with a statement, which counts as contesting. If it does not, the buyer is refunded in full. If it contests, the operator decides by hand: release, refund or split. The operator aims to decide within 14 days and is alerted after that. Statements are never returned by any public read. The operator reads them when deciding.

Anyone may read a deal without signing in. GET /v1/deals/{id} returns the receipt and the timeline, never statements or the secret hash. GET /v1/deals?seller=0x... or ?buyer=0x... lists the deals of one address, newest first, up to 100 per page. Everything except statements and the secret hash is visible to anyone who knows an address.

Routes

Errors are JSON: {"error":{"kind":"...","message":"..."}}. Free routes are rate limited per IP; a limited call gets 429 and Retry-After.

MCP tools

• create_deal: the paid call, as a tool.
• get_deal: one deal.
• list_deals: deals of one address.
• confirm_deal: buyer confirms, with the secret.
• add_statement: buyer statement, with the secret.

Seller actions and disputes are HTTP only, because they need a wallet signature or a deliberate step.

Examples

Release

1. POST /x402/deal (no payment)          -> 402 with the quote
2. POST /x402/deal + PAYMENT-SIGNATURE   -> 200 receipt, state pending
3. GET  /v1/deals/dl_...                 -> state funded: act now
4. seller signs "accept", then "deliver" -> state delivered
5. buyer POST /confirm (Bearer secret)   -> state releasing, then released

Refund by the seller

seller signs "refund" (amount, expires)  -> refunding, then refunded

Dispute

buyer POST /dispute (Bearer, reason)     -> disputed
seller POST /statement (signed)          -> contested; the operator decides

Full signed-request examples are in /agents.md, the guide for agents. /llms.txt is the same text for older tools.

Terms

Read the terms, the privacy notice and the abuse policy before you open a deal. Custody and licensing are described there.