quicknode

Quicknode Solana 基础设施

使用 Quicknode 构建高性能 Solana 应用——Quicknode 是区块链基础设施提供商，支持 80+ 条链，提供低延迟 RPC 端点、DAS API、Yellowstone gRPC 流式传输、实时数据管道和以开发者为先的 API。

概览

Quicknode 提供：

• RPC 端点：低延迟访问 Solana，身份验证信息嵌入在 URL 中
• DAS API：统一查询 NFT 和代币——标准 NFT、压缩 NFT（cNFT）、同质化代币、MPL Core Assets、Token 2022
• Yellowstone gRPC：通过 Geyser 插件实时流式传输 Solana 数据
• 优先费用 API：估算交易上链费用
• Streams：支持 JavaScript 过滤的实时和历史数据管道
• Webhooks：事件驱动的区块链通知
• Metis：Jupiter Swap API 集成
• IPFS：去中心化文件存储
• 键值存储：为 Streams 提供无服务器状态持久化
• 管理 API：以编程方式管理端点
• x402：通过 USDC 小额支付按请求付费使用 RPC（无需 API 密钥）
• 多链：支持 80+ 个网络，包括 Ethereum、Polygon、Arbitrum、Base、BSC、Avalanche、Bitcoin 等

快速开始

获取端点

1. 访问 quicknode.com/endpoints
2. 选择 Solana 和你的网络（Mainnet / Devnet）
3. 创建端点
4. 复制 HTTP 和 WSS URL

环境设置

# .env file
QUICKNODE_RPC_URL=https://your-endpoint.solana-mainnet.quiknode.pro/your-token/
QUICKNODE_WSS_URL=wss://your-endpoint.solana-mainnet.quiknode.pro/your-token/
QUICKNODE_API_KEY=your_console_api_key  # Optional: for Admin API

使用 @solana/kit 进行基本设置

import { createSolanaRpc, createSolanaRpcSubscriptions } from "@solana/kit";

const rpc = createSolanaRpc(process.env.QUICKNODE_RPC_URL!);
const rpcSubscriptions = createSolanaRpcSubscriptions(process.env.QUICKNODE_WSS_URL!);

// Make RPC calls
const slot = await rpc.getSlot().send();
const balance = await rpc.getBalance(address).send();

身份验证

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

https://{ENDPOINT_NAME}.solana-mainnet.quiknode.pro/{TOKEN}/

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

RPC 端点

Solana 端点

网络	URL 模式
Mainnet	https://{name}.solana-mainnet.quiknode.pro/{token}/
Devnet	https://{name}.solana-devnet.quiknode.pro/{token}/
WebSocket	wss://{name}.solana-mainnet.quiknode.pro/{token}/

与 @solana/kit 配合使用

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  address,
  lamports,
} from "@solana/kit";

const rpc = createSolanaRpc(process.env.QUICKNODE_RPC_URL!);
const rpcSubscriptions = createSolanaRpcSubscriptions(process.env.QUICKNODE_WSS_URL!);

// Account balance
const balance = await rpc.getBalance(address("E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk")).send();

// Account info
const accountInfo = await rpc.getAccountInfo(address("E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk"), {
  encoding: "base64",
}).send();

// Recent blockhash
const { value: blockhash } = await rpc.getLatestBlockhash().send();

// Token accounts
const tokenAccounts = await rpc.getTokenAccountsByOwner(
  address("E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk"),
  { programId: address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA") },
  { encoding: "jsonParsed" },
).send();

与 Legacy web3.js 配合使用

import { Connection, PublicKey } from "@solana/web3.js";

const connection = new Connection(process.env.QUICKNODE_RPC_URL!);
const balance = await connection.getBalance(new PublicKey("E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk"));

速率限制与套餐

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

DAS API（数字资产标准）

用于查询 Solana 数字资产的综合 API——标准 NFT、压缩 NFT（cNFT）、同质化代币、MPL Core Assets 和 Token 2022 Assets。可作为 Marketplace 附加服务使用（Metaplex DAS API）。

按所有者获取资产

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

搜索资产

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: "searchAssets",
    params: {
      ownerAddress: "E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk",
      tokenType: "fungible",
      limit: 50,
    },
  }),
});

获取资产证明（压缩 NFT）

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: "getAssetProof",
    params: { id: "compressed_nft_id" },
  }),
});

DAS 方法参考

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

Yellowstone gRPC（Solana Geyser）

高性能 Solana Geyser 插件，可通过 gRPC 实时流式传输区块链数据。可作为 Marketplace 附加服务使用。

设置

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

// Derive gRPC URL from HTTP endpoint:
// HTTP:  https://example.solana-mainnet.quiknode.pro/TOKEN/
// gRPC:  https://example.solana-mainnet.quiknode.pro:10000
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("Transaction:", data.transaction);
  }
  if (data.account) {
    console.log("Account update:", data.account);
  }
});

// Subscribe to transactions for a specific program
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 条目更新

gRPC 最佳实践

