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

# Perps API 개요

> Raydium Perpetual Futures를 위한 구성 및 메타데이터 서비스입니다.

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

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

## Perps API란?

Raydium Perps API (V1)는 Raydium Perpetual Futures 프론트엔드 및 통합을 지원하는 구성 및 메타데이터 서비스입니다. 다음을 제공합니다:

* **UI 구성** – 현재 버전, 최소 버전 지원
* **RPC 엔드포인트** – UI에 허용된 Solana RPC 엔드포인트
* **시장 통계** – 24시간/7일/30일 거래량 및 오픈 이자
* **지역 제한** – 국가별 가용성 확인
* **풀 메타데이터** – 활성 perp 시장 및 거래량 데이터
* **캠페인 데이터** – 리더보드, 사용자 통계 및 보상
* **P\&L 공유** – 공유 가능한 포지션 스크린샷 생성

**중요**: 주문 배치 자체는 Orderly Network의 API에서 처리합니다. 이 서비스는 프론트엔드 지원 및 메타데이터에 중점을 두고 있습니다.

## 아키텍처 개요

Perps 시스템은 두 가지 독립적인 구성요소로 이루어져 있습니다:

1. **Raydium Perp API (본 서비스)** – 구성을 읽고, UI 데이터를 제공하며, 이미지를 생성합니다
2. **Orderly Network** – 주문을 실행하고, 포지션을 관리하며, 결제를 처리합니다

사용자가 Raydium UI를 통해 perp 주문을 배치할 때:

1. UI는 이 API에서 시장 구성을 가져옵니다 (풀, RPC, 가용성)
2. UI는 주문을 Orderly Network의 API로 전송합니다
3. Orderly는 주문을 실행하고 포지션 상태를 유지합니다
4. UI는 Orderly의 API 또는 캠페인 엔드포인트에서 포지션 데이터 및 통계를 검색합니다

이러한 분리를 통해 Raydium은 메타데이터 및 브랜딩을 관리하는 동안 Orderly는 주문 매칭 및 결제의 핵심 업무를 처리합니다.

## 카테고리별 API 엔드포인트

### Main 엔드포인트

핵심 서비스 정보 및 가용성 확인입니다.

#### `GET /main/version`

현재 안정적인 UI 버전 및 최소 지원 버전을 반환합니다.

**사용**: 클라이언트의 UI 버전이 여전히 지원되는지 확인합니다.

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "latest": "1.2.0",
    "least": "1.0.0"
  }
}
```

#### `GET /main/rpcs`

UI에서 사용할 허용된 Solana RPC 엔드포인트를 반환합니다.

**사용**: UI의 RPC 선택기를 채웁니다. 클라이언트가 안정적인 Raydium 승인 엔드포인트에 연결되도록 보장합니다.

#### `GET /main/info`

시장 전체 통계를 반환합니다.

**사용**: 대시보드에 24시간 거래량, 7일 거래량, 30일 거래량 및 총/롱/숏 오픈 이자를 표시합니다.

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "volume": {
      "24h": 1234567,
      "7d": 9876543,
      "30d": 50000000
    },
    "openInterest": {
      "long": 5000000,
      "short": 3000000,
      "all": 8000000
    }
  }
}
```

#### `GET /main/availability-check`

사용자의 지역에서 perp 거래가 가능한지 확인합니다.

**사용**: 제한된 지역 (예: 미국)에서 접근을 경고하거나 제한합니다.

**작동 방식**:

* Cloudflare의 `cf-ipcountry` 헤더를 읽습니다 (Cloudflare 뒤에 있는 경우)
* 헤더가 없으면 기본 구성으로 대체합니다
* 지역별 가용성 상태를 반환합니다

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "available": true,
    "country": "US"
  }
}
```

#### `GET /main/temp-key?wallet=...`

초기 인증 또는 임시 서명을 위한 임시 Ed25519 키페어를 생성합니다.

**사용**: 특정 인증 흐름에 대한 비수탁 임시 키 생성입니다.

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "key": "ed25519:AAAA..."
  }
}
```

### Pool 엔드포인트

Perpetual 시장 구성입니다.

#### `GET /pool/default-list`

24시간/7일/30일 거래량이 포함된 기본 perp 시장 목록을 반환합니다.

