跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.raydium.io/llms.txt

Use this file to discover all available pages before exploring further.

本页内容由 AI 自动翻译，所有内容以英文版本为准。查看英文版 →
版本提示。 本页面文档适用于 @raydium-io/raydium-sdk-v2@0.2.42-alpha，这是本网站所有代码演示验证过的版本（2026-04）。SDK 还未发布 1.0，类型表面在不同版本间有演变 — 请锁定你使用的版本。

​
安装

npm install @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
# 或
pnpm add @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
SDK 采用 TypeScript 编写，附带 .d.ts 文件。最低工具链要求：Node 18+、TypeScript 5.0+、moduleResolution: "bundler" 或 "node16"。

​
初始化

入口点是 Raydium.load： 
import { Raydium } from "@raydium-io/raydium-sdk-v2";
import { Connection, Keypair, clusterApiUrl } from "@solana/web3.js";

const connection = new Connection(process.env.RPC_URL ?? clusterApiUrl("mainnet-beta"));
const owner      = Keypair.fromSecretKey(/* ... */);

const raydium = await Raydium.load({
  owner,
  connection,
  cluster: "mainnet",           // "mainnet" | "devnet"
  disableFeatureCheck: true,    // 跳过 SDK 启动时的特性检测 API 调用
  blockhashCommitment: "confirmed",
});
Raydium.load 是异步的，因为它在启动时从 api-v3.raydium.io 拉取一个小的 /config 载荷（包含当前的 AmmConfig 账户、费用等级等）。在离线环境中设置 disableFeatureCheck: true；你需要手动为某些构建器提供这些值。

​
四个模块门面

加载完成后，raydium 对象暴露四个模块门面，每个产品表面一个： 
raydium.cpmm       // CPMM 池：createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // CLMM 池：createPool, openPositionFromBase, increasePositionFromBase,
                   //         decreaseLiquidity, harvestAllRewards, swap, ...
raydium.liquidity  // AMM v4 池：computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // 农场 v3/v5/v6：deposit, withdraw, harvestAllRewards, create, setRewards
raydium.launchpad  // LaunchLab：createLaunchpad, buyExactIn, sellExactIn, graduate, ...
raydium.trade      // 多池路由：quotes、路由执行（在 0.2.41 中为 beta）
raydium.token      // 辅助函数：获取代币列表、元数据、ATA 创建
（实际上共有五个门面 — “四个”是 Raydium 公开分组的方式，trade 和 token 作为支持工具。）

​
交易构建器

每个修改性函数返回一个构建器而不是立即执行： 
const { execute, builder, transaction, innerTransactions, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    amountInA,
    amountInB,
    slippage: 0.005,
    txVersion: TxVersion.V0,
  });
返回字段：
  • execute — 便捷函数，执行签名和发送。等价于 builder.execute。
  • builder — 已累积所有指令和签名者的 TxBuilder 实例。调用 .build() 获得 VersionedTransaction[]；当你需要注入自己的指令或使用外部签名者签名时很有用。
  • transaction / innerTransactions — 原始指令数组。用于构建组合的多程序交易。
  • extInfo — 产品特定的额外信息。例如，createPool 返回 extInfo.poolId；createLaunchpad 返回新的启动状态 PDA。
txVersion 控制旧版交易与 V0 交易格式。V0（地址查询表）是默认推荐 — 它可以让更大的交换在单个交易中进行。

​
为什么构建器是异步的？

几乎每个构建器内部都会抓取链上状态：池信息（用于报价）、代币程序所有权（用于 Token-2022 与 SPL 路由）、账户租金豁免（用于 ATA 创建）等。SDK 会进行激进缓存，但第一次调用新池涉及 RPC 往返。保持一个长期存活的 raydium 实例以避免重新抓取。

​
CLMM 模块新增内容（最新发布）

CLMM 门面增加了新的动态费用、单边费用和限价单功能的接口：
  • raydium.clmm.createCustomizablePool — createPool 的超集，接受 collectFeeOn、enableDynamicFee 和 dynamicFeeConfigId。对需要新功能的任何新池使用此方法；经典 createPool 继续适用于默认费用池。
  • raydium.clmm.openLimitOrder — 在支持限价单的池上开设单个 tick 的限价单。接受 poolInfo、poolKeys、limitOrderConfig（来自 /main/clmm-limit-order-config）、inputMint、inputAmount 和目标 tick。
  • raydium.clmm.increaseLimitOrder / decreaseLimitOrder — 调整现有订单的未成交部分。在订单完全成交时减小会以 InvalidOrderPhase 回滚。
  • raydium.clmm.settleLimitOrder / settleAllLimitOrder — 将成交输出扫到所有者的 ATA。订单所有者或池的 limit_order_admin 保管人都可以调用。
  • raydium.clmm.closeLimitOrder / closeAllLimitOrder — 关闭已完全结算的订单以恢复租金。
  • raydium.api.getClmmDynamicConfigs() / getClmmLimitOrderConfigs() — REST 辅助函数，访问新的 /main/clmm-dynamic-config 和 /main/clmm-limit-order-config 端点。
