> ## 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.42-alpha`, the version verified for every code demo in this site (2026-04). The SDK is pre-1.0 and the type surface has evolved across releases — pin your version.
</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 it fetches a small `/config` payload from `api-v3.raydium.io` on startup (listing current `AmmConfig` accounts, fee tiers, etc.). Set `disableFeatureCheck: true` in offline environments; you will have to supply those values manually to some builders.

## The four module facades

Once loaded, the `raydium` object exposes four module facades, one per product surface:

```ts theme={null}
raydium.cpmm       // CPMM pools: createPool, addLiquidity, withdrawLiquidity, swap, ...
raydium.clmm       // CLMM pools: createPool, openPositionFromBase, increasePositionFromBase,
                   //             decreaseLiquidity, harvestAllRewards, swap, ...
raydium.liquidity  // AMM v4 pools: computeAmountOut, swap, addLiquidity, removeLiquidity, ...
raydium.farm       // Farm v3/v5/v6: deposit, withdraw, harvestAllRewards, create, setRewards
raydium.launchpad  // LaunchLab: createLaunchpad, buyExactIn, sellExactIn, graduate, ...
raydium.trade      // Multi-pool routing: quotes, route-execution (beta in 0.2.41)
raydium.token      // Helpers: get token list, metadata, ATA creation
```

(Yes, five facades in total — "four" is the way Raydium groups them publicly, with `trade` and `token` as supporting utilities.)

## Transaction builders

Every mutating function returns a builder rather than executing immediately:

```ts theme={null}
const { execute, builder, transaction, innerTransactions, extInfo } =
  await raydium.cpmm.addLiquidity({
    poolInfo,
    amountInA,
    amountInB,
    slippage: 0.005,
    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. Call `.build()` to get a `VersionedTransaction[]`; useful when you need to inject your own instructions or sign with external signers.
* **`transaction` / `innerTransactions`** — the raw instruction arrays. Use when building composed multi-program transactions.
* **`extInfo`** — product-specific extras. For example, `createPool` returns `extInfo.poolId`; `createLaunchpad` returns the new launch state PDA.

`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`, `enableDynamicFee`, and `dynamicFeeConfigId`. Use this for any new pool that needs the new knobs; classic `createPool` continues to work for default-fee pools.
* **`raydium.clmm.openLimitOrder`** — open a single-tick limit order on a pool that supports them. Takes `poolInfo`, `poolKeys`, `limitOrderConfig` (from `/main/clmm-limit-order-config`), `inputMint`, `inputAmount`, and the target `tick`.
* **`raydium.clmm.increaseLimitOrder` / `decreaseLimitOrder`** — adjust the unfilled portion of an existing order. Decreasing reverts on a fully-filled order with `InvalidOrderPhase`.
* **`raydium.clmm.settleLimitOrder` / `settleAllLimitOrder`** — sweep filled output to the owner's ATA. Either the order's owner or the pool's `limit_order_admin` keeper can call them.
* **`raydium.clmm.closeLimitOrder` / `closeAllLimitOrder`** — close fully-settled orders to recover rent.
* **`raydium.api.getClmmDynamicConfigs()` / `getClmmLimitOrderConfigs()`** — REST helpers that hit the new `/main/clmm-dynamic-config` and `/main/clmm-limit-order-config` endpoints.

A small reorg also moved `utils/` to `libraries/`. Code that imported from `@raydium-io/raydium-sdk-v2/utils/...` should switch to `@raydium-io/raydium-sdk-v2/libraries/...`. The top-level package barrel is unchanged, so most users never see the rename.

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,
  inputAmount: new BN(...),
  swapResult: ...,
  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.trade` (routing), re-verify the route shape — it is the most unstable part of the surface.

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