**사용**: 시장 선택기 또는 대시보드 위젯을 사용 가능한 perp 쌍으로 채웁니다.

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": [
    {
      "symbol": "BTC/USDC",
      "volume24h": "1000000",
      "volume7d": "7000000",
      "volume30d": "30000000"
    }
  ]
}
```

### Campaign 엔드포인트

리더보드, 사용자 통계 및 보상 데이터입니다.

#### `GET /campaign/configs`

활성 캠페인 매개변수 및 규칙을 반환합니다.

**사용**: UI에서 캠페인 약관 및 참여 요구사항을 표시합니다.

#### `GET /campaign/user?wallet=...&index=0`

사용자의 캠페인 통계 (거래량, P\&L, 점수, 획득한 보상)를 반환합니다.

**사용**: 사용자의 프로필 또는 계정 대시보드에 표시합니다.

**응답** (히스토리가 없는 사용자는 기본적으로 0 데이터):

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "userInfo": {
      "index": "42",
      "walletAddress": "11111...1111",
      "volume": 500000,
      "pnl": 25000,
      "pnlW": 22500,
      "score": 850,
      "rewards": [...]
    }
  }
}
```

#### `GET /campaign/list?index=0`

주어진 캠페인 인덱스에 대한 리더보드를 반환합니다 (페이지 나눔).

**사용**: 상위 거래자 및 순위를 표시합니다.

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "updateTime": 1699999999000,
    "rows": [
      {
        "rank": 1,
        "wallet": "11111...1111",
        "volume": 5000000,
        "pnl": 250000,
        "score": 9500
      }
    ]
  }
}
```

### Share 엔드포인트

공유 가능한 포지션 스크린샷을 생성합니다.

#### `POST /share/position`

사용자의 현재 perp 포지션의 공유 가능한 이미지를 생성합니다.

**사용**: 라이브 포지션의 소셜 공유 (Twitter, Discord).

**요청**:

```json theme={null}
{
  "symbol": "BTC/USDC",
  "side": "long",
  "size": "0.5",
  "entryPrice": "45000",
  "markPrice": "46000",
  "pnl": "500",
  "leverage": "5x"
}
```

**응답**:

```json theme={null}
{
  "id": "...",
  "success": true,
  "data": {
    "imgFileName": "abc123def456",
    "msg": "Position image generated"
  }
}
```

#### `POST /share/history-position`

실현된 P\&L이 포함된 종료된 포지션의 공유 가능한 이미지를 생성합니다.

**사용**: 손익 세부정보가 포함된 종료된 거래를 공유합니다.

**요청**:

```json theme={null}
{
  "symbol": "ETH/USDC",
  "side": "short",
  "size": "10",
  "entryPrice": "2500",
  "exitPrice": "2450",
  "realizedPnl": "500"
}
```

**응답**: `/share/position`과 동일합니다.

## 응답 envelope

모든 엔드포인트는 표준 envelope을 반환합니다:

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

오류 시:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": false,
  "msg": "Error message or code"
}
```

## 캐싱

대부분의 엔드포인트는 `cache-control: max-age=60` 헤더를 반환합니다. 이는 다음을 의미합니다:

* 결과는 서버 측에 캐시되고 60초마다 업데이트됩니다
* 클라이언트도 부하를 줄이기 위해 60초 동안 캐시할 수 있습니다
* 실시간 데이터는 보장되지 않습니다. 0\~60초의 오래된 데이터를 예상하세요

## 지역별 가용성

지역 제한은 `cf-ipcountry` 헤더 (Cloudflare)를 통해 처리됩니다. 지원되는 지역 및 제한 사항은 서버 측에서 구성되고 주기적으로 업데이트됩니다.

## 네트워크 엔드포인트

| 환경   | 호스트                      |
| ---- | ------------------------ |
| 프로덕션 | `api-perp-v1.raydium.io` |

devnet 버전은 없습니다. perp 거래는 mainnet 전용입니다.

## Orderly Network와의 통합

주문을 배치하려면:

1. `/campaign/user` 또는 `/main/info`를 호출하여 메타데이터를 가져오고 사용자에게 표시합니다
2. 주문을 **Orderly Network의 API**로 전송합니다 (본 API 아님)
3. Orderly는 거래 확인 및 포지션 상태를 반환합니다
4. 나중에 `/campaign/user`를 다시 호출하여 업데이트된 통계를 확인합니다

Raydium의 perp API는 주문 배치를 처리하지 않습니다. 순수 읽기 전용 메타데이터 및 구성입니다.

## 참고 자료

* [OpenAPI Specification](/ko/api-reference/openapi/perp-api-v1.yaml)
* [Raydium Perpetual Futures](/ko/products/perps)
* [Orderly Network](https://orderly.network)