Discovery probe silently rejects valid V1 body when V2 PAYMENT-REQUIRED header is malformed

[dadang11]

Summary

In @agentcash/discovery (used by x402scan via apps/scan/src/lib/discovery/probe.ts), the probeMethod function tries parsePaymentRequiredBody2 (V2 header parser) first, but does not fall back to parsePaymentRequiredBody (V1 body parser) when V2 parse returns null. Servers that ship a valid V1 body alongside a malformed V2 payment-required header are silently rejected as "No valid x402 response found".

This is a common transitional pattern in the early x402 ecosystem: many servers emit both formats for client compatibility, but the V2 header construction can be subtly wrong (e.g. base64 of a raw accepts array instead of the proper { x402Version: 2, accepts, extensions } envelope).

Repro

Any server that returns:

HTTP/1.1 402 Payment Required
Content-Type: application/json
payment-required: <base64 of raw accepts array, NOT a V2 envelope>

{"x402Version":1,"accepts":[{...valid V1 fields...}]}

Hits registerFromOrigin and gets "No valid x402 response found" even though the body is V1-valid.

Root cause

packages/.../core/source/probe/index.ts, around probeMethod:

const headerValue = response.headers.get("payment-required");
const parsed = headerValue !== null
  ? parsePaymentRequiredBody2(headerValue)
  : await parsePaymentRequiredBody(response);

When headerValue !== null but parsePaymentRequiredBody2 returns null (e.g. payload is an array, not an object envelope, so isRecord fails), parsed = null and the V1 body is never inspected.

Proposed fix

Always try V1 body when V2 header parse returns null:

const headerValue = response.headers.get("payment-required");
let parsed = headerValue !== null ? parsePaymentRequiredBody2(headerValue) : null;
if (parsed === null) {
  parsed = await parsePaymentRequiredBody(response);
}

Pure additive fallback. V2-only servers unaffected. V1-only servers unaffected. Previously-failing dual-format servers now succeed.

Discovered while

Integrating CryptoIZ MCP (Solana whale intelligence, 9 tools, 7 paid) with x402scan. Our gateway emitted V1 body + V2 header. After diagnosing this bug from the source of @agentcash/discovery@1.6.3, we patched our Cloudflare Worker to drop the malformed V2 header so V1 body fallback kicks in. Result: registration went from 0 registered, 9 failed → 7 registered, 0 failed.

Reference listing: https://x402scan.com/server/cbd8fff5-d636-4331-b22b-3291717a4e9e

Why fix matters for ecosystem

Many builders shipping x402 MCP servers in early 2026 emit dual format for safety. Without this fallback, x402scan silently misses them. Our team only diagnosed it because we were debugging our own listing — most builders will just see "failed" without knowing why.

Happy to submit a PR if/when the discovery package opens up. For now, flagging as a tracking issue here at x402scan since this is the surface where the symptom appears.

cc @merit_systems team — would love a quick look.

[dadang11]

Pinging maintainers for visibility — happy to provide more repro detail or work with whoever owns the discovery package on a patch.

@0xMasonH @jsonhedman @rsproule @samrags_ @zdql_Reproducible against @agentcash/discovery@1.6.3. Diff between malformed-header vs no-header is documented in the PR description.

[Bortlesboat]

Adding a concrete fixture shape that would catch this and keep the fallback behavior tight:

HTTP/1.1 402 Payment Required
content-type: application/json
payment-required: <base64url(JSON.stringify(validV1AcceptsArray))>

{x402Version:1,accepts:[{scheme:exact,network:eip155:8453,maxAmountRequired:10000,resource:https://example.com/paid,description:fixture,mimeType:application/json,payTo:0x0000000000000000000000000000000000000001,maxTimeoutSeconds:60,asset:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913}]}

Expected result: treat the malformed v2 header as non-authoritative, parse the valid v1 body, and register the resource with a warning like invalid_payment_required_header instead of failing as No valid x402 response found.

I would pair it with two negative fixtures:

• malformed v2 header + malformed/missing body => still fails
• valid v2 header + conflicting v1 body => v2 header wins, with no fallback ambiguity

Patch shape still looks as small as:

const headerValue = response.headers.get(payment-required);
let parsed = headerValue !== null ? parsePaymentRequiredBody2(headerValue) : null;
if (parsed === null) {
  parsed = await parsePaymentRequiredBody(response);
}

The important bit is that a bad transitional v2 header should not shadow an otherwise valid v1 body. That gives builders a migration path without making scanners silently drop real paid endpoints.

[dadang11]

Excellent diagnosis @Bortlesboat — your two-fixture matrix (malformed-both / valid-V2 vs conflicting-V1) is exactly the right test discipline. The fallback semantics you proposed make sense: V2 header should be authoritative when valid, but a transitional malformed V2 must not shadow an otherwise valid V1 body.

Quick update from the server side: while debugging this same issue against mcp.cryptoiz.org we ended up tracing it through @x402/core 2.9.0's getPaymentRequiredResponse and @agentcash/discovery 1.6.3's parsePaymentRequiredBody2. Confirmed the silent-drop path triggers because parsePaymentRequiredBody2 returns null for any payload that's missing x402Version: 2, with no V1 fallback. So a server emitting payment-required: <base64(rawAcceptsArray)> ends up looking like "no paid endpoint" to scanners even though the V1 body is fine.

On our end we just shipped a server-side fix: gateway v50 now emits the V2 header as a proper { x402Version: 2, error, resource: { url, description, mimeType }, accepts: [v2PaymentRequirements] } envelope, alongside the existing V1 body. That unblocks both x402scan probing AND agentcash fetch without waiting on a parser change. But the parser-side fallback you proposed is still the right ecosystem fix — there are several other endpoints I bumped into during debugging that are emitting the raw-array form and getting silently dropped today.

Happy to provide before/after probe logs and a live endpoint to test against if helpful for the test fixtures. Will report back here once x402scan's next probe cycle picks up the v50 deployment.

[Bortlesboat]

Yeah, drop the live endpoint and I'll run it.

Most useful comparison: v50 valid-envelope (should pass V2 parser) plus a saved capture of the pre-v50 malformed-header-with-valid-V1-body shape — that second one is the fixture the parser-side fallback would actually catch.

If you have a paid v50 route, I can hit it both raw and via npx agentcash@latest fetch and post structured logs. agentcash exposes whether the silent-drop happens at parse or at spend-attempt, which is useful for separating discovery-side bugs from registry-side ones.