diff --git a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx index d696c104bd58..54f44f3e5246 100644 --- a/website/src/pages/en/subgraphs/tooling/x402-payments.mdx +++ b/website/src/pages/en/subgraphs/tooling/x402-payments.mdx @@ -14,9 +14,9 @@ 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 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,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**. 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 | Environment | Base URL | Payment Network | USDC Token Address | @@ -64,6 +66,34 @@ 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` 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, 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 +{ + subgraphDeployments(where: { ipfsHash: "" }) { + indexerAllocations(where: { activeForIndexer_not: null }, first: 1) { + id + } + } +} +``` + +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 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 ### Using API Key @@ -77,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