如何通过 @quicknode/x402-solana 使用 x402 支付访问 QuickNode Solana RPC

概览

@quicknode/x402-solana 是一个 npm 库，它使用 @solana/kit 创建 Solana RPC 和 WebSocket 订阅客户端，通过 Quicknode 使用 USDC 经由 x402 支付协议为每个请求付费。它不需要 API Key，不需要账户，也不需要订阅，只需要一个包含 USDC 的 Solana 钱包文件。

该库导出一个函数 createSolanaX402Clients()，该函数返回标准的 Solana Kit rpc 和 rpcSubscriptions 对象。

TL;DR

• 你将构建什么： 使用 @quicknode/x402-solana 构建经过身份验证的 Solana RPC 和 WebSocket 客户端，无需 API Key 或账户
• 你将学到什么： 如何安装、配置以及使用基于钱包的 x402 支付，通过 Quicknode 访问 Solana RPC
• 最终结果： 能够正常工作的 RPC 客户端，通过 x402 协议 使用 USDC 按请求付费

你将学到什么

本指南涵盖了安装和配置该库、在 credit-drawdown 和 pay-per-request 支付模式之间进行选择、在开发过程中使用 devnet USDC 支付 mainnet RPC 访问费用，以及了解 x402 协议在底层如何与 Solana Kit 集成。到最后，你将拥有可以自动使用 USDC 支付的可用 RPC 客户端。

你需要准备什么

• 对 x402 支付 有基本了解
• 一个 Solana 密钥对 JSON 文件，格式由 solana-keygen new 生成，通常位于 ~/.config/solana/id.json（一个包含 64 个数字的 JSON 数组，代表私钥字节）
• 钱包中有 USDC，在 mainnet 上对于 credit-drawdown 模式至少需要 $10 USDC，或者在 devnet 上至少 $0.01。对于 pay-per-request 模式，任何金额均可。
• 不需要 Quicknode RPC 账户。 无需注册，无需 API Key，无需订阅。

本指南中使用的依赖

如果你没有 Solana 密钥对文件，请使用 Solana CLI 创建一个：

solana-keygen new

这将在 ~/.config/solana/id.json 创建一个密钥对。如果你计划使用 devnet 进行支付，你将需要 devnet USDC。你可以从 Circle Faucet 获取一些。

安装并使用 @quicknode/x402-solana

安装软件包并用三行代码创建经过身份验证的 Solana 客户端。

npm install @quicknode/x402-solana

• Solana Kit
• Kite

// Solana Kit
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { address } from "@solana/kit";
import { homedir } from "node:os";

const keyPairFile = `${homedir()}/.config/solana/id.json`;

const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  "mainnet",
  keyPairFile,
);

// 发起 RPC 调用以测试连接
const balance = await rpc
  .getBalance(address("dDCQNnDmNbFVi8cQhKAgXhyhXeJ625tvwsunRyRc7c8"))
  .send();
console.log("Balance:", balance.value);

Kite 使用更简单的 API 封装了 Solana Kit：

// Kite
import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { connect, loadWalletFromFile } from "solana-kite";
import { homedir } from "node:os";

const keyPairFile = `${homedir()}/.config/solana/id.json`;

const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  "mainnet",
  keyPairFile,
);
const connection = connect(rpc, rpcSubscriptions);

const wallet = await loadWalletFromFile(keyPairFile);
const balance = await connection.getBalance(wallet.address);
console.log("Balance:", balance);

为什么要使用 @quicknode/x402-solana 而不是传统的 RPC 提供商？

传统的 Solana RPC 提供商需要创建账户、管理 API Key 以及订阅计划。@quicknode/x402-solana 用一个 Solana 钱包替代了所有这些。

以下是两种方法的并排对比：

该库使用了 x402 协议，这是一个开放标准，服务器在其中响应 HTTP 402 Payment Required 以及支付指令。支持 x402 的客户端会自动使用 USDC 完成支付并完成请求，所有操作都在一次往返中完成。

这对于 AI Agent 特别有用。自主 Agent 无法注册账户、管理订阅或轮换 API Key。然而，它们可以持有一个带有 USDC 的钱包，这使得基于钱包的身份验证成为 Agent 驱动的区块链访问的自然选择。

@quicknode/x402-solana API 参考

@quicknode/x402-solana 导出一个异步函数：

const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  network,
  keyPairFile,
  options?,
);

参数：

返回值：

返回 { rpc, rpcSubscriptions }，它们是标准的 @solana/kit Rpc 和 RpcSubscriptions 对象，可以与任何 Solana Kit 或 Kite API 一起使用。

选择支付模式

@quicknode/x402-solana 支持两种支付模式：credit-drawdown（默认）进行一次身份验证并批量购买额度，而 pay-per-request 为每个 RPC 调用单独付费。

Credit Drawdown 示例

import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";

const keyPairFile = `${homedir()}/.config/solana/id.json`;

// credit-drawdown 是默认设置，不需要选项
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  "mainnet",
  keyPairFile,
);

