如何通过 x402 支付访问 Quicknode 端点

概览

Quicknode 的基础架构为 所有受支持的区块链网络 提供了数十亿次请求的支持。通过 Quicknode 上的 x402，任何持有钱包的客户端都可以通过基于 x402 协议 构建的三种支付模式访问相同的基础架构：按请求付费 (pay-per-request)、微支付 (nanopayment) 和额度扣减 (credit drawdown)。使用 受支持的稳定币 进行支付。无需账户、API Key 或订阅。

这为 开发者 和 AI Agent 消费区块链基础架构开辟了新的可能性。无需提前配置端点，你只需连接钱包即可立即跨 JSON-RPC、REST、gRPC-Web 和 WebSocket 协议进行调用。

本指南将带你了解 Quicknode 上的 x402 如何工作、其适用对象，以及如何发起你的第一个由 x402 驱动的 RPC 请求。

Alpha 版本发布

Quicknode 上的 x402 目前处于 alpha 阶段。它是为实验和早期采用而设计的。虽然底层基础架构与驱动 Quicknode 平台的生产级系统相同，但 x402 访问层是全新的且在不断演进。随着产品的成熟，请预见潜在的 API 变更、速率限制 (rate limits) 的变动以及持续的功能改进。

Agent 支付

Quicknode 还支持用于 Agent 支付的 MPP (机器支付协议)。MPP 使用 IETF 支付认证标头，并提供基于收费和基于会话的访问模式。请参阅 Agent 支付概览 进行横向对比。

• 比较三种支付模式：按请求付费、微支付和额度扣减，并为你的用例选择合适的一种
• 使用额度扣减运行 JSON-RPC 示例，以观察 Base Sepolia 上完整的认证和支付周期
• 探索涵盖 JSON-RPC、REST、gRPC-Web 和 WebSocket 的多协议示例

你将需要

• Node.js (v20 或更高版本) 和 npm
• 对区块链概念的基本了解

就这些。你不需要 Quicknode 账户或 API Key。@quicknode/x402 软件包会自动处理身份验证、支付签名和协商，尽管具体细节取决于你选择的支付模式。对于本指南中的额度扣减示例，你需要一个在 Base Sepolia 上拥有测试网 USDC 的钱包。你可以从 Circle 水龙头 获取一些。

为什么选择 Quicknode 上的 x402

x402 在现有方案之外，增加了一种消费 Quicknode 基础架构的新方式。x402 支持三种访问模式：按请求付费、微支付和额度扣减。它专为以下基于钱包、按需访问比传统账户设置更合适的用例而设计：

• AI Agent 和自主机器人，它们需要在没有人工干预的情况下进行身份验证和支付。Agent 只需要一个持有受支持稳定币的钱包即可开始调用。
• 开发者构建基于 Agent 的工具，最终用户无需拥有自己的账户即可与 Quicknode 基础架构交互。
• 低频使用的开发者，他们希望偶尔访问跨多个链的高质量端点，而无需绑定订阅计划。
• 关注隐私的用户，他们更倾向于基于钱包的访问而非账户注册。
• 实验和原型设计，开发者希望在没有设置开销的情况下快速在各网络间进行测试。

关键区别在于：现有方案针对具有可预测账单的持续使用进行了优化；而 x402 针对按需访问进行了优化，其中每个请求都是独立出资的。

工作原理

Quicknode 上的 x402 支持三种支付模式。这三种模式都使用 @quicknode/x402 客户端；paymentModel 选项控制激活哪一个：

• 按请求付费 (paymentModel: 'pay-per-request')：无需身份验证。每个请求都包含由客户端自动处理的支付签名。
• 微支付 (paymentModel: 'nanopayment')：无需身份验证。通过 Circle Gateway 进行批量支付。需要向 Gateway 钱包合约进行一次性的 USDC 存款；Gateway API 在更新你的余额前会等待 特定链的区块确认。支付链仅限于选定的 EVM 测试网：Base Sepolia、Polygon Amoy 和 Arc Testnet。
• 额度扣减 (paymentModel: 'credit-drawdown'，默认)：通过 SIWX 进行一次身份验证，购买额度包，并按请求消耗额度。gRPC-Web 和 WebSocket 传输协议需要此模式。

