> ## 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 개요

> Solana 스왑 트랜잭션 빌더 서버입니다.

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

  [영문판 보기 →](/api-reference/route-api-v2/overview)
</Info>

## 트랜잭션 API란?

Raydium 트랜잭션 API (Route V2)는 클라이언트가 RPC 연결을 유지하거나 전체 Raydium SDK를 번들링할 필요 없이 직렬화된 Solana 스왑 트랜잭션을 빌드하는 서버 측 서비스입니다. 다음과 같은 통합을 크게 간소화합니다:

* 로컬 RPC 클라이언트를 실행할 수 없는 웹 프론트엔드
* 리소스가 제한된 모바일 애플리케이션
* 헤드리스 트레이딩 봇
* 애그리게이터 및 지갑 공급자

클라이언트에서 복잡한 풀 라우팅 및 트랜잭션 구성을 수행하는 대신, 우리 API에서 스왑 견적과 트랜잭션 빌딩을 요청한 후 모든 Solana RPC를 사용하여 결과에 서명하고 브로드캐스트합니다.

## 워크플로우 개요

트랜잭션 API는 관심사를 두 가지 단계로 분리합니다:

### 1. 계산 단계: 견적 받기

`/compute/swap-base-in` 또는 `/compute/swap-base-out`을 호출하여 현재 풀 상태에 따른 예상 스왑 출력 (또는 필요한 입력)을 받습니다. 이 엔드포인트는 **읽기 전용**이며 서명이 필요하지 않습니다:

```bash theme={null}
GET /compute/swap-base-in?inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0
```

응답에 포함되는 항목:

* 예상 출력 금액
* 라우트 분석 (사용되는 풀 및 유동성 소스)
* 가격 영향

### 2. 트랜잭션 단계: 빌드 및 서명

계산 응답을 받으면 이를 (지갑 및 구성과 함께) `/transaction/swap-base-in` 또는 `/transaction/swap-base-out`에 전달합니다:

```bash theme={null}
POST /transaction/swap-base-in
Content-Type: application/json

{
  "wallet": "YourWalletAddress",
  "swapResponse": { ...response from /compute/swap-base-in },
  "txVersion": "V0",
  "computeUnitPriceMicroLamports": "1000",
  "wrapSol": false,
  "unwrapSol": false,
  "inputAccount": "TokenAccount1...",
  "outputAccount": "TokenAccount2..."
}
```

응답에 포함되는 항목:

* 서명할 준비가 된 Base64 인코딩된 버전화 트랜잭션
* 주소 조회 테이블 주소 (txVersion=V0인 경우)

클라이언트는 다음을 수행합니다:

1. 트랜잭션 디코딩
2. 사용자의 키페어로 서명
3. 모든 Solana RPC를 통해 브로드캐스트
4. 확인 대기

## 계산 엔드포인트

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

**사용 사례**: 사용자가 입력 금액을 지정하면 출력을 계산합니다.

**필수 쿼리 매개변수**:

* `inputMint` – 보내는 토큰의 민트 주소
* `outputMint` – 원하는 토큰의 민트 주소
* `amount` – 입력 금액 (최소 단위인 라모포)
* `slippageBps` – 최대 허용 슬리피지 (기본점, 0–10000)
* `txVersion` – `V0` 또는 `LEGACY`

**선택 사항**:

* `referrerBps` – 리페러 권한이 있는 경우 리페러 수수료로 수집할 출력의 기본점

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

**사용 사례**: 사용자가 원하는 출력을 지정하면 필요한 입력을 계산합니다.

**필수 쿼리 매개변수**:

* `inputMint`, `outputMint`, `amount` (원하는 출력), `slippageBps`, `txVersion`

**참고**: Base-out의 경우 리페러 기본점이 없습니다 (아직 구현되지 않음).

## 트랜잭션 엔드포인트

### `POST /transaction/swap-base-in`

고정 입력 금액에 대한 트랜잭션을 빌드합니다.

**필수 본문**:

* `wallet` – 서명 지갑 주소
* `swapResponse` – 전체 계산 응답 객체
* `txVersion` – 트랜잭션 버전
* `computeUnitPriceMicroLamports` – 마이크로라모포 단위의 우선순위 수수료

**선택 사항**:

* `wrapSol` – true인 경우 입력을 위해 기본 SOL을 래핑합니다
* `unwrapSol` – true인 경우 출력에서 WSOL을 SOL로 언래핑합니다
* `inputAccount` – 입력용 토큰 계정 (SOL을 래핑하지 않는 경우 필수)
* `outputAccount` – 출력용 토큰 계정
* `nonceInfo` – 오프라인 서명을 위한 내구성 nonce
* `jitoInfo` – Jito MEV 보호 번들 매개변수
* `referrerWallet` – 수수료 수집을 위한 리페러 지갑

### `POST /transaction/swap-base-out`

고정 출력 금액에 대한 트랜잭션을 빌드합니다.

**Base-in과 동일한 매개변수**, 단:

* `referrerInfo` 필드는 현재 주석 처리되어 있습니다 (아직 구현되지 않음)

## 응답 엔벨로프

