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

# 도구 체인

> Raydium 온체인 상태 읽기, 거래 구성, 프로그램 개발을 위한 최소 작동 환경. Solana CLI, Anchor, TypeScript 및 Python SDK, devnet/localnet 팁.

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

  [영문판 보기 →](/solana-fundamentals/toolchain)
</Info>

이 문서의 모든 내용은 정상적으로 작동하는 Solana 개발 도구 체인을 전제로 합니다. 이 페이지에서는 도구, 2026년 4월 기준 Raydium과 호환되는 최소 버전, 그리고 특정 설정 주의사항을 나열합니다. 이후 장의 코드 예제를 실행하기 전에 먼저 이 페이지부터 시작하세요.

## 핵심 도구

### Solana CLI

Solana 클러스터와 상호작용하기 위한 공식 명령행 인터페이스 — 지갑 관리, RPC 호출, 프로그램 배포.

설치:

```bash theme={null}
sh -c "$(curl -sSfL https://release.solana.com/v1.18.22/install)"
# 또는 최신 안정 버전:
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
```

검증:

```bash theme={null}
solana --version   # → solana-cli 1.18.22 (또는 그 이상)
```

메인넷 구성:

```bash theme={null}
solana config set --url https://api.mainnet-beta.solana.com
solana config set --keypair ~/.config/solana/id.json
solana-keygen new                           # 지갑이 없으면 생성
solana address                              # 공개 키 확인
```

Raydium 테스트를 위해서는 거의 항상 자금이 충전된 devnet 지갑이 필요합니다:

```bash theme={null}
solana config set --url https://api.devnet.solana.com
solana airdrop 2                            # 테스트용 2 SOL
```

### SPL Token CLI

SPL Token / Token-2022 작업을 위한 공식 CLI — 민트 생성, 토큰 발행, 양도.

설치 (Solana CLI에 포함):

```bash theme={null}
spl-token --version
```

일반적인 작업:

```bash theme={null}
spl-token create-token                                  # SPL Token 민트 생성
spl-token create-token --program-id TOKEN_2022 ...      # Token-2022 민트 생성
spl-token create-account <MINT>                         # ATA 생성
spl-token mint <MINT> 1000                              # ATA에 1000개 토큰 발행
spl-token transfer <MINT> 100 <RECIPIENT>               # 100개 양도
spl-token display <ACCOUNT_OR_MINT>                     # 확인
```

### Anchor CLI

Raydium IDL 가져오기, 클라이언트 구성, 프로그램 검증에 필요합니다.

설치:

```bash theme={null}
cargo install --git https://github.com/coral-xyz/anchor avm --locked
avm install 0.30.1
avm use 0.30.1
anchor --version
```

일반적인 작업:

```bash theme={null}
anchor idl fetch <PROGRAM_ID> -o program.idl.json       # 온체인 IDL 가져오기
anchor idl init -f idl.json <PROGRAM_ID>                # IDL 업로드
anchor build                                             # 소스에서 프로그램 빌드
```

## TypeScript 설정

Raydium의 기본 통합 경로입니다.

### 패키지

```bash theme={null}
npm install \
  @solana/web3.js \
  @solana/spl-token \
  @coral-xyz/anchor \
  @raydium-io/raydium-sdk-v2 \
  bn.js \
  decimal.js
```

2026년 4월 기준으로 함께 작동하는 것으로 알려진 버전:

| 패키지                          | 버전            |
| ---------------------------- | ------------- |
| `@solana/web3.js`            | ≥1.95         |
| `@solana/spl-token`          | ≥0.4          |
| `@coral-xyz/anchor`          | ≥0.30         |
| `@raydium-io/raydium-sdk-v2` | ≥0.2.42-alpha |

### 최소 스크립트

```ts theme={null}
import { Connection, Keypair } from "@solana/web3.js";
import { Raydium } from "@raydium-io/raydium-sdk-v2";

const connection = new Connection("https://api.mainnet-beta.solana.com", "confirmed");
const owner      = Keypair.fromSecretKey(/* your key */);

const raydium = await Raydium.load({
  connection,
  owner,
  cluster:      "mainnet",
  disableFeatureCheck: true,
});

const poolInfo = await raydium.api.fetchPoolById({ id: "..." });
console.log(poolInfo);
```

전체 SDK 레퍼런스는 [`sdk-api/typescript-sdk`](/ko/sdk-api/typescript-sdk)를 참조하세요.

## Rust 설정

CPI 통합 및 온체인 프로그램용입니다.

### 도구 체인