无论你使用哪种支付模式或支付链，你都可以查询 Quicknode 受支持网络 中的任何一个。请参阅 多协议支持 章节了解各模式的协议可用性。

下图展示了本指南示例所使用的 额度扣减 流程。对于按请求付费和微支付，步骤 1 和 2 会被跳过：每个请求直接包含支付签名，无需事先身份验证。

sequenceDiagram
    participant Client as 客户端 (Agent 或 开发者)
    participant Proxy as Quicknode x402 代理
    participant Facilitator as x402 促进者
    participant Endpoints as Quicknode 端点

    Note over Client, Proxy: 当额度用尽时，回到步骤 2

    rect rgb(240, 240, 240)
    Note right of Client: 1. SIWX 身份验证
    Proxy-->>Client: JWT Token (1小时有效期)
    end

    Client->>Proxy: 2. 请求 (带 JWT)
    Proxy-->>Client: HTTP 402 需要支付

    rect rgb(240, 240, 240)
    Note right of Client: 3. 使用 x402 支付重试 (使用受支持的稳定币)
    Proxy->>Facilitator: 结算支付
    Facilitator-->>Proxy: 支付已确认
    Proxy->>Endpoints: 转发请求
    Endpoints-->>Proxy: 响应
    Proxy-->>Client: 响应 + 额度
    end

    rect rgb(240, 240, 240)
    Note right of Client: 4. 后续请求 (带 JWT)
    Proxy->>Endpoints: 转发请求 (扣除额度)
    Endpoints-->>Proxy: 响应
    Proxy-->>Client: 响应
    end

额度扣减：逐步解析

当你设置 preAuth: true 时，@quicknode/x402 软件包会自动处理整个额度扣减流程。你无需手动实现这些步骤。以下是后台发生的事情：

1. 使用 SIWX 进行身份验证

客户端使用其钱包签署一条 以 X 登录 (SIWX) 消息。这证明了钱包地址的所有权，而无需暴露任何私钥。代理返回一个有效期为一小时的 JWT Token，客户端在后续请求中包含该 Token。

2. 第一个请求返回 402

当你进行第一次调用，或在额度为零时进行任何调用，代理会返回 HTTP 402 Payment Required。此响应包含遵循 x402 v2 规范 的支付要求，指定了支付金额和网络。

3. 支付并获得额度

客户端签署一个稳定币支付授权——EVM 使用 EIP-712，Solana 使用 SPL 转账——并带上支付标头重试请求。x402 促进者在链上结算支付，代理会为你的账户存入一个请求额度包。

4. 消耗额度

从那时起，每个请求都会扣除一个额度。当余额归零时，下一个请求会触发另一个 402，循环往复。代理背后的基础架构是为所有 Quicknode 端点提供支持的同一个生产系统。

支付选项

测试网上限针对每种支付模式独立跟踪。达到上限后，请切换到主网进行生产使用。

有关受支持支付网络及其支持模式的完整列表，请参阅 x402 参考文档中的 受支持支付网络 表格。

通过 x402 受支持的网络

无论你使用哪种支付模式或支付网络，你都可以查询 Quicknode 支持的任何区块链网络，包括 Ethereum、Base、Solana、Arbitrum、Polygon、Aptos、Flow 等等。

有关受支持链的完整列表，请参阅 Quicknode 受支持链页面。

多协议支持

Quicknode 上的 x402 跨多个协议工作，但协议可用性取决于支付模式。按请求付费和微支付仅支持 JSON-RPC 和 REST。gRPC-Web 和 WebSocket 需要额度扣减。

通过单个钱包，你可以访问跨所有四种协议的任何 Quicknode 受支持链：通过 JSON-RPC 访问 EVM 链或 Solana，通过 REST 访问 Aptos，通过 gRPC 访问 Flow，以及通过 WebSocket 访问实时以太坊数据。

qn-x402-examples 代码库 包含了针对每种协议的可运行脚本。在下一节中，我们将逐步演示一个基础的 JSON-RPC 示例，你可以按照自己的节奏探索这些运行脚本。

