4 minutes
Using x402 to Pay for Subgraph Data on The Graph Network
Pay-per-query access to Subgraphs on The Graph Network using the x402 payment protocol.
The Graph’s Subgraph Gateways accept x402 payments for per-query access on The Graph Network. Agents and applications can pay in USDC over HTTP without an API key.
Overview
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
- x402 v2 payments using the
exactscheme, 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/....
How It Works
- The client sends a GraphQL query to an
/api/x402/...endpoint. - The Gateway responds with
402 Payment Requiredand payment requirements (amount, network, asset, recipient). - The client signs a USDC payment payload and retries the request with the payment header.
- 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 |
|---|---|---|---|
| Mainnet | https://gateway.thegraph.com | Base | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Testnet | https://testnet.gateway.thegraph.com | Base Sepolia | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |
Options for Accessing the API
Option 1: API Key (Best for Humans)
Get an API key from Subgraph Studio and include it in requests.
Endpoints:
POST /api/subgraphs/id/{subgraph_id}POST /api/deployments/id/{deployment_id}
Header: Authorization: Bearer <API_KEY>
Option 2: x402 Payment (Best for Agents)
Pay per query with USDC. No API key required.
Endpoints:
POST /api/x402/subgraphs/id/{subgraph_id}POST /api/x402/deployments/id/{deployment_id}
When to Use x402
x402 is well suited to:
- Autonomous agents and short-lived processes that can’t store long-term credentials
- Per-query workloads where pre-purchased credits don’t fit the access pattern
- Integrations that prefer HTTP-native payment over account creation and key management
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:
1{ "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 before paying. Use the deployment ID (Qm...) as ipfsHash:
1{2 subgraphDeployments(where: { ipfsHash: "<DEPLOYMENT_ID>" }) {3 indexerAllocations(where: { activeForIndexer_not: null }, first: 1) {4 id5 }6 }7}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.
Minimal Examples
Using API Key
1curl -X POST https://gateway.thegraph.com/api/subgraphs/id/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV \2 -H "Authorization: Bearer YOUR_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{"query": "{ tokens(first: 5) { symbol } }"}'Using x402 Payment
Use an x402 v2 client that supports the exact payment scheme on the gateway’s payment network. We recommend the official Graph x402 client.
1npm install @graphprotocol/client-x402Option A: Command Line
1export X402_PRIVATE_KEY=0xabc123...23npx graphclient-x402 "{ pairs(first: 5) { id } }" \4 --endpoint https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID> \5 --chain baseOption B: Programmatic
1import { createGraphQuery } from '@graphprotocol/client-x402'23const query = createGraphQuery({4 endpoint: 'https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID>',5 chain: 'base',6})78const result = await query('{ pairs(first: 5) { id } }')Option C: Typed SDK (full type safety)
1npm install @graphprotocol/client-cli @graphprotocol/client-x402Configure .graphclientrc.yml:
1customFetch: '@graphprotocol/client-x402'23sources:4 - name: uniswap5 handler:6 graphql:7 endpoint: https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID>89documents:10 - ./src/queries/*.graphqlBuild and use:
1export X402_PRIVATE_KEY=0xabc123...2export X402_CHAIN=base3npx graphclient build1import { execute, GetPairsDocument } from './.graphclient'23const result = await execute(GetPairsDocument, { first: 5 })Environment Variables
X402_PRIVATE_KEY: Wallet private key for payment signingX402_CHAIN:base(mainnet) orbase-sepolia(testnet)