> ## 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       // Farm v3/v5/v6：deposit、withdraw、harvestAllRewards、create、setRewards
raydium.launchpad  // LaunchLab：createLaunchpad、buyExactIn、sellExactIn、graduate、...
raydium.trade      // 多池路由：quotes、route-execution（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 vs SPL 路由）、帳戶租賃豁免額（用於 ATA 建立）等。SDK 會積極快取，但第一次呼叫新池涉及 RPC 往返。保持長期的 `raydium` 實例以避免重新獲取。

## CLMM 模組新增功能（最新版本）

CLMM 外觀新增了動態費用、單邊費用和限價訂單功能的表面：

* **`raydium.clmm.createCustomizablePool`** — `createPool` 的超集，接受 `collectFeeOn`、`enableDynamicFee` 和 `dynamicFeeConfigId`。用於任何需要新旋鈕的新池；傳統 `createPool` 仍適用於預設費用池。
* **`raydium.clmm.openLimitOrder`** — 在支援限價訂單的池上開立單一刻度限價訂單。接受 `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-Hant/products/clmm/code-demos)。

## 常見坑洞

### 1. 集群不匹配

SDK 的啟動設定是集群特定的。混用 `cluster: "mainnet"` 與 devnet `Connection` 會導致靜默誤導向：SDK 針對主網 `AmmConfig` 報價，但發送至 devnet。務必同時傳遞兩者。

### 2. 忘記預先建立 ATA

首次與代幣互動時，使用者的關聯代幣帳戶可能不存在。SDK 在偵測到遺失的 ATA 時，會自動預加 `AssociatedTokenAccount::create` 指令，這會花費少量租金。若你的錢包 SOL 不足，將靜默失敗。檢查並在重試前充值。

### 3. 過期的 `poolInfo`

`poolInfo` 是快取的快照。若池狀態自你獲取後已改變（大交易移動了價格，例如），交換的 `minAmountOut` 可能以舊狀態計算，落於鏈上輸出量下方，導致交易回復。在構建高價值交易前立即重新獲取 `poolInfo`，或使用 SDK 的 `computeAmountOut` 重新查詢準備金。

### 4. 優先費用

SDK 預設不新增運算單價。在高交易量期間（新池啟動、迷因幣事件），這表示你的交易與許多其他交易競爭，可能無法成交。提供明確的 `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-Hant/integration-guides/priority-fee-tuning) 了解調整規模指南。

### 5. 滑點容差必須與池類型相符

CPMM 和 AMM v4 使用 CPMM 數學（正常交易的影響很低）。CLMM 是分段的（影響在刻度穿越時跳躍）。若你將 0.5% 滑點容差從 CPMM 範例複製到穿越數個刻度的 CLMM 交換，交易很可能回復。SDK 的 `computeAmountOut` 會回傳 `priceImpact`；調整你的容差至大於它。

### 6. `BN` vs `number`

SDK 中的所有數額欄位都是 `bn.js` `BN` 實例 — 絕不是 JavaScript `number`。透過 `.toNumber()` 轉換數額值會在 `2^53` 時靜默截斷；對於任何大於約 9 千兆（在 9 位小數代幣上並不罕見）的值，這會產生錯誤結果。直到最後的 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 尚未發佈 1.0。0.x 次要版本間可能出現重大變更；固定你已驗證的版本，升級時檢查 GitHub 版本說明。

## 升級

升級 SDK 次要版本時：

1. 重新檢查每個變異呼叫的回傳類型 — 形狀變更（例如 `extInfo`）頻繁出現。
2. 重新產生 `poolInfo` 獲取簽署 — 欄位可能已重命名。
3. 重新驗證你的滑點處理；SDK 跨版本在自動綁定和選擇綁定行為間移動。
4. 若你使用 `raydium.trade`（路由），重新驗證路由形狀 — 它是表面中最不穩定的部分。

## 獲取幫助

關於 SDK 和 API 問題：

* **GitHub 議題** — 提交至 [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-Hant/security/disclosure)。

## 指標

* [`sdk-api/rest-api`](/zh-Hant/sdk-api/rest-api) — SDK 的 HTTP 補充。
* [`sdk-api/trade-api`](/zh-Hant/sdk-api/trade-api) — 伺服器構建的交換交易。
* [`sdk-api/anchor-idl`](/zh-Hant/sdk-api/anchor-idl) — 直接從程式 IDL 重新產生客戶端。
* [`sdk-api/python-integration`](/zh-Hant/sdk-api/python-integration) — 透過 `solana-py` 的 Python 等效項。
* [`integration-guides/priority-fee-tuning`](/zh-Hant/integration-guides/priority-fee-tuning) — 調整 `computeBudgetConfig` 規模。

來源：

* [Raydium SDK v2 原始碼](https://github.com/raydium-io/raydium-sdk-V2)
* Raydium SDK 版本說明。