本文介绍了The Graph网络基于x402支付协议的按查询付费子图访问方式。用户可通过HTTP请求直接使用USDC（在Base主网或Base Sepolia测试网）支付单次查询费用，无需API密钥或账户注册。文章详细说明了工作原理、支持的端点、适用场景（如自主智能体、短生命周期进程）以及三种客户端使用方式（命令行、编程调用、类型安全SDK），并提供了环境变量配置示例。
概述
Graph 的 x402 Subgraph 端点可实现以下功能：
- 按查询访问任何发布在 Graph Network 上的 Subgraph
- 在 Base 主网和 Base Sepolia 测试网上使用 USDC 支付
- 无需 API 密钥、账户或会话：支付和访问在单个 HTTP 往返中完成
- 兼容任何 x402 客户端，并通过
@graphprotocol/client-x402 提供一级支持
现有的 API 密钥端点保持不变；x402 是 /api/x402/... 路径下的额外访问方式。
工作原理
- 客户端向
/api/x402/... 端点发送 GraphQL 查询。
- 网关响应
402 Payment Required 并附带支付要求（金额、网络、资产、收款方）。
- 客户端签署 USDC 支付负载，并携带支付标头重试请求。
- 网关通过协调者验证支付，并返回查询结果。
网络环境
| 环境 |
基础 URL |
支付网络 |
USDC Token 地址 |
| 主网 |
https://gateway.thegraph.com |
Base |
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| 测试网 |
https://testnet.gateway.thegraph.com |
Base Sepolia |
0x036CbD53842c5426634e7929541eC2318f3dCF7e |
API 访问选项
选项 1：API 密钥（最适合人类）
从 Subgraph Studio 获取 API 密钥，并在请求中包含它。
端点：
POST /api/subgraphs/id/{subgraph_id}POST /api/deployments/id/{deployment_id}
标头： Authorization: Bearer <API_KEY>
选项 2：x402 支付（最适合 Agent）
按查询使用 USDC 支付。无需 API 密钥。
端点：
POST /api/x402/subgraphs/id/{subgraph_id}POST /api/x402/deployments/id/{deployment_id}
何时使用 x402
x402 非常适合以下场景：
- 自主 Agent 和无法存储长期凭证的短生命周期进程
- 按查询工作负载，预购积分不适合的访问模式
- 偏好 HTTP 原生支付的集成，避免创建账户和管理密钥
对于持续、高流量的应用场景，现有 API 密钥流程仍是推荐路径。
最小示例
使用 API 密钥
（此处粘贴 API 密钥请求示例）
使用 x402 支付
任何支持该方案的 x402 工具都可以与网关的 x402 端点配合使用。我们推荐使用官方的 Graph x402 客户端：
选项 A：命令行
（插入命令行示例）
选项 B：编程方式
（插入编程示例）
选项 C：类型化 SDK（完全类型安全）
配置 .graphclientrc.yml：
（插入 YAML 配置）
构建并使用：
（插入构建步骤）
环境变量
X402_PRIVATE_KEY：用于支付签名的钱包私钥X402_CHAIN：base（主网）或 base-sepolia（测试网）
