quicknode-skill

Quicknode 区块链基础设施

接入问题

• Quicknode 应面向哪个链和网络？
• 这是只读操作，还是需要创建基础设施（Streams、Webhooks、IPFS 写入）？
• 是否需要实时流式传输（Solana gRPC/Blazar WSS/HyperCore gRPC），还是标准 RPC？
• 应使用哪个端点或 API 密钥（默认：QUICKNODE_RPC_URL，可选：QUICKNODE_WSS_URL / QUICKNODE_API_KEY）？
• 如果没有 API 密钥，Agent 是否希望使用按请求付费的访问方式（x402、MPP），还是通过 Agent 订阅 使用钱包付费的 Quicknode 账户？
• 有哪些限制（延迟、地区、吞吐量、目标位置）？

安全默认设置

• 未指定网络时，默认使用测试网/开发网。
• 创建资源前，优先执行只读操作和试运行。
• 切勿索取或接受私钥或密钥。

写入前确认

• 创建或修改 Streams、Webhooks 或上传 IPFS 前，必须获得明确确认。
• 创建 Agent 订阅、充值，或通过 x402 或 MPP 执行任何会花费真实资金的操作前，必须获得明确确认。
• 如果缺少确认，请返回准确的 API 载荷以供审核。

快速参考

基础设施

产品	描述	使用场景
Core RPC API	为 80+ 条链提供高性能区块链访问	dApp 后端、钱包交互
Dedicated Clusters	专用私有节点集群	高吞吐量生产环境、合规隔离
IPFS	去中心化文件存储	NFT 元数据、资产托管

实时数据

产品	描述	使用场景
Streams	实时和历史区块链数据管道	事件监控、分析、索引
Streams Backfills	按需将历史数据回填至 Streams	缺口恢复、历史数据重新索引
Webhooks	事件驱动通知	警报、交易监控
Solana gRPC	Solana Geyser 流式传输 — 包含在 Scale/Business 方案中，Build/Accelerate 方案可作为附加服务	实时账户、交易、插槽数据
Blazar WSS	Quicknode 构建的 Solana WebSocket 引擎 — 所有方案均可使用，免费	快速订阅区块、账户、交易和插槽
HyperCore gRPC	Hyperliquid L1 的 gRPC 流式传输 — 包含在所有付费方案中	实时交易、订单簿差异、事件、区块

索引数据

产品	描述	使用场景
SQL Explorer	直接通过 SQL 访问已索引的区块链数据	交易分析、历史查询、市场分析
Agent Identity (ERC-8004)	链上 Agent 发现和信誉记录	Agent 身份、能力宣传
Blockbook	通过 JSON-RPC 提供以钱包为中心的区块链数据	地址余额、UTXO、交易历史
Metaplex DAS API	Solana 数字资产标准 — NFT、cNFT、同质化代币、MPL Core	NFT/代币查询、压缩 NFT、资产搜索
Ordinals & Runes API	Bitcoin 铭文和 Runes 协议数据	铭文查询、UTXO 跟踪、Runes 余额

交易与 DeFi

产品	描述	使用场景
Swap API	聚合多个 DEX 的代币兑换	Solana (Jupiter/Metis)、EVM (0x、OpenOcean、Aerodrome、Velodrome、Titan)

端点附加功能

产品	描述	使用场景
Solana Priority Fee API	为 Solana 交易推荐优先费	费用估算、确保交易上链
Jito Bundles	Solana 捆绑交易提交和状态 API	支持 MEV 感知的交易交付
Single Flight RPC	对相同的进行中 RPC 请求进行去重	高并发读取工作负载
Multi-region Transaction Broadcast	跨多个区域传播交易	对延迟敏感的交易提交
Risk Assessment API	钱包和交易风险数据	合规、欺诈监控
Block Timestamp Lookup	时间戳到区块的查询工具	将时间窗口转换为区块范围
Multi-chain Stablecoin Balance API	支持的链上的稳定币余额	资金管理、支付、投资组合状态
GoldRush Multichain Data APIs	多链钱包和投资组合数据	钱包摘要、代币/NFT 持仓

Agent 功能

产品	描述	使用场景
x402	测试网每月限额，加上主网通过稳定币按请求付费	无密钥 RPC 访问、AI Agent、按使用量付费
MPP	测试网每月限额，加上主网通过 IETF Payment Authentication 按请求付费	AI Agent、多服务支付、高用量会话
Agent Subscriptions	通过钱包付费创建 Quicknode 账户，并返回 QN_* 完整平台 API 密钥	需要完整平台访问权限的自主 Agent
Quicknode CLI	用于通过终端管理端点、Streams、Webhooks、KV 和 SQL 的 qn CLI，还可通过 Tooling Access 或 x402/MPP 付款使用 RPC	脚本编写、CI/CD、基础设施自动化、无密钥付费 RPC
Quicknode MCP	原生 Claude/OpenAI 连接器和通用 MCP 服务 — 通过 MCP 使用 Admin API	从 Claude、ChatGPT、Codex、Cursor 或任何支持 MCP 的 AI 工具管理 Quicknode

平台

产品	描述	使用场景
Admin API	用于账户管理的 REST API	端点增删改查、用量监控、账单管理
Key-Value Store	无服务器键值和列表存储（测试版）	为 Streams 提供持久状态、动态地址列表
Quicknode SDK	Quicknode 产品 API 的官方 SDK，还可通过 Tooling Access 或 x402/MPP 付款使用 RPC	Admin API、Streams、Webhooks、KV、SQL Explorer、RPC 调用

---

核心 RPC API

Quicknode 为 80 多个区块链网络提供低延迟 RPC 端点。

qn rpc call（CLI）和 qn.rpc.call（SDK）可通过 Tooling Access 访问任何受支持的网络。Tooling Access 是 Quicknode 自动配置的单一多链只读端点，使用短期 JWT。无需设置端点。请参阅 references/cli-reference.md / references/sdk-reference.md。如需固定 URL、非只读方法或专用吞吐量，请使用下方的专用端点。

