x402: Payment requirements parsing assumes JSON body, but spec allows headers

[jelilat]

While working with the x402 SDK and interacting with an x402 API facilitator, I ran into the following runtime error:

Cannot read properties of undefined (reading 'map')

Tracing this back, the error originates from this line in fetchWithPayment.ts:

const parsedPaymentRequirements = accepts.map((x) =>
  RequestedPaymentRequirementsSchema.parse(x),
);

In this case, accepts was undefined.

Root cause

The wrapper currently assumes that x402 payment requirements are always returned in the response JSON body, via:

const { x402Version, accepts, error } = await response.json();

However, according to the x402 spec and some facilitator implementations, payment requirements may also be returned via response headers (for example to support non-JSON responses, streaming endpoints, or HEAD requests).

When the facilitator returns requirements in headers instead of the body, accepts is undefined, leading to the error above.

A better approach would be to:

1. Check response headers for x402 payment requirements first
2. Fall back to parsing the JSON body if headers are not present
3. Normalise both paths into the same internal structure before calling .map()

This would make the wrapper compatible with a wider range of x402 facilitators and avoid runtime errors for valid responses.

[linear]

BLD-540

[joaquim-verges]

thanks for the report @jelilat - will look into this

[jelilat]

thanks for the report @jelilat - will look into this

fixed it here