Pay-Per-Request 示例

import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";

const keyPairFile = `${homedir()}/.config/solana/id.json`;

const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  "mainnet",
  keyPairFile,
  { paymentModel: "pay-per-request" },
);

对于大多数应用，请使用 credit-drawdown（默认值）。当你需要零预付承诺、在运行周期较短的无服务器函数中运行，或者每个会话的请求少于 50 个左右时，请使用 pay-per-request。

使用 Devnet USDC 支付 Mainnet Solana RPC 访问费用

通过在选项中设置 paymentNetwork: "devnet"，你可以使用 devnet USDC 支付 mainnet 或 testnet 的 RPC 访问费用。这对于在不花费真钱的情况下针对真实的 mainnet 数据进行开发和测试非常有用。

配置组合

跨网络支付示例

import { createSolanaX402Clients } from "@quicknode/x402-solana";
import { homedir } from "node:os";

const keyPairFile = `${homedir()}/.config/solana/id.json`;

// 连接到 mainnet RPC，使用 devnet USDC 支付
const { rpc, rpcSubscriptions } = await createSolanaX402Clients(
  "mainnet",
  keyPairFile,
  { paymentNetwork: "devnet" },
);

x402 协议与 Solana Kit 集成

在底层，该库构建了一个支持 x402 协议 的标准 Kit RpcTransport。当请求到达需要支付的端点时，服务器会响应 HTTP 402 和机器可读的支付要求。传输层拦截该响应，使用你钱包中的 USDC 完成支付，并重试原始请求。

QuickNode RPCSolana Chain (USDC)x402-solanaYour AppQuickNode RPCSolana Chain (USDC)x402-solanaYour AppInitialization (credit-drawdown mode)Normal RPC requestCredit bundle exhaustedcreateSolanaX402Clients(network, keypairFile)Read keypair, derive signing keySIWX auth + purchase credit bundle (USDC)JWT session tokenrpc.getLatestBlockhash()HTTP request + JWTRPC responseResultrpc.getTransaction(...)HTTP request + JWT402 lifetime_limit_reachedPurchase new credit bundle (USDC)ConfirmedSIWX re-auth → new JWTRetry original requestRPC responseResult

在初始化时，该库读取你的 Solana 密钥对文件并将私钥转换为 base58 格式，以便签署支付交易。然后，它通过 @quicknode/x402 创建一个经过 x402 验证的 HTTP 客户端，并将其封装为 Solana Kit 传输层。

在 credit-drawdown 模式下，这包括一个一次性的 SIWX (Sign-In With X) 身份验证步骤，该步骤会预先购买 USDC 额度包。单个 RPC 调用不会每次都产生单独的链上交易。如果额度包在会话中间耗尽，该库会检测到 lifetime_limit_reached 错误，重新进行身份验证，购买新的额度包，并自动重试请求。

在 pay-per-request 模式下，没有会话或预先购买。每次调用都单独结算。

@quicknode/x402-solana 兼容性

createSolanaX402Clients() 返回的客户端是标准的 @solana/kit v6+ 对象，与任何接受 Solana Kit 客户端的库或工具兼容。

何时使用 @quicknode/x402-solana

以下是一些真实的用例，在这些用例中，基于钱包的 RPC 访问释放了传统 API Key 模型不支持的新机会。

需要自主区块链访问的 AI Agent

AI Agent 可以使用 @quicknode/x402-solana 自主访问 Solana RPC，而无需人工提供的 API Key，仅需一个带有 USDC 的钱包。由于 Agent 无法注册账户或管理订阅，通过 x402 进行基于钱包的身份验证是 Agent 驱动的区块链交互的自然选择。

无服务器函数和临时环境

无服务器函数、Lambda 和容器可以在不预先配置账户的情况下，仅使用密钥对文件获得 Solana RPC 访问权限。pay-per-request 模式在这里非常理想，因为无需管理会话，无需预付额度包，且在函数空闲时成本缩减为零。

CI/CD 和集成测试

CI 流水线可以通过将密钥对存储为仓库机密（SOLANA_KEYPAIR）来访问实时 Solana RPC，而无需管理单独的 RPC 提供商凭证。该库自身的测试套件就使用了这种模式。

原型设计和黑客松

你可以在不到一分钟的时间内获得一个可用的 Solana RPC 连接：npm install @quicknode/x402-solana，指向一个密钥对文件，然后开始进行 RPC 调用。

CLI 工具和开发者实用程序

构建适用于任何拥有标准 Solana 密钥对文件（~/.config/solana/id.json）的人的 Solana CLI 工具，除了 Solana 开发者已经拥有的配置外，无需任何额外配置。

低访问量监控和分析

对于定期检查链上状态（余额、Token 账户、程序数据）的脚本，使用 pay-per-request 模式。成本与实际使用情况成正比，没有最低承诺。

何时不要使用 @quicknode/x402-solana

对于每个 Solana 应用程序来说，这个库并不总是正确的选择。在某些情况下，带有专用端点和 API Key 的传统 RPC 提供商更合适。例如：

