> ## 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.

# TypeScript SDK

> @raydium-io/raydium-sdk-v2 端到端指南 — 安装、四个模块门面、交易构建，以及每个新集成者都会遇到的常见陷阱。

<Info>
  **本页内容由 AI 自动翻译，所有内容以英文版本为准。**

  [查看英文版 →](/sdk-api/typescript-sdk)
</Info>

<Info>
  **版本提示。** 本页面文档适用于 `@raydium-io/raydium-sdk-v2@0.2.42-alpha`，这是本网站所有代码演示验证过的版本（2026-04）。SDK 还未发布 1.0，类型表面在不同版本间有演变 — 请锁定你使用的版本。
</Info>

## 安装

```bash theme={null}
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`：

```ts theme={null}
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` 对象暴露四个模块门面，每个产品表面一个：

```ts theme={null}
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` 作为支持工具。）

## 交易构建器

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

```ts theme={null}
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`](/zh/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`：

```ts theme={null}
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`](/zh/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 问题：

* **GitHub issues** — 在 [github.com/raydium-io/raydium-sdk-V2/issues](https://github.com/raydium-io/raydium-sdk-V2/issues) 提交 bug 和功能请求。Raydium 团队主动监控。
* **Discord** — [discord.gg/raydium](https://discord.gg/raydium) 的 `#dev-support` 频道获得同步帮助。
* **Telegram** — 开发者聊天从 [raydium.io](https://raydium.io) 链接（避免未验证的 Telegram 群组）。

对于安全问题，**不要**在公开频道发布 — 参见 [`security/disclosure`](/zh/security/disclosure)。

## 相关资源

* [`sdk-api/rest-api`](/zh/sdk-api/rest-api) — SDK 的 HTTP 补充。
* [`sdk-api/trade-api`](/zh/sdk-api/trade-api) — 服务器构建的交换交易。
* [`sdk-api/anchor-idl`](/zh/sdk-api/anchor-idl) — 直接从程序 IDL 重新生成客户端。
* [`sdk-api/python-integration`](/zh/sdk-api/python-integration) — 通过 `solana-py` 的 Python 等价物。
* [`integration-guides/priority-fee-tuning`](/zh/integration-guides/priority-fee-tuning) — 调整 `computeBudgetConfig` 大小。

来源：

* [Raydium SDK v2 源代码](https://github.com/raydium-io/raydium-sdk-V2)
* Raydium SDK 发布说明。