TypeScript SDK

​

설치

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

​

초기화

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

​

트랜잭션 빌더

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

• execute — 서명 + 전송하는 편의 함수입니다. builder.execute와 동등합니다.
• builder — 모든 명령어와 서명자가 누적된 TxBuilder 인스턴스입니다. builder.build()는 transaction이 단일 레거시 Transaction인 TxBuildData를 반환하고, builder.buildV0()은 단일 VersionedTransaction을 담은 TxV0BuildData를 반환합니다. 배열을 만드는 것은 buildMultiTx / buildMultiTxV0뿐입니다.
• transaction — 빌드된 Transaction / VersionedTransaction입니다.
• instructionTypes / signers — 누적된 명령어 라벨과 서명자 집합입니다.
• extInfo — 제품별 추가 정보입니다. 예를 들어 cpmm.createPool은 extInfo.address.{poolId, lpMint, vaultA, vaultB}를 반환하고, launchpad.createLaunchpad는 extInfo.address(LaunchpadPoolInfo와 poolId)를 반환합니다.

​

왜 비동기 빌더인가요?

​

CLMM 모듈 추가 (최신 릴리스)

• raydium.clmm.createCustomizablePool — collectFeeOn과 dynamicFeeConfig(구성 계정의 PublicKey)를 허용하는 createPool의 상위 집합입니다. dynamicFeeConfig를 제공하는 것이 곧 동적 수수료를 활성화하는 것이며, 별도의 enableDynamicFee 플래그도 dynamicFeeConfigId도 없습니다. 클래식 createPool은 기본 수수료 풀에 계속 작동합니다.
• raydium.clmm.openLimitOrder — 단일 틱 지정가 주문을 엽니다. poolInfo, baseIn(방향), orderTick, amount, 그리고 선택적으로 tickArrayBitmap, noneIndex, ownerInfo를 받습니다. 틱을 양자화하려면 내보내진 getOrderTick({ baseIn, mintADecimal, mintBDecimal, tickSpacing, price }) 헬퍼를 사용하세요.
• raydium.clmm.increaseLimitOrder / decreaseLimitOrder — 기존 주문의 미체결 부분을 조정합니다. 둘 다 { poolInfo, limitOrder, amount }를 받으며, decreaseLimitOrder는 선택적 slippage를 추가합니다. 완전히 체결된 주문에서 감소하면 InvalidOrderPhase로 되돌립니다.
• raydium.clmm.settleLimitOrder / settleAllLimitOrder — 체결된 출력을 소유자의 ATA로 스윕합니다. settleLimitOrder는 { limitOrder }만 받으며 poolInfo는 받지 않습니다. 주문의 소유자 또는 프로그램의 limit_order_admin 키퍼가 호출할 수 있습니다.
• raydium.clmm.closeLimitOrder / closeAllLimitOrder — 완전히 정산된 주문을 닫아 렌트를 회수합니다.
• raydium.api.getClmmDynamicConfigs() — 새로운 /main/clmm-dynamic-config 엔드포인트를 호출하는 REST 헬퍼입니다. (지정가 주문 구성 헬퍼나 엔드포인트는 없습니다: 지정가 주문은 풀별 구성 계정이 아니라 틱으로 키가 지정됩니다.)

​

일반적인 함정

​

1. 클러스터 불일치

​

2. ATA 사전 생성 잊기

​

3. 오래된 poolInfo

​

4. 우선순위 수수료

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 제한
    microLamports: 50_000,   // CU당 우선순위 수수료
  },
});

​

5. 슬리피지 허용치는 풀 유형과 일치해야 합니다

​

6. BN vs number

​

버전 관리 정책

• @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 릴리스 노트를 확인하세요.

​

업그레이드

1. 모든 변경 호출의 반환 타입을 다시 확인하세요 — 형태 변경 (예: extInfo)이 자주 발생합니다.
2. poolInfo 가져오기 서명을 다시 생성하세요 — 필드가 이름 변경되었을 수 있습니다.
3. 슬리피지 처리를 다시 검증하세요. SDK는 릴리스에 걸쳐 자동 바운드와 옵트인 바운드 동작 사이를 전환해 왔습니다.
4. raydium.tradeV2(라우팅)를 사용한다면 경로 형태를 다시 검증하세요 — 표면에서 가장 불안정한 부분입니다. 파사드 이름이 trade에서 tradeV2로 변경되었으며 기존 이름은 더 이상 존재하지 않는다는 점에 유의하세요.

​

도움 받기

• GitHub 이슈 — 버그 및 기능 요청은 github.com/raydium-io/raydium-sdk-V2/issues에 제출하세요. Raydium 팀이 적극적으로 모니터링합니다.
• Discord — discord.gg/raydium의 #dev-support 채널에서 동기식 도움을 받으세요.
• Telegram — raydium.io에서 연결된 개발자 채팅 (검증되지 않은 Telegram 그룹 피하기).

​

포인터

• sdk-api/rest-api — SDK의 HTTP 보완.
• sdk-api/trade-api — 서버 구축 스왑 트랜잭션.
• sdk-api/anchor-idl — 프로그램 IDL에서 직접 클라이언트 재생성.
• sdk-api/python-integration — solana-py를 통한 Python 동등물.
• integration-guides/priority-fee-tuning — computeBudgetConfig 크기 조정.

• Raydium SDK v2 소스
• Raydium SDK 릴리스 노트.