TypeScript SDK

이 페이지는 AI 자동 번역입니다. 모든 내용은 영문판을 기준으로 합니다.영문판 보기 →

설치

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

SDK는 TypeScript로 작성되었으며 JS 아티팩트와 함께 .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,    // skip the SDK's startup feature-detect API call
  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에서 베타)
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 대 SPL 라우팅), 계정 렌트 면제 (ATA 생성용) 등. SDK는 적극적으로 캐싱하지만 새로운 풀에 대한 첫 호출에는 RPC 왕복이 포함됩니다. 다시 가져오기를 방지하려면 오래 살아있는 raydium 인스턴스를 유지하세요.

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

CLMM 파사드는 새로운 동적 수수료, 단측 수수료 및 지정가 주문 기능을 위한 표면을 얻었습니다:

raydium.clmm.createCustomizablePool — collectFeeOn, enableDynamicFee 및 dynamicFeeConfigId를 허용하는 createPool의 상위집합입니다. 새 수수료 옵션이 필요한 모든 새로운 풀에 이를 사용하세요. 클래식 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() — 새로운 /main/clmm-dynamic-config 및 /main/clmm-limit-order-config 끝점을 사용하는 REST 헬퍼입니다.

작은 재조직이 또한 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는 mainnet AmmConfig에 대해 견적을 제공하지만 devnet으로 전송합니다. 항상 둘 다 전달하세요.

2. ATAs 미리 생성하지 않음

민트와 처음 상호작용할 때 사용자의 Associated Token Account가 존재하지 않을 수 있습니다. 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 limit
    microLamports: 50_000,   // priority fee per CU
  },
});

크기 조정 지침은 integration-guides/priority-fee-tuning을 참조하세요.

5. 슬리피지 허용 오차는 풀 유형과 일치해야 함

CPMM과 AMM v4는 CPMM 수학입니다 (정상적인 거래에서 영향 낮음). CLMM은 구간별입니다 (여러 틱 교차에서 영향이 점프함). CPMM 예제에서 0.5% 슬리피지 허용 오차를 복사하여 여러 틱을 교차하는 CLMM 스왑에 붙여넣으면 거래가 되돌아갈 가능성이 높습니다. SDK의 computeAmountOut은 priceImpact를 반환합니다. 허용 오차를 그 위에 크기 조정하세요.

6. `BN` 대 `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 마이너 버전 간 업그레이드 시:

모든 뮤테이팅 호출의 반환 유형을 다시 확인하세요 — 형태 변경 (예: extInfo)이 자주 착지합니다.
poolInfo 가져오기 서명을 재생성하세요 — 필드가 이름을 바꿀 수 있습니다.
슬리피지 처리를 다시 검증하세요. SDK는 릴리스 전반에 걸쳐 자동 바운드와 옵트인 바운드 동작 간에 이동했습니다.
raydium.trade (라우팅)을 사용하면 경로 형태를 다시 검증하세요 — 이는 표면의 가장 불안정한 부분입니다.

도움말 받기

SDK 및 API 질문의 경우:

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

보안 문제의 경우 공개 채널에 게시하지 마세요 — security/disclosure를 참조하세요.

포인터

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 릴리스 노트.

Solana 기초

빠른 시작

SDK & API

연동 가이드

설치

초기화

네 가지 모듈 파사드

트랜잭션 빌더

비동기 빌더인 이유?

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

일반적인 함정

1. 클러스터 불일치

2. ATAs 미리 생성하지 않음

3. 오래된 `poolInfo`

4. 우선 수수료

5. 슬리피지 허용 오차는 풀 유형과 일치해야 함

6. `BN` 대 `number`

버전 정책

업그레이드

도움말 받기

포인터

Solana 기초

빠른 시작

SDK & API

연동 가이드

Documentation Index

​설치

​초기화

​네 가지 모듈 파사드

​트랜잭션 빌더

​비동기 빌더인 이유?

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

​일반적인 함정

​1. 클러스터 불일치

​2. ATAs 미리 생성하지 않음

​3. 오래된 poolInfo

​4. 우선 수수료

​5. 슬리피지 허용 오차는 풀 유형과 일치해야 함

​6. BN 대 number

​버전 정책

​업그레이드

​도움말 받기

​포인터

설치

초기화

네 가지 모듈 파사드

트랜잭션 빌더

비동기 빌더인 이유?

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

일반적인 함정

1. 클러스터 불일치

2. ATAs 미리 생성하지 않음

3. 오래된 `poolInfo`

4. 우선 수수료

5. 슬리피지 허용 오차는 풀 유형과 일치해야 함

6. `BN` 대 `number`

버전 정책

업그레이드

도움말 받기

포인터