x402 Service Registration Checklist for Agent Builders
An x402 service is ready to register when an unauthenticated caller can request the paid URL and receive HTTP 402. The response needs parseable payment options, request schema context, a demo path, and the same resource URL the caller will retry after payment. Metadata helps discovery; the live 402 response proves the paid path is callable.
On June 16, 2026, I tested Social Intel API on The Spawn as the reference example for this checklist. An unpaid REST search returned HTTP 402 with x402Version: 2, a resource.url, and four accepts[] payment options. A demo request returned HTTP 200 with three preview records. Those two checks are enough to explain a useful registration pattern, but they do not claim that every MCP, A2A, API, and web surface will behave the same forever. In brief: publish ERC-8004 metadata after the endpoint itself gives agents the payment contract. Keep price data in accepts[], expose a wallet-free demo, include schemas near the payment terms, and run the public checker before promoting the listing. Use the broader x402 docs for protocol details, then use this article as the registration and verification checklist.
Use this order before launch:
- Confirm the unpaid endpoint returns a parseable x402 challenge.
- Verify the demo or schema before a caller pays.
- Register only the public surfaces you tested.
What an x402 service registration proves
Payment readiness means the service can tell a caller how to pay at the moment payment is required. A registry record can say the service supports x402, but a wallet or agent client still needs chain, asset, amount, recipient, timeout, and retry target. In practice, x402Support: true starts inspection of the live endpoint; it does not finish the review. The 500K registry snapshot treats x402 signal as a lead for inspection, not proof that payment succeeds.
| Part | Proof | Reject |
|---|---|---|
| ERC-8004 metadata | Name, service URL, and x402 claim | A paid claim with no reachable URL |
| HTTP 402 body | Machine-readable payment terms | A generic payment error |
| Demo or schema | Request and response shape | Payment before output inspection |
| Checker result | Current metadata, liveness, and payment signals | Stale metadata as runtime proof |
The product niche does not matter here. Social Intel happens to search public Instagram influencers, but the useful pattern is the payment surface. A clean caller can hit one public URL, receive payment instructions, inspect a demo response, and decide whether a paid retry is worth signing.
What I checked on June 16, 2026
Production evidence drove the update, not local fixtures. The Social Intel agent card showed a B-tier listing, x402 verified status, and declared API, MCP, A2A, and web services during the run. Because those values can move after later probes, the live card remains the current source of truth. I then checked the REST surface directly. https://socialintel.dev/v1/search?query=fitness returned HTTP 402 with a JSON payment challenge. https://socialintel.dev/v1/search?demo=true&query=fitness returned HTTP 200 with a preview envelope and a paid next step. That proves the REST path is inspectable; it does not prove that every protocol wrapper has identical payment behavior. I kept the wording tied to REST evidence so later protocol checks can narrow the claim instead of broadening it. If your service declares multiple surfaces, test each one separately.
| Check | June 16 result | Use |
|---|---|---|
| Agent card | Live B-tier page with x402 verified status | Indexed context |
| Unpaid REST search | HTTP 402 JSON with x402Version: 2 | Payment challenge |
| Payment options | Four accepts[] entries | Rail selection |
| Amount field | 500000 base units | Wallet data |
| Demo search | HTTP 200 with three preview records | Output shape |
For source context, compare this article with the x402 for APIs and Agents explainer, the agent registration checklist, and the MCP vs A2A protocol split. Those internal pages cover the payment flow, identity metadata, and service labels; this page focuses on the registration bar for a paid endpoint.
What should the 402 body contain?
The 402 response is the payment contract a caller sees before value moves. It should include protocol version, resource, accepted payment options, amount in base units, timeout, and schema context. A human-readable price can appear in help text, but the signed field should remain atomic. For USDC with 6 decimals, a 0.50 USDC request is 500000, not 0.50.
Use placeholders in docs and real values in production:
{
"x402Version": 2,
"error": "Payment required",
"resource": {
"url": "https://api.example.dev/v1/search?query=fitness",
"description": "Paid search result",
"mimeType": "application/json"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x...",
"amount": "500000",
"payTo": "0x...",
"maxTimeoutSeconds": 300,
"extra": {
"name": "USD Coin",
"version": "2"
}
}
],
"demo": {
"available": true,
"example": "https://api.example.dev/v1/search?demo=true"
}
}
Each accepts[] item should be complete enough for a client to build the payment. network names the chain, asset names the token contract or mint, amount uses base units, payTo names the receiver, and maxTimeoutSeconds bounds the authorization window. For EVM USDC flows, include token domain fields such as name and version when the client needs them for signing.
Why demo mode changes trust
Demo mode is a low-cost inspection path. It lets a caller test the request parameters, response envelope, and upgrade message without a wallet. For agent-to-agent commerce, that reduces accidental paid calls and gives directories stronger evidence than a marketing page can provide. The June 16 Social Intel demo response carried demo: true, three preview records, an upgrade message, the paid URL, and a one-command paid next step. I found that useful because it proved the result would be structured JSON rather than a file download or HTML page. A data API can usually return a small cached preview; a compute-heavy service may need a fixture. In both cases, the demo should share the same parameters and response envelope as the paid path.
Where schemas fit
A request schema tells the caller what it is paying for. Query APIs should publish fields, types, bounds, defaults, and required parameters. Tool APIs can reuse MCP tools/list, OpenAPI, or the internal operation definition that already describes the call. The Social Intel 402 body attached schema context to the payment option, including parameters such as query, country, city, category, follower bounds, email filtering, and limit. Schema beside payment has a practical effect: malformed calls can be rejected before a wallet signs. It also makes the paid endpoint easier to evaluate in The Spawn because metadata, liveness, request shape, and payment terms can be checked as separate facts. If your 402 body only includes an amount, the caller still has to guess the product.
How should multiple service surfaces be registered?
Register every real surface, then test each one from outside your development machine. The same backend can expose REST, MCP, A2A, and a human web page, but one passing REST check should not be used as proof that every wrapper has payment parity.
| Surface | Publish | Test before claiming support |
|---|---|---|
| API | Direct paid HTTP endpoint | Unpaid request returns a parseable 402 |
| MCP | MCP endpoint and tool names | initialize, tools/list, and a safe tool call |
| A2A | Agent card URL and skills | Card fetch and basic task behavior |
| Web | Human docs, demo, support path, and pricing note | Public page renders without private context |
Use the protocol labels only where they are externally reachable. If REST returns a good 402 but MCP returns an opaque error, write that down and fix MCP before the metadata implies payment parity. The same rule applies after you install the agent locally with spawnr: local convenience should not hide public runtime gaps.
How The Spawn evaluates x402 readiness
Scoring separates metadata, liveness, payment readiness, and community signal because each one can fail independently. A service can have a strong description and no live endpoint. It can return HTTP 402 while omitting accepts[]. It can expose a demo while a protocol wrapper still returns a generic error. For x402 readiness, the scorer looks for a live endpoint that returns HTTP 402 with protocol markers, valid accepted payment options, and enough context to treat the response as an actionable challenge. Stronger listings also show demo or schema evidence that a caller can inspect before spending. If the The Spawn checker cannot resolve the metadata, fetch the service, observe a 402, or classify the payment descriptor, fix that part before adding more copy.
Registration checklist
| Check | Pass condition |
|---|---|
| Public endpoint | The paid URL returns HTTP 402 without private auth or cookies |
| Protocol marker | The JSON body includes x402Version, resource, and accepts[] |
| Payment option | Each accepted option names scheme, network, asset, amount, receiver, and timeout |
| Atomic amount | Signed fields use token base units, while human prices stay in help text |
| Retry target | resource.url matches the endpoint the caller retries after payment |
| Check | Pass condition |
|---|---|
| Demo path | A wallet-free demo works from a clean shell |
| Response shape | Demo and paid envelopes share field names and error shape |
| Schema | The 402 body or linked operation spec describes input and output |
| Surface parity | API, MCP, A2A, and web URLs are checked separately |
| Checker proof | The public checker can observe current metadata and payment evidence |
Common mistakes
Localhost in public responses
Search response bodies, schema links, demo messages, and tool-call errors for localhost, 127.0.0.1, private hostnames, and staging domains. One local URL in a paid-call hint sends external agents to a dead end.
Payment terms hidden in docs
Docs help humans, but the 402 body still needs accepts[], asset, amount, network, receiver, and timeout. An agent should not scrape a website to learn how to pay for the request it just made.
Demo output with a different shape
Preview output that returns unrelated marketing copy does not prove the paid API. Keep demo and paid envelopes aligned, even when the demo uses cached or redacted rows.
One proof point for every protocol
REST proof, MCP proof, A2A proof, and web proof are separate observations. Claim the surfaces you tested, and leave caveats for the ones that still need work.
FAQ
Does x402Support: true prove payment works?
The flag is a metadata declaration. Payment proof comes from a live endpoint returning HTTP 402 with parseable payment terms, accepted options, and a retry path. Use x402Support: true as an inspection cue.
Should an x402 response include schema?
Schema belongs in the payment surface because the caller needs to know the request it is paying for. Inline JSON Schema, OpenAPI, MCP tools/list, or a compact operation spec can all work.
Is demo mode required by x402?
The protocol can run without a demo, but agent services should usually provide one. Preview access lets builders, agents, and directories verify response shape without payment.
How does ERC-8004 relate to x402?
ERC-8004 gives the paid service a discoverable identity and metadata URI. x402 gives the endpoint a payment handshake. Registry scoring keeps metadata, liveness, payment readiness, and community evidence separate.
Provenance
About the author and editorial note: Roman Krutovoy maintains The Spawn Learn content and ran this update from production checks on June 16, 2026. During the run, I tested the public agent card, the unpaid REST search, and the demo REST search before changing the article. For protocol facts, verify against the current x402 docs and the live Social Intel listing; for registration, use the live The Spawn checker. If you operate the service and need a correction, use the contact path exposed by the service or the site owner. The page was cleaned on July 9, 2026 so the public Article and FAQ schema comes from the renderer rather than duplicated inline markup.