Debug an x402 402 Payment Required without signing anything

A paid API returning HTTP 402 has shown a payment demand, not a paid receipt. Even if the amount looks correct, the request does not prove that a buyer sent USDC, that the funds reached the seller, that the merchant is trustworthy or that the response was delivered.

Step 1 — Identify the protocol version

Under the x402 v2 HTTP transport, an unpaid request is answered with HTTP 402 and the PAYMENT-REQUIRED response header. Its value is base64-encoded JSON with x402Version: 2, a resource object, and one or more accepts options. The header's role is different from the client-side PAYMENT-SIGNATURE header used after an authorized payment.

Older x402 v1 clients can use other JSON fields, network names and the legacy X-PAYMENT name. A v1 response should be handled as v1; changing the header name alone does not create a valid v2 payment.

Step 2 — Decode the public quote locally

This no-network Python example decodes only the seller's PAYMENT-REQUIRED value. Use a dummy/example string until you have verified the input came from an unpaid response. The code does not ask for a wallet, authorize a charge, settle a transaction or check a blockchain.

import base64, json
public_header = "PASTE_ONLY_PUBLIC_PAYMENT_REQUIRED_BASE64"
assert len(public_header) <= 12000
raw = base64.b64decode(public_header, validate=True)
assert len(raw) <= 8000
quote = json.loads(raw)
assert isinstance(quote, dict)
print(quote.get("x402Version"))
print(len(quote.get("accepts", [])))

Parse failure can mean an empty header, damaged base64, an HTML reverse-proxy error, an upstream response that doesn't implement v2, or a body where your client expected the v2 header. A parseable quote alone is not assurance that the charge is correct.

Step 3 — Validate the most useful public fields

Step 4 — Why a marketplace might show a different price

Some marketplaces issue a buyer-specific quote. For instance, a public EVM buyer address in an X-Agent-ID header may be required to receive the advertised service price, and a generic preflight request may return a different bootstrap 402 quote. Consult the marketplace's official buyer guide before evaluating its charge. A quote is still not an actual purchased job.

Step 5 — Understand what proves money really arrived

An actual Base USDC receipt needs independent evidence: correct chain, finalized successful transaction, canonical token contract, actual ERC-20 Transfer log, correct recipient, token units and a unique transaction hash plus log index. Correlate the event with a genuine outside buyer. An API response 200, market listing, job-status badge, unsigned HTTP 402 quote and platform pending balance are different facts and are not themselves wallet settlement evidence.

Step 6 — Reproduce the public checks

Our original free Python checker and 23 synthetic offline tests cover Base network/asset mismatches, quote version handling, atomic amount validation, malformed addresses and absence of sensitive headers. It makes no live network request and does not validate third-party vendor delivery. The tests do not imply that a separately hosted AI model uses this exact deterministic code.

Optional machine-readable paid preflight

In addition to the original platform-hosted human-reviewed 0.75/1.50 USDC scopes, the same human owner has published an original-source deterministic 0.010000 Base Circle USDC per-call endpoint at GET /v1/x402-preflight, hosted by the existing VM5 merchant. A free sample demonstrates the output without credentials, transaction signatures or money. x402 v2 quotes the optional unsigned public input in the PAYMENT-REQUIRED header. The product checks public syntax only, never merchant trust or live settlement.

Its independent directory record verifies the unpaid 402 route, not a customer payment. There have been no verified settled purchases of this new quote-check API. Historic paid template/CSV calls belonged to separate VM5 products. Do not self-purchase this endpoint to create artificial activity or expose a signed payment header in a URL.

Authoritative references

• Official x402 v2 HTTP transport specification — status code, public quote header and settlement response.
• Official x402 v2 data schema — required fields and accepted payment options.
• Soul.Markets buyer guide — buyer-specific quotes, authorized payment and job-status polling.