> ## 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 end-to-end — installation, the four module facades, transaction building, and the gotchas that bite every new integrator.

<Info>
  **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`](https://github.com/raydium-io/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](https://github.com/raydium-io/raydium-docs-v1/issues/new).
</Info>

## Install

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

```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,    // 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:

```ts theme={null}
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:

```ts theme={null}
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`).

<Note>
  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 }`.
</Note>

`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`](/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`:

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

1. Re-check the return type of every mutating call — shape changes (e.g. `extInfo`) land frequently.
2. Regenerate `poolInfo` fetch signatures — a field may have been renamed.
3. Re-verify your slippage handling; the SDK has shifted between auto-bound and opt-in bound behaviors across releases.
4. 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](https://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](https://discord.gg/raydium) for synchronous help.
* **Telegram** — developer chat linked from [raydium.io](https://raydium.io) (avoid unverified Telegram groups).

For security issues, do **not** post in public channels — see [`security/disclosure`](/security/disclosure).

## Pointers

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

Sources:

* [Raydium SDK v2 source](https://github.com/raydium-io/raydium-sdk-V2)
* Raydium SDK release notes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.