跳轉到主要內容

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       // 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 是支援工具。）

​
交易構建器

每個變異函式都會回傳一個構建器，而不是立即執行： 
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。

​
常見坑洞

​
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： 
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 是分段的（影響在刻度穿越時跳躍）。若你將 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 問題： 關於安全問題，不要在公開頻道發佈 — 參見 security/disclosure。

​
指標

來源：