An agent looking for a paid endpoint today gets a list and no way to choose. The catalogue it searches carries usage counters for every resource in it, and shows none of them at the point of the decision. There is no way to ask which of two candidates has a thousand distinct paying addresses and which has one.
This document is the rule behind an answer to that question: how a query becomes an ordered list, what each published figure is, and - the part that matters most - what it is not. Every number here is a count. None of them is a score, a grade, or a statement about anybody's intent.
One call per paying address can be a campaign. It can equally be a tool people try exactly once, or a single onboarding step. We cannot tell those apart, so we publish the ratio and the two numbers it came from, and we do not publish a conclusion. A service whose product is that the inputs travel with the figure cannot make an exception for figures about other people.
It is versioned because a ranking that can change silently has told its readers nothing they can rely on.
402rates x402 Directory Method
Version 1.0.0. The rule behind compass.discovery and the MCP tool find_x402_resource: how a query becomes an ordered list of other people's resources, what each published figure means, and what this service will not say about anyone.
1. What this is, and why the rule is written down
402rates publishes observations about named third parties. Done as arithmetic that is unremarkable; done as judgement it is defamation-shaped. The entire difference is in the rules below, so they are written down, versioned, and carried inside every answer.
The directory answers one question: which paid resource can answer this, what does it cost, and how broad is its paying base. It answers it from a stored snapshot of a public catalogue, and it says which day the snapshot is from.
Scope. This document governs search, ranking, and the figures published per result. It does not govern the yields 402rates computes - that is the Open Treasury Yield Basis, basis-spec-v1.
2. The source, and the boundary of what it can see
Every figure comes from the CDP x402 discovery catalogue (GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources), walked in full, without credentials, on a weekly schedule. Each resource in that catalogue carries the catalogue's own quality counters: total paid calls in the last 30 days, distinct paying addresses in the last 30 days, and the time of the last paid call.
Three limits follow, and all three appear in every answer:
- The catalogue counts only payments settled through it. A resource used
heavily through a different facilitator, or under a direct agreement between two parties, appears quiet here. Quiet is not absence of use.
- The figures are a snapshot, not a live reading. The answer names the day.
A directory that claimed to be as fresh as the request would be making the one false statement a directory cannot afford.
- 402rates does not verify what a provider says about itself. Descriptions
are the provider's own words, subject only to §9.
3. Indexed text, and the boundary rule
For each resource the snapshot stores two normalised strings:
haystack- the provider's description, service name, resource URL and tags,
concatenated, lower-cased, every run of non-alphanumeric characters replaced by a single space, and padded with one leading and one trailing space.
description_haystack- the description alone, normalised the same way.
A token matches only as a whole word. Because the stored form is padded and space-separated, the test LIKE '% token %' is the word-boundary test; there is no separate implementation that could disagree with it.
This rule exists because its absence has already cost a real number. In segment definition 1.0.0 a substring match placed a loyalty-voucher API on the domain loyalspark.online into the DeFi-lending segment, because the protocol name spark occurs inside the company name. Seven listings and roughly 4,200 calls of noise sat at the top of that segment. Under word boundaries the segment's traffic was 703 calls, not 7,217.
4. Matching
A query is lower-cased, split on non-alphanumeric characters, de-duplicated, tokens of fewer than two characters are dropped, and at most eight tokens are kept.
Every remaining token must match. There is no OR path.
There is no stemming, no lemmatisation and no synonym expansion. The visible cost is real and is stated rather than hidden: a query for yield does not match a description that says yields. The alternative - a ranking that cannot be explained by looking at the text - is worse for a directory whose entire value rests on being checkable, and worse still for one that also lists its own operator.
A query that matches nothing returns an empty result and the rule that was applied. There is no relaxed second search. A directory that answers "no" with something similar is worse than one that says nothing, because the caller cannot tell the two apart.
Optional filters, applied as conjunctions: max_price (USDC per call, inclusive; a resource with no readable USD price is excluded when this filter is present), network (a chain id the resource accepts payment on, matched whole), and limit (1 to 50, default 10).
5. Ranking
In order:
match_scoredescending - how many query tokens appear as whole words in the
provider's own description. Tokens matching only the URL, service name or tags qualify a resource but do not raise its rank: a word inside a domain name is not a statement about what an endpoint does.
unique_payers_30ddescending.calls_30ddescending.resourceascending, so two runs over one snapshot produce one order.
Why payers before calls. Calls can be produced from a single address; a broad base of distinct paying addresses cannot be produced as cheaply. That is the whole of the claim. It is not an assertion that payers are honest, or that a high payer count is a recommendation - only that of the two available figures it is the harder one to manufacture, and it should be read exactly that narrowly.
The scoring and the ordering are computed in the same statement that selects and truncates the candidates, so the truncation is over the final order and a better-matching resource cannot fall outside it. Where more resources match than were ranked, the answer says so and gives both counts.
6. The published figures
Each figure ships with its definition and with what it does not show. The raw numbers a ratio was computed from are published beside it, always, so a subject who disagrees can argue with the arithmetic rather than with an adjective.
calls_30d, unique_payers_30d
The catalogue's own counters, unmodified.
calls_per_payer
calls_30d ÷ unique_payers_30d, to three decimals; null when no address paid.
What it does not show: anything about intent or quality. A value near 1 means one call per paying address. That can be a campaign. It can equally be a tool everyone tries exactly once, a one-time onboarding step, or a resource whose callers each need one answer. 402rates cannot tell these apart and does not claim to. The ratio is published because a reader deciding between two resources is better off knowing it than not; it is published as a ratio and never as a label.
days_since_last_call
Whole days between the catalogue's last_called_at and the snapshot date.
What it does not show: whether the service is up, or whether it is used outside this catalogue. See §2.
match_score
The count from §5.1. What it does not show: relevance in any semantic sense. It is a word count, not an understanding of the question.
7. What is never published
No score, no grade, no rating, no ranking of "quality", no label describing anyone's intent, and no field whose name or value carries a verdict. Concretely, fields such as quality: "farming", suspicious: true, trust_score, or recommended will not appear in this response, in any version of it, whatever the figures say.
The reason is not caution about being sued. It is that we would be wrong: the data cannot distinguish the cases, and a service whose whole product is "the inputs travel with the figure" cannot publish a conclusion its own inputs do not support.
8. Self-listing
Resources operated by 402rates.com appear in this directory under exactly the same rule as every other entry, with no boost, no pinning and no separate section. A test in the repository asserts it by ranking a synthetic set in which our own entry would move if any preference existed.
A directory that sorts its operator upwards is advertising. The entire value of this one is that it is not.
9. Foreign text handed to a model
This is the first 402rates surface that repeats text written by other people to an agent that may act on it.
Every description is screened, at serve time, against the same anti-injection lint 402rates applies to its own published strings. A description that matches is withheld, not sanitised: the field is null, a description_withheld object states the reason and how many patterns matched, and the offending text is not echoed back, because echoing it is the delivery. The resource keeps its place in the results with all of its figures, and its URL is published so it can be inspected directly.
Screening happens when the answer is built, never when the snapshot is written, so a corrected pattern list takes effect without a new census run - and a description screened out today can be published tomorrow if the pattern that caught it is found to be wrong.
description_withheld is present on every result, null when nothing was withheld. A field that appears only when something is wrong teaches a consumer to ignore it until the one time it matters.
10. Empty is not unavailable
Two outcomes that look alike and mean opposite things:
| Outcome | Answer |
|---|---|
| The query matched nothing | HTTP 200, data: [], the rule that was applied |
| No snapshot exists, or the newest one predates this index | HTTP 503, SOURCE_UNAVAILABLE, with what would fix it |
A directory that answers the second with the first is telling a caller the catalogue is empty. It is the most useful-sounding wrong answer available to it, which is exactly why the distinction is in the specification rather than left to an implementer.
11. Versioning and change policy
DISCOVERY_METHOD_VERSION covers §3 to §6: the normalisation, the matching rule, the ranking order and the meaning of every published figure. It travels in every answer as meta.method.version.
- A change that can move a result's position or alter a figure's meaning is a
minor version at least.
- A change that removes a field or changes its type is a major version.
- Adding a field, or adding a filter that defaults to off, is a patch.
Two answers may only be compared when their method.version is identical. The version exists because a comparison across weeks is worth nothing if the rule moved between them - and because a directory that changes its ranking silently has told its readers nothing they can rely on.
SEGMENT_DEFINITION_VERSION, which governs the segment labels carried on each result, is versioned separately and for the same reason.
12. Corrections
Every figure here is a restatement of a public counter, so the usual correction is upstream: a resource's owner who believes a count is wrong should raise it with the catalogue operator, and the corrected figure reaches this directory at the next weekly snapshot.
Two things 402rates will correct directly, on notice, and record in 99_log/externe_befunde.md with the date:
- A misattribution - a row whose figures belong to a different resource.
- A withheld description that should not have been - §9 screening is a
pattern match and can be wrong. The pattern that caught it will be named.
402rates will not remove a resource from the directory on request while it is listed in the public catalogue, and will not adjust a ranking on request. Both would make every other figure in this document unreliable.