• 使用端口 10000 建立 gRPC 连接
• 大多数场景将 commitment 设为 CONFIRMED；如需确保不可逆，则设为 FINALIZED
• 启用 zstd 压缩以减少带宽占用
• 每隔 10 秒发送一次 keepalive ping，以维持连接
• 使用指数退避实现重连逻辑
• 使用范围较窄的过滤器（指定账户或程序），以尽量减少数据量

Priority Fee API

估算优先级费用，以优化交易上链效果。

// Get recommended priority fees
const response = await fetch(process.env.QUICKNODE_RPC_URL!, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    method: "qn_estimatePriorityFees",
    params: {
      last_n_blocks: 100,
      account: "YOUR_ACCOUNT_PUBKEY",
    },
  }),
});

在交易中使用优先级费用

import {
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  prependTransactionMessageInstructions,
  appendTransactionMessageInstruction,
} from "@solana/kit";
import {
  getSetComputeUnitLimitInstruction,
  getSetComputeUnitPriceInstruction,
} from "@solana-program/compute-budget";

// 1. Get fee estimate
const feeResponse = await fetch(process.env.QUICKNODE_RPC_URL!, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    method: "qn_estimatePriorityFees",
    params: { last_n_blocks: 100, account: payer.address },
  }),
});
const feeData = await feeResponse.json();
const priorityFee = feeData.result.per_compute_unit.high;

// 2. Build transaction with compute budget
const tx = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(payer.address, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(blockhash, tx),
  (tx) => prependTransactionMessageInstructions([
    getSetComputeUnitLimitInstruction({ units: 200_000 }),
    getSetComputeUnitPriceInstruction({ microLamports: BigInt(priorityFee) }),
  ], tx),
  (tx) => appendTransactionMessageInstruction(mainInstruction, tx),
);

Metis — Jupiter Swap API

Quicknode 托管的 Jupiter Swap API，用于 DEX 聚合。可作为 Marketplace 附加项使用。

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

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

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

// Get swap transaction
const swapResult = await jupiterApi.swapPost({
  swapRequest: {
    quoteResponse: quote,
    userPublicKey: "YourPubkey...",
  },
});

Streams

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

流类型

类型	数据	使用场景
Block	完整区块数据	区块浏览器、分析
Transaction	交易详情	交易监控、索引
Logs	合约事件	DeFi 跟踪、代币转账
Receipt	交易回执	状态跟踪

设置

1. 在 Quicknode 控制面板中创建流
2. 选择 Solana 和数据类型
3. 添加过滤函数（JavaScript）
4. 配置目标位置（webhook、S3、PostgreSQL、Azure）

过滤函数示例

function main(data) {
  // Filter for transactions involving a specific program
  const PROGRAM_ID = "YOUR_PROGRAM_ID";
  const hasProgram = data.transaction?.message?.accountKeys?.some(
    (key) => key === PROGRAM_ID
  );
  if (!hasProgram) return null;
  return data;
}

Streams 与 Webhooks 的对比

特性	Streams	Webhooks
复杂度	需要更多配置	设置简单
过滤	自定义 JavaScript	基于模板
目标位置	Webhook、S3、Postgres、Azure、Snowflake	仅 HTTP 端点
处理	完整转换	有限
使用场景	复杂管道	简单提醒

Webhooks

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

Webhook 设置

通过 Quicknode 控制面板或 Admin API 创建 Webhook，以便在发生特定链上事件时接收通知。

API 示例和配置请参阅 resources/webhooks-reference.md。

IPFS 存储

通过 Quicknode 的 IPFS 网关进行去中心化文件存储。

// Upload file to IPFS
const formData = new FormData();
formData.append("file", fileBuffer);

const response = await fetch("https://api.quicknode.com/ipfs/rest/v1/s3/put-object", {
  method: "POST",
  headers: { "x-api-key": process.env.QUICKNODE_API_KEY! },
  body: formData,
});

const { pin } = await response.json();
// Access via: https://quicknode.quicknode-ipfs.com/ipfs/{pin.cid}

常见使用场景

• NFT 元数据存储
• 集合的资产托管
• 去中心化内容持久化

键值存储

用于存储列表和键值集合的无服务器存储，可通过 qnLib 帮助程序库从 Streams 过滤函数访问。

Streams 集成（qnLib）

// In a Streams filter function:

// List operations — manage address watchlists
await qnLib.qnAddListItem("my-watchlist", "E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk");
const isWatched = await qnLib.qnContainsListItems("my-watchlist", [data.from]);

// Set operations — store key-value pairs
await qnLib.qnAddSet("token-prices", { key: "SOL", value: "150.25" });
const price = await qnLib.qnGetSet("token-prices", "SOL");

列表操作

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

集合操作

• qnLib.qnAddSet — 创建键值集合
• qnLib.qnGetSet — 按键获取值
• qnLib.qnBulkSets — 批量创建或移除集合
• qnLib.qnDeleteSet — 删除集合

Quicknode SDK

