TypeScript SDK

Version banner. This page documents @raydium-io/raydium-sdk-v2@0.2.64-alpha, the pin every code demo in this site carries. The SDK is pre-1.0 and the type surface has evolved across releases — pin your version.The pin was advanced from 0.2.42-alpha on 2026-09-09 alongside the program upgrades: 0.2.64-alpha is the SDK’s current release. The raydium-sdk-V2-demo repo that the code-demo pages link to installs 0.2.62-alpha, so pin either if you are following a demo verbatim. The demos on these pages were last executed against 0.2.42-alpha (2026-04); their call signatures were re-checked against the 0.2.64-alpha source on 2026-09-09, but treat any mismatch as a documentation bug and open an issue.

Install

npm install @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token
# or
pnpm add @raydium-io/raydium-sdk-v2 @solana/web3.js @solana/spl-token

The SDK is written in TypeScript and ships .d.ts alongside its JS artifact. Minimum toolchain: Node 18+, TypeScript 5.0+, moduleResolution: "bundler" or "node16".

Initialize

The entry point is 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,    // skip the SDK's startup feature-detect API call
  blockhashCommitment: "confirmed",
});

Raydium.load is async because, by default, it loads the token list (raydium.token.load()) from api-v3.raydium.io. Pass disableLoadToken: true to skip that fetch. The availability feature-check is a separate call to /v3/main/AvailabilityCheckAPI and is already skipped unless you explicitly pass disableFeatureCheck: false. Fee configs are not fetched at load time at all — they come lazily from raydium.api.getCpmmConfigs() / getClmmConfigs() on first use.

The module facades

Once loaded, the raydium object exposes ten module facades plus an API client:

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, ...)

Transaction builders

Every mutating function returns a builder rather than executing immediately:

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,
  });

Returned fields:

execute — a convenience function that signs + sends. Equivalent to builder.execute.
builder — the TxBuilder instance with all instructions and signers accumulated. builder.build() returns a TxBuildData whose transaction is a single legacy Transaction; builder.buildV0() returns a TxV0BuildData with a single VersionedTransaction. Only buildMultiTx / buildMultiTxV0 produce an array.
transaction — the built Transaction / VersionedTransaction.
instructionTypes / signers — the accumulated instruction labels and signer set.
extInfo — product-specific extras. For example, cpmm.createPool returns extInfo.address.{poolId, lpMint, vaultA, vaultB}; launchpad.createLaunchpad returns extInfo.address (a LaunchpadPoolInfo plus poolId).

There is no innerTransactions field on the return type — destructuring it is a TypeScript error. Builders whose return type is MakeMultiTxData (for example clmm.harvestAllRewards, farm.harvestAllRewards, tradeV2.swap, launchpad.createLaunchpad) expose transactions instead, and their execute requires { sequentially: boolean } and resolves to { txIds } rather than { txId }.

txVersion controls legacy vs V0 transaction format. V0 (address lookup tables) is the default recommendation — it lets larger swaps fit in a single transaction.

Why async builders?

Almost every builder internally fetches on-chain state: pool info (for quotes), token program ownership (for Token-2022 vs SPL routing), account rent-exemption (for ATA creation), etc. The SDK caches aggressively but the first call for a new pool involves RPC round-trips. Keep a long-lived raydium instance to avoid re-fetching.

CLMM module additions (latest release)

The CLMM facade gained surfaces for the new dynamic-fee, single-sided-fee, and limit-order features:

raydium.clmm.createCustomizablePool — superset of createPool that accepts collectFeeOn and dynamicFeeConfig (the config account’s PublicKey). Supplying dynamicFeeConfig is what enables dynamic fees; there is no separate enableDynamicFee flag and no dynamicFeeConfigId. Classic createPool continues to work for default-fee pools.
raydium.clmm.openLimitOrder — open a single-tick limit order. Takes poolInfo, baseIn (direction), orderTick, amount, and optionally tickArrayBitmap, noneIndex, ownerInfo. Use the exported getOrderTick({ baseIn, mintADecimal, mintBDecimal, tickSpacing, price }) helper to quantize the tick.
raydium.clmm.increaseLimitOrder / decreaseLimitOrder — adjust the unfilled portion of an existing order. Both take { poolInfo, limitOrder, amount }; decreaseLimitOrder adds an optional slippage. Decreasing reverts on a fully-filled order with InvalidOrderPhase.
raydium.clmm.settleLimitOrder / settleAllLimitOrder — sweep filled output to the owner’s ATA. settleLimitOrder takes only { limitOrder } — no poolInfo. Either the order’s owner or the program’s limit_order_admin keeper can call it.
raydium.clmm.closeLimitOrder / closeAllLimitOrder — close fully-settled orders to recover rent.
raydium.api.getClmmDynamicConfigs() — REST helper that hits the new /main/clmm-dynamic-config endpoint. (There is no limit-order-config helper or endpoint: limit orders are keyed by tick, not by a per-pool config account.)

The package declares no subpath exports, so @raydium-io/raydium-sdk-v2/<anything> does not resolve in any spelling — import everything from the top-level barrel. (Internally, src/raydium/clmm/utils/ was renamed to src/raydium/clmm/libraries/, but that was never a public entry point.) End-to-end TypeScript walkthroughs live in products/clmm/code-demos.

