TypeScript SDK

本页内容由 AI 自动翻译，所有内容以英文版本为准。查看英文版 →

版本说明。 本页文档对应 @raydium-io/raydium-sdk-v2@0.2.64-alpha，这是本站所有代码示例所使用的版本。SDK 尚未发布 1.0，类型接口在各版本间有所变化 — 请锁定你使用的版本。版本号从 0.2.42-alpha 升级到 0.2.64-alpha，时间为 2026-09-09，同步了程序升级。0.2.64-alpha 是 SDK 的当前发布版本。代码演示页面链接的 raydium-sdk-V2-demo 仓库安装的是 0.2.62-alpha，如果你逐字按照演示操作，可以选择锁定其中任一版本。本页的演示最后一次执行是针对 0.2.42-alpha（2026-04）；其调用签名已在 2026-09-09 针对 0.2.64-alpha 源代码重新检查，但如果发现不匹配，请视为文档 bug 并提交 issue。

安装

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 编写，随 JS 产物一起提供 .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 加载代币列表（raydium.token.load()）。传入 disableLoadToken: true 可跳过该请求。可用性特性检查是对 /v3/main/AvailabilityCheckAPI 的另一次调用，并且默认已被跳过，除非你显式传入 disableFeatureCheck: false。费用配置在加载时完全不会被获取 —— 它们在首次使用时通过 raydium.api.getCpmmConfigs() / getClmmConfigs() 延迟获取。

模块门面

加载后，raydium 对象暴露十个模块门面，外加一个 API 客户端：

raydium.cpmm       // CPMM pools: createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // CLMM pools: createPool, openPositionFromBase, increasePositionFromBase,
                   //             decreaseLiquidity, harvestAllRewards, swap, limit orders, ...
raydium.liquidity  // AMM v4 pools: computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // Farm v3/v5/v6: deposit, withdraw, harvestAllRewards, create,
                   //                restartReward(s), addNewRewardToken(s)
raydium.launchpad  // LaunchLab: createLaunchpad, buyToken, buyTokenExactOut, sellToken,
                   //            claimCreatorFee, curve-rule and platform-config builders, ...
raydium.tradeV2    // Multi-pool routing: route discovery, compute, route-execution
raydium.marketV2   // OpenBook market creation (legacy)
raydium.utils1216  // One-off historical-claim helpers
raydium.token      // Token list + metadata: load(), getTokenInfo()
raydium.account    // Wallet token accounts, ATA lookup and creation
raydium.api        // The REST client (fetchPoolById, getCpmmConfigs, fetchLaunchConfigs, ...)

交易构建器

每个修改函数都返回一个构建器，而不是立即执行：

import { Percent } from "@raydium-io/raydium-sdk-v2";

const { execute, builder, transaction, instructionTypes, signers, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    inputAmount,              // BN — one side, not a pair
    baseIn: true,
    slippage: new Percent(1, 100),   // a Percent, not a number
    txVersion: TxVersion.V0,
  });

返回的字段：

execute — 便利函数，执行签名 + 发送。等同于 builder.execute。
builder — TxBuilder 实例，包含所有累积的指令和签名者。builder.build() 返回一个 TxBuildData，其 transaction 是单个旧式 Transaction；builder.buildV0() 返回一个 TxV0BuildData，带单个 VersionedTransaction。只有 buildMultiTx / buildMultiTxV0 会产生数组。
transaction — 构建好的 Transaction / VersionedTransaction。
instructionTypes / signers — 累积的指令标签和签名者集合。
extInfo — 产品特定的额外信息。例如，cpmm.createPool 返回 extInfo.address.{poolId, lpMint, vaultA, vaultB}；launchpad.createLaunchpad 返回 extInfo.address（一个 LaunchpadPoolInfo 加上 poolId）。

返回类型上没有 innerTransactions 字段 —— 解构它会是一个 TypeScript 错误。返回类型为 MakeMultiTxData 的构建器（例如 clmm.harvestAllRewards、farm.harvestAllRewards、 tradeV2.swap、launchpad.createLaunchpad）暴露的是 transactions，并且它们的 execute 要求 { sequentially: boolean }，解析结果是 { txIds } 而不是 { txId }。

txVersion 控制旧版本与 V0 交易格式。V0（地址查找表）是默认推荐 — 它让更大的交换能在单个交易中完成。

为什么是异步构建器？

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

CLMM 模块新增功能（最新版本）

CLMM 门面获得了新的动态费用、单边费用和限价单功能的接口：