Quicknode 服务的官方 JavaScript/TypeScript SDK。

npm install @quicknode/sdk

import { Core } from "@quicknode/sdk";

const core = new Core({
  endpointUrl: process.env.QUICKNODE_RPC_URL!,
});

// Token API
const balances = await core.client.qn_getWalletTokenBalance({
  wallet: "E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk",
});

// NFT API
const nfts = await core.client.qn_fetchNFTs({
  wallet: "E645TckHQnDcavVv92Etc6xSWQaq8zzPtPRGBheviRAk",
  page: 1,
  perPage: 10,
});

Admin API

用于以编程方式管理 Quicknode 端点、用量、速率限制、安全和账单的 REST API。

身份验证

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

const QN_API_KEY = process.env.QUICKNODE_API_KEY!;

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

// Get usage metrics
const usage = await fetch("https://api.quicknode.com/v0/usage/rpc", {
  headers: { "x-api-key": QN_API_KEY },
});

快速参考

资源	方法	端点
链	GET	/v0/chains
端点	GET, POST, PATCH, DELETE	/v0/endpoints
指标	GET	/v0/endpoints/{id}/metrics
速率限制	GET, POST, PUT	/v0/endpoints/{id}/rate-limits
用量	GET	/v0/usage/rpc
账单	GET	/v0/billing/invoices

x402（按请求付费的 RPC）

通过 Base 上的 USDC 微支付使用按请求付费的 RPC。无需 API 密钥。

import { wrapFetch } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

// Wrap fetch to auto-handle 402 payments
const x402Fetch = wrapFetch(fetch, walletClient);

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

多链支持

Quicknode 支持 Solana 之外的 80 多个区块链网络：

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

完整列表：quicknode.com/chains

多链设置

import { Core } from "@quicknode/sdk";

const chains = {
  solana: new Core({ endpointUrl: process.env.QUICKNODE_SOL_RPC! }),
  ethereum: new Core({ endpointUrl: process.env.QUICKNODE_ETH_RPC! }),
  polygon: new Core({ endpointUrl: process.env.QUICKNODE_POLYGON_RPC! }),
};

安全默认设置

• 未指定网络时，默认使用 devnet
• 优先使用只读操作，并在创建资源前进行试运行
• 绝不索取或接受私钥或密钥
• 创建 Streams、Webhooks 或上传到 IPFS 前，必须获得明确确认

错误处理

try {
  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: "getSlot", params: [] }),
  });
  if (!response.ok) {
    if (response.status === 401) console.error("Invalid endpoint URL or token");
    if (response.status === 429) console.error("Rate limited — upgrade plan or reduce requests");
    if (response.status >= 500) console.error("Server error — retry with backoff");
  }
} catch (error) {
  console.error("Network error:", error);
}

常见错误代码

代码	含义	解决方案
401	身份验证无效	检查端点 URL 和令牌
429	超出速率限制	升级套餐或增加延迟
500+	服务端错误	使用指数退避重试

最佳实践

API 密钥安全

• 切勿将端点 URL 或 API 密钥提交到 git
• 使用环境变量
• 在生产环境中启用 IP 允许列表
• 对敏感操作使用 JWT 身份验证
• 定期轮换凭据

性能

• 使用 WebSocket 订阅获取实时数据
• 批量发送 RPC 请求以减少 API 调用
• 数据变化不频繁时缓存响应
• 使用 Yellowstone gRPC 实现最低延迟的数据流传输
• 设置适当的 commitment 级别（大多数情况使用 confirmed，不可逆操作使用 finalized）

可靠性

• 使用指数退避实现重试逻辑
• 通过退避机制妥善处理速率限制
• 使用 Streams 可靠地处理事件（自动重试）
• 通过 Admin API 指标监控端点运行状况

资源

• Quicknode 文档
• Solana 专属文档
• DAS API 参考
• Yellowstone gRPC
• Streams 文档
• Quicknode SDK
• Admin API
• Key-Value Store
• x402
• 针对 LLM 优化的文档（llms.txt）
• 指南
• Marketplace
• 示例应用
• 指南示例仓库

技能结构

quicknode/
├── SKILL.md                       # This file
├── resources/
│   ├── rpc-reference.md           # RPC methods and WebSocket patterns
│   ├── das-api-reference.md       # DAS API methods and parameters
│   ├── yellowstone-grpc-reference.md  # gRPC streaming reference
│   ├── streams-reference.md       # Streams filter functions and destinations
│   ├── webhooks-reference.md      # Webhook configuration
│   └── marketplace-addons.md      # Token API, NFT API, Metis, Priority Fees
├── examples/
│   ├── basic-rpc/                 # Basic RPC calls
│   ├── das-api/                   # DAS API queries
│   ├── streaming/                 # Yellowstone gRPC examples
│   └── streams-webhooks/          # Streams and webhook setup
├── templates/
│   └── quicknode-setup.ts         # Starter template
└── docs/
    └── troubleshooting.md         # Common issues and solutions