Imported from graphprotocol/gateway-x (SKILL.md). Install upstream with npx skills add graphprotocol/gateway-x. Copyright stays with the author.

The Graph Gateway

Query blockchain data from The Graph Network's decentralized indexers.

Environments

Authentication

Two 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 on Base. No API key required. The x402 protocol handles payment negotiation automatically.

Endpoints:

• POST /api/x402/subgraphs/id/{subgraph_id}
• POST /api/x402/deployments/id/{deployment_id}

Examples

With API Key

curl -X POST https://gateway.thegraph.com/api/subgraphs/id/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ tokens(first: 5) { symbol } }"}'

With x402 Payment

Any x402 tooling that supports exact scheme will work with the gateway's x402 endpoints. We recommend the official Graph x402 client.

Option A: Command Line (no install required)

export X402_PRIVATE_KEY=0xabc123...

npx @graphprotocol/client-x402 "{ pairs(first: 5) { id } }" \
  --endpoint https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID> \
  --chain base

Option B: Programmatic

npm install @graphprotocol/client-x402

import { createGraphQuery } from '@graphprotocol/client-x402'

const query = createGraphQuery({
  endpoint: 'https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID>',
  chain: 'base',
})

const result = await query('{ pairs(first: 5) { id } }')

Option C: Typed SDK (full type safety)

npm install @graphprotocol/client-cli @graphprotocol/client-x402

Configure .graphclientrc.yml:

customFetch: '@graphprotocol/client-x402'

sources:
  - name: uniswap
    handler:
      graphql:
        endpoint: https://gateway.thegraph.com/api/x402/subgraphs/id/<SUBGRAPH_ID>

documents:
  - ./src/queries/*.graphql

Build and use:

export X402_PRIVATE_KEY=0xabc123...
export X402_CHAIN=base
npx graphclient build

import { execute, GetPairsDocument } from './.graphclient'

const result = await execute(GetPairsDocument, { first: 5 })

Environment Variables:

• X402_PRIVATE_KEY (required): Wallet private key for payment signing
• X402_CHAIN (optional): base (mainnet, default) or base-sepolia (testnet)