What an x402 seller should do that the spec doesn't require
An x402 seller that only returns HTTP 402 and settles a signature is compliant but fragile. A production seller should also refuse bad input before it charges, never keep a payment when its handler fails, quote the same price twice, let a buyer recover an interrupted purchase, and describe itself to machines once. Red Cup Engineering operates one such seller, market.561.group, with 130 per-call offers priced in USDC on Base, and this article lists what it does beyond the protocol minimum.
What does the x402 specification actually require of a seller?
x402 revives the long-reserved HTTP status code 402 Payment Required. In version 2 of the protocol a seller answers an unpaid request with 402 and a base64 JSON PAYMENT-REQUIRED header listing what it will accept (scheme, network, asset, amount, payee, timeout). The buyer signs a payment authorization, repeats the request with a PAYMENT-SIGNATURE header, and the seller asks a facilitator to verify and settle it. A successful answer carries a PAYMENT-RESPONSE header with the settlement receipt. The step-by-step walkthrough decodes a real challenge from our seller.
That is the contract. It says nothing about what happens when the buyer's JSON is malformed, when your handler throws after the buyer has signed, when the buyer's connection drops after settlement, or when a buyer is an autonomous agent that cannot read your documentation. Those are seller-engineering questions, and the answers decide whether an agent that tried your API once will try it again.
Our seller is built on the official @x402/core and @x402/evm packages. It does not replace the protocol; it wraps it with the policies below.
Which behaviors does a seller add beyond the spec?
| # | Behavior | One-line rule | Article |
|---|---|---|---|
| 1 | Refuse before charging | A request that can never succeed gets 400 or 422, never 402 | Refuse before you charge |
| 2 | Cancel settlement on handler failure | If the handler returns 4xx or 5xx, the signed payment is cancelled | same |
| 3 | Price from the body, deterministically | The same body quotes the same amount on both legs of the exchange | Per-byte x402 pricing |
| 4 | Recoverable purchases | A buyer can repeat the same signed request and receive the same bytes | X-Payment-Recovery |
| 5 | Buyer-side payee pinning | The buyer never takes the payee from the seller's own challenge | Never trust the payee |
| 6 | Sign-in-with-X on the 402 | A returning wallet can prove who it is without paying again | Sign-in-with-X |
| 7 | One catalog, many machine faces | MCP, A2A, ActivityPub, OpenAPI, llms.txt and x402 discovery from one source | One catalog, five faces |
| 8 | Honest evidence labels | A 402, a settlement, a delivery and a customer acceptance are four different facts | below |
Why refuse before charging?
An agent pays by signing a spend authorization. If the seller discovers only after payment that the JSON was invalid, the agent has either lost money or depends on a refund process nobody specified. The cheapest fix is ordering: validate the request body against the offer's published schema first, and only a request that passes earns a 402 challenge. On our seller, a malformed body to POST /v1/data/json-pointer returns 400 with {"error":"request body must be valid JSON"}, and a schema violation returns 400 with application/problem+json. Neither carries a PAYMENT-REQUIRED header. The full evidence, including the exact responses, is in Refuse before you charge.
Why cancel settlement when the handler fails?
In the fetch-based server in the Red Cup x402 engine, the handler runs after the payment verifies and before it settles. If the handler throws, or returns a status of 400 or above, the engine calls the payment library's cancellation path with a reason (handler_threw or handler_failed) and returns the failure to the buyer. The signed authorization is never submitted. A seller that settles first and fails afterwards has taken money for nothing. A seller that fails first does not.
Why must a price be deterministic?
Some offers are priced by the size of the request. If the quote depended on a wall clock, a traffic counter or a client-supplied Content-Length, the amount signed by the buyer could differ from the amount the seller expects when the signature comes back. Our seller derives the price from the canonical JSON bytes of the admitted body, so the same body produces the same amount on the unpaid probe and on the paid retry. We measured the live quotes and tabulate them in Per-byte x402 pricing.
Why make purchases recoverable?
Networks fail between settlement and delivery. For the digital goods on our seller that carry recovery in the catalog (seven priced publications and a briefing), the buyer generates a random 32-byte token, sends it as X-Payment-Recovery, and can later repeat the identical signed request to receive the original bytes. The signature alone is not a credential, because it becomes public on the chain. Details and the status codes (400, 409, 410, 503) are in Repeat purchases with X-Payment-Recovery.
Why should a buyer pin the payee?
A 402 challenge is written by the party asking for money. A buyer that spends whatever address the challenge names can be redirected by any compromised or malicious seller. The Red Cup buyer library requires an independently authorized expectedPayTo before it probes or signs, and refuses a challenge naming anyone else. The seller's own receiving script uses the same discipline through X402_EXPECTED_PAY_TO. See Never trust the payee in a 402 challenge.
Why attach sign-in-with-X to the challenge?
Some wallets have been granted access out of band: a subscriber, a partner, a paid-up customer. The x402 extension sign-in-with-x lets the seller include an EIP-4361 style challenge inside the 402 so such a wallet can prove control of its address instead of paying. Our implementation issues stateless nonces from an HMAC, accepts a proof for five minutes, and binds it to the resource URL. See Sign-in-with-X.
Why publish one catalog in five formats?
An agent might find a seller through an MCP server, an A2A agent card, an ActivityPub actor, an llms.txt, or the x402 /.well-known/x402 document. We maintain a single catalog file and project it. Every format therefore agrees on price, route and input schema, and none can drift. See One catalog, five machine faces.
What does "honest evidence labels" mean?
The seller's own documentation keeps four facts apart: an unsigned 402 challenge proves only that the route is configured; a facilitator success is an observation, not proof of an on-chain transfer; a delivered HTTP status is not buyer acceptance; and traffic is not independent customer demand. We do not claim revenue or customer counts in these articles because none of those observations establishes them. Neither should your dashboard.
How can I verify these claims myself?
Every behavior above can be exercised without spending anything, because an unpaid request reveals the challenge and the refusals:
# 1. The machine-readable offer list (130 resources)
curl -s https://market.561.group/.well-known/x402 | head -c 600
# 2. A malformed body is refused before any payment challenge
curl -s -i -X POST https://market.561.group/v1/data/json-pointer \
-H 'content-type: application/json' -d '{"nope":' | head -n 12
# 3. A valid body earns a 402 with a PAYMENT-REQUIRED header
curl -s -i -X POST https://market.561.group/v1/data/json-pointer \
-H 'content-type: application/json' \
-d '{"value":{"a/b":[1,null]},"pointer":"/a~1b/1"}' | grep -i '^HTTP\|^payment-required' | cut -c1-120The first returns a JSON list of resources, the second a 400, the third a 402 with a long base64 header. If any of these differ from what we describe here, the live seller is authoritative and we want to know.
Where is the code, and what is its license?
The payment-boundary reference is public under Apache-2.0: 561-group/x402-boundary-reference. It builds an explicit exact-EVM x402 v2 boundary for an Express route and inspects a public challenge without paying. The buyer library x402-exact-purchase-service is public under MIT at red-cup-engineering/x402-exact-purchase-service. The full seller engine, @red-cup-engineering/x402-services-section (version 0.10.9 at the time of writing), is distributed from the house registry rather than public npm; the articles describe its behavior from source and from the live endpoint.
What are the honest limits?
The recoverable-purchase store claims no crash-exactly-once production: the caller still owns cross-process exclusion and idempotence of the effect after settlement. Usage-based (upto) pricing exists in the engine but the market catalog remains on the fixed exact scheme. A listing in a directory or a 402 on a route is not a purchase, and a purchase we make from ourselves is not demand. We say so in the code's own documentation, and repeat it here.