Common pitfalls

1. Cluster mismatch

The SDK’s startup config is cluster-specific. Mixing cluster: "mainnet" with a devnet Connection causes silent mis-routing: the SDK quotes against mainnet AmmConfig but sends to devnet. Always pass both.

2. Forgetting to pre-create ATAs

On first interaction with a mint, the user’s Associated Token Account may not exist. The SDK auto-prepends an AssociatedTokenAccount::create instruction when it detects a missing ATA, which costs a small amount of rent. If your wallet is low on SOL this will fail silently. Check and fund before retrying.

3. Stale `poolInfo`

poolInfo is a cached snapshot. If the pool state has changed since you fetched it (a large trade moved the price, say), the swap’s minAmountOut may be computed against the old state and land below the on-chain amount-out, reverting. Re-fetch poolInfo immediately before building high-value transactions, or use the SDK’s computeAmountOut which re-queries reserves.

4. Priority fees

The SDK does not add compute-unit prices by default. In high-volume windows (new-pool launches, meme-coin events) this means your transaction competes with many others and may not land. Supply an explicit 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 limit
    microLamports: 50_000,   // priority fee per CU
  },
});

See integration-guides/priority-fee-tuning for sizing guidance.

5. Slippage tolerance must match the pool type

CPMM and AMM v4 are CPMM math (low impact on normal trades). CLMM is piecewise (impact jumps at tick crossings). If you copy a 0.5% slippage tolerance from a CPMM example into a CLMM swap that crosses several ticks, the transaction is likely to revert. The SDK’s computeAmountOut returns priceImpact; size your tolerance above it.

6. `BN` vs `number`

All amount fields in the SDK are bn.js BN instances — never JavaScript number. Converting amount values via .toNumber() silently truncates at 2^53; for any value above ~9 quadrillion (not uncommon on 9-decimal mints), this produces the wrong result. Keep everything in BN until the final UI render.

Versioning policy

@raydium-io/raydium-sdk-v2 is the only SDK Raydium maintains. All docs, demos, and integration guidance target it.
An older v1 package (@raydium-io/raydium-sdk) exists on npm for historical reasons. Maintenance ended after CPMM and LaunchLab shipped (v1 never gained support for either), and there have been no v1 releases since 2024. Treat v1 as end-of-life: do not use it for new code, and migrate any remaining v1 integrations to v2.
SDK v2 is pre-1.0. Breaking changes between 0.x minor releases are possible; pin the version you’ve verified against and check the GitHub release notes when upgrading.

Upgrading

When upgrading between SDK minor versions:

Re-check the return type of every mutating call — shape changes (e.g. extInfo) land frequently.
Regenerate poolInfo fetch signatures — a field may have been renamed.
Re-verify your slippage handling; the SDK has shifted between auto-bound and opt-in bound behaviors across releases.
If you use raydium.tradeV2 (routing), re-verify the route shape — it is the most unstable part of the surface. Note the facade was renamed from trade to tradeV2; the old name no longer exists.

Getting help

For SDK and API questions:

GitHub issues — file at github.com/raydium-io/raydium-sdk-V2/issues for bugs and feature requests. The Raydium team monitors actively.
Discord — #dev-support channel at discord.gg/raydium for synchronous help.
Telegram — developer chat linked from raydium.io (avoid unverified Telegram groups).

For security issues, do not post in public channels — see security/disclosure.

Pointers

sdk-api/rest-api — the HTTP complement to the SDK.
sdk-api/trade-api — server-built swap transactions.
sdk-api/anchor-idl — regenerating clients directly from program IDLs.
sdk-api/python-integration — Python equivalent via solana-py.
integration-guides/priority-fee-tuning — sizing computeBudgetConfig.

Sources:

Raydium SDK v2 source
Raydium SDK release notes.

Solana fundamentals

Quick start

SDK & API

Integration guides

Install

Initialize

The module facades

Transaction builders

Why async builders?

CLMM module additions (latest release)

Common pitfalls

1. Cluster mismatch

2. Forgetting to pre-create ATAs

3. Stale `poolInfo`

4. Priority fees

5. Slippage tolerance must match the pool type

6. `BN` vs `number`

Versioning policy

Upgrading

Getting help

Pointers

​Install

​Initialize

​The module facades

​Transaction builders

​Why async builders?

​CLMM module additions (latest release)

​Common pitfalls

​1. Cluster mismatch

​2. Forgetting to pre-create ATAs

​3. Stale poolInfo

​4. Priority fees

​5. Slippage tolerance must match the pool type

​6. BN vs number

​Versioning policy

​Upgrading

​Getting help

​Pointers

Install

Initialize

The module facades

Transaction builders

Why async builders?

CLMM module additions (latest release)

Common pitfalls

1. Cluster mismatch

2. Forgetting to pre-create ATAs

3. Stale `poolInfo`

4. Priority fees

5. Slippage tolerance must match the pool type

6. `BN` vs `number`

Versioning policy

Upgrading

Getting help

Pointers