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

# Gambaran Umum Perps API

> Layanan konfigurasi dan metadata untuk Raydium Perpetual Futures.

<Info>
  **Halaman ini diterjemahkan secara otomatis oleh AI. Versi bahasa Inggris adalah acuan resmi.**

  [Lihat versi bahasa Inggris →](/api-reference/perp-api-v1/overview)
</Info>

## Apa itu Perps API?

Raydium Perps API (V1) adalah layanan konfigurasi dan metadata untuk frontend serta integrasi Raydium Perpetual Futures. API ini menyediakan:

* **Konfigurasi UI** – versi terkini, dukungan versi minimum
* **Endpoint RPC** – endpoint Solana RPC terpilih untuk UI
* **Statistik pasar** – volume perdagangan dan open interest selama 24h/7h/30h
* **Pembatasan regional** – pemeriksaan ketersediaan per negara
* **Metadata pool** – pasar perp aktif dan data volume
* **Data kampanye** – leaderboard, statistik pengguna, dan reward
* **Berbagi P\&L** – menghasilkan tangkapan layar posisi yang dapat dibagikan

**Penting**: Penempatan order itu sendiri ditangani oleh API Orderly Network. Layanan ini fokus pada dukungan frontend dan metadata.

## Gambaran Arsitektur

Sistem Perps terdiri dari dua komponen independen:

1. **Raydium Perp API (layanan ini)** – Membaca konfigurasi, menyediakan data UI, menghasilkan gambar
2. **Orderly Network** – Mengeksekusi order, mengelola posisi, dan settlement

Ketika pengguna menempatkan order perp melalui UI Raydium:

1. UI mengambil konfigurasi pasar dari API ini (pool, RPC, ketersediaan)
2. UI mengirim order ke API Orderly Network
3. Orderly mengeksekusi order dan memelihara status posisi
4. UI mengambil data posisi dan statistik dari API Orderly atau endpoint kampanye kami

Pemisahan ini memungkinkan Raydium mengelola metadata dan branding sementara Orderly menangani pekerjaan berat pencocokan order dan settlement.

## Endpoint API Berdasarkan Kategori

### Endpoint Utama

Informasi layanan inti dan pemeriksaan ketersediaan.

#### `GET /main/version`

Mengembalikan versi UI stabil terkini dan versi minimum yang didukung.

**Penggunaan**: Periksa apakah versi UI klien masih didukung.

**Response**:

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

#### `GET /main/rpcs`

Mengembalikan endpoint RPC Solana terpilih untuk digunakan UI.

**Penggunaan**: Isi pemilih RPC di UI; memastikan klien terhubung ke endpoint yang stabil dan disetujui Raydium.

#### `GET /main/info`

Mengembalikan statistik pasar luas.

**Penggunaan**: Tampilkan volume 24h, 7h, 30h, dan open interest total/long/short di dashboard.

**Response**:

```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`

Memeriksa apakah trading perp tersedia di wilayah pengguna.

**Penggunaan**: Peringatkan atau batasi akses di wilayah yang dibatasi (mis., USA).

**Cara kerjanya**:

* Membaca header `cf-ipcountry` dari Cloudflare (jika berada di belakang Cloudflare)
* Kembali ke konfigurasi default jika header tidak ada
* Mengembalikan status ketersediaan per wilayah

**Response**:

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

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

Menghasilkan keypair Ed25519 sementara untuk autentikasi awal atau penandatanganan sementara.

**Penggunaan**: Pembuatan kunci sementara non-custodial untuk alur otentikasi tertentu.

**Response**:

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

### Endpoint Pool

Konfigurasi pasar perpetual.

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

Mengembalikan daftar pasar perp default dengan volume 24h/7h/30h.

**Penggunaan**: Isi pemilih pasar atau widget dashboard dengan pasangan perp yang tersedia.

**Response**:

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

### Endpoint Kampanye

Leaderboard, statistik pengguna, dan data reward.

#### `GET /campaign/configs`

Mengembalikan parameter dan aturan kampanye aktif.

**Penggunaan**: Tampilkan syarat kampanye dan persyaratan partisipasi di UI.

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

Mengembalikan statistik kampanye pengguna (volume, P\&L, skor, reward yang diperoleh).

**Penggunaan**: Tampilkan di profil pengguna atau dashboard akun.

**Response** (pengguna tanpa riwayat default ke data bernol):

```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`

Mengembalikan leaderboard untuk indeks kampanye tertentu (dipaginasi).

**Penggunaan**: Tampilkan trader teratas dan peringkat.

**Response**:

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

### Endpoint Berbagi

Hasilkan tangkapan layar posisi yang dapat dibagikan.

#### `POST /share/position`

Menghasilkan gambar yang dapat dibagikan dari posisi perp pengguna saat ini.

**Penggunaan**: Berbagi sosial (Twitter, Discord) posisi aktif.

**Request**:

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

**Response**:

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

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

Menghasilkan gambar yang dapat dibagikan dari posisi tertutup dengan P\&L yang direalisasikan.

**Penggunaan**: Bagikan perdagangan tertutup dengan detail profit/loss.

**Request**:

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

**Response**: Sama dengan `/share/position`.

## Envelope Response

Semua endpoint mengembalikan envelope standar:

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

Pada error:

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

## Caching

Sebagian besar endpoint mengembalikan header `cache-control: max-age=60`, yang berarti:

* Hasil di-cache di sisi server dan diperbarui setiap 60 detik
* Klien juga dapat melakukan cache selama 60 detik untuk mengurangi beban
* Data real-time tidak dijamin; harapkan kedaluwarsa 0–60 detik

## Ketersediaan Regional

Pembatasan regional ditangani melalui header `cf-ipcountry` (Cloudflare). Wilayah dan pembatasan yang didukung dikonfigurasi di sisi server dan diperbarui secara berkala.

## Network Endpoints

| Lingkungan | Host                     |
| ---------- | ------------------------ |
| Production | `api-perp-v1.raydium.io` |

Tidak ada versi devnet yang tersedia; trading perp hanya di mainnet.

## Integrasi dengan Orderly Network

Untuk menempatkan order:

1. Panggil `/campaign/user` atau `/main/info` untuk mengambil metadata dan tampilkan kepada pengguna
2. Kirim order ke **API Orderly Network** (bukan API ini)
3. Orderly mengembalikan konfirmasi perdagangan dan status posisi
4. Panggil `/campaign/user` lagi nanti untuk melihat statistik yang diperbarui

API perp Raydium tidak menangani penempatan order; API ini murni read-only untuk metadata dan konfigurasi.

## Lihat Juga

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