모든 엔드포인트는 표준 엔벨로프를 반환합니다:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "version": "V1",
  "data": { ... }
}
```

오류의 경우 `success`는 `false`이고 `msg`는 오류 코드를 포함합니다 (예: `REQ_WALLET_ERROR`, `REQ_SLIPPAGE_BPS_ERROR`).

## 트랜잭션 응답 형태

성공적인 트랜잭션 응답은 다음과 같습니다:

```json theme={null}
{
  "id": "...",
  "success": true,
  "version": "V1",
  "data": {
    "transaction": "AgABB...",
    "addressLookupTableAddresses": ["Address1...", "Address2..."]
  }
}
```

## 통합 예제

다음은 의사 코드의 일반적인 흐름입니다:

```typescript theme={null}
// 1. Get quote
const quote = await fetch(
  'https://transaction-v1.raydium.io/compute/swap-base-in?' +
  'inputMint=EPjF...&outputMint=So111...&amount=1000000&slippageBps=50&txVersion=V0'
).then(r => r.json());

// 2. Validate quote
if (!quote.success) {
  throw new Error(quote.msg);
}

// 3. Build transaction
const tx = await fetch(
  'https://transaction-v1.raydium.io/transaction/swap-base-in',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      wallet: userWalletAddress,
      swapResponse: quote,
      txVersion: 'V0',
      computeUnitPriceMicroLamports: '1000',
      inputAccount: userInputTokenAccount,
      outputAccount: userOutputTokenAccount,
    }),
  }
).then(r => r.json());

// 4. Decode and sign
const transaction = VersionedTransaction.deserialize(
  Buffer.from(tx.data.transaction, 'base64')
);
transaction.sign([userKeypair]);

// 5. Send via RPC
const rpc = new Connection('https://api.mainnet-beta.solana.com');
const sig = await rpc.sendTransaction(transaction);
await rpc.confirmTransaction(sig);
```

## 주요 매개변수 설명

### `txVersion`

* **V0**: 주소 조회 테이블 (ALT)이 있는 최신 Solana 트랜잭션입니다. 더 작은 직렬화 크기, 낮은 수수료.
* **LEGACY**: ALT 이전 트랜잭션 형식입니다. 더 크지만 모든 RPC 엔드포인트에서 작동합니다.

가능할 때 **V0**를 선택하고, RPC 또는 지갑이 ALT를 지원하지 않으면 **LEGACY**로 폴백합니다.

### `computeUnitPriceMicroLamports`

더 빠른 블록 포함을 위한 우선순위 수수료입니다. 우선순위 수수료가 없으려면 `0`으로 설정하거나, 혼잡한 네트워크에서 경쟁하기 위해 더 높은 값 (예: `1000`)으로 설정합니다. 단위는 컴퓨트 유닛당 마이크로라모포입니다.

### `slippageBps`

기본점 단위의 최대 슬리피지 허용량입니다. `100` = 1%, `50` = 0.5%.

* 대부분의 안정적인 스왑의 경우 더 낮은 값 (예: 25–50 bps) 사용
* 변동성이 크거나 유동성이 낮은 쌍의 경우 증가

### `wrapSol` 및 `unwrapSol`

* **wrapSol**: `true`인 경우 API가 기본 SOL을 WSOL로 래핑합니다. `inputAccount`가 필요하지 않습니다.
* **unwrapSol**: `true`인 경우 API가 출력 WSOL을 기본 SOL로 언래핑합니다. `outputAccount`가 필요하지 않습니다.

둘 다 `false`인 경우 명시적 토큰 계정을 제공해야 합니다.

## 네트워크 엔드포인트

| 네트워크 | 메인넷                         | 데브넷                                |
| ---- | --------------------------- | ---------------------------------- |
| 호스트  | `transaction-v1.raydium.io` | `transaction-v1-devnet.raydium.io` |
| 프로토콜 | HTTPS                       | HTTPS                              |

## 오류 코드

일반적인 오류 메시지:

| 코드                        | 의미                          |
| ------------------------- | --------------------------- |
| `REQ_SLIPPAGE_BPS_ERROR`  | 슬리피지가 유효하지 않거나 범위를 벗어남      |
| `REQ_INPUT_MINT_ERROR`    | 입력 민트 주소가 유효하지 않음           |
| `REQ_OUTPUT_MINT_ERROR`   | 출력 민트 주소가 유효하지 않음           |
| `REQ_AMOUNT_ERROR`        | 금액이 유효한 숫자가 아님              |
| `REQ_TX_VERSION_ERROR`    | txVersion은 V0 또는 LEGACY여야 함 |
| `REQ_WALLET_ERROR`        | 지갑 주소가 유효하지 않음              |
| `REQ_INPUT_ACCOUT_ERROR`  | 입력 토큰 계정이 누락되었거나 유효하지 않음    |
| `REQ_OUTPUT_ACCOUT_ERROR` | 출력 토큰 계정이 누락되었거나 유효하지 않음    |
| `UNKNOWN_ERROR`           | 서버 측 오류입니다. 요청 매개변수를 확인하세요  |

## 참고 자료

* [OpenAPI 사양](/ko/api-reference/openapi/route-api-v2.yaml)
* [애그리게이터 통합 가이드](/ko/integration-guides/aggregator)