From 07d505219e51d01ffeaa57566662ed20ce6f8a2d Mon Sep 17 00:00:00 2001 From: PaulieB14 <94752445+PaulieB14@users.noreply.github.com> Date: Fri, 15 May 2026 22:04:28 -0400 Subject: [PATCH 1/4] docs(x402): note v2 Payment-Signature header + caveats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../en/subgraphs/guides/x402-payments.mdx | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/website/src/pages/en/subgraphs/guides/x402-payments.mdx b/website/src/pages/en/subgraphs/guides/x402-payments.mdx index d696c104bd58..0bc47abc67ed 100644 --- a/website/src/pages/en/subgraphs/guides/x402-payments.mdx +++ b/website/src/pages/en/subgraphs/guides/x402-payments.mdx @@ -25,6 +25,8 @@ The existing API-key endpoints continue to work unchanged with x402 is an additi 3. The client signs a USDC payment payload and retries the request with the payment header. 4. The Gateway verifies the payment via a facilitator and returns the query result. +> **Protocol version:** The gateway implements **x402 v2**. The signed payment payload must be sent in a `Payment-Signature` header (base64-encoded JSON containing `x402Version`, `accepted`, and `payload`). x402 v1 clients that send only `X-PAYMENT` will receive `402 Payment-Signature header is required` even after signing — use a v2-aware client such as `@graphprotocol/client-x402` or upgrade your SDK. + ## Network Environments | Environment | Base URL | Payment Network | USDC Token Address | @@ -64,6 +66,32 @@ x402 is well suited to: For sustained, high-volume application use, the existing API-key flow remains the recommended path. +## Caveats + +### Payment applies even when no indexer is serving the Subgraph + +A valid `subgraph_id` or `deployment_id` is not a guarantee that any indexer is currently allocated to it. When no indexer is serving the deployment, the gateway responds with `200 OK` and the payload: + +```json +{ "errors": [{ "message": "subgraph not found: no allocations" }] } +``` + +The USDC payment is still settled — there is no refund. To avoid charging for known-unserved deployments, check active allocations against the Graph Network Subgraph before paying: + +```graphql +{ + subgraphDeployment(id: "") { + indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { id } + } +} +``` + +If `indexerAllocations` is empty, no one is serving it — paying will produce the error above. Agent-side discovery layers should treat "0 active allocations" as an unservable Subgraph and either skip it or surface the warning. + +### Errors still cost USDC + +Any response from the gateway that includes a `Payment-Response` header has been settled on-chain. This includes responses containing GraphQL `errors` (bad query shape, missing fields, schema mismatch, "no allocations", etc.). Validate queries against `get_schema_by_subgraph_id` or a cached schema before paying. + ## Minimal Examples ### Using API Key From 5519bec6bc6b56f846a169958fadca9fe51f3a7c Mon Sep 17 00:00:00 2001 From: PaulieB14 <94752445+PaulieB14@users.noreply.github.com> Date: Fri, 15 May 2026 22:14:02 -0400 Subject: [PATCH 2/4] style: prettier --write --- website/src/pages/en/subgraphs/guides/x402-payments.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/src/pages/en/subgraphs/guides/x402-payments.mdx b/website/src/pages/en/subgraphs/guides/x402-payments.mdx index 0bc47abc67ed..b89f10c8d558 100644 --- a/website/src/pages/en/subgraphs/guides/x402-payments.mdx +++ b/website/src/pages/en/subgraphs/guides/x402-payments.mdx @@ -81,7 +81,9 @@ The USDC payment is still settled — there is no refund. To avoid charging for ```graphql { subgraphDeployment(id: "") { - indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { id } + indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { + id + } } } ``` From ce70e77188e666ab297f475bc9e262acea40f1c2 Mon Sep 17 00:00:00 2001 From: Brandon Kramer Date: Fri, 20 Nov 2026 11:43:29 -0500 Subject: [PATCH 3/4] docs(x402): fix allocation check query, generalize schema advice, apply house style --- .../pages/en/subgraphs/tooling/x402-payments.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx index b89f10c8d558..6a80926b0bc0 100644 --- a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx +++ b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx @@ -16,7 +16,7 @@ The Graph's x402 Subgraph endpoints enable: - **No API keys, accounts, or sessions**: payment and access happen in a single HTTP round trip - **Compatible with any x402 client**, with first-class support via `@graphprotocol/client-x402` -The existing API-key endpoints continue to work unchanged with x402 is an additional access path under `/api/x402/...`. +The existing API-key endpoints continue to work unchanged. x402 is an additional access path under `/api/x402/...`. ## How It Works @@ -25,7 +25,7 @@ The existing API-key endpoints continue to work unchanged with x402 is an additi 3. The client signs a USDC payment payload and retries the request with the payment header. 4. The Gateway verifies the payment via a facilitator and returns the query result. -> **Protocol version:** The gateway implements **x402 v2**. The signed payment payload must be sent in a `Payment-Signature` header (base64-encoded JSON containing `x402Version`, `accepted`, and `payload`). x402 v1 clients that send only `X-PAYMENT` will receive `402 Payment-Signature header is required` even after signing — use a v2-aware client such as `@graphprotocol/client-x402` or upgrade your SDK. +> **Protocol version:** The Gateway implements **x402 v2**. Send the signed payment payload in a `Payment-Signature` header (base64-encoded JSON containing `x402Version`, `accepted`, and `payload`). x402 v1 clients that send only `X-PAYMENT` receive `402 Payment-Signature header is required`, even after signing. Use a v2-compatible client such as `@graphprotocol/client-x402`, or upgrade your SDK. ## Network Environments @@ -68,19 +68,19 @@ For sustained, high-volume application use, the existing API-key flow remains th ## Caveats -### Payment applies even when no indexer is serving the Subgraph +### Payment applies even when no Indexer is serving the Subgraph -A valid `subgraph_id` or `deployment_id` is not a guarantee that any indexer is currently allocated to it. When no indexer is serving the deployment, the gateway responds with `200 OK` and the payload: +A valid `subgraph_id` or `deployment_id` does not guarantee that any Indexer is currently allocated to it. When no Indexer is serving the deployment, the Gateway responds with `200 OK` and this payload: ```json { "errors": [{ "message": "subgraph not found: no allocations" }] } ``` -The USDC payment is still settled — there is no refund. To avoid charging for known-unserved deployments, check active allocations against the Graph Network Subgraph before paying: +The USDC payment is still settled, and there is no refund. To avoid paying for a deployment that no Indexer is serving, check for active allocations in the [Network Subgraph](https://thegraph.com/explorer/subgraphs/DZz4kDTdmzWLWsV373w2bSmoar3umKKH9y82SUKr5qmp?view=Query&chain=arbitrum-one) before paying. Use the deployment ID (`Qm...`) as `ipfsHash`: ```graphql { - subgraphDeployment(id: "") { + subgraphDeployments(where: { ipfsHash: "" }) { indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { id } @@ -88,11 +88,11 @@ The USDC payment is still settled — there is no refund. To avoid charging for } ``` -If `indexerAllocations` is empty, no one is serving it — paying will produce the error above. Agent-side discovery layers should treat "0 active allocations" as an unservable Subgraph and either skip it or surface the warning. +If `indexerAllocations` is empty, or no deployment is returned, no Indexer is serving it and paying will return the error above. Agents that discover Subgraphs automatically should treat a deployment with no active allocations as unservable, and either skip it or surface a warning. ### Errors still cost USDC -Any response from the gateway that includes a `Payment-Response` header has been settled on-chain. This includes responses containing GraphQL `errors` (bad query shape, missing fields, schema mismatch, "no allocations", etc.). Validate queries against `get_schema_by_subgraph_id` or a cached schema before paying. +Any response from the Gateway that includes a `Payment-Response` header has been settled onchain. This includes responses that contain GraphQL `errors`, such as a bad query shape, missing fields, a schema mismatch, or "no allocations". Validate your query against the Subgraph's schema before paying, for example with a cached schema or the [Subgraph MCP](/subgraphs/tooling/subgraph-mcp/introduction/). ## Minimal Examples From b64e7056e0857346cb1cf1d4b10394f9fd05494a Mon Sep 17 00:00:00 2001 From: Jerry Okolo <73024324+itsjerryokolo@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:20:22 +0100 Subject: [PATCH 4/4] Clarify x402 v2 client requirements --- website/src/pages/en/subgraphs/tooling/x402-payments.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx index 6a80926b0bc0..54f44f3e5246 100644 --- a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx +++ b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx @@ -14,7 +14,7 @@ The Graph's x402 Subgraph endpoints enable: - **Per-query access** to any Subgraph published on The Graph Network - **USDC payments** on Base (mainnet) and Base Sepolia (testnet) - **No API keys, accounts, or sessions**: payment and access happen in a single HTTP round trip -- **Compatible with any x402 client**, with first-class support via `@graphprotocol/client-x402` +- **x402 v2 payments** using the `exact` scheme, with first-class support via `@graphprotocol/client-x402` The existing API-key endpoints continue to work unchanged. x402 is an additional access path under `/api/x402/...`. @@ -107,7 +107,7 @@ curl -X POST https://gateway.thegraph.com/api/subgraphs/id/5zvR82QoaXYFyDEKLZ9t6 ### Using x402 Payment -Any x402 tooling that supports exact scheme will work with the gateway's x402 endpoints. We recommend to use the official Graph x402 client: +Use an x402 v2 client that supports the `exact` payment scheme on the gateway's payment network. We recommend the official Graph x402 client. ```bash npm install @graphprotocol/client-x402