端点设置

// EVM chains (ethers.js)
import { JsonRpcProvider } from 'ethers';
const provider = new JsonRpcProvider(process.env.QUICKNODE_RPC_URL!);

// EVM chains (viem)
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
const client = createPublicClient({
  chain: mainnet,
  transport: http(process.env.QUICKNODE_RPC_URL!),
});

// Solana
import { createSolanaRpc } from '@solana/kit';
const rpc = createSolanaRpc(process.env.QUICKNODE_RPC_URL!);

身份验证

Quicknode 端点在 URL 中包含身份验证信息：

https://{ENDPOINT_NAME}.{NETWORK}.quiknode.pro/{API_KEY}/

如需增强安全性，可在 Quicknode 控制面板中启用 JWT 身份验证或 IP 允许列表。

支持的网络

类别	网络
EVM	Ethereum、Polygon、Arbitrum、Optimism、Base、BSC、Avalanche、Fantom、zkSync、Scroll、Linea、Hyperliquid EVM (HyperEVM)
非 EVM	Solana、Bitcoin、NEAR、Stacks、Cosmos、Sei、Aptos、Sui、TON、Hyperliquid (HyperCore)

未列出全部网络。完整列表：https://www.quicknode.com/chains

速率限制与套餐

截至 2026-02-02。确定生产系统规模前，请在 Quicknode 文档中核实当前限制。

套餐	请求数/秒	每月积分
免费试用	15	10M
Build	50	80M
Accelerate	125	450M
Scale	250	950M
Business	500	2B

有关完整的 RPC 文档，包括 EVM、Solana 和 Bitcoin 链的方法表、WebSocket 模式和批量请求示例，请参阅 references/rpc-reference.md。

IPFS

借助 Quicknode 的 IPFS 网关实现去中心化文件存储。

有关上传示例、元数据示例和完整的 IPFS 文档，请参阅 references/ipfs-reference.md。

专用集群

面向需要确定性吞吐量、区域固定或合规隔离的团队提供专用私有节点集群。Agent 通常不会直接配置专用集群；这是由账户所有者做出的基础设施决策。

产品介绍： https://www.quicknode.com/clusters 文档： https://www.quicknode.com/docs/custom-rpc-options

---

Streams

实时和历史区块链数据管道，可筛选、转换数据并将其发送至目标位置。

Stream 类型

类型	数据	用例
区块	完整区块数据	区块浏览器、分析
交易	交易详情	交易监控、索引
日志	合约事件	DeFi 追踪、NFT 销售、代币转账
回执	交易回执	Gas 分析、状态追踪

快速设置

1. 在 Quicknode 控制面板中创建 Stream
2. 选择网络和数据类型
3. 添加筛选函数（JavaScript）
4. 配置目标位置（webhook、S3、数据库）

有关筛选示例和完整的 Streams 文档，请参阅 references/streams-reference.md。

Streams 回填

按需将历史数据传送至现有 Stream。使用回填可恢复数据缺口、为新数据存储填充历史数据，或在不重建管道的情况下重新索引一段区块。

文档： https://www.quicknode.com/docs/streams/backfilling

适用场景

• Stream 的目标位置曾不可用，需要重放遗漏的区块。
• 正在启动新的 Stream，需要从区块 N 到当前最新区块的历史数据。
• 更新筛选函数后，需要重新处理一段区块。

需要提供的信息

要求 Agent 触发回填时，请提供：

• Stream ID（可从 Quicknode 控制面板或 Admin API 获取）
• 起始区块编号
• 结束区块编号（或 latest）
• 目标位置确认（回填会发送至 Stream 现有的目标位置）

有关数据集选择、范围规划、批处理、压缩、成本指南和自动化说明，请参阅 references/streams-backfills-reference.md。

Webhooks

用于区块链活动的事件驱动通知。

Webhooks 与 Streams 对比

功能	Webhooks	Streams
设置	简单	需要更多配置
筛选	基于地址/事件	自定义 JavaScript
目标位置	仅 HTTP 端点	Webhook、S3、Postgres、Azure
处理	基础处理	完整转换
用例	简单提醒	复杂管道

有关 API 示例和完整的 Webhooks 文档，请参阅 references/webhooks-reference.md。

Solana gRPC（原名 Yellowstone gRPC）

高性能 Solana Geyser 插件，可通过 gRPC 实时流式传输区块链数据。Scale 和 Business 套餐包含此功能；Build 和 Accelerate 套餐可将其作为附加项使用。

快速设置

import Client, { CommitmentLevel } from "@triton-one/yellowstone-grpc";

// Derive from HTTP URL: https://example.solana-mainnet.quiknode.pro/TOKEN/
const client = new Client(
  "https://example.solana-mainnet.quiknode.pro:10000",
  "TOKEN",
  {}
);

const stream = await client.subscribe();
stream.on("data", (data) => {
  if (data.transaction) console.log("Tx:", data.transaction);
});

stream.write({
  transactions: {
    txn_filter: {
      vote: false,
      failed: false,
      accountInclude: ["PROGRAM_PUBKEY"],
      accountExclude: [],
      accountRequired: [],
    },
  },
  accounts: {},
  slots: {},
  blocks: {},
  blocksMeta: {},
  transactionsStatus: {},
  entry: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.CONFIRMED,
});

过滤器类型

过滤器	描述
accounts	按公钥、所有者或数据模式筛选账户数据变更
transactions	交易事件，支持投票、失败和账户过滤器
transactionsStatus	轻量级交易状态更新
slots	Slot 进度和状态变更
blocks	完整区块数据，可选择包含交易/账户
blocksMeta	不含完整内容的区块元数据
entry	PoH 条目更新

完整的 Solana gRPC 文档请参阅 references/solana-grpc-reference.md。

Blazar WSS

