> ## 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 엔드-투-엔드 — 설치, 네 가지 모듈 파사드, 트랜잭션 구축, 그리고 모든 새로운 통합자를 괴롭히는 함정들.

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

  [영문판 보기 →](/sdk-api/typescript-sdk)
</Info>

## 설치

```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
```

SDK는 TypeScript로 작성되었으며 JS 아티팩트와 함께 `.d.ts` 파일을 제공합니다. 최소 요구 사항: Node 18+, TypeScript 5.0+, `moduleResolution: "bundler"` 또는 `"node16"`.

## 초기화

진입점은 `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`는 시작 시 `api-v3.raydium.io`에서 작은 `/config` 페이로드를 가져오기 때문에 비동기입니다 (현재 `AmmConfig` 계정, 수수료 등급 등을 나열). 오프라인 환경에서는 `disableFeatureCheck: true`를 설정하면 됩니다. 일부 빌더에 수동으로 값을 제공해야 합니다.

## 네 가지 모듈 파사드

로드되면 `raydium` 객체는 제품 표면당 하나씩 네 가지 모듈 파사드를 노출합니다:

```ts theme={null}
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`은 지원 유틸리티입니다.)

## 트랜잭션 빌더

모든 뮤테이팅 함수는 즉시 실행하지 않고 빌더를 반환합니다:

```ts theme={null}
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`](/ko/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`를 제공하세요:

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

크기 조정 지침은 [`integration-guides/priority-fee-tuning`](/ko/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 마이너 버전 간 업그레이드 시:

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

## 도움말 받기

SDK 및 API 질문의 경우:

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

보안 문제의 경우 공개 채널에 게시하지 **마세요** — [`security/disclosure`](/ko/security/disclosure)를 참조하세요.

## 포인터

* [`sdk-api/rest-api`](/ko/sdk-api/rest-api) — SDK의 HTTP 보완입니다.
* [`sdk-api/trade-api`](/ko/sdk-api/trade-api) — 서버 구축 스왑 거래입니다.
* [`sdk-api/anchor-idl`](/ko/sdk-api/anchor-idl) — 프로그램 IDL에서 직접 클라이언트 재생성입니다.
* [`sdk-api/python-integration`](/ko/sdk-api/python-integration) — `solana-py`를 통한 Python 동등물입니다.
* [`integration-guides/priority-fee-tuning`](/ko/integration-guides/priority-fee-tuning) — `computeBudgetConfig` 크기 조정입니다.

출처:

* [Raydium SDK v2 소스](https://github.com/raydium-io/raydium-sdk-V2)
* Raydium SDK 릴리스 노트.