开始使用：JSON-RPC 示例

本演练使用 额度扣减 模式来演示完整的认证和支付周期。如果你希望完全跳过身份验证，请在客户端配置中改为设置 paymentModel: 'pay-per-request'。

我们将使用 @quicknode/x402 软件包在 Base Sepolia 上进行 eth_blockNumber 调用，并在 Solana Devnet 上进行 getSlot 调用。

qn-x402-examples 代码库 也包含了其自身的 JSON-RPC 示例，以及 REST、gRPC-Web 和 WebSocket 脚本，所有脚本都内置了对 Base Sepolia 的水龙头支持。下面的指南将从头开始构建一个独立脚本，以便你可以清晰地看到每个步骤。

第 1 步：设置项目

mkdir x402-quickstart && cd x402-quickstart
npm init -y
npm install @quicknode/x402 tsx

第 2 步：创建 .env 文件

在项目根目录下创建一个 .env 文件，并添加你的 Base Sepolia EVM 私钥：

PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

第 3 步：创建脚本

创建一个名为 index.ts 的文件。此脚本使用 @quicknode/x402 创建一个客户端，重复进行 eth_blockNumber 和 getSlot 调用以消耗额度，并在每次调用后记录剩余额度。

import { createQuicknodeX402Client } from '@quicknode/x402'

const X402_BASE_URL = 'https://x402.quicknode.com'
const NETWORK = 'eip155:84532' // Base Sepolia

async function main() {
    // 额度扣减：preAuth 通过预先认证 (SIWX + JWT) 来加速支付
    const client = await createQuicknodeX402Client({
        baseUrl: X402_BASE_URL,
        network: NETWORK,
        evmPrivateKey: process.env.PRIVATE_KEY || undefined,
        paymentModel: 'credit-drawdown',
        preAuth: true,
    })

    console.log('客户端就绪。支付将使用 Base Sepolia 上的 USDC 进行。')
    console.log(
        '正在发起调用：Base Sepolia 上的 eth_blockNumber 和 Solana Devnet 上的 getSlot...\n'
    )

    // 在循环中发起请求以观察额度消耗
    for (let i = 1; i <= 10; i++) {
        const evmResponse = await client.fetch(`${X402_BASE_URL}/base-sepolia`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                jsonrpc: '2.0',
                id: i,
                method: 'eth_blockNumber',
                params: [],
            }),
        })

        const evmData = await evmResponse.json()
        const block = BigInt(evmData.result)
        console.log(`请求 #${i}: 区块 ${block}`)
        console.log(
            '额度:',
            (
                await fetch('https://x402.quicknode.com/credits', {
                    headers: { Authorization: `Bearer ${client.getToken()}` },
                }).then(r => r.json())
            ).credits
        )

        const solanaResponse = await client.fetch(
            'https://x402.quicknode.com/solana-devnet',
            {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    id: 1,
                    method: 'getSlot',
                    params: [],
                }),
            }
        )
        const solanaData = await solanaResponse.json()
        const slot = solanaData.result
        console.log(`请求 #${i}: Solana Slot ${slot}`)
        console.log(
            '额度:',
            (
                await fetch('https://x402.quicknode.com/credits', {
                    headers: { Authorization: `Bearer ${client.getToken()}` },
                }).then(r => r.json())
            ).credits
        )

        console.log('\n')
    }
}

main().catch(console.error)

第 4 步：运行它

你的钱包在进行 x402 支付前需要 Base Sepolia USDC。你可以从 Circle 水龙头 获取测试网 USDC。或者，qn-x402-examples 代码库 包含了一个具有内置自动水龙头逻辑的 setupExample 助手，用于自动化流程。

npx tsx --env-file=.env index.ts

第一次运行时，客户端将：

1. 使用提供的私钥和配置 创建一个客户端
2. 设置 preAuth: true 时，通过签署消息并预先获取 JWT 进行 SIWX 预身份验证
3. 发起 eth_blockNumber 和 getSlot 调用，每个成功的响应消耗一个额度
4. 当额度耗尽时，自动 处理 402 支付

预期输出：

