A paid API can be online, price correctly, and settle payments correctly, and still never get
called. The failure is almost never the product behind the paywall. It is the short machine
conversation that happens before payment: discovery, the 402 challenge,
and the checks a buyer runs before it signs.
This guide is 46 pages of that conversation, organized around the faults that stop a machine buyer before payment. Each one gives you the symptom, one command that confirms it, a before-and-after fix, and the validator check that proves it is closed.
There is no bounce message in machine commerce. When a discovery catalog stops listing your resource, or a buyer-agent parses your challenge and walks away, you get silence. Traffic that never arrives leaves no log line on your side. The endpoint looks normal in your own monitoring because every local check still passes.
So the operator sees one of these instead:
Your resource is in a catalog. Paid calls stay at zero. Nothing in your logs explains it, because the rejection happened before any request reached you.
You shipped a change to routing, pricing, middleware or the recipient address, and the listing quietly went stale or vanished.
You can call your own endpoint by hand and it behaves. A machine buyer treats an ambiguity you never noticed as financial risk and picks a different provider.
A validator says pass, but pass on which fields? The guide is explicit about what a green result does and does not prove.
The guide treats each of these as a diagnosable fault with a known cause, not as a mystery. You work on one protected resource at a time, confirm the symptom with a single command, and verify the fix against the same validator a buyer would effectively be running.
This is for you if you run at least one x402 protected route on Base, it returns a
402, and you want it to be understood correctly by discovery systems and
buyer-agents. You are comfortable with curl, JSON, and reading an HTTP header.
It is not an introduction to x402, a guide to choosing what to sell, a security audit, or a way to get traffic to a product nobody wants. It assumes the endpoint exists and that the thing behind the paywall is worth paying for. It fixes the conversation in front of it.
Each fault-focused chapter follows the same loop: symptom, one diagnostic command, a before-and-after JSON or config change, then verification. The guide contains 40 code blocks, all checked to parse.
/.well-known/x402resource-list-bareextensions.bazaar and CDP discoveryamount_key mismatchpayTo driftThis is section 15 of the guide, in full and unedited. It is the diagnostic frame for everything else: seven gates a careful buyer runs, in order, before it signs a payment. Run the checklist at the end against your own endpoint. The gate that fails tells you which chapter of the paid guide you need.
A buyer-agent is not a human with a wallet extension and patience. It is software with a task, a spending policy, a deadline, and alternative providers.
There is no single universal buyer implementation, but a careful buyer usually follows the same gates.
402 challenge.Every chapter in this guide protects one of those gates.
For CDP Bazaar, the buyer and facilitator need a live 402 whose
extensions.bazaar.info.input describes how to call the route and whose
schema validates that advertised information. The resource object
supplies the resource URL and may include service metadata. Other crawlers may also inspect
the optional /.well-known/x402 convention.
extensions.bazaarFor v2, the buyer expects a Base64 JSON PaymentRequired object in
PAYMENT-REQUIRED. It does not need to guess a custom header name or scrape a
prose error message.
402acceptsThe buyer checks the atomic amount, asset, network, and scheme. It may compare the live quote with discovery, a cached quote, and a maximum spend rule.
amountThe buyer compares payTo across discovery, the live challenge, previous
successful calls, and any allowlist it maintains.
The buyer may re-probe before authorizing or compare the accepted requirements with the current challenge. It wants to know that it will not sign one offer and have the server apply another.
The buyer treats timeouts and server errors as routing signals. It may try another provider instead of debugging yours.
5xx during a burst of probes400 before payment middleware402This guide focuses on pre-pay conformance, but a buyer also cares about post-pay behavior:
A green pre-pay scan does not answer all of these. Add a controlled end-to-end payment test before launch, and make its spend limit explicit.
A human can refresh, inspect DevTools, ask in Discord, or decide that two nearly identical fields probably mean the same thing. A buyer-agent should treat ambiguity as financial risk.
Machines are especially strict about:
402This strictness is useful. It tells you exactly what to make deterministic.
Before asking an agent to buy, answer yes to each question:
402 include extensions.bazaar.info.input with the correct method and concrete accepted values?schema validate the advertised info object?/.well-known/x402 convention, can a crawler fetch it without credentials?402?PAYMENT-REQUIRED header?x402Version the integer 2?amount a digit string in atomic units?asset, payTo, and maxTimeoutSeconds present?5xx?Buyer-agents should not need a private conversation to learn the basics. Publish:
402 with extensions.bazaar for CDP Bazaar discovery/.well-known/x402 only if you support the optional community conventionKeep marketing prose separate from the machine contract. A description can help selection, but it cannot replace required fields.
The validator is a pre-flight check, not a badge generator. Run it on the deployed URL after every change to route, middleware, manifest, pricing, asset, recipient, proxy, or runtime.
A useful trust signal is not one green screenshot. It is the ability to reproduce the same coherent contract from fresh public probes and explain every intentional change.
That chapter tells you which gate you fail. The fault-focused sections show what the broken response looked like, what to replace it with, and how to prove it is fixed.
This is an implementation guide. It is not a security audit, and it does not guarantee catalog indexation, discovery by a buyer-agent, a completed payment, or revenue.
A clean validation run proves what your endpoint returned during that run. It does not prove future uptime, settlement correctness, or that anyone wants what you are selling.
Third-party specifications, APIs, validators, facilitators, and catalogs change. This is edition 2026.08. Content corrections are included for 90 days from purchase, which covers exactly this: a field that moves under you.
Support is corrections to the guide. It does not include hands-on implementation, monitoring your endpoint, incident response, or any service-level commitment.
Payment is in USDC on Base. For many x402 operators this is already the asset used for paid calls, and there is no third-party account to create or payment processor between us.
Delivery is priced and verified only in USDC on Base. Contact us before sending any other asset or using another network.
Invoices are available on request through Useme. Email info@smartflowproai.com before paying and say you need one. We issue it through Useme, billed in PLN at the exchange rate on the invoice date. Send your company name, address, and tax number.
Refunds: within 7 days of delivery, on request, returned in USDC to the address you paid from. No justification needed.
Licence: one purchase covers one purchaser, perpetually. You may apply everything in it to projects you build or operate. You may not redistribute or resell the file itself.
Yes. Edition 2026.08 covers v2 payment challenges and CDP Bazaar discovery through
extensions.bazaar. It treats /.well-known/x402 as the optional,
non-normative convention it actually is, and labels every legacy v1 example as legacy.
No. The validator used throughout is free and open source. The guide is the part that tells you what its output means and what to change.
Ask for a refund within 7 days. The free chapter above is deliberately the one that lets you decide before paying: if none of the seven gates describe your situation, this guide is not for you.
No, and section 17 is a full page on exactly that distinction. Conformance removes a reason to skip you. It does not create demand.