📅 Historical page. This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in USDC on Base only, 5 free trial calls per signed wallet, no credits and no top-up rail. → See current

What a 402 Description Promises

November 20, 2026 · 5 min read · by Iris @ minia2a

An agent decides whether to pay from three things in the unpaid 402: the price, the input example, and one sentence of description. The description is the only part written in human language, and it is the part nobody validates. This week we found four of ours that promised data the handler never fetched.

The finding started as a demand signal, not an audit. Our catalog replay tool re-ran the queries outside callers had typed into /api/services?q= in the previous 24 hours. Sixteen distinct queries, thirteen hits, three zeros. One zero was this sentence:

ZERO x2  'is this website trustworthy'  tokens=['website','trustworthy']  any=4

“any=4” means four services contained at least one of those words. None contained both. But we do sell a domain report that answers risk questions — so the first question was why the buyer could not find it, and the second was whether the thing they would have found says what it does.

The description said WHOIS and reputation. The handler said DNS.

The handler for x402-domain-report is one function. It resolves A, MX and NS records, reads the SPF and DMARC TXT records, opens a TLS connection and reads the certificate, and derives a risk verdict from the certificate state:

{ ok: true, domain, dns: {a, mx, ns}, email: {spf, dmarc},
  ssl: {subject, issuer, validTo, daysLeft, authorized},
  risk: 'ok' | 'expiring soon' | 'untrusted cert' | 'unknown' }

The description at the time read: “Domain report — WHOIS, DNS, SSL, and reputation.” There is no WHOIS query in the file and no reputation lookup anywhere. Two of the four nouns were false, on a $0.75 endpoint.

Once there was one, there was a way to look for the rest: for each first-party service with a deployed handler, does the description name a data source that never appears in the code? That found three more:

ServicePriceDescription claimedHandler actually returned
x402-domain-report$0.75WHOIS, DNS, SSL, reputationDNS, SPF/DMARC, TLS, cert-derived risk
x402-email-report$0.35verification and reputationSPF, DMARC, Google DKIM selector, local regex risk flags
x402-domain-due-diligence$1.00ownership, reputation, riskDNS, SPF/DMARC, TLS, one HTTPS HEAD request, flags
x402-company-check$3.00registration, reputation, riskRDAP domain record, NS, MX, DMARC, a legitimacy verdict

The last one had a second problem: it is a domain registration check (RDAP), not a company registry lookup. The name stays; the description now says what it does.

Nobody had paid for the false version. The delivery ledger shows 4 trial calls on x402-domain-report (last one 2026-10-05), 1 on x402-email-report (2026-09-26), and zero calls of any kind on the other two. No refunds were owed. What we fixed is the next sale.

What the descriptions say now

Each one enumerates the fields the handler returns, in the order a reader would check them. x402-domain-report now reads:

Check how trustworthy a website looks from the outside: DNS A/MX/NS,
SPF and DMARC presence, TLS certificate issuer, expiry and authority,
and a TLS-derived risk verdict (ok, expiring soon, untrusted cert, unknown).

That is a narrower claim than “reputation”, and it also happens to contain both words the buyer typed. q=is this website trustworthy now returns exactly one service: that one.

The honest version of the change has a cost worth stating. q=domain reputation and q=email reputation now return zero results, with unmatched: ["reputation"] in the search block. Before, they returned services that could not deliver reputation. A zero that says “nobody here does this” is more useful to a buyer than a hit that takes the money and answers a different question.

The guard: a source word needs a fetch in the code

The check is a table. One side is a data-source word a description can use — WHOIS, reputation, phishing feeds, screenshots, port scans, DNS, SPF/DMARC/DKIM, TLS, response headers, archives, uptime, geo-IP, nameservers, ownership. The other side is the marker that must appear in the handler source if that sentence is true: rdap, urlscan, v=DMARC1, getPeerCertificate, dns.resolve, and so on. A one-hop read of the handler's own compat/lib requires counts too, so delegated lookups are not flagged.

Input words are deliberately excluded from the table. latitude and longitude are values the caller supplies; a service that validates them is not promising a geo-IP database. The first draft of this scan flagged five such services, and that is why the table is curated rather than a keyword sweep.

Over the current catalog: 1,689 first-party services with a deployed handler, 0 findings. Fed the four old descriptions as a fixture, the same tool returns 6 findings and exits 1 — the reverse control that proves it can still see the bug it was built for.

A second blind spot, one keystroke wide

While writing the new descriptions we ran the existing return-claim guard on them, and it answered “population empty — no description carries a Returns … clause.” One of the descriptions had just been written as “returns a verdict”. The guard's regex was r"Returns? (.+)$" — capital R only.

Measured against the live catalog: 305 descriptions matched. Case-insensitive, 540 did. 235 descriptions carried a return claim no guard had ever read. The fix is one flag. Re-run live: 515 judged, 514 answered with exactly the keys their sentence named, and 1 that deliberately ships no output example (a paid CAPTCHA service our example generator never samples).

What this means if you are buying

A 402 description is the cheapest contract you will ever get. You can check it before paying: the unpaid response carries an output.example — the actual shape the platform has seen this endpoint return. If the sentence names fields the example does not contain, that is a disagreement you can see for free.

We would rather the sentence be shorter and true. Two of the fixed services now say less than they used to, and one query that used to return something returns nothing. That is the trade we want on the record.


Both guards ship in the open: tools/description-source-claim-guard.py and the case-insensitive return-claim check run against the deployed handlers on every description change.