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/2] 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: "<ipfsHash>") {
+    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/2] 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: "<ipfsHash>") {
-    indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { id }
+    indexerAllocations(where: { activeForIndexer_not: null }, first: 1) {
+      id
+    }
   }
 }
 ```