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

# 트레이드 API

> Raydium의 서버 기반 스왑 트랜잭션 엔드포인트: 견적, 빌드, 서명, 전송. SDK를 번들링하지 않으면서 Raydium 라우팅을 원하는 앱을 위한 통합 패턴 — 반환되는 내용, SDK와의 차이점, 그리고 애그리게이터의 사용 방법.

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

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

<Info>
  **트레이드 API**는 `transaction-v1.raydium.io` (및 `api-v3.raydium.io`의 일부 미러링 경로)에 있는 엔드포인트들의 간단한 집합으로, 스왑을 견적하고, 서명 준비가 완료된 Solana 트랜잭션을 빌드한 뒤, 한 번의 왕복으로 반환합니다. Raydium UI가 사용하는 것과 동일한 표면입니다. TS SDK를 번들링하지 않고 Raydium 라우팅을 원할 때 사용하세요 — 백엔드, Blinks 핸들러, Telegram 봇, 제3자 앱 등에 적합합니다.
</Info>

## 트레이드 API 대 SDK 사용 기준

| 요구 사항                                                                | 사용할 것                                                  |
| -------------------------------------------------------------------- | ------------------------------------------------------ |
| npm 패키지를 번들링할 수 없는 백엔드에 스왑을 통합하고 싶어요 (예: Python 봇, Go 서비스, Rust 서비스) | **트레이드 API**                                           |
| 소셜 포스트에 스왑 Blink를 렌더링하고 싶어요                                          | **트레이드 API**                                           |
| 킬로바이트 절감이 중요한 브라우저 앱을 빌드하고 싶어요                                       | **트레이드 API**                                           |
| 다른 Solana 프로그램 내에 라우팅 로직을 임베드하고 싶어요 (CPI)                            | 둘 다 아님 — [`sdk-api/rust-cpi`](/ko/sdk-api/rust-cpi) 사용 |
| 커스텀 경로 미리보기, 차트 오버레이, 우선순위 수수료 휴리스틱이 있는 완전한 DEX형 클라이언트를 빌드하고 싶어요     | **TS SDK**                                             |
| 네트워크 왕복 없이 결정론적인 오프라인 견적이 필요해요                                       | **TS SDK** (로컬 풀 상태 포함)                                |

SDK는 더 풍부한 기능을 제공하고, 트레이드 API는 더 간단합니다. 둘 다 동일한 CPMM/CLMM/AMM v4 프로그램을 래핑하므로, 결과적인 온체인 스왑은 동일합니다.

## 세 개의 엔드포인트

### 1. `GET /compute/swap-base-in`

입력 금액이 주어지면 경로를 선택하고 견적을 반환합니다.

```
GET https://transaction-v1.raydium.io/compute/swap-base-in
  ?inputMint=So11111111111111111111111111111111111111112
  &outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  &amount=1000000000
  &slippageBps=50
  &txVersion=V0
```

응답:

```json theme={null}
{
  "id": "b2e4...",
  "success": true,
  "version": "V1",
  "data": {
    "swapType": "BaseIn",
    "inputMint":  "So11111111111111111111111111111111111111112",
    "inputAmount":  "1000000000",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputAmount": "165234567",
    "otherAmountThreshold": "164408394",
    "slippageBps": 50,
    "priceImpactPct": 0.0012,
    "referrerAmount": "0",
    "routePlan": [
      { "poolId": "58oQ...", "inputMint": "So11...", "outputMint": "USDC...", "feeAmount": "2500000", "feeMint": "So11..." }
    ]
  }
}
```

`id` 필드는 다음 엔드포인트에 전달되는 불명시적 견적 핸들입니다. 견적은 약 30초 동안 유효하며, 그 이상 지나면 다시 견적을 받아야 합니다.

### 2. `GET /compute/swap-base-out`

역방향 형태: "출력에서 정확히 N을 받고 싶어요; 필요한 입력을 견적해 주세요."

```
GET /compute/swap-base-out
  ?inputMint=<MINT_IN>
  &outputMint=<MINT_OUT>
  &amount=<DESIRED_OUTPUT_AMOUNT>
  &slippageBps=50
  &txVersion=V0
```

`swap-base-in`과 대칭적인 응답 형태입니다; `amount` 필드 의미론은 반대입니다.

