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

# REST API 표면

> Raydium의 11개 공개 HTTP 서비스에 대한 개괄 — 각 서비스의 역할, 공유하는 규칙(응답 봉투, 인증, 속도 제한, 캐싱), 그리고 통합에 적합한 서비스를 선택하는 방법.

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

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

<Info>
  **엔드포인트별 문서는 [API Reference](/ko/api-reference) 탭에서 제공합니다.** 여기의 모든 엔드포인트에는 Mintlify의 OpenAPI 플레이그라운드로 구동되는 인터랙티브 **시도** 패널이 있습니다. 브라우저에서 매개변수를 입력하고 실시간 메인넷(또는 이용 가능한 데브넷)에 직접 요청할 수 있습니다. 이 페이지는 **내용 설명 자료**입니다. 어떤 서비스가 있는지, 어떤 것을 언제 사용해야 하는지, 그리고 모든 서비스에 공통으로 적용되는 규칙을 설명합니다. "`GET /pools/info/ids`가 뭘 받는가"를 찾는다면 API Reference로 이동하고, "어떤 서비스를 통합해야 하나"를 찾는다면 아래를 읽으세요.
</Info>

## 11개 서비스 개요

Raydium은 11개의 공개 HTTP 서비스를 운영합니다. 각각은 [API Reference](/ko/api-reference) 탭의 그룹으로 문서화되어 있으며, 인터랙티브 플레이그라운드를 지원하는 OpenAPI 스펙을 보유하고 있습니다.

| 서비스                                                                   | 메인넷 호스트                        | 데브넷 호스트                               | 제공 내용                                                        |
| --------------------------------------------------------------------- | ------------------------------ | ------------------------------------- | ------------------------------------------------------------ |
| [API v3](/ko/api-reference/api-v3/overview)                           | `api-v3.raydium.io`            | `api-v3-devnet.raydium.io`            | 정규 풀 / 민트 / 구성 / 체인 정보 읽기 API. UI와 대부분의 통합자를 위한 기본 진입점입니다.   |
| [Transaction API](/ko/api-reference/route-api-v2/overview)            | `transaction-v1.raydium.io`    | `transaction-v1-devnet.raydium.io`    | 서버 측 스왑 트랜잭션 구성입니다.                                          |
| [Perps API](/ko/api-reference/perp-api-v1/overview)                   | `api-perp-v1.raydium.io`       | —                                     | Raydium Perps 프런트엔드용 설정, 자산 메타데이터, RPC 선택입니다.                |
| [LaunchLab Mint API](/ko/api-reference/launch-mint-v1/overview)       | `launch-mint-v1.raydium.io`    | `launch-mint-v1-devnet.raydium.io`    | 토큰 검색, 인덱스, 리더보드, 민트별 메타데이터입니다.                              |
| [LaunchLab History API](/ko/api-reference/launch-history-v1/overview) | `launch-history-v1.raydium.io` | `launch-history-v1-devnet.raydium.io` | LaunchLab 풀의 거래 이력 및 OHLC 캔들스틱 통합입니다.                        |
| [LaunchLab Forum API](/ko/api-reference/launch-forum-v1/overview)     | `launch-forum-v1.raydium.io`   | `launch-forum-v1-devnet.raydium.io`   | LaunchLab 런칭의 댓글 스레드 및 IPFS 업로드입니다. **지갑 서명 필요.**            |
| [LaunchLab Auth API](/ko/api-reference/launch-auth-v1/overview)       | `launch-auth-v1.raydium.io`    | `launch-auth-v1-devnet.raydium.io`    | 지갑 서명 메시지에서 단기 `ray-token` JWT를 발급합니다. Forum에 필수입니다.         |
| [Dynamic IPFS API](/ko/api-reference/dynamic-ipfs-v1/overview)        | `dynamic-ipfs.raydium.io`      | `dynamic-ipfs-devnet.raydium.io`      | 동적 NFT(CLMM 포지션 등)의 이미지 / 메타데이터 재생성입니다.                      |
| [Owner API](/ko/api-reference/owner-api-v1/overview)                  | `owner-v1.raydium.io`          | `owner-v1-devnet.raydium.io`          | 지갑별 포지션, 잔액, 청구 가능한 보상입니다.                                   |
| [API v1 (레거시)](/ko/api-reference/api-v1/overview)                     | `api.raydium.io`               | —                                     | API v3으로 마이그레이션하지 않은 클라이언트를 위해 유지되는 레거시 `/v1` 및 `/v2` 경로입니다. |
| [Temp API](/ko/api-reference/temp-api-v1/overview)                    | `temp-api-v1.raydium.io`       | `temp-api-v1-devnet.raydium.io`       | 단기 맞춤형 엔드포인트의 보관소입니다. **표면이 예고 없이 변경될 수 있습니다.**              |

