docs(x402): note v2 Payment-Signature header + payment-on-failure caveats#1103
Open
PaulieB14 wants to merge 2 commits into
Open
docs(x402): note v2 Payment-Signature header + payment-on-failure caveats#1103PaulieB14 wants to merge 2 commits into
PaulieB14 wants to merge 2 commits into
Conversation
Two costly footguns for new x402 integrators that aren't covered today:
1. Protocol version. The gateway is x402 v2, so payments must be sent in
`Payment-Signature` (not v1's `X-PAYMENT`). v1 SDKs that sign correctly
still receive 402 "Payment-Signature header is required". The current
"any x402 tooling that supports exact scheme will work" line implies
v1 compatibility — adding an explicit callout pointing v1 users at
`@graphprotocol/client-x402` (or a v2-aware upgrade).
2. Payment-on-failure. Two real cases where USDC is charged but the caller
gets no usable data:
- Valid subgraph_id with zero active indexer allocations → returns
`{"errors":[{"message":"subgraph not found: no allocations"}]}` with
payment settled.
- Any errors-shaped GraphQL response (bad shape, schema mismatch, etc.)
is still settled.
Both surprise first-time agent integrators. Added a `## Caveats` section
with a Graph Network Subgraph query agents can use to pre-check active
allocations before paying.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two real footguns hitting agent integrators of the
/api/x402/...endpoints that aren't covered in the current guide:1. Protocol version (v2 header)
The gateway implements x402 v2 — payments must be sent in a
Payment-Signatureheader, not v1'sX-PAYMENT. Verified live againstgateway.thegraph.com/api/x402/subgraphs/id/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV:X-PAYMENT: <base64>→402 Payment-Signature header is requiredPayment-Signature: <base64>→200 OKwith dataThe current line "Any x402 tooling that supports exact scheme will work with the gateway's x402 endpoints" is misleading for v1 SDKs, which sign correctly but still get 402'd. The added callout under How It Works points v1 users at
@graphprotocol/client-x402or a v2-aware upgrade.2. Payment-on-failure cases
USDC settles even when the gateway returns no usable data:
subgraph_idwhose deployment has no indexer allocations returns{"errors":[{"message":"subgraph not found: no allocations"}]}with payment settled.errors(bad query shape, schema mismatch, etc.) is also settled.Added a
## Caveatssection so agent integrators know to pre-check active allocations against the Graph Network Subgraph, and to validate query shape againstget_schema_by_subgraph_idbefore paying. Both can be done cheaply / for free and avoid burning real USDC.Test plan
Payment-Signatureagainst four deployments (Uniswap V3 on ETH/Polygon/Arbitrum/Base) — all returned 200 + data after settlement; one returned errors after settlement (different schema variant), confirming the "errors still cost" point.QmWFi6uciaQPQmo1xRrahNwfiWLGeN9GTDJMuCfV8iVXSe(Substreams Uniswap v3 Ethereum) — valid registry ID, no active indexers, $0.01 settled with no data.