There is a quiet assumption in the x402 ecosystem that if you publish a .well-known/x402 manifest, agents and indexers will find your endpoints. That assumption is only half right. Publishing the manifest gets you eligible for discovery. Whether you actually appear in any index depends on which of two very different indexing models that index uses — and confusing the two has real, observable consequences.
The x402 discovery convention is a thin, well-understood chain. A crawler fetches a domain's .well-known/x402 manifest, which advertises the operator's settlement address, supported networks, and the endpoints it serves. From there the crawler walks each endpoint and asks the question that only the endpoint itself can answer: "what does a call actually cost?"
That question is answered by the 402 Payment Required response. A crawler GETs an endpoint, receives a 402 challenge carrying the amount, asset, network, and pay-to address, and records the price. This is the x402 design's core trick: the 402 response is the price source of truth, because manifest-side price data rots — endpoints change price, and only the live challenge knows the current number.
So the canonical discovery walk looks like this:
GET /.well-known/x402 → manifest (networks, pay-to, endpoint list)
GET /x402/<service> → 402 challenge (amount, asset, network)
record price → next endpoint
A thorough crawler goes one step further: after reading the challenge, it POSTs a settlement probe to confirm the endpoint actually settles, not just advertises. A price that can't be paid is not a discoverable price.
The difference that matters is what earns an entry in the index.
| Model | How an endpoint gets indexed | What the index reflects |
|---|---|---|
| Manifest-driven | The crawler enumerates every endpoint it can reach and verifies each 402 challenge | The full catalog, whether or not anyone has ever paid |
| Call-gated | An endpoint appears only after a real transaction settles through the index's own facilitator | Only endpoints with genuine, paid usage |
Manifest-driven indexing is generous: enumerate everything, index everything that passes verification. Call-gated indexing is conservative: the index is a side effect of payment, not of enumeration. If no one has settled a call through that facilitator, the endpoint simply isn't listed.
Both are defensible. Manifest-driven gives a newcomer instant visibility but invites junk. Call-gated keeps the index clean but means a brand-new endpoint — even a perfectly good one — starts invisible and stays invisible until someone pays, which is hard to do when you're invisible.
Here's the part that bites operators. A spec-compliant discovery crawler — the thing you want hitting your catalog — behaves, at the HTTP layer, almost identically to a scraper you'd want to block. It makes many requests, quickly, across many endpoints, sometimes distributed across many cloud IPs. It GETs and POSTs each endpoint in turn. A naive per-IP rate limiter cannot tell the difference.
We watched this happen on a live catalog this week. A distributed, spec-compliant crawler walked the manifest and began enumerating endpoints — GET then POST, endpoint by endpoint, exactly as the discovery flow prescribes. It was doing the right thing. And a meaningful share of its requests came back 429 Too Many Requests, because the crawl looked like an aggressive scrape to the rate limiter. The crawler could only read part of the catalog before backing off.
The consequence is subtle and worth naming: a rate limiter tuned to block scrapers can quietly block your own discovery. The crawler doesn't send you an angry email. It just indexes a subset of your endpoints, or skips you and moves on. You keep the 429s out of your logs and never learn that you were invisible.
There are three practical mitigations, in increasing order of effort:
1. Expose a crawl-friendly catalog. A static manifest that already lists every endpoint and its price means an indexer can read your catalog in one request instead of hammering every endpoint for its 402 challenge. Serve it at a stable path and keep it current.
2. Make the 402 challenge carry its own discovery data. The x402 challenge already supports an extensions object. Putting structured capability metadata there lets a crawler learn what it needs from the single 402 it already has to fetch — no extra round-trips.
3. Distinguish crawlers from scrapers before you rate-limit. A discovery crawler follows a recognizable sequence: it reads .well-known/x402 (or your catalog file) first, then enumerates the endpoints that file names. A scraper typically blasts paths without the manifest step. That sequencing signal is a better discriminator than raw request velocity.
Rails are cheap; being found is hard. The x402 discovery convention gives every operator the same starting line — a manifest and a 402 challenge. What separates the catalogs that get indexed from the ones that stay invisible is not the spec. It's whether the operator understands the two indexing models and doesn't accidentally throttle the crawler that was trying to find them.
The one-line version: publishing a manifest makes you eligible for discovery. Whether you actually get indexed depends on the index's model — and your rate limiter can turn a manifest-driven crawler into a manifest-driven miss.