```bash theme={null}
rustup install 1.76.0           # 또는 Anchor에서 현재 요구하는 버전
rustup component add rustfmt clippy
solana-install init 1.18.22     # BPF 도구 체인 포함
```

### Raydium CPI 통합용 프로그램 Cargo.toml

```toml theme={null}
[dependencies]
anchor-lang        = "0.30.1"
anchor-spl         = "0.30.1"
raydium-cp-swap    = { version = "0.2", features = ["cpi"] }
raydium-clmm       = { version = "0.1", features = ["cpi"] }
```

`"cpi"` 피처는 CPI 헬퍼와 함께 `cpi` 모듈을 가져옵니다 (`raydium_cp_swap::cpi::swap_base_input(...)` 사용 가능). [`sdk-api/rust-cpi`](/ko/sdk-api/rust-cpi)를 참조하세요.

## Python 설정

보조 통합 경로 — 봇 개발자에게 일반적입니다.

### 패키지

```bash theme={null}
pip install solders solana-py anchorpy
pip install raydium-py    # 커뮤니티 Raydium SDK (비공식)
```

버전:

| 패키지          | 버전     |
| ------------ | ------ |
| `solders`    | ≥0.21  |
| `solana-py`  | ≥0.34  |
| `anchorpy`   | ≥0.21  |
| `raydium-py` | ≥0.2.1 |

### 최소 스크립트

```python theme={null}
from solana.rpc.async_api import AsyncClient
from solders.keypair import Keypair
from anchorpy import Provider, Wallet, Program

async def main():
    conn = AsyncClient("https://api.mainnet-beta.solana.com")
    owner = Keypair()
    wallet = Wallet(owner)
    provider = Provider(conn, wallet)

    # IDL 및 프로그램 로드
    with open("cpmm.idl.json") as f:
        idl = json.load(f)
    program = Program(idl, CPMM_PROGRAM_ID, provider)

    pool = await program.account["PoolState"].fetch(pool_id)
    print(pool)
```

[`sdk-api/python-integration`](/ko/sdk-api/python-integration)를 참조하세요.

## RPC 엔드포인트

공용 메인넷 RPC (`api.mainnet-beta.solana.com`)는 심각한 속도 제한이 있으며 부하가 있으면 스로틀됩니다. 비자명한 사용을 위해 프라이빗 엔드포인트를 확보하세요:

| 제공자       | 설명                          |
| --------- | --------------------------- |
| Helius    | 가장 인기 있음; 관대한 무료 티어.        |
| Triton    | 엔터프라이즈; 프리미엄 가격, 안정적.       |
| QuickNode | 견고함; 낮은 지연 시간.              |
| 자체 RPC 노드 | 월 약 \$500의 하드웨어 비용; 완전한 제어. |

구성:

```ts theme={null}
const connection = new Connection("https://mainnet.helius-rpc.com/?api-key=...");
```

일부 RPC 작업에는 확장된 기능이 필요합니다:

* `getProgramAccounts` — 제한 없는 스캔은 비용이 많이 드니; 일부 제공자는 스캔당 게이트 또는 요금 부과.
* `getPriorityFeeEstimate` — Helius 전용 엔드포인트; 다른 제공자는 동등한 기능 보유.
* `geyser` / WebSocket 스트리밍 — 저지연 봇에 필요; 모든 제공자가 노출하지는 않음.

## Devnet 및 Localnet

### Devnet

Solana의 공용 테스트 클러스터. Raydium은 부분적인 devnet 배포를 가지고 있습니다:

* 테스트용 CPMM 풀 존재.
* AMM v4는 역사적 devnet 풀 보유.
* CLMM은 몇 가지 데모 풀 보유.
* Farm v6 배포됨.

```bash theme={null}
solana config set --url https://api.devnet.solana.com
solana airdrop 2
```

SDK는 `cluster: "devnet"`을 통해 devnet을 지원합니다:

```ts theme={null}
const raydium = await Raydium.load({ connection, owner, cluster: "devnet" });
```

**주의**: devnet 풀은 유동성이 적고 상태가 오래되었을 수 있습니다. 가격 발견을 위해 devnet에 의존하지 마세요; 명령어 흐름 구성-테스트 용도로만 사용하세요.

### Forked 메인넷 상태를 사용한 Localnet

현실적인 테스트를 위해 메인넷 상태를 로컬 검증자로 포크합니다:

```bash theme={null}
solana-test-validator \
  --url https://api.mainnet-beta.solana.com \
  --clone CPMMoo8L3F4NbTegBCKVNunggL7H1Zpdmwpwh8KMoZ0F \
  --clone CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK \
  --clone <SOME_POOL_ID> \
  --clone <SOME_MINT_ID>
```