raydium.clmm.createCustomizablePool — createPool 的超集，接受 collectFeeOn 和 dynamicFeeConfig（配置账户的 PublicKey）。传入 dynamicFeeConfig 才是启用动态费用的方式；没有单独的 enableDynamicFee 标志，也没有 dynamicFeeConfigId。经典的 createPool 继续用于默认费用池。
raydium.clmm.openLimitOrder — 开设单个 tick 的限价单。接受 poolInfo、baseIn（方向）、orderTick、amount，以及可选的 tickArrayBitmap、noneIndex、ownerInfo。使用导出的 getOrderTick({ baseIn, mintADecimal, mintBDecimal, tickSpacing, price }) 辅助函数来量化 tick。
raydium.clmm.increaseLimitOrder / decreaseLimitOrder — 调整现有订单的未成交部分。两者都接受 { poolInfo, limitOrder, amount }；decreaseLimitOrder 另有一个可选的 slippage。减少操作在完全成交的订单上会以 InvalidOrderPhase 回滚。
raydium.clmm.settleLimitOrder / settleAllLimitOrder — 将成交输出扫入所有者的 ATA。settleLimitOrder 只接受 { limitOrder } —— 没有 poolInfo。订单所有者或程序的 limit_order_admin keeper 都可以调用它。
raydium.clmm.closeLimitOrder / closeAllLimitOrder — 关闭完全结算的订单以恢复租金。
raydium.api.getClmmDynamicConfigs() — REST 辅助函数，调用新的 /main/clmm-dynamic-config 端点。（不存在限价单配置的辅助函数或端点：限价单以 tick 为键，而不是以按池的配置账户为键。）

该包没有声明任何子路径导出，所以 @raydium-io/raydium-sdk-v2/<anything> 在任何拼写下都无法解析 —— 请从顶层入口导入一切。（在内部，src/raydium/clmm/utils/ 被重命名为 src/raydium/clmm/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 可能是针对旧状态计算的，最终低于链上的 amount-out，导致回滚。在构建高价值交易前立即重新获取 poolInfo，或使用 SDK 的 computeAmountOut 它会重新查询储备。

4. 优先费用

SDK 默认不添加计算单位价格。在高交易量窗口（新池启动、meme 币事件）中，这意味着你的交易与许多其他交易竞争，可能无法上链。提供显式的 computeBudgetConfig：

const { execute } = await raydium.cpmm.swap({
  poolInfo,
  baseIn,                    // required: which side inputAmount is denominated in
  inputAmount: new BN(...),
  swapResult: ...,           // required: from CurveCalculator.swapBaseInput/Output
  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` vs `number`

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

版本控制策略

@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 次版本之间升级时：

重新检查每个修改调用的返回类型 — 形状变化（例如 extInfo）经常出现。
重新生成 poolInfo 获取签名 — 字段可能已重命名。
重新验证你的滑点处理；SDK 在不同版本之间曾在自动绑定和选择加入绑定行为之间切换。
如果你使用 raydium.tradeV2（路由），重新验证路由形状 — 它是表面中最不稳定的部分。注意该门面已从 trade 重命名为 tradeV2；旧名称已不存在。

获取帮助

对于 SDK 和 API 问题：

GitHub issues — 在 github.com/raydium-io/raydium-sdk-V2/issues 提交 bug 和功能请求。Raydium 团队积极监控。
Discord — discord.gg/raydium 的 #dev-support 频道获取同步帮助。
Telegram — 开发者聊天链接来自 raydium.io（避免未验证的 Telegram 群组）。

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

Solana 基础

快速开始

SDK 与 API

集成指南

安装

初始化

模块门面

交易构建器

为什么是异步构建器？

CLMM 模块新增功能（最新版本）

常见陷阱

1. 集群不匹配

2. 忘记预创建 ATA

3. 过期的 `poolInfo`

4. 优先费用

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

6. `BN` vs `number`

版本控制策略

升级

获取帮助

相关链接

​安装

​初始化

​模块门面

​交易构建器

​为什么是异步构建器？

​CLMM 模块新增功能（最新版本）

​常见陷阱

​1. 集群不匹配

​2. 忘记预创建 ATA

​3. 过期的 poolInfo

​4. 优先费用

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

​6. BN vs number

​版本控制策略

​升级

​获取帮助

​相关链接

安装

初始化

模块门面

交易构建器

为什么是异步构建器？

CLMM 模块新增功能（最新版本）

常见陷阱

1. 集群不匹配

2. 忘记预创建 ATA

3. 过期的 `poolInfo`

4. 优先费用

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

6. `BN` vs `number`

版本控制策略

升级

获取帮助

相关链接