一个小的重组将 utils/ 移至 libraries/。从 @raydium-io/raydium-sdk-v2/utils/... 导入的代码应切换到 @raydium-io/raydium-sdk-v2/libraries/...。顶级包导出保持不变，所以大多数用户永远不会看到重命名。 端到端 TypeScript 演练在 products/clmm/code-demos 中。

​
常见陷阱

​
1. 集群不匹配

SDK 的启动配置是集群特定的。将 cluster: "mainnet" 与 devnet Connection 混合会导致静默误路由：SDK 针对 mainnet AmmConfig 报价但发送到 devnet。务必同时传递两者。

​
2. 忘记预创建 ATA

首次与某个 mint 交互时，用户的关联代币账户可能不存在。SDK 在检测到缺失的 ATA 时会自动前置 AssociatedTokenAccount::create 指令，这会消耗少量租金。如果你的钱包 SOL 不足，这将以静默方式失败。重试前检查并补充资金。

​
3. 陈旧的 poolInfo

poolInfo 是一个缓存快照。如果自你抓取它以来池状态已改变（大笔交易移动了价格，比如），交换的 minAmountOut 可能是根据旧状态计算的，会低于链上输出量，导致回滚。在构建高价值交易前立即重新抓取 poolInfo，或使用 SDK 的 computeAmountOut 它会重新查询储备。

​
4. 优先费

SDK 默认不添加计算单价。在高交易量时期（新池启动、meme币事件），这意味着你的交易与许多其他交易竞争，可能无法登陆。提供显式的 computeBudgetConfig： 
const { execute } = await raydium.cpmm.swap({
  poolInfo,
  inputAmount: new BN(...),
  swapResult: ...,
  slippage: 0.005,
  txVersion: TxVersion.V0,
  computeBudgetConfig: {
    units: 250_000,          // CU 限制
    microLamports: 50_000,   // 每 CU 的优先费
  },
});
参见 integration-guides/priority-fee-tuning 了解大小指导。

​
5. 滑点容差必须与池类型匹配

CPMM 和 AMM v4 使用 CPMM 数学（对正常交易影响很小）。CLMM 是分段的（在 tick 交叉处影响跳跃）。如果你从 CPMM 示例复制 0.5% 的滑点容差到跨越多个 tick 的 CLMM 交换，交易很可能会回滚。SDK 的 computeAmountOut 返回 priceImpact；将你的容差设置在它之上。

​
6. BN 与 number

SDK 中的所有金额字段都是 bn.js BN 实例 — 永远不要使用 JavaScript number。通过 .toNumber() 转换金额值会在 2^53 处静默截断；对于任何高于约 9 千万亿的值（在 9 小数 mint 上并不罕见），这会产生错误的结果。在最终 UI 渲染前将所有内容保持在 BN 中。

​
版本管理策略

  • @raydium-io/raydium-sdk-v2 是 Raydium 唯一维护的 SDK。所有文档、演示和集成指导都以它为目标。
  • 一个较旧的 v1 包（@raydium-io/raydium-sdk）因历史原因存在于 npm 上。维护在 CPMM 和 LaunchLab 发布后结束（v1 从未获得对任一功能的支持），自 2024 年后没有 v1 发布。将 v1 视为生命终止：不要为新代码使用它，并将任何剩余的 v1 集成迁移到 v2。
  • SDK v2 处于 pre-1.0。0.x 次版本之间可能有破坏性变更；锁定你验证过的版本，升级时检查 GitHub 发布说明。

​
升级

升级 SDK 次版本时：
  1. 重新检查每个修改性调用的返回类型 — 形状变化（例如 extInfo）频繁出现。
  2. 重新生成 poolInfo 抓取签名 — 字段可能被重命名。
  3. 重新验证你的滑点处理；SDK 在不同版本间在自动绑定和可选绑定行为间切换。
  4. 如果你使用 raydium.trade（路由），重新验证路由形状 — 它是表面上最不稳定的部分。

​
获取帮助

对于 SDK 和 API 问题： 对于安全问题，不要在公开频道发布 — 参见 security/disclosure。

​
相关资源

来源：