由 Quicknode 构建的 Solana WebSocket 引擎。重新构建了所有标准 Solana 订阅方法（blockSubscribe、accountSubscribe、transactionSubscribe、logsSubscribe 等），以提升可靠性和速度。所有套餐均免费包含，无需额外购买插件。使用与标准 Solana RPC 相同的 WSS 端点 URL（QUICKNODE_WSS_URL）。

文档： https://www.quicknode.com/docs/solana

快速设置

const ws = new WebSocket(process.env.QUICKNODE_WSS_URL!);

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'blockSubscribe',
    params: ['all', { commitment: 'confirmed', encoding: 'jsonParsed' }]
  }));
});

ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.params?.result?.value?.block) {
    console.log('New block slot:', msg.params.result.context.slot);
  }
});

支持的订阅方法

blockSubscribe、accountSubscribe、logsSubscribe、programSubscribe、signatureSubscribe、slotSubscribe、slotsUpdatesSubscribe、transactionSubscribe、voteSubscribe

HyperCore（Hyperliquid）

Quicknode 为 Hyperliquid L1 链提供的数据交付基础设施。支持通过 gRPC、JSON-RPC、WebSocket 和 Info API 访问。目前处于公开测试阶段。所有付费套餐均包含此服务。

访问方式

方法	路径 / 端口	使用场景
Info API	/info (POST)	用于市场数据、持仓和订单的 50 多种方法
JSON-RPC	/hypercore (POST)	区块查询（hl_getBlock、hl_getBatchBlocks）
WebSocket	/hypercore/ws	实时订阅（hl_subscribe）
gRPC	端口 10000	用于交易、订单和订单簿的最低延迟流式传输

gRPC 流类型

流	数据量	描述
TRADES	高	执行数据：币种、价格、数量、方向、费用
ORDERS	很高	订单生命周期，包含 18 种以上状态类型
BOOK_UPDATES	很高	L2 订单簿差异更新
TWAP	低	时间加权平均价格订单更新
EVENTS	高	账本更新、资金费、存款、提现
BLOCKS	极高	原始 HyperCore 区块（仅限 gRPC）
WRITER_ACTIONS	低	系统级代币转账

HyperEVM

路径	调试/追踪	归档	使用场景
/evm	否	部分	标准 EVM 操作
/nanoreth	是	扩展	调试、追踪、WebSocket 订阅

完整的 HyperCore 和 Hyperliquid 文档请参阅 references/hypercore-hyperliquid-reference.md。

---

SQL Explorer

无需基础设施即可直接访问区块链索引数据。使用标准 SQL 语法查询数十亿行链上数据，并在数秒内获取结果。

文档： https://www.quicknode.com/docs/sql-explorer

快速设置

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "SELECT timestamp, coin, side, price, size FROM hyperliquid_trades WHERE block_time > now() - INTERVAL 1 HOUR ORDER BY block_number DESC LIMIT 10",
    "clusterId": "hyperliquid-core-mainnet"
  }'

覆盖范围

Hyperliquid（HyperCore） - 涵盖交易、订单、成交、资金费、订单簿差异更新、永续市场、现货市场、区块、交易、系统操作、构建者活动、质押、账本更新等的表。

主要功能

• 无需基础设施 - 无需设置数据库或索引器
• 标准 SQL - 完整 SQL 语法，包括联接、子查询、CTE、窗口函数
• 40 多个预构建查询 - 适用于交易分析、巨鲸追踪、清算的常见模式
• 优化的性能 - 按月分区、排序键、列式存储
• REST API - 通过 HTTPS 以编程方式执行查询

完整的表结构、查询示例、优化技巧和 API 参考请参阅 references/sql-explorer.md。

Agent 身份（ERC-8004）

基于 ERC-8004 标准的链上 Agent 身份与声誉发现。erc-8004.quicknode.com 可跨受支持的 EVM 网络索引注册、反馈、验证和声誉信息。

API 基础地址： https://erc-8004.quicknode.com REST 前缀： /v1

有关经过验证的端点、x402 行为、速率限制和链上注册指南，请参阅 references/agent-identity-reference.md。

Blockbook

通过 Blockbook JSON-RPC 插件提供以钱包为中心的区块链数据。可跨受支持的链提供地址余额、UTXO 集和交易历史记录，尤其适用于 Bitcoin 等基于 UTXO 的链，因为标准 RPC 方法缺少钱包级索引。

产品介绍： https://www.quicknode.com/blockbook 文档： https://www.quicknode.com/docs/bitcoin/blockbook/overview

支持的链

Bitcoin（BTC）、Ethereum（ETH）、Bitcoin Cash（BCH）、Dogecoin（DOGE）、Litecoin（LTC）、Zcash（ZEC）——每种链均作为独立插件添加到你的端点。

适用场景

• 获取 Bitcoin 或其他基于 UTXO 的链上某个地址的完整余额和交易历史记录。
• 获取 UTXO 以构建交易。
• 查询某个地址的已确认／未确认余额，无需运行个人索引器。

有关方法和示例，请参阅 references/blockbook-reference.md。

Metaplex DAS API（Solana）

用于查询 Solana 数字资产的综合 API，涵盖标准 NFT、压缩 NFT（cNFT）、同质化代币、MPL Core 资产和 Token 2022 资产。可作为 Metaplex Digital Asset Standard（DAS）API 插件添加到你的 Quicknode Solana 端点。此前本技能文档将其称为“Solana DAS API”。

产品介绍： https://www.quicknode.com/metaplex-das-api 文档： https://www.quicknode.com/docs/solana/solana-das-api

快速设置

// Get all assets owned by a wallet
const response = await fetch(process.env.QUICKNODE_RPC_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'getAssetsByOwner',
    params: {
      ownerAddress: 'E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk',
      limit: 10,
      options: { showFungible: true, showCollectionMetadata: true }
    }
  })
});
const { result } = await response.json();
// result.total — total assets
// result.items — array of asset metadata
// result.cursor — for pagination

