SAYLOR Design a discoverable paid HTTP resource with explicit price, network, schema, payment verification, idempotency, and safe fulfillment boundaries.
The result you're building
A testnet-verified paid API route that advertises a clear resource and price, returns a standards-compliant 402 challenge, verifies and settles payment before fulfillment, handles duplicate requests safely, and publishes accurate discovery metadata.
Use when: you have a real API result autonomous software would pay to receive immediately and programmatically; you need usage-based or fixed-price payment without building accounts/subscription billing; you can measure cost and reliability per response.
Not a substitute for: charging for an undifferentiated wrapper around free public data with no reliability, normalization, freshness, or decision value; launching on mainnet before negative payment tests, spend caps, idempotency, observability, and a kill switch work.
Before you change anything, collect: one narrow resource path/method/input schema/output schema/examples/latency target/freshness promise; receiving wallet address on a supported test network (private keys stay in a wallet/secret manager); chosen facilitator, scheme, asset/network, price ceiling, settlement behavior; measured upstream cost per call and failure behavior; a separate low-balance buyer test wallet and acceptance test matrix.
Understand the system first
- x402 monetizes a resource, not a whole site — keep discovery, schema, health, samples, and human explanation free so an agent can decide whether to buy.
- Payment verification and business authorization are different — a valid payment proves the payload satisfies the advertised requirement, not that the caller may access someone else's data or trigger an unsafe operation.
- Price must follow contribution margin — gross payment minus facilitator/network cost, upstream cost, compute, refunds, and failed paid responses is the number that matters. A popular endpoint can lose money if these aren't bounded.
- x402 v2 is an evolving surface — pin SDK versions, publish the supported network/scheme explicitly, test protocol edge cases, recheck current docs before launch.
Evidence-to-decision map
| Evidence | Likely layer | First check | Meaning |
|---|---|---|---|
| Unpaid request doesn't return 402 | Middleware/order | Call route without payment, inspect headers/body | Route unprotected or middleware mounted incorrectly |
| 402 returned but client can't decode | Protocol/schema | Decode payment-required structure/version | Header/body/version/network identifiers mismatch client expectations |
| Payment verifies, fulfillment fails | Upstream/service | Correlate payment ID with resource job | Need preflight, refund policy, stable paid error, cost tracking |
| Paid retry duplicates work | Idempotency | Repeat same logical request/payment identifier | Fulfillment lacks atomic dedup or uses a fresh business key |
| Endpoint absent/misleading in discovery | Catalog | Fetch discovery entry, compare live route | Published method/price/network/schema/examples are stale |
Step-by-step procedure
01 Define the paid unit and free preview. Specify one resource, supported inputs, response schema, freshness, latency, exclusions, and a free sample that reveals structure without giving away unlimited output. If value can't be stated in one sentence, the endpoint isn't ready to charge for.
02 Choose scheme, network, asset, recipient, price. Fixed exact, usage-capped upto, or the current supported scheme based on real billing semantics; a supported test network and stable receiving address; minimum viable price from real costs and target margin.
03 Implement the unpaid challenge.
curl -i https://example.com/api/v1/paid-resource
# decode payment requirements, compare every field to server policyAn unpaid request should get 402, not 401/403/500, decoding to the intended recipient/amount/network/asset/expiry.
04 Verify and settle before irreversible fulfillment. Validate protocol version, scheme, network, asset, destination, amount/max, expiry, resource binding, payment identifier. Verification failure returns a stable payment error with no fulfillment. Settlement and fulfillment share one correlation/idempotency key.
05 Make retries safe and observable. Use a client-supplied or generated stable idempotency identifier; store the first terminal result atomically; log sanitized payment status, fulfillment status, latency, and cost. Same key + different payload must be rejected. Same key + same payload must not charge or fulfill twice.
06 Publish and test discovery.
curl -sS https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources | jq .
curl -fsS https://example.com/openapi.json | jq .Discovery conversion needs a working example buyer and deterministic schema, not just a listing.
07 Pass testnet and mainnet gates. Run unpaid, valid, wrong network, wrong asset, wrong recipient, over-price, expired, invalid signature, duplicate, timeout, upstream-failure, and refund tests; then use a low-balance mainnet wallet for one capped call. Mainnet is allowed only when every safety gate is documented and the kill switch is tested.
Worked example
A token-risk snapshot costs $0.02 while upstream data and compute average $0.028 per successful response. Testnet and discovery both work; paid-response failure rate is 4%, duplicate retries repeat upstream work; gross receipts look positive while contribution margin is negative. Fix: added a short freshness cache keyed by chain/mint/version, made duplicate payment identifiers return the stored terminal result, raised price to cover p95 cost plus failure allowance and target margin, published observed-at time and cache age. Proof: negative tests pass; one payment yields one fulfillment; p95 total cost stays below price policy; kill switch blocks new charges.
Verify, recover, hand off
Complete when: unpaid calls return a decodable x402 v2 402 for the intended resource; valid testnet payment returns the documented schema; wrong network/asset/destination/amount/expiry/signature/binding are rejected before fulfillment; identical retry can't double-charge or duplicate; discovery/OpenAPI match the live route; margin/latency/error rate meet launch limits.
Rollback: activate the paid-route kill switch while leaving free health/schema available; return to testnet if facilitator/SDK/network behavior changes; preserve payment/fulfillment correlation records for reconciliation — never delete them to solve an incident.
| Symptom | Usually means | Next move |
|---|---|---|
| 402 body looks correct but SDK refuses | Protocol version or encoding differs | Decode the exact challenge, compare with current SDK/spec |
| Buyer paid but got 5xx | Fulfillment failed after settlement | Return stable correlation ID, reconcile, apply refund policy, fix preflight |
| Duplicate paid results | Idempotency outside the atomic fulfillment boundary | Store request hash + terminal result before/reliably with side effect |
| No agents purchase | Discovery, proof, value, freshness, trust, or price weak | Run a demonstration buyer, publish examples/metrics, narrow the job |
Handoff record: versioned route, schemas, examples, free preview, value statement; server-owned payment policy (scheme/network/asset/recipient/price/expiry); negative and positive test matrix with receipts; idempotency model, kill switch, refund rule, sanitized logs; discovery entry plus cost/price/margin/latency/paid-success scoreboard.
For agents
Inputs: resource (stable route/identifier), method, inputSchema (strict JSON Schema, examples, size limits), paymentPolicy (scheme/network/asset/recipient/price/expiry/facilitator), economics (p50/p95 cost, target margin, cache policy, paid-failure allowance). Output: routeConfig, challengeTests, fulfillmentTests, discovery, launchDecision. Same refusal/escalation/confidence rules as the series.
References
- https://docs.x402.org/getting-started/quickstart-for-sellers
- https://docs.x402.org/schemes/overview
- https://docs.x402.org/extensions/bazaar
- https://docs.x402.org/guides/mcp-server-with-x402
*Educational technical and risk-analysis information, not financial, investment, legal, or tax advice. Blockchain transactions can be irreversible; no checklist guarantees profit or safety.*