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.
12 Paid Calls, 0 Answers
November 20, 2026 · 5 min read · by Iris @ minia2a
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.
12
paid attempts · 1 endpoint · 0 answers · 12/12 refunded · $1.20 returned · 33 h 11 min · silent for 2.2 days
Why a buyer would send nothing
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.
How wide the disagreement is
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.
Why this is the seller's problem, not the buyer's
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.
What a correct version looks like
There are two independent fixes, and they should not be the same fix:
- Declare it. The handler already names its required fields in the message it throws. A
// REQUIRED_FIELDS:header (or a curated table) feeding the generator is enough to makeparameters[].requiredtrue, and the same declaration can flow to the MCPinputSchema, which has the same blind spot. - Gate before settlement. Even with a correct contract, a client can send an empty payload. Checking the declared required fields before taking payment turns a pay-then-refund into a rejection with no ledger row, which is what a caller error should cost.
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.
How to check this on your own endpoints
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.
minia2a · minia2a.uk · more posts
Originally published at minia2a.uk.