可用方法

方法	描述
getAsset	获取单个资产的元数据
getAssets	获取多个资产的元数据
getAssetProof	获取压缩资产的 Merkle 证明
getAssetProofs	获取多个资产的 Merkle 证明
getAssetsByAuthority	按权限方列出资产
getAssetsByCreator	按创建者列出资产
getAssetsByGroup	按群组列出资产（例如，合集）
getAssetsByOwner	按钱包所有者列出资产
getAssetSignatures	获取压缩资产的交易签名
getTokenAccounts	按铸币地址或所有者查询代币账户
getNftEditions	获取主 NFT 的版本详情
searchAssets	使用灵活的筛选条件搜索资产

有关包含所有方法、参数和示例的 DAS API 完整文档，请参阅 references/metaplex-das-reference.md。

Ordinals 与 Runes API

通过 Quicknode Ordinals & Runes API 插件提供 Bitcoin 铭文和 Runes 协议数据。可在你的 Bitcoin 端点上通过 JSON-RPC 和兼容 ORD 的 REST 查询铭文元数据、聪数据、Rune 详情和合集数据。共提供 21 种方法。

产品介绍： https://www.quicknode.com/ordinals-runes 文档： https://www.quicknode.com/docs/bitcoin/ord_getInscription

适用场景

• 查询指定铭文 ID 的铭文详情（内容类型、聪编号、稀有度、创世交易）。
• 查询 Rune 蚀刻详情、铸造参数和实时供应量。
• 获取 Bitcoin 输出，以及其中包含的铭文或 Runes。

有关支持的方法和示例，请参阅 references/ordinals-runes-reference.md。

插件

可启用到 Quicknode 端点上的专用功能插件。有关确切的 API 格式，请参阅插件文档或控制面板提供的端点详情。

Solana 优先费 API

// Get recommended priority fees
const response = await rpc.request('qn_estimatePriorityFees', {
  last_n_blocks: 100,
  account: 'YOUR_ACCOUNT'
}).send();

Jito Bundles

为已启用 Jito 插件的用户提供具备 MEV 感知能力的 Solana Bundle 提交和状态 API。

单次飞行 RPC

对相同的进行中 RPC 调用进行请求去重。适用于高并发应用，例如许多工作线程或用户同时请求相同数据的场景。

多区域交易广播

通过多个区域广播已签名的交易，以提高传播速度，适用于对延迟敏感的交易提交。

风险评估 API

提供钱包和交易风险数据，适用于合规、欺诈监控以及风险感知型交易工作流。

区块时间戳查询

提供时间戳到区块的查询工具，可将人类可读的时间范围转换为区块范围。

多链稳定币余额 API

提供受支持链上的稳定币余额，适用于资金管理、支付和投资组合工作流。

GoldRush 多链数据 API

提供多链钱包和投资组合数据，包括余额、代币持有量、NFT 持有量以及受支持情况下的交易历史记录。

有关当前附加组件指南和特定产品的参考链接，请参阅 references/addons.md。

---

Swap API

通过 Quicknode 附加组件聚合多种 DEX 代币兑换。支持 Metis/Jupiter、0x、OpenOcean、Aerodrome、Velodrome、Titan Meta Aggregator 和 Hyperliquid Exchange API。每个提供商都作为单独的附加组件或产品入口在你的端点/账户上启用。

营销页面： https://www.quicknode.com/swap-api

Solana — Metis（Jupiter）

import { createJupiterApiClient } from '@jup-ag/api';

const jupiterApi = createJupiterApiClient({
  basePath: process.env.QUICKNODE_METIS_URL!
});

const quote = await jupiterApi.quoteGet({
  inputMint: 'So11111111111111111111111111111111111111112',   // SOL
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: 1_000_000_000,  // 1 SOL in lamports
  slippageBps: 50
});

const swapResult = await jupiterApi.swapPost({
  swapRequest: {
    quoteResponse: quote,
    userPublicKey: 'YourPubkey...'
  }
});
// swapResult.swapTransaction — serialized tx ready for signing

将 QUICKNODE_METIS_URL 设置为你的 Metis 端点（例如，https://jupiter-swap-api.quiknode.pro/YOUR_TOKEN）。在 Quicknode 控制面板中启用 Metis Jupiter Swap API 附加组件。

有关提供商定位、已验证示例、安全默认值和故障排查，请参阅 references/swap-api-reference.md。

---

x402（按请求付费 RPC）

通过稳定币支付按请求访问 RPC。无需 API 密钥。提供三种支付模式：按请求付费（$0.001/次调用）、纳米支付（通过 Circle Gateway 批量处理）以及额度扣减（SIWX 身份验证，$10/100 万个主网额度）。测试网钱包共用每个钱包每月 1,000,000 个额度的上限；主网钱包不设上限。支持 Base/Polygon/Solana 上的 USDC，以及 XLayer 上的 USDG。可访问 140 多个链端点。

快速设置

import { createQuicknodeX402Client } from "@quicknode/x402";

const client = await createQuicknodeX402Client({
  baseUrl: "https://x402.quicknode.com",
  network: "eip155:84532", // Base Sepolia payment network
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
  paymentModel: "pay-per-request",
});

// Use like normal fetch — payment negotiation is handled automatically
const response = await client.fetch("https://x402.quicknode.com/ethereum-mainnet", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    method: "eth_blockNumber",
    params: [],
    id: 1,
  }),
});

通常，使用 Quicknode CLI 或 SDK 而非网关包是最快的方式：qn rpc call --x402（CLI v0.6.0+），或使用 scheme: "x402" 的 rpc.payment（SDK Node 3.8.0+，其他语言为 0.8.0+）。

有关完整的 x402 文档，包括 SIWX 身份验证、额度管理和 @quicknode/x402 设置，请参阅 references/x402-reference.md。

MPP（机器支付协议）

