Skip to content

Our x402 extension was missing the one field the facilitator drops services for

We read the canonical spec instead of assuming our shape was fine. Six of our paid endpoints would have been discarded on contact.

2026-09-281129 words5 min read

We sell six paid API endpoints. Each returns a proper HTTP 402 with a PAYMENT-REQUIRED header carrying a Bazaar extension, which is the metadata format a facilitator is supposed to use when it catalogues x402 services.

Every one of the six is wrong in the same way.

We had never read the canonical specification. We built a shape that looked plausible, it returned valid JSON, and it looked like metadata. So we went and read what the facilitator actually documents, and compared it field by field against what we were emitting.

Six discrepancies. Three of them are named in the spec's own list of common mistakes.

What the spec says

The Bazaar extension is how a facilitator learns what an endpoint does before anyone calls it. The spec is explicit about the most frequent failure:

Common protocol-level mistakes include: 1. The settled PaymentPayload did not carry the extension. 2. missing info.input.type / info.output.type (when output is present) 3. a relative resource.url — use an absolute URL

The canonical resource shape:

"extensions": {
  "bazaar": {
    "info": {
      "input":  { "type": "http", "method": "GET",
                  "queryParams": { "city": "San Francisco" } },
      "output": { "type": "json",
                  "example": { "city": "San Francisco", "weather": "foggy", "temperature": 60 } }
    }
  }
}

And the consequence, stated plainly in the spec:

Facilitators validate the payload before cataloging; non-conforming content may be dropped even when verify and settle succeed.

Read that again. Verification and settlement can both pass, the money can move, the caller can get their data — and the service still never enters the catalogue. Payment success is not cataloging.

What we were actually emitting

Decoded from the live PAYMENT-REQUIRED header on GET /api/quote, all six endpoints identical in structure:

{
  "method": "GET",
  "schema": {
    "properties": {
      "input":  { "type": "object",
                  "properties": { "query": { "type": "object",
                    "properties": { "symbol": { "type": "string", "default": "btc,eth,sol" } } } } },
      "output": { "type": "object",
                  "properties": { "example": { "type": "object" } } }
    }
  },
  "outputType": "application/json",
  "title": "Munchausen Lab — quote",
  "description": "real-time market quote ($0.01)"
}

No info. No input.type. No output.type. The parameters live at schema.properties.input.properties.query.properties instead of input.queryParams. The "example" is a bare { "type": "object" }, which is a type annotation where the spec wants an actual response.

The field-by-field comparison

#FieldSpecOursVerdict
1inforequired objectabsentcritical
2input.type"http" or "mcp"absentcritical
3input.methodinside inputat bazaar top levelmismatch
4parametersinput.queryParams / input.bodyParams`schema.properties.input.properties.{query\body}`mismatch
5output.type"json" when output presentabsent (only outputType)critical
6output.examplea real example response{ "type": "object" }mismatch
7outputType, titlenot in the specpresentharmless extras
8resource.urlabsoluteabsolutecorrect
9accepts[].amountatomic units, stringstringcorrect

Three of the six are exactly the fields the spec names as the most common mistake. None of them is a soft-drop candidate. Our shape is not a superset of the spec's with extras — it is a different structure that happens to be valid JSON.

Two endpoints were never the problem

Worth separating, because the fix is smaller than the discrepancy list suggests.

Two of our six endpoints take no parameters at all. For those, a minimal declaration is correct per the spec, and the empty input we emit is the right shape. So of the six discrepancies, the ones that are actually about content rather than form apply to four endpoints.

What is missing from all six regardless: info, input.type, output.type, queryParams / bodyParams, and a real output.example.

We built the example values from actual observed responses rather than inventing them — the free-tier call we already serve returns the same structure with real prices in it. One caveat we stated and are restating here: two fields in the analysis example were type-matched illustrative placeholders, not observed values. Everything else in it is fact.

The second problem, which is worse

Correcting the shape is necessary and not sufficient. Spec item 1:

The settled PaymentPayload did not carry the extension. Cataloging happens when a facilitator processes a PaymentPayload that includes the echoed bazaar extension and paymentPayload.resource.

So declaring metadata on our server catalyses nothing on its own. Cataloging is triggered by a settled payment whose payload echoes our extension back.

Two consequences:

  1. The fix has to ship, and then one real payment has to happen, or nothing appears in the catalogue

regardless of how correct the form is.

  1. We have no settled-payment counter anywhere. Our stats track issued 402 challenges, which is not

the same thing, so we had no way to tell a quiet service from a listed one.

Why we could not get a validation verdict

The facilitator exposes POST /platform/v2/x402/validate, which would confirm whether our metadata passes. All six resources return HTTP 400 with an identical body:

{"errorMessage":"this feature is not available in your region","errorType":"invalid_request"}

Six for six, not one differing. That is a fixture, not an endpoint fault — the response is cut at a geographic gate before schema validation runs. We cannot get a valid: true from here at all.

That limit is worth stating plainly because it is the kind of thing that gets quietly reported as "validation passed" when nobody actually read the body. We have no validation verdict, in either direction.

The verdict

No-go on claiming indexation. Conditional go on the fix.

The form is non-conforming and will be dropped. Spending on a test payment before fixing the form would have been waste — the facilitator discards the metadata either way. The sequence is: fix the shape, deploy, get a validation verdict from a non-blocked region, and only then pay once to check for catalogue presence.

No code was changed for this writeup. Deployment was deliberately out of scope.

Why this is public

This is the third post in a row where the finding was a defect in our own system, and the second where we had assumed our output was fine because it looked right. Valid JSON, correct HTTP status, a metadata extension present — and structurally wrong in the exact three places the spec warns about.

Any vendor publishing paid endpoints to agents should read that spec list before shipping. It is short, and it names the failure before you spend money finding out.

All articles