버전 관리는 v3 / v1 서비스의 **호스트명**에 존재하며, 경로 수준의 추가 버전 관리는 없습니다. 주요 변경 사항은 겹치면서 새로운 호스트로 배포됩니다. 팀은 v3 → v4 마이그레이션 시 최소 6개월의 겹침 기간을 공개적으로 약속했습니다.

## 서비스 선택

| 다음을 원한다면                               | 사용                                                             |
| -------------------------------------- | -------------------------------------------------------------- |
| 풀 메타데이터, 가격, APR, 수수료 구성 읽기            | **API v3**                                                     |
| 민트 메타데이터(이름, 기호, 로고, 소수 자릿수, 위험 태그) 읽기 | **API v3** `/mint/list`, `/mint/price`                         |
| 서버 측에서 스왑 / 유동성 추가 / 유동성 제거 트랜잭션 작성    | **Transaction API**                                            |
| 지갑의 포지션(LP 토큰, CLMM 포지션, 팜 스테이크) 표시    | **Owner API**                                                  |
| LaunchLab 토큰 검색, 리더보드 탐색, 민트별 메타데이터 조회 | **LaunchLab Mint API**                                         |
| LaunchLab 풀의 캔들스틱 차트 렌더링               | **LaunchLab History API**                                      |
| LaunchLab 런칭의 댓글 작성 또는 읽기              | **LaunchLab Auth API** → `ray-token` → **LaunchLab Forum API** |
| CLMM 포지션 NFT 이미지 렌더링                   | **Dynamic IPFS API**                                           |
| Perps UI의 선물 시장 설정 또는 자산 목록 표시         | **Perps API**                                                  |
| v1/v2 경로 접두사 클라이언트와의 호환성 유지            | **API v1 (레거시)**                                               |

## 공통 규칙

### 응답 봉투

IPFS를 제외한 모든 서비스는 동일한 JSON 봉투를 반환합니다:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": true,
  "data":    { ... }
}
```

실패 시:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": false,
  "msg":     "human-readable error string",
  "data":    null
}
```

일부 서비스는 추가로 `error.code` 정수를 포함합니다(API v3는 이를 부 버전 간 안정적인 오류 식별자에 사용). 각 서비스의 개요 페이지에서 정확한 형태를 확인하세요.

### 인증

두 가지 패턴이 있습니다:

* **인증 없음** — Forum을 제외한 모든 서비스. HTTPS를 통해 익명으로 접근합니다.
* **지갑 서명 핸드셰이크** — **LaunchLab Forum API**에 필요합니다. `time:<unix-seconds>` 형식의 Solana ed25519 메시지를 지갑으로 서명하고, 서명과 지갑 주소를 **LaunchLab Auth API** `/request-token`으로 전송하고, JWT를 받아서 이후 포럼 호출 시 `ray-token` 요청 헤더로 전달합니다.

Mintlify 플레이그라운드는 포럼 요청을 보내기 전에 인증 패널에서 `ray-token`을 허용합니다. 이 값은 브라우저에만 저장됩니다.

### 속도 제한

모든 호스트는 Cloudflare 뒤에 있으며 소스 IP별 점진적 속도 제한을 적용합니다. 통합자를 위한 공개 지침:

공개된 제한을 초과하는 버스트는 `Retry-After` 헤더와 함께 `HTTP 429`를 반환합니다. 더 높은 제한이 필요한 수집가나 봇은 공개 호스트를 계속 요청하는 대신 Raydium 팀에 문의해야 합니다. 온체인 프로그램 ID에 대해 자신의 인덱서를 실행하는 것도 읽기 집약적 작업 부하를 위한 옵션입니다.

### 캐싱 및 일관성

* 대부분의 API v3 읽기 엔드포인트는 엣지에서 5\~60초 동안 캐시됩니다. 구체적인 TTL은 각 엔드포인트의 API Reference 페이지에 기록됩니다.
* 캐시는 인덱서가 관찰한 프로그램 접촉 이벤트에 의해 무효화됩니다.
* 대규모 재조직이나 혼잡 중에는 API의 보기와 온체인 상태 사이에 1\~2 슬롯 불일치가 있을 수 있습니다. **SDK와 직접 RPC 읽기가 항상 더 최신입니다** — 클라이언트가 트랜잭션에 서명하려는 경우, 관련 계정을 RPC를 통해 다시 조회하고 API 값을 맹목적으로 신뢰하지 마세요.