특정 프로그램/계정 상태를 localhost로 복제하여 자유롭게 거래할 수 있습니다. 다음에 이상적입니다:

* 실제 Raydium 프로그램에 대해 CPI 통합을 단위 테스트.
* 수정된 파라미터로 거래 재실행하여 디버깅.
* 대규모 합성 거래량으로 스트레스 테스트.

Raydium 팀은 메인넷 배포 전 회귀 테스트를 위해 forked localnet을 광범위하게 사용합니다.

## 프로젝트 템플릿

### TypeScript 통합 스타터

```
my-raydium-app/
├── package.json
├── tsconfig.json
├── src/
│   ├── swap.ts           # 스왑 예제
│   ├── add-liquidity.ts
│   └── read-pool.ts
└── .env                  # RPC URL, 지갑 경로
```

최소 `package.json`:

```json theme={null}
{
  "name": "my-raydium-app",
  "type": "module",
  "scripts": { "swap": "tsx src/swap.ts" },
  "dependencies": {
    "@raydium-io/raydium-sdk-v2": "^0.2.42-alpha",
    "@solana/web3.js": "^1.95",
    "@solana/spl-token": "^0.4"
  },
  "devDependencies": {
    "@types/node": "^20",
    "tsx": "^4",
    "typescript": "^5"
  }
}
```

### Anchor CPI 프로그램 스타터

```
my-raydium-cpi/
├── Anchor.toml
├── Cargo.toml
├── programs/
│   └── my-cpi/
│       ├── Cargo.toml
│       └── src/lib.rs
└── tests/
    └── my-cpi.ts
```

Anchor 0.30 사용:

```bash theme={null}
anchor init my-raydium-cpi
cd my-raydium-cpi
# Cargo.toml에 raydium-cp-swap을 features = ["cpi"]로 추가
anchor build
anchor test
```

## 유용한 CLI 유틸리티

### `solana-keygen`

```bash theme={null}
solana-keygen new --outfile ./wallet.json          # 키 생성
solana-keygen pubkey ./wallet.json                 # 공개 키 표시
```

### 모든 계정 읽기

```bash theme={null}
solana account <ADDRESS> --output json-compact
```

디코더 없이 풀 상태를 둘러보는 데 유용합니다.

### 프로그램 로그

```bash theme={null}
solana logs | grep CPMMoo                         # CPMM 관련 tx 로그 추적
```

### 거래 검사

```bash theme={null}
solana confirm <TX_SIGNATURE> -v                   # 로그를 보기 좋게 출력
```

또는 [explorer](https://explorer.solana.com) 경유 — 서명을 붙여넣고 "Program Logs" 탭을 보세요.

## 환경 정리

### 목적별 별도 지갑

* **개발 지갑**: 테스트넷 SOL 보유, 구성에 사용.
* **프로덕션 지갑**: 실제 SOL 보유, 배포/멀티시그 제출에만 사용.
* **봇용 핫 지갑**: 소액, 제한된 권한.

키는 절대 하드코딩되어서는 안 됩니다. 환경 변수 또는 시크릿 매니저를 사용하세요.

### `.env` 패턴

```
# .env (커밋되지 않음)
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...
WALLET_PATH=/Users/you/.config/solana/id.json
```

```ts theme={null}
import { config } from "dotenv";
config();

const connection = new Connection(process.env.SOLANA_RPC_URL!);
```

### 버전 고정

모든 Solana 에코시스템 의존성을 고정합니다. 에코시스템은 빠르게 움직이고; `@solana/web3.js`의 마이너 버전 범프는 이전에 주요 변경을 도입했습니다. `package-lock.json` / `Cargo.lock`을 종교적으로 사용하세요.

## 포인터

* [`sdk-api/typescript-sdk`](/ko/sdk-api/typescript-sdk) — TypeScript SDK 레퍼런스.
* [`sdk-api/rust-cpi`](/ko/sdk-api/rust-cpi) — Rust CPI 사용법.
* [`sdk-api/python-integration`](/ko/sdk-api/python-integration) — Python 설정.
* [`solana-fundamentals/programs-and-anchor`](/ko/solana-fundamentals/programs-and-anchor) — Anchor 배경.

출처:

* [Solana 설치 문서](https://docs.solana.com/cli/install-solana-cli-tools).
* [Anchor 북: 시작하기](https://book.anchor-lang.com/getting_started/installation.html).
* [Raydium SDK v2 저장소](https://github.com/raydium-io/raydium-sdk-V2).