> ## 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 永續期貨的設定與中繼資料服務。

<Info>
  **本頁內容由 AI 自動翻譯，所有內容以英文版本為準。**

  [查看英文版 →](/api-reference/perp-api-v1/overview)
</Info>

## 什麼是永續期貨 API？

Raydium 永續期貨 API (V1) 是為 Raydium 永續期貨前端和整合服務提供的設定與中繼資料服務。它提供：

* **UI 設定** – 當前版本、最低版本支援
* **RPC 端點** – 為 UI 列入白名單的 Solana RPC 端點
* **市場統計** – 24h/7d/30d 交易量和未平倉量
* **地區限制** – 各國可用性檢查
* **流動性池中繼資料** – 活躍永續期貨市場與交易量數據
* **活動數據** – 排行榜、用戶統計和獎勵
* **損益分享** – 生成可分享的持倉截圖

**重要**：訂單執行本身由 Orderly Network 的 API 處理。本服務專注於前端支援與中繼資料。

## 架構概覽

永續期貨系統由兩個獨立的組件組成：

1. **Raydium 永續期貨 API（本服務）** – 讀取設定、提供 UI 數據、生成圖像
2. **Orderly Network** – 執行訂單、管理持倉和清算

當用戶通過 Raydium UI 下達永續期貨訂單時：

1. UI 從本 API 取得市場設定（流動性池、RPC、可用性）
2. UI 將訂單發送至 Orderly Network 的 API
3. Orderly 執行訂單並維護持倉狀態
4. UI 從 Orderly 的 API 或我們的活動端點檢索持倉數據與統計

這種分離允許 Raydium 管理中繼資料和品牌，同時 Orderly 處理訂單撮合和清算的核心工作。

## API 端點按類別

### 主要端點

核心服務資訊與可用性檢查。

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

返回市場範圍的統計資訊。

**用途**：在儀表板上顯示 24h 交易量、7d 交易量、30d 交易量和總/多頭/空頭未平倉量。

**回應**：

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

檢查用戶所在地區是否提供永續期貨交易。

**用途**：警告或限制在受限地區（例如美國）的存取。

**工作方式**：

* 從 Cloudflare（如果在 Cloudflare 後方）讀取 `cf-ipcountry` 標頭
* 如果缺少標頭，則回退到預設設定
* 按地區返回可用性狀態

**回應**：

```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..."
  }
}
```

### 流動性池端點

永續期貨市場設定。

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

返回具有 24h/7d/30d 交易量的預設永續期貨市場清單。

**用途**：使用可用的永續期貨交易對填充市場選擇器或儀表板小部件。

**回應**：

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

### 活動端點

排行榜、用戶統計與獎勵數據。

#### `GET /campaign/configs`

返回活躍活動參數和規則。

**用途**：在 UI 中顯示活動條款和參與要求。

#### `GET /campaign/user?wallet=...&index=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
      }
    ]
  }
}
```

### 分享端點

生成可分享的持倉截圖。

#### `POST /share/position`

生成用戶當前永續期貨持倉的可分享圖像。

**用途**：在社交媒體（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`

生成已平倉持倉（具有已實現損益）的可分享圖像。

**用途**：分享帶有利潤/損失詳情的已平倉交易。

**請求**：

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

**回應**：與 `/share/position` 相同。

## 回應信封

所有端點返回標準信封：

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

沒有開發網版本；永續期貨交易只在主網進行。

## 與 Orderly Network 的整合

要下達訂單：

1. 呼叫 `/campaign/user` 或 `/main/info` 取得中繼資料並顯示給用戶
2. 將訂單發送至 **Orderly Network 的 API**（不是本 API）
3. Orderly 返回交易確認和持倉狀態
4. 稍後再次呼叫 `/campaign/user` 以查看更新的統計

Raydium 的永續期貨 API 不處理訂單執行；它純粹是唯讀的中繼資料和設定。

## 另請參閱

* [OpenAPI 規格](/zh-Hant/api-reference/openapi/perp-api-v1.yaml)
* [Raydium 永續期貨](/zh-Hant/products/perps)
* [Orderly Network](https://orderly.network)