### 3. `POST /transaction/swap-base-in` 및 `/transaction/swap-base-out`

단계 1에서의 견적을 받아 서명 준비가 완료된 버전 트랜잭션을 반환합니다:

```
POST https://transaction-v1.raydium.io/transaction/swap-base-in
Content-Type: application/json

{
  "computeUnitPriceMicroLamports": "50000",
  "swapResponse": { ... swap-base-in의 data 객체를 붙여넣으세요 ... },
  "txVersion": "V0",
  "wallet": "<user_pubkey>",
  "wrapSol": true,
  "unwrapSol": false,
  "inputAccount": "<optional_token_account>",
  "outputAccount": "<optional_token_account>"
}
```

응답:

```json theme={null}
{
  "id": "9f1c...",
  "success": true,
  "version": "V1",
  "data": [
    { "transaction": "<base64-encoded-versioned-transaction>" }
  ]
}
```

스왑에 설정이 필요한 경우 (예: ATA 생성, SOL 래핑) 여러 트랜잭션이 반환될 수 있습니다. 순서대로 서명하고 전송하세요.

## 최소 엔드투엔드 예제 (Python)

```python theme={null}
import base64, requests
from solders.transaction import VersionedTransaction
from solders.keypair import Keypair
from solana.rpc.api import Client

rpc = Client("https://api.mainnet-beta.solana.com")
kp = Keypair.from_bytes(bytes([...]))    # your signer

SOL  = "So11111111111111111111111111111111111111112"
USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

quote = requests.get(
    "https://transaction-v1.raydium.io/compute/swap-base-in",
    params={
        "inputMint": SOL, "outputMint": USDC,
        "amount": 1_000_000_000, "slippageBps": 50, "txVersion": "V0",
    },
).json()

built = requests.post(
    "https://transaction-v1.raydium.io/transaction/swap-base-in",
    json={
        "computeUnitPriceMicroLamports": "50000",
        "swapResponse": quote,
        "txVersion": "V0",
        "wallet": str(kp.pubkey()),
        "wrapSol": True,
        "unwrapSol": False,
    },
).json()

for entry in built["data"]:
    raw = base64.b64decode(entry["transaction"])
    tx = VersionedTransaction.from_bytes(raw)
    tx.sign([kp])
    sig = rpc.send_raw_transaction(bytes(tx)).value
    print(f"Sent: {sig}")
```

이것은 약 20줄입니다. TS SDK로 하는 동등한 작업은 약 30줄이지만 더 풍부한 제어를 제공합니다 (커스텀 경로 선택기, 풀별 컴퓨트 유닛 예산 책정, 상세한 에러 메타데이터).

## 라우팅 및 풀 선택

트레이드 API는 **모든** Raydium 프로그램 (CPMM, CLMM, AMM v4)을 통해 라우팅하고 견적된 크기에 대해 최고의 실행을 선택합니다. 특징:

* **멀티홉 지원.** SOL→USDC 스왑이 비용이 더 저렴하면 wSOL→JUP→USDC를 통해 라우팅될 수 있습니다.
* **동일 프로그램 다중 풀 분할 미지원.** 단일 견적은 정확히 하나의 경로를 거칩니다; 크기를 여러 풀로 분할하려면 클라이언트 측에서 처리하세요 (두 개의 견적, 두 개의 트랜잭션).
* **안정적 vs 집중형.** 라우터는 범위 내 유동성이 충분할 때 CLMM을 선호하고, 긴 꼬리 쌍의 경우 CPMM으로 폴백합니다.
* **AMM v4 포함.** AMM v4 풀은 라우팅에 포함되지만 CPMM/CLMM 대안보다 더 나은 가격을 제공할 때만 선택됩니다.

특정 풀을 통한 라우팅을 강제하려면 SDK를 사용하세요 — 트레이드 API는 풀 핀 매개변수를 노출하지 않습니다.

## 레퍼러 매개변수

계산 엔드포인트에 `&referrer=<wallet_pubkey>`를 추가하여 스왑에서 1% 레퍼럴 컷을 받으세요. 의미론은 [`user-flows/referrals-and-blinks`](/ko/user-flows/referrals-and-blinks)를 참조하세요. 존재할 때:

* 견적 응답의 `referrerAmount`는 레퍼러로 라우팅될 입력 민트의 절대 금액입니다.
* 최종 트랜잭션은 레퍼러의 ATA에 대한 추가 SPL 토큰 전송을 포함합니다.

## 우선순위 수수료

빌드 요청의 `computeUnitPriceMicroLamports`는 반환된 트랜잭션의 우선순위 수수료를 설정합니다. 경험칙:

* `50_000` (0.00005 lamports/CU × 200k CU ≈ 0.00001 SOL): 최소, 혼잡하지 않은 시간에 괜찮습니다.
* `200_000`: 중간 정도의 혼잡.
* `1_000_000`: 심각한 혼잡.

적응적 튜닝을 위해 먼저 RPC에서 `getRecentPrioritizationFees`를 호출한 다음 중앙값을 전달하세요. [`integration-guides/priority-fee-tuning`](/ko/integration-guides/priority-fee-tuning)을 참조하세요.

## 트랜잭션 버전

* `"V0"`은 공통 계정에 대한 조회 테이블을 사용하는 버전화된 (`MessageV0`) 트랜잭션을 반환합니다. 더 작고 빠릅니다. **권장됩니다.**
* `"LEGACY"`는 레거시 트랜잭션을 반환합니다. 더 큽니다; 지갑/인프라가 V0을 처리하지 않는 경우에만 사용하세요.

## 에러 형태

API는 논리적 에러의 경우 `success: false`와 함께 HTTP 200을 반환하고, 전송/인프라 에러의 경우 HTTP 4xx/5xx를 반환합니다.

일반적인 논리적 에러:

* `"No route found"` — 이 크기에서 두 민트 간의 경로가 없습니다. `amount`를 줄이거나 쌍을 다시 고려하세요.
* `"Insufficient liquidity"` — 경로는 존재하지만 `slippageBps`를 초과할 것입니다. 슬리피지를 넓히세요.
* `"Quote expired"` — `swapResponse`가 30초 이상 오래되었습니다. 다시 견적을 받으세요.
* `"Unsupported mint"` — 민트가 Raydium의 범위에 없습니다 (미등록 또는 더 이상 사용되지 않는 프로그램).

## 속도 제한

* **견적 엔드포인트:** IP당 분당 120개 요청.
* **빌드 엔드포인트:** IP당 분당 60개 요청 (서버에서 비용이 높음).
* 제한을 초과하면 `Retry-After` 헤더와 함께 HTTP 429를 반환합니다.

더 높은 처리량을 원하면 Raydium 개발자 관계팀에 문의하세요; 애그리게이터 티어 키가 있습니다.

## 통합자를 위한 아키텍처 패턴

```
┌─────────────┐   quote   ┌───────────────┐   build   ┌───────────────┐   sign/send   ┌──────────┐
│ Your front  │──────────►│ Trade API     │──────────►│ Trade API     │──────────────►│ Solana   │
│   end       │◄──────────│ /compute/...  │◄──────────│ /transaction/ │               │   RPC    │
└─────────────┘           └───────────────┘           └───────────────┘               └──────────┘
                              (stateless)                 (stateless)
```

모든 것은 상태가 없습니다 — 견적 호출과 빌드 호출 사이에 전달해야 할 유일한 것은 견적 응답 본문 자체입니다.

## 다음으로 갈 곳

* [`sdk-api/typescript-sdk`](/ko/sdk-api/typescript-sdk) — 동일한 기본 프로그램을 가진 더 풍부한 프로그래매틱 인터페이스.
* [`sdk-api/rest-api`](/ko/sdk-api/rest-api) — 트레이드 API의 쓰기 측면을 보완하는 읽기 전용 엔드포인트 (풀 정보, 민트 정보).
* [`user-flows/swap`](/ko/user-flows/swap) — 엔드투엔드 UI 스왑 흐름.
* [`integration-guides/aggregator`](/ko/integration-guides/aggregator) — 많은 DEX를 통해 라우팅하는 애그리게이터의 패턴.

출처:

* `transaction-v1.raydium.io` 라이브 엔드포인트.
* Raydium UI 네트워크 탭 검사 (동일한 소비 표면).