通过 IETF Payment Authentication 标头按请求访问 RPC。无需 API 密钥。提供两种支付意图类型：charge（$0.001/次请求）和 session（通过链下凭证支付 $0.00001/次请求）。Tempo 测试网钱包共用每个钱包每月 1,000,000 个额度的上限；主网钱包不设上限。可通过 Tempo 主网上的 PathUSD 或 USDC.e、Tempo 测试网上的 PathUSD，或 Solana 上的 USDC 支付。可访问 140 多个链端点。

快速设置

import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

// Polyfills globalThis.fetch — handles 402 challenges automatically
Mppx.create({
  methods: [tempo({ account })],
})

// Charge intent ($0.001/req) — payment is transparent
const response = await fetch('https://mpp.quicknode.com/tempo-mainnet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_blockNumber',
    params: [],
  }),
})

const { result } = await response.json()
console.log('Block number:', BigInt(result))

Quicknode CLI 和 SDK 也封装了此网关：qn rpc call --mpp（CLI v0.6.0+），或使用 scheme: "mpp" 的 rpc.payment（SDK Node 3.8.0+，其他语言为 0.8.0+）。

有关完整的 MPP 文档，包括 charge 与 session 支付意图、Solana 设置、CLI 用法和支付收据，请参阅 references/mpp-reference.md。

Agent 订阅

为自主 Agent 提供 Quicknode 账户的程序化创建功能。只需向 /api/v1/agent/subscriptions 发送一个包含 x402 或 MPP 付款的 POST 请求，即可同步创建付费账户并返回 QN_* 完整平台 API 密钥，无需在控制面板注册或确认电子邮件。用于 x402 和 MPP 按请求 RPC 的相同支付 SDK 也可为订阅付款签名。

文档： https://www.quicknode.com/docs/build-with-ai/agent-subscriptions

适用场景

• 按请求付费（x402、MPP）：当 Agent 只需要短期 RPC 访问且不需要持久状态时。
• Agent 订阅：当 Agent 需要完整平台功能时，包括 Streams、Webhooks、Key-Value Store、多个端点、安全规则、计费或任何其他 Admin API 功能。

发现套餐

若要获取实时套餐列表、价格、接受的支付网络、资产合约地址和收款方（payTo）地址，请在请求中不发送支付标头。服务器会返回 HTTP 402，正文中包含详细信息，并带有 PAYMENT-REQUIRED 标头（经过 base64 编码的 x402 要求）。

curl -X POST https://www.quicknode.com/api/v1/agent/subscriptions \
  -H "Content-Type: application/json" \
  -d '{}'

解析 402 响应正文，选择套餐，然后通过 SDK 重试请求。

快速设置（x402）

import { createQuicknodeX402Client } from '@quicknode/x402'

const client = await createQuicknodeX402Client({
  baseUrl: 'https://www.quicknode.com',
  network: 'eip155:8453', // Base Mainnet
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

const res = await client.fetch(
  'https://www.quicknode.com/api/v1/agent/subscriptions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      plan_name: 'b6_build', // b6_build | b6_accelerate | b6_scale | b6_business
      interval: 'monthly', // monthly | yearly
      email: '[email protected]',
      password: process.env.ACCOUNT_PASSWORD,
      password_confirmation: process.env.ACCOUNT_PASSWORD,
      full_name: 'Autonomous Agent',
      name: 'Agent Account',
      billing_address: {
        line1: '123 Main St',
        city: 'New York',
        postal_code: '10001',
        country: 'US',
      },
    }),
  },
)

const { api_key } = await res.json() // "QN_..." full platform API key

返回的 api_key 与此技能其他部分使用的 QUICKNODE_API_KEY 相同。使用它访问 https://api.quicknode.com/v0/...，以配置端点、设置安全性、充值、读取余额等。

使用 Solana 付款？ 使用 @quicknode/x402-solana，通过 Solana 密钥对签署 x402 付款，而不是使用 EVM 私钥。配置完成后，订阅请求正文和 Admin API 步骤与上方的 x402 示例相同。设置详情请参阅 如何使用 x402 访问 Solana RPC 指南。

快速设置（MPP）

import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

Mppx.create({ methods: [tempo({ account })] })

const subscriptionRes = await fetch(
  'https://www.quicknode.com/api/v1/agent/subscriptions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      plan_name: 'b6_build', // b6_build | b6_accelerate | b6_scale | b6_business
      interval: 'monthly', // monthly | yearly
      email: '[email protected]',
      password: process.env.ACCOUNT_PASSWORD,
      password_confirmation: process.env.ACCOUNT_PASSWORD,
      full_name: 'Autonomous Agent',
      name: 'Agent Account',
      billing_address: {
        line1: '123 Main St',
        city: 'New York',
        postal_code: '10001',
        country: 'US',
      },
    }),
  },
)

const { api_key } = await subscriptionRes.json() // "QN_..." full platform API key

端点

方法	路径	身份验证	速率限制	用途
POST	/api/v1/agent/subscriptions	支付标头（x402 或 MPP）	每个 IP + 邮箱每分钟 20 次、每小时 5 次	创建账户和订阅
POST	/api/v1/agent/top_up	API 密钥 + 支付标头	每个 API 密钥每分钟 30 次	为现有订阅充值
GET	/api/v1/agent/balance	API 密钥	每个 API 密钥每分钟 60 次	读取当前额度余额

所有请求都发往 https://www.quicknode.com。

套餐 ID

b6_build、b6_accelerate、b6_scale、b6_business。分别对应 定价页面 上公开的 Build、Accelerate、Scale 和 Business 套餐。当 Agent 需要动态选择套餐时，使用上方介绍的 402 发现方式。

安全措施

