Skip to content

docs: 402 body now mirrors the x402 challenge (x402Version, accepts) - #67

Closed
VickyXAI wants to merge 2 commits into
mainfrom
docs/x402-body-parity
Closed

docs: 402 body now mirrors the x402 challenge (x402Version, accepts)#67
VickyXAI wants to merge 2 commits into
mainfrom
docs/x402-body-parity

Conversation

@VickyXAI

Copy link
Copy Markdown
Contributor

Summary

BlockRun's gateway now spreads x402Version/accepts at the top level of every 402 JSON body, in addition to the signed PAYMENT-REQUIRED/X-Payment-Required/WWW-Authenticate headers — see BlockRunAI/blockrun#TBD for the code change. Pre-v2-era x402 clients (early x402-fetch/x402-axios, third-party wrappers) only ever parsed the body and, finding no top-level accepts, silently gave up instead of auto-paying.

This PR brings every doc's 402 example in line with the new body shape:

  • docs/api-reference/errors.md — canonical 402 shape + new explanatory paragraph
  • docs/x402/payment-flow.md — the "402 Response" step now shows the mirrored fields, with a note on what the headers carry that the body mirror omits (resource, extensions)
  • docs/x402/how-it-works.md — one-line update to the "requirements are base64-encoded..." paragraph
  • All 12 endpoint reference pages with a 402 example (chat-completions, defillama, exa-search, image-generation, modal-sandbox, polymarket-funding, realface, responses, search, text-to-speech, video-generation, virtual-portrait) + music-generation

While touching docs/api-reference/responses.md I also picked up an upstream fix already on main (fee-inclusive price.amount wording) via the merge — no separate action needed, just noting it so the diff isn't a surprise.

Not in this PR

.gstack/* local browse-session artifacts have unrelated pre-existing local diffs on this machine and are left out.

Test plan

  • Spot-check the rendered docs site for the touched pages
  • Confirm the blockrun PR (code + tests) merges around the same time so the two stay in sync

1bcMax added 2 commits August 30, 2026 21:39
BlockRun's 402 responses now spread x402Version/accepts at the top level
of the JSON body, not just the signed headers — v1-era x402 clients that
only parse the body were silently failing to auto-pay. Updates every
endpoint doc's 402 example plus the x402 protocol pages to match.
@VickyXAI

Copy link
Copy Markdown
Contributor Author

Closing as already shipped: this branch was the base of #68, so its commits went to main inside that squash (6b4c84f) — docs/x402/how-it-works.md and docs/x402/payment-flow.md are live. Nothing here is lost; reopen if you see anything missing.

@VickyXAI VickyXAI closed this Aug 31, 2026
@VickyXAI
VickyXAI deleted the docs/x402-body-parity branch August 31, 2026 03:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant