Docs
Search⌘ K
  • Home
  • About The Graph
  • Supported Networks
  • Protocol Contracts
  • AI Tooling
  • Subgraphs
    • Substreams
      • Indexer Software
        • Gateway Software
          • Data Services
            • Resources
              Subgraphs > Testing & Tooling

              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 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/....

              How It Works

              1. The client sends a GraphQL query to an /api/x402/... endpoint.
              2. The Gateway responds with 402 Payment Required and payment requirements (amount, network, asset, recipient).
              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

              EnvironmentBase URLPayment NetworkUSDC Token Address
              Mainnethttps://gateway.thegraph.comBase0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
              Testnethttps://testnet.gateway.thegraph.comBase Sepolia0x036CbD53842c5426634e7929541eC2318f3dCF7e

              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-x402

              Option 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 base

              Option 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-x402

              Configure .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/*.graphql

              Build and use:

              1export X402_PRIVATE_KEY=0xabc123...2export X402_CHAIN=base3npx graphclient build
              1import { execute, GetPairsDocument } from './.graphclient'23const result = await execute(GetPairsDocument, { first: 5 })

              Environment Variables

              • X402_PRIVATE_KEY: Wallet private key for payment signing
              • X402_CHAIN: base (mainnet) or base-sepolia (testnet)
              ⁠Edit on GitHub⁠

              Matchstick Unit TestingOverview
              On this page
              • Overview
              • How It Works
              • Network Environments
              • Options for Accessing the API
              • Option 1: API Key (Best for Humans)
              • Option 2: x402 Payment (Best for Agents)
              • When to Use x402
              • Caveats
              • Payment applies even when no Indexer is serving the Subgraph
              • Errors still cost USDC
              • Minimal Examples
              • Using API Key
              • Using x402 Payment
              • Environment Variables
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service