• 真实资金：订阅通过主网支付网络，以真实稳定币结算。发送请求前，先与用户确认套餐、周期和支付网络。
• 重复邮箱保护：重复使用已有邮箱会返回错误。恢复失败的请求时，请使用相同的 email 和 password，不要创建重复账户。
• 支付重试安全性：生成支付标头后若验证失败，请逐字节原样重试，并使用相同的已签名支付标头。除非服务器要求新的挑战，否则不要为同一操作重新签署支付。
• 无免费试用：所有订阅从首次请求起即为正式服务。
• 同步创建：账户创建和订阅激活在同一请求中完成。无需等待异步任务或 Webhook。
• 不得编造信息：不得编造计费详情、密码或邮箱地址。必须要求用户明确提供。密码长度须为 8–64 个字符，并至少包含一个小写字母、一个大写字母、一个数字和一个特殊字符。

完整的端点参考、充值流程和余额检查，请参阅 references/agent-subscriptions-reference.md。

Quicknode CLI

命令行工具（qn），用于在终端管理 Quicknode 基础设施。所有付费套餐均可使用。

它还提供无需密钥的付费方式（v0.6.0+）：通过 qn wallet 和 qn rpc call --x402/--mpp 使用稳定币支付 RPC 调用，无需 Quicknode 账户、API 密钥、登录、Tooling Access 或已配置的端点。

安装

# Homebrew
brew install quicknode/tap/qn

# Docker
docker pull quiknode/qn-cli:latest

身份验证

本地工作时使用交互式登录，或在非交互式环境中显式传入 API 密钥：

qn auth login
qn auth login --api-key <KEY>
qn auth whoami

凭据优先级依次为 --api-key、--config-file，然后是 ~/.config/qn/config.toml。CLI 不会直接从环境变量读取 API 密钥。

Agent 上下文

qn agent context
qn agent context -o json

主要命令

# Endpoints
qn endpoint list
qn endpoint create --chain ethereum --network mainnet

# RPC (Tooling Access) — no endpoint setup required
qn tooling-access status
qn tooling-access enable
qn rpc call eth_getBlockByNumber '["latest", false]' --network base-mainnet

# Account and chain metadata
qn auth whoami --format json
qn chain credits ethereum --format json

# SQL Explorer
qn sql query "SELECT COUNT(*) FROM hyperliquid_trades" --cluster-id hyperliquid-core-mainnet --format json
qn sql schema hyperliquid-core-mainnet

# Streams / Webhooks / KV
qn stream list
qn webhook list
qn kv set get my-key

使用 --format json 获取机器可读的输出。执行修改操作的命令会在操作前提示；在自动化中绕过提示时，必须先获得用户的明确确认。

付费 RPC（x402 / MPP）

需要 v0.6.0+。请发现当前提供的网络和资产，而不要将其硬编码，并在每个签名操作中设置 --max-amount（以资产的整数最小单位表示的单次调用上限）。

# One-time keyless setup — the key is written locally and is not recoverable
qn wallet generate --vm evm --name payer

# Discover what each gateway accepts
qn rpc x402 supported-payments
qn rpc mpp supported-payments

# Pay per request (query network and payment network are independent)
qn rpc call eth_blockNumber --network ethereum-mainnet \
  --x402 --payment-wallet payer \
  --payment-network base-sepolia --payment-asset USDC --max-amount 1000

# Prepaid credits (x402) or an escrow channel (MPP) for sustained usage
qn rpc x402 buy-credits --network ethereum-mainnet --payment-wallet payer \
  --payment-network base-sepolia --payment-asset USDC --max-amount 10000000
qn rpc call eth_blockNumber --network ethereum-mainnet --x402-drawdown --payment-wallet payer

这些命令会转移真实资金。请先获得用户的明确确认，并使用专用且仅存入最低限额资金的钱包。qn wallet rm、qn rpc x402 buy-credits 和 qn rpc mpp open/top-up/close 受保护，执行前会提示。付费调用不会自动重试：退出码 2 表示未完成结算；退出码 3 表示结果未知，钱包可能已被扣款——请检查钱包，而不要重新运行。

完整 CLI 文档请参阅 references/cli-reference.md。

Quicknode MCP

原生 Claude/OpenAI 连接器和通用 MCP 服务，可通过 Model Context Protocol（MCP）向 AI 助手提供 Quicknode Admin API 功能。

设置

Claude Web/Desktop： 设置 → 自定义 → 连接器 → 找到 Quicknode → 连接。

Claude Code：

claude mcp add --transport http quicknode https://mcp.quicknode.com/mcp

交互式设置使用 OAuth：登录 Quicknode，选择 Viewer 或 Admin，然后批准访问权限。只读检查请选择 Viewer；只有在助手需要创建、删除或修改资源时才选择 Admin。

OpenAI（ChatGPT/Codex）： 从 ChatGPT Apps 目录安装 Quicknode；也可以在 Codex 中通过 /plugin 安装（如果已提供）。有关当前设置详情，请查看 Quicknode MCP 文档页面上的 OpenAI 综合选项卡。

功能

MCP 服务提供用于端点管理（列出、创建、删除、速率限制）、安全规则、用量监控、计费和链发现的工具。Agent 和用户无需离开 AI 工具，即可通过对话管理 Quicknode 工作区。

完整工具功能和设置说明请参阅 references/mcp-reference.md。

---

Quicknode SDK

用于 Quicknode 产品 API 的官方 SDK：Admin API、Streams、Webhooks、Key-Value Store 和 SQL Explorer。rpc 客户端（Node 3.7.0+，其他语言 0.7.0+）还可以通过 Tooling Access 向任何受支持的网络发起 JSON-RPC 调用，无需设置端点。对于类型化链抽象或专用端点，仍需使用特定链的客户端库。

同一个 rpc 客户端还可以通过 x402 或 MPP 使用稳定币支付调用（Node 3.8.0+，其他语言 0.8.0+），无需 Quicknode 账户或 API 密钥。

安装

npm install @quicknode/sdk

基本用法

import { QuicknodeSdk } from '@quicknode/sdk';

const qn = QuicknodeSdk.fromEnv();

