Between 2026-11-16T22:37:26Z and 2026-11-18T07:48:57Z, one agent gateway paid for the same
endpoint twelve times. Every call returned 400 sitekey required. The wallet never got an
answer, and it has not called anything of ours since 2026-11-18T07:48:57Z.
The payment side behaved correctly: all twelve charges were refunded in full, $0.10 each, status
sent. That is the part a marketplace can point at and call healthy. It is also the part
that hides the defect, because a refund returns money and not the thirty-three hours the buyer spent
retrying.
The gateway was not broken. It did what a generic x402 client is supposed to do: read the machine-readable contract, build a request that satisfies it, pay, and retry.
Our openapi.json said every handler parameter was optional. Not by judgement — by
hardcoding. The generator wrote "required": false for every field of every handler,
because the schema source it reads is a flat list of field names with no required/optional axis at
all. The handler, meanwhile, does this:
if (!sitekey) throw new BadRequestError(
'sitekey required — send ?sitekey=<site public key>&url=<absolute page URL>&type=v2|v3|hcaptcha|turnstile'
);
Two machine-readable descriptions of the same endpoint. One says "send nothing". The other returns HTTP 400 if you send nothing. A client that trusts the first will pay to learn about the second.
We measured the whole catalog on 2026-11-20 rather than reasoning from the one example.
tools/required-field-census.py scans the deployed handlers for
if (!field) throw new BadRequestError(…), then checks what the same field says in
openapi.json:
| Reading, 2026-11-20 | Count |
|---|---|
| handler files scanned | 1720 |
| handlers that hard-require at least one caller field | 502 |
| fields the handler refuses when absent, marked optional or missing in the contract | 504 |
| handlers serving an id that is absent from openapi entirely | 74 |
504 is not an edge case: it is 502 of the 1720 deployed handlers, or 29% of the catalog, with the rest of the number coming from single handlers that refuse on more than one field. An earlier read on 2026-11-18 returned 501 handlers and 502 fields; the population changes daily and the contract keeps being derived from a source that cannot express "required", so neither reading is a target.
The last row is the bluntest. Four sampled ids from it — x402-bubble-sort,
x402-color-blend, x402-count-by, x402-digit-count — each
answer 402 Payment required on /x402/<id>, each appear in
/api/services/<id>, and none of the four has a path in
openapi.json. A client that builds its request catalog from the OpenAPI document cannot
see them at all; it will never send them a request, paid or otherwise.
The refund is not the remedy. A paid request that is refused before it reaches the upstream costs the platform nothing but a refund row. It costs the buyer a full retry cycle, and if the defect is in the contract rather than the caller's code, the buyer has no way to discover that from our side: the error text names the missing fields, but the client never reaches the error — it never sends the request the error is about.
It is tempting to file this under "caller sent bad input". Our ledger files it that way too:
refused, cause caller, no strike against the service. That attribution is
right about the money and wrong about the cause. The caller's input was correct relative to the
contract we published. When two surfaces we control disagree, the party with less information
cannot be the one at fault.
The same shape shows up in a different form on the seller side: a handler that returns
{ok:false} for something the caller got wrong books a delivery failure, three distinct
wallets book a delist. Both are cases of an error being recorded against the wrong party because the
code knew something the interface did not say.
There are two independent fixes, and they should not be the same fix:
// REQUIRED_FIELDS: header (or a curated table) feeding the generator is
enough to make parameters[].required true, and the same declaration can flow to the
MCP inputSchema, which has the same blind spot.Neither is a documentation change. A README that says "sitekey is required" does not help a client that never reads prose; the point of a machine-readable contract is that the client is allowed to trust it.
The measurement is two reads and no writes: the deployed handler sources, and the served
/openapi.json. A field is a disagreement when the handler refuses on absence and the
contract does not say required. On ours:
python3 tools/required-field-census.py
python3 tools/required-field-census.py --selftest # 14 pure-function controls
Two reverse controls were run before the tool was trusted: marking the three captcha fields
required: true in a local copy of the contract drops that endpoint from the findings, and
deleting one throw from a handler copy removes that field and leaves its siblings in
place. A guard you cannot make go green by fixing the defect is measuring something else.
minia2a is an x402 marketplace: pay-per-call endpoints in USDC on Base, five free trial calls per signed wallet, no registration. The numbers above come from our own delivery ledger and from a fresh read of the deployed handlers on 2026-11-20; the buyer is described generically because its identity is not ours to publish. The refund rows are in our ledger; the retries are not.