• 高吞吐量、成本敏感的生产系统。 如果你每天进行数百万次 RPC 调用，并需要尽可能低的单次调用成本，那么带有协商计划的专用 RPC 端点会更便宜。
• 已经拥有 Quicknode 账户的应用程序。 如果你已经拥有带有 API Key 的 Quicknode 订阅，请直接使用它们。这个库解决了“无账户”的问题。
• 浏览器或客户端应用程序。 该库使用 Node.js fs 从磁盘读取密钥对文件，因此它只能在 Node.js 服务端环境中运行。它不能在浏览器中运行。
• 需要自定义 RPC 传输配置的应用程序。 除了内置的自动重新认证外，该库不公开传输层选项，如自定义 Header、超时或重试策略。

在 CI/CD 中测试 @quicknode/x402-solana

将你的 Solana 密钥对 JSON 存储为 SOLANA_KEYPAIR 仓库机密，测试套件将自动检测到它。

- name: Run tests
  env:
    SOLANA_KEYPAIR: ${{ secrets.SOLANA_KEYPAIR }}
  run: npm test

在本地，测试会自动检测 ~/.config/solana/id.json，如果文件缺失则优雅地跳过。在 CI 中，SOLANA_KEYPAIR 环境变量被写入一个临时文件，并在测试运行后清理。所有测试都是针对实时 RPC 端点的集成测试，没有任何模拟（mocked）内容。

故障排除

错误："lifetime_limit_reached"

这意味着你的额度包已耗尽。在 credit-drawdown 模式下，库会通过重新认证并购买新额度包来自动处理此问题。如果此错误传播到你的应用程序，请确保你的钱包有足够的 USDC（mainnet 最低 $10，devnet 最低 $0.01）。

读取密钥对文件错误

确保 keyPairFile 路径指向一个有效的 Solana 密钥对 JSON 文件，即一个包含 64 个数字（字节）的 JSON 数组。标准位置是 ~/.config/solana/id.json。如果需要，使用 solana-keygen new 生成一个。

USDC 余额不足

credit-drawdown 模型在 mainnet 上至少需要 $10 USDC，在 devnet 上需要 $0.01。pay-per-request 模型没有最低限额，但每次单独调用都需要足够的 USDC。

WebSocket 订阅无法连接

WebSocket 身份验证使用作为查询参数附加的 JWT Token。该 Token 来自 credit-drawdown 模式下的 SIWX 身份验证流。如果使用 pay-per-request，WebSocket 连接可能没有有效的 Token。对于需要 WebSocket 订阅的应用程序，请使用 credit-drawdown。

常见问题解答

使用 @quicknode/x402-solana 是否需要 Quicknode 账户或 API Key？

不需要。@quicknode/x402-solana 不需要 Quicknode 账户，不需要 API Key，也不需要订阅。你只需要一个包含 USDC 的 Solana 钱包文件。支付通过 x402 协议自动处理。

@quicknode/x402-solana 的成本是多少？

成本取决于支付模式。使用 credit-drawdown（默认），你购买一个额度包，mainnet 最低 $10 USDC，devnet $0.01 起。使用 pay-per-request，每个 RPC 调用单独支付，没有最低限额。

我可以使用 devnet USDC 支付 mainnet Solana RPC 访问费用吗？

可以。在选项中设置 paymentNetwork: "devnet"，即可在连接到 mainnet 或 testnet RPC 端点时使用 devnet USDC 支付。这对于在不花费真钱的情况下针对真实的 mainnet 数据进行开发和测试非常有用。

当我的额度用完时会发生什么？

在 credit-drawdown 模式下，库会自动检测到 lifetime_limit_reached 错误，重新认证，购买新的额度包，并重试请求。只要钱包有足够的 USDC，就不需要人工干预。

什么是 x402 协议？

x402 是一个基于 HTTP 402 Payment Required 状态码的开放支付协议。当服务器需要支付时，它会返回 402 状态和支付指令。支持 x402 的客户端会自动完成支付（在这种情况下，使用 Solana 上的 USDC）并重试请求。

总结

你现在已经掌握了在没有账户、API Key 或订阅的情况下，通过 Quicknode 访问 Solana RPC 所需的一切。使用 @quicknode/x402-solana，你可以仅使用带有 USDC 的钱包连接到任何 Solana 网络，根据你的用例在 credit-drawdown 和 pay-per-request 模式之间进行选择，甚至在开发期间使用 devnet USDC 支付。无论你是在构建 AI Agent、无服务器函数、CLI 工具还是快速原型，通过 x402 协议进行的基于钱包的 RPC 访问都消除了传统提供商入驻的摩擦。

资源

• 如何通过 x402 支付访问 Quicknode 端点 以获取单次调用定价和其他 x402 详情
• x402 协议规范
• Quicknode MCP
• Solana Kit GitHub
• Solana Kite

我们 ❤️ 反馈！

如果你有任何反馈或对新主题的需求，请告知我们。我们很乐意听取你的意见。

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