const endpoints = await qn.admin.getEndpoints({
  limit: 20,
  sortBy: 'created_at',
  sortDirection: 'desc',
});

const account = await qn.admin.accountInfo();
const apiCredits = await qn.admin.getApiCredits('ethereum');

const trades = await qn.sql.query(
  'SELECT * FROM hyperliquid_trades LIMIT 5',
  'hyperliquid-core-mainnet'
);

RPC 小额支付

设置 rpc.payment 后，SDK 会响应 402 Payment Required 挑战，签署付款并重新发送请求。此方式无需 API 密钥。

import { QuicknodeSdk, generatePaymentWallet } from '@quicknode/sdk';

// One-time: the key is returned once and cannot be recovered. Persist it securely.
const wallet = generatePaymentWallet('evm'); // 'evm' or 'svm'
console.log('Fund this address:', wallet.address);

const qn = new QuicknodeSdk({
  rpc: {
    payment: {
      scheme: 'x402', // or 'mpp'
      key: process.env.QN_PAYMENT_KEY!,
      payNetwork: 'eip155:84532', // Base Sepolia
      asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // Base Sepolia USDC
      maxAmount: '10000', // spend ceiling in base units, not the amount sent
    },
  },
});

const blockNumber = await qn.rpc.call('eth_blockNumber', [], 'ethereum-mainnet');

callWithReceipt 会返回结算元数据（MPP 时为非空，x402 时为 null）。如需持续使用，请使用 gatewayAuthenticate/gatewayBuyCredits/gatewayDrawdownCall（x402 额度）或 mppOpen/mppSessionCall（MPP 通道）。此方式会转移真实资金——请先获得用户的明确确认，并且切勿记录付款配置，因为其中包含原始私钥。

完整 SDK 文档请参阅 references/sdk-reference.md。

Admin API

用于以编程方式管理 Quicknode 端点、用量、速率限制、安全、计费和团队的 REST API。支持基础设施即代码工作流。

快速参考

资源	方法	端点
链	GET	/v0/chains
账户信息	GET	/v0/account/info
API 额度	GET	/v0/api-credits/{chain}
端点	GET、POST、PATCH、DELETE	/v0/endpoints
指标	GET	/v0/endpoints/{id}/metrics
速率限制	GET、POST、PUT	/v0/endpoints/{id}/method-rate-limits、/v0/endpoints/{id}/rate-limits
安全	GET	/v0/endpoints/{id}/security_options
工具访问权限	GET、PATCH、POST	/v0/tooling-access、/v0/tooling-access/token
用量	GET	/v0/usage/rpc、by-endpoint、by-method、by-chain
账单	GET	/v0/billing/invoices
团队	GET	/v0/teams

身份验证

所有请求均通过 x-api-key 请求头访问 https://api.quicknode.com/v0/。

const QN_API_KEY = process.env.QUICKNODE_API_KEY!;

const res = await fetch('https://api.quicknode.com/v0/endpoints', {
  headers: { 'x-api-key': QN_API_KEY },
});
const endpoints = await res.json();

完整的 Admin API 文档请参阅 references/admin-api-reference.md，其中包括端点的 CRUD 操作、用量监控、速率限制配置、安全选项、工具访问权限、账单和团队。

键值存储（Beta）

用于存储列表和键值集合的无服务器存储，主要通过 qnLib 辅助库在 Streams 过滤函数中访问。也可通过 REST API 使用。

Stream 集成（qnLib）

列表操作 — 管理条目列表（例如钱包地址）：

• qnLib.qnUpsertList — 创建或更新列表
• qnLib.qnAddListItem — 向列表添加条目
• qnLib.qnRemoveListItem — 从列表中移除条目
• qnLib.qnContainsListItems — 批量检查成员关系
• qnLib.qnDeleteList — 删除列表

集合操作 — 管理键值对：

• qnLib.qnAddSet — 创建键值集合
• qnLib.qnGetSet — 根据键获取值
• qnLib.qnBulkSets — 批量创建或移除集合
• qnLib.qnListAllSets — 列出所有集合键
• qnLib.qnDeleteSet — 删除集合

REST API 用法、大小限制和 CLI（qn kv）命令请参阅 references/kv-reference.md。

---

其他 Quicknode 产品

以下 Quicknode 产品可供使用，但 Agent 通常不会直接调用。它们由账户所有者通过控制面板配置，或由人工操作员配置。

• 验证器即服务 — 非托管式 Ethereum 质押，支持自定义费用接收方和 MEV-boost。https://www.quicknode.com/validator-as-a-service
• Solana 验证器 — 托管式 Solana 验证器基础设施。https://www.quicknode.com/chains/solana/validator
• Monad 验证器 — 托管式 Monad 验证器基础设施。https://www.quicknode.com/chains/monad/validator
• ChainKit — 无代码区块链数据工具和集成。https://www.quicknode.com/chainkit

---

常见模式

多链 RPC 设置

import { JsonRpcProvider } from 'ethers';

const ethereum = new JsonRpcProvider(process.env.QUICKNODE_ETH_RPC_URL!);
const base = new JsonRpcProvider(process.env.QUICKNODE_BASE_RPC_URL!);

const [ethBlock, baseBlock] = await Promise.all([
  ethereum.getBlockNumber(),
  base.getBlockNumber(),
]);

实时交易监控

1. 创建 Stream，筛选你的合约地址
2. 添加过滤函数，提取相关事件
3. 配置 Webhook 目标地址为你的服务
4. 在后端处理事件

使用 Solana gRPC 进行实时 Solana 监控

1. 通过 gRPC 连接，使用端口 10000 和你的身份验证令牌
2. 订阅交易，按程序或账户进行筛选
3. 通过流式接口实时处理更新
4. 实现带有指数退避的重新连接

Hyperliquid 交易数据管道

