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

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.

Network Environments

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.

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

Any x402 tooling that supports exact scheme will work with the gateway’s x402 endpoints. We recommend to use 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)