### 오류 형식

오류는 HTTP 4xx/5xx로 동일한 봉투(`success: false`, 채워진 `msg`)와 함께 반환됩니다. API v3은 추가로 안정적인 `error.code`를 포함합니다:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": false,
  "msg":     "Pool not found",
  "error":   { "code": 40401, "message": "Pool not found" }
}
```

`error.code`는 부 API 버전 간에 안정적입니다. 클라이언트 로직에서 이를 주요 신호로 취급하고 `msg`를 사람이 읽을 수 있는 표면으로 취급하세요.

### 민트 쌍 인수 규칙

많은 API v3 엔드포인트는 `mint1=…&mint2=…`를 허용하며 `mint1 < mint2`(오름차순 pubkey 바이트 순서)를 요구합니다. 이는 API가 호출자의 선호 인수 순서와 관계없이 동일한 정규 풀을 반환할 수 있도록 하기 위함입니다. URL을 작성하기 전에 클라이언트 측에서 두 민트를 정렬하세요. 엔드포인트별 문서는 [API Reference](/ko/api-reference)에서 이 제약이 적용되는 경우를 반복합니다.

## 권장 클라이언트 패턴

1. **한 번 수화, 게으르게 새로고침.** `GET /main/info`와 `GET /mint/list`(둘 다 API v3)를 앱 로드 시 가져오고 1시간 TTL로 로컬 캐시합니다. 둘 다 엣지 캐시가 많고 거의 변경되지 않습니다.
2. **엔드포인트가 허용하는 곳에서 대량 처리.** `GET /pools/info/ids?ids=…`는 쉼표로 구분된 목록을 허용합니다. 10개의 풀을 10개의 요청이 아닌 1개의 요청으로 가져옵니다.
3. **핫 경로 가격 조회 피하기.** `GET /mint/price`는 UI 렌더링에는 괜찮습니다. 봇에서 이를 루프하지 마세요. 거래 봇의 경우 인덱서를 실행하거나 RPC `programSubscribe` 이벤트를 직접 구독하세요.
4. **높은 처리량을 위해 미러 또는 프록시.** 공개된 속도 제한 상한을 초과하는 모든 항목은 공개 호스트가 아닌 자신의 캐시 계층에서 제공되어야 합니다. `transaction-v1`에 대해 지속적으로 `>120 req/min`을 사용하는 수집가는 자신의 견적 / 경로 엔진을 실행해야 합니다.
5. **서명 전에 다시 조회.** API 응답은 5\~60초 오래될 수 있습니다. 서명 시 실제로 정확한 풀 스냅샷을 얻으려면, SDK 또는 직접 RPC `getMultipleAccounts` 호출을 통해 관련 계정을 다시 읽으세요. API 값을 조회 힌트로 취급하고, 결산 소스로는 취급하지 마세요.
6. **낮은 마찰 통합을 위해 Transaction API 사용.** 클라이언트에서 SDK를 번들로 제공하고 싶지 않다면(모바일 네이티브, 제한된 환경의 봇), Transaction API는 사용자가 서명할 base64 인코딩 버전 트랜잭션을 반환합니다. 반환되는 `swapResponse`는 견적을 포함합니다. 약 30초 동안 유효한 것으로 취급하세요.

## 다음 단계

* **엔드포인트 참조(인터랙티브)** — [API Reference](/ko/api-reference). 모든 서비스에는 자신의 그룹이 있습니다. 매개변수, 응답 형태, 코드 샘플 및 시도 패널을 보려면 엔드포인트를 클릭하세요.
* **TypeScript SDK** — [`sdk-api/typescript-sdk`](/ko/sdk-api/typescript-sdk). SDK는 여러 경로에 대해 내부적으로 API v3를 사용합니다. 트랜잭션 작성의 경우 항상 RPC에서 상태를 다시 조회하며, API를 맹목적으로 신뢰하지 않습니다.
* **Trade API 통합** — [`integration-guides/aggregator`](/ko/integration-guides/aggregator). 다중 DEX 수집가에 Raydium 유동성을 연결하기 위한 패턴입니다.
* **AI 친화적 문서** — [`sdk-api/ai-integration`](/ko/sdk-api/ai-integration). 이 API를 호출해야 하는 AI 코딩 에이전트를 위한 포인터입니다.