1. 通过 gRPC 连接，使用端口 10000 获取最低延迟数据
2. 订阅 TRADES/ORDERS 流，并按币种筛选
3. 处理事件 — 处理约 12 个区块/秒的吞吐量
4. 使用 Info API（/info）获取账户状态和市场元数据

使用 SQL Explorer 进行历史交易分析

1. 查询历史交易 — SELECT * FROM hyperliquid_trades WHERE block_time > ...
2. 汇总指标 — 使用 GROUP BY 统计交易量、计数和平均值
3. 联接表 — 组合交易、订单和资金费率数据，进行全面分析
4. 导出数据 — 将结果导出为 JSON，以供下游处理

最佳实践

RPC

• 使用 WebSocket 进行订阅和实时数据传输
• 实现带指数退避的重试逻辑
• 对变化不频繁的数据缓存响应
• 使用批量请求减少 API 调用

流

• 从较窄的筛选条件开始，根据需要逐步扩大范围
• 部署前在本地测试筛选函数
• 流会在失败时自动重试
• 通过仪表板监控流的运行状况

安全

• 将 API 密钥存储在环境变量中
• 在生产环境中启用 IP 允许列表
• 对敏感操作使用 JWT 身份验证
• 定期轮换 API 密钥

gRPC

• 启用 zstd 压缩以减少带宽（Hyperliquid 上最多可减少 70%）
• 实现带指数退避的重连逻辑 — 流可能会断开
• 使用较窄的筛选条件（特定账户、币种或程序），尽量减少数据量
• 设置适当的确认级别（Solana gRPC：大多数用例使用 CONFIRMED；需要不可逆性时使用 FINALIZED）
• 发送 keepalive ping（Solana gRPC 每 10 秒一次，HyperCore 每 30 秒一次）以保持连接

SQL Explorer

• 始终按时间范围筛选，以便进行分区裁剪（WHERE block_time > ...）
• 在探索性查询中使用 LIMIT，以减少扫描的数据量
• 利用排序键（查看架构参考）优化查询性能
• 从预构建查询开始，并根据需求进行自定义
• 监控查询统计信息（rows_read、bytes_read）以优化性能

文档链接

Quicknode 产品

• 主要文档：https://www.quicknode.com/docs/
• Core RPC API：https://www.quicknode.com/core-api
• Streams：https://www.quicknode.com/docs/streams
• Streams 回填：https://www.quicknode.com/docs/streams/backfilling
• Webhooks：https://www.quicknode.com/docs/webhooks
• Blazar WSS：https://www.quicknode.com/docs/solana
• Solana gRPC：https://www.quicknode.com/docs/solana/solana-grpc/overview
• HyperCore gRPC：https://www.quicknode.com/docs/hyperliquid/grpc-api
• IPFS：https://www.quicknode.com/docs/ipfs
• SDK：https://www.quicknode.com/docs/sdk
• SDK RPC 微支付：https://www.quicknode.com/docs/sdk/micropayments
• 管理 API：https://www.quicknode.com/docs/admin-api
• Metaplex DAS API（Solana）：https://www.quicknode.com/docs/solana/solana-das-api
• Blockbook：https://www.quicknode.com/docs/bitcoin/blockbook/overview
• Ordinals 和 Runes API：https://www.quicknode.com/docs/bitcoin/ord_getInscription
• Quicknode CLI：https://www.quicknode.com/docs/cli
• CLI RPC 微支付：https://www.quicknode.com/docs/cli/micropayments
• Quicknode MCP：https://www.quicknode.com/docs/build-with-ai/quicknode-mcp
• Hyperliquid：https://www.quicknode.com/docs/hyperliquid
• SQL Explorer：https://www.quicknode.com/docs/sql-explorer
• SQL Explorer REST API：https://www.quicknode.com/docs/sql-explorer/using-rest-api
• Hyperliquid 查询：https://www.quicknode.com/docs/sql-explorer/hyperliquid-queries
• 架构参考：https://www.quicknode.com/docs/sql-explorer/schema-reference
• 键值存储：https://www.quicknode.com/docs/key-value-store
• x402：https://x402.quicknode.com
• MPP：https://mpp.quicknode.com
• Agent 订阅：https://www.quicknode.com/docs/build-with-ai/agent-subscriptions
• Agent 身份（ERC-8004）：https://erc-8004.quicknode.com
• Swap API（Metis/Jupiter）：https://www.quicknode.com/docs/solana/metis-overview
• AI 构建概览：https://www.quicknode.com/docs/build-with-ai
• Agent 参考（agents.md）：https://www.quicknode.com/agents.md

特定链文档

• Ethereum：https://www.quicknode.com/docs/ethereum
• Solana：https://www.quicknode.com/docs/solana
• Polygon：https://www.quicknode.com/docs/polygon
• Arbitrum：https://www.quicknode.com/docs/arbitrum
• Base：https://www.quicknode.com/docs/base
• Optimism：https://www.quicknode.com/docs/optimism
• Avalanche：https://www.quicknode.com/docs/avalanche
• BNB Smart Chain：https://www.quicknode.com/docs/bnb-smart-chain
• Hyperliquid：https://www.quicknode.com/docs/hyperliquid

面向大模型优化的文档

• 平台概览（llms.txt）：https://www.quicknode.com/llms.txt — Quicknode 所有产品、链、指南和解决方案的高级索引
• 文档索引（llms.txt）：https://www.quicknode.com/docs/llms.txt — 按链和产品划分的文档索引（链接至 https://www.quicknode.com/docs/{chain-or-product}/llms.txt）
• x402（llms.txt）：https://x402.quicknode.com/llms.txt
• MPP（llms.txt）：https://mpp.quicknode.com/llms.txt

其他资源

• Quicknode 指南：https://www.quicknode.com/guides
• SDK 参考：https://www.quicknode.com/docs/sdk
• 附加组件目录：https://www.quicknode.com/add-ons
• 示例应用库：https://www.quicknode.com/sample-app-library
• 指南示例仓库：https://github.com/quiknode-labs/qn-guide-examples