An issue landed on one of our repos with the title "Publisher docs and CLI disagree with live seller API." The author had tried to list an API on our marketplace, followed the published instructions, and got HTTP 400.
Our first instinct was that the reporter had the wrong route. They claimed the seller endpoint was POST /api/register with header-based signature auth. That did not match what we believed the API to be.
So we tested it. Not from memory — against the live gateway:
POST /api/register
{"name":"...","endpoint":"https://...","priceCents":5,"wallet":"0x..."}
X-Wallet-Signature: 0x...
X-Signature-Ts: 1755...
→ {"error":"name, wallet and signature required"}That is the buyer registration error. The endpoint ignored endpoint and priceCents entirely. We then sent the identical request with the two signature headers removed and got a byte-for-byte identical response — proof the handler never reads those headers at all.
The reporter's conclusion about which route works was wrong. But their complaint was exactly right, and the reason they believed it was our fault: that route and that header scheme are what our own canonical agent guide told them to use.
Once we knew the canonical guide was wrong, we checked every document that describes publishing. Each one was broken, and no two were broken the same way.
| Document | What was wrong |
|---|---|
| AGENTS.md the canonical guide, linked from everywhere | Wrong route (a buyer alias), wrong field name (priceCents instead of price_cents), missing two required fields, plus a documented header-auth scheme that is no longer honoured |
| llms.txt | Correct route, but the example omitted a required field → 400 |
| agent-cookbook.html | Correct route, same missing required field → 400 |
| mcp-x402.html | Missing endpoint and signature (both required), wrong field name, and an invalid category value — four errors in one call |
There was no working documented path. If you were a developer who wanted to sell an API on our marketplace and you read our documentation, you could not do it.
The required field everyone was missing is description, which must be at least 20 characters. Here is what the API returns for an empty request:
POST /api/v1/publish-service {}
→ {"error":"name, endpoint, wallet and signature required"}description is not in that list. It is enforced, but it is not announced. So a developer doing the sensible thing — reading the error and adding exactly the fields it names — still gets a 400, with a new error that finally mentions the real requirement.
This is the part we consider most instructive. A wrong example is one problem. A wrong example plus an error message that under-reports the contract is a loop that punishes the exact debugging strategy a competent developer would use.
A human developer who hits a 400 has options. They read the error, try variations, search for someone with the same problem, look at the HTML on another page, or give up and email support. Humans route around bad documentation. It costs them time, and some fraction of them succeed anyway.
An agent does not do this. An agent reads AGENTS.md or llms.txt, constructs the call exactly as specified, gets a 400, and stops. If it retries, it retries the same wrong shape. The machine-readable documentation is not a helpful supplement to the API — for an autonomous client, the documentation is the interface. A wrong llms.txt is not a docs bug; it is an outage that returns 200.
This industry spends a lot of energy on agent-facing discovery formats — llms.txt, agent cards, .well-known manifests, OpenAPI specs. All of that infrastructure assumes the content is true. We had all of those files. Several of them were confidently describing an API that would reject you.
Our catalog has 1,644 active services. Twelve of them run on someone else's server. The rest are ours.
Meanwhile the buyer side — whose documentation was correct throughout, and which we had verified before — has 775 registered wallets and has served 21,155 free trial calls.
We are not going to claim the documentation is the sole cause of that asymmetry. Selling an API is inherently a bigger commitment than calling one, and this is an early market on both sides. But the simplest explanation for near-zero external supply is that the on-ramp returned an error to everyone who tried it, and we should have caught that long before a user did.
We will also be honest about the other side of the funnel, because it is the number that actually matters: those 21,155 trial calls correspond to 54 settled paid transactions and 3.522 USDC of real on-chain volume. Fixing the seller path does not fix that. Demand generation is a separate and harder problem, and we have written about it before.
One thing we did not fix: the catalog does not record an HTTP method, so a service published to be called with POST is read back indistinguishably from a GET service and generic clients call it with GET. That is a gateway change rather than a documentation one. Until it ships, it is written down in the docs and the CLI warns about it after a successful publish. Naming a known defect is better than letting a publisher discover it from silent failures.
If you run anything that agents are supposed to use autonomously, the test is not "is the documentation good." The test is: can a machine that reads only your documentation complete the task? That question has a yes-or-no answer, it can be checked automatically, and we were not checking it.
The fix that generalizes is not "write better docs" — it is to stop hand-maintaining the files that describe a system that changes. Our discovery surface now regenerates from live state on a schedule, and the examples in it are captured from real responses. Anything still hand-written is a snapshot, and every snapshot is drifting from the moment it is written. Ours drifted for weeks, in public, while telling agents exactly how to fail.
All figures in this post were measured against the live API on August 18, 2026, and are snapshots — current values are at /api/stats. Catalog composition figures come from /api/services.