客户端就绪。支付将使用 Base Sepolia 上的 USDC 进行。
正在发起调用：Base Sepolia 上的 eth_blockNumber 和 Solana Devnet 上的 getSlot...

请求 #1: 区块 38357505
额度: 99
请求 #1: Solana Slot 445776251
额度: 98

请求 #2: 区块 38357506
额度: 97
请求 #2: Solana Slot 445776252
额度: 96

## ... 如果你多次运行该脚本，你将在额度用完时看到 402 支付流程的运行：

请求 #4: 区块 38375819
额度: 1
请求 #4: Solana Slot 445872102
额度: 0

请求 #5: 区块 38375821
额度: 99
请求 #5: Solana Slot 445872112
额度: 98

Solana 前提条件

要在 Solana 上使用 x402，你需要一个持有 Devnet USDC 的钱包。/drip 水龙头仅支持 EVM，因此 Solana 钱包必须手动注资。

1. 设置 Solana 钱包：生成一个新的密钥对或使用现有的 Base58 编码私钥。

生成新的 Solana 密钥对

npm install tweetnacl bs58
npx tsx -e "
import nacl from 'tweetnacl'; import bs58 from 'bs58';
const kp = nacl.sign.keyPair();
console.log('公钥:', bs58.encode(Buffer.from(kp.publicKey)));
console.log('私钥:', bs58.encode(Buffer.from(kp.secretKey)));
"

2. 充值 Solana Devnet USDC：访问 faucet.circle.com 并为你的钱包地址申请 Mint 为 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU 的 Devnet USDC。你 不需要 SOL。x402 促进者会支付交易费用。

3. 使用 Solana 配置创建客户端：

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
    baseUrl: 'https://x402.quicknode.com',
    network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', // Solana Devnet
    svmPrivateKey: '<你的_BASE58_私钥>',
    preAuth: true,
})

svmPrivateKey 参数接受 Base58 编码的私钥。对于 EVM 链，请改用 evmPrivateKey 并传入十六进制编码的密钥。

然后，你可以使用同一个客户端对任何链（不仅是 Solana）发起调用，支付将使用你的 Solana Devnet USDC 进行。

理解代码

让我们看看示例运作的关键部分。

客户端设置

createQuicknodeX402Client 函数创建一个处理跨所有三种模式的支付协商的客户端。对于额度扣减，它还管理 SIWX 身份验证和 JWT 会话：

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
    baseUrl: 'https://x402.quicknode.com',
    network: 'eip155:84532',
    evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
    paymentModel: 'credit-drawdown',
    preAuth: true,
})

发起请求

client.fetch 方法与标准的 Fetch API 一致。身份验证和支付是透明处理的：

const evmResponse = await client.fetch(`${X402_BASE_URL}/base-sepolia`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        jsonrpc: '2.0',
        id: i,
        method: 'eth_blockNumber',
        params: [],
    }),
})

const evmData = await evmResponse.json()
const block = BigInt(evmData.result)
console.log(`请求 #${i}: 区块 ${block}`)

const solanaResponse = await client.fetch(
    'https://x402.quicknode.com/solana-devnet',
    {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            jsonrpc: '2.0',
            id: 1,
            method: 'getSlot',
            params: [],
        }),
    }
)
const solanaData = await solanaResponse.json()
const slot = solanaData.result
console.log(`请求 #${i}: Solana Slot ${slot}`)

使用 https://x402.quicknode.com/{network} 格式的 URL 来针对不同的链。在客户端创建时设置的 network（支付网络）不需要与你查询的链一致。

探索其他请求类型

在运行了指南中的示例后，请探索 qn-x402-examples 代码库 中的其他脚本，以观察 x402 在不同协议和链上的运作。所有示例都使用了 @quicknode/x402。

REST API

rest.ts 脚本演示了在 Aptos 主网上使用 REST API 端点的 x402。它向 /v1/（账本信息）、/v1/blocks/by_height/{h} 和 /v1/accounts/0x1 等端点发起标准的 HTTP GET 请求。

npm run start:rest

gRPC-Web

grpc.ts 脚本展示了在 Flow 主网上使用 @connectrpc/connect-web 的一元调用（Ping 和 GetLatestBlock）以及通过 SubscribeBlocksFromLatest 进行的服务端流式传输。

npm run start:grpc

WebSocket

websocket.ts 脚本通过 eth_subscribe 订阅 Base 主网上的 newHeads，在实时区块头产生时接收它们。它使用非阻塞额度轮询器来跟踪剩余额度，而不会中断数据流。当额度耗尽时，连接会处理 4402 关闭代码并可以自动重新认证。

npm run start:ws

有关每个脚本的完整详细信息，包括配置选项和网络覆盖，请参阅 示例代码库 README。

在 Quicknode 上使用 AI 进行构建

x402 是 Quicknode 的 AI 和 Agent 工具集中的一层。每个工具都针对工作流的不同部分：发现文档、生成正确代码、访问端点以及管理基础架构。使用 AI 构建 文档涵盖了全套工具：

• LLM 优化的文档： llms.txt 索引可帮助 LLM 为任何问题发现正确的 Quicknode 内容。
• 区块链 Skills： 一个轻量级的参考包，赋予 AI 编程 Agent 准确的 Quicknode API 知识。一条命令即可安装：npx skills add quiknode-labs/blockchain-skills。
• x402 支付： 基于钱包的访问，具有三种支付模式：按请求付费、微支付和额度扣减。
• MPP 支付： 使用 IETF 支付认证标头的按请求付费访问，按请求定价为 $0.001，基于会话的定价为 $0.00001/请求。
• Quicknode MCP： 在 Claude Code、Cursor、Codex 和其他兼容 MCP 的 Agent 中通过自然语言管理 Quicknode 基础架构。

尝试将 x402 用于 Hyperliquid 数据集

Quicknode 开源的 HyperCore CLI 也支持 x402 访问。开发者可以直接从终端流式传输和回填 Hyperliquid 数据集，使用钱包按请求付费，而无需 Quicknode 账户。

后续步骤

既然你已经见识了 Quicknode 上的 x402 的运作方式，这里有一些进一步探索的方法。

尝试其他协议

本指南演示了一个 JSON-RPC 示例，但 qn-x402-examples 代码库 同样包含了 REST、gRPC-Web 和 WebSocket 的可运行脚本。gRPC-Web 和 WebSocket 需要额度扣减模式；JSON-RPC 和 REST 则适用于所有三种支付模式。

迁移到主网

测试网账户对每种支付模式都有终身上限：额度扣减为 1,000 额度，按请求付费为 1,000 个请求，微支付为 10,000 个请求。这些上限是独立跟踪的。达到上限后，请切换到相应的主网进行生产使用。支付机制是完全相同的，只是使用了真实的资金。

构建 Agent 工作流

将 x402 集成到你的 AI Agent 或机器人中。@quicknode/x402 软件包会自动处理身份验证和支付，因此任何使用 fetch 的应用程序都可以通过极小的改动进行适配。由于整个流程是基于 HTTP 的，任何能够签署消息并进行 HTTP 请求的客户端都可以使用它。

深入了解 x402

有关 x402 协议本身的深度技术解析，请查阅：

• x402 协议规范：由 Coinbase 发布的开源协议规范
• Quicknode 上的 x402：为开发者和 AI Agent 提供即时区块链访问：Quicknode 关于 x402 的发布博客文章
• 如何使用 x402 实现加密货币付费墙：构建你自己的由 x402 驱动的付费墙
• x402 支付与 Rails 的集成：Ruby on Rails 的服务端 x402 集成
• x402 协议解析：Quicknode 关于 x402 的深度解析博客文章

结论

Quicknode 上的 x402 开启了一种消费区块链基础架构的新方式，专为希望通过基于钱包的身份验证进行按需访问的 Agent、机器人和开发者设计。安装 @quicknode/x402，通过按请求付费、微支付或额度扣减使用受支持的稳定币支付，并使用 JSON-RPC、REST、gRPC-Web 或 WebSocket 访问所有受支持的网络。无需注册。

这是一个 alpha 版本，Quicknode 正在根据开发者和 Agent 的反馈积极迭代。

• 原文链接： quicknode.com/guides/age...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～