> ## 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 永续期货的配置和元数据服务。

<Info>
  **本页内容由 AI 自动翻译，所有内容以英文版本为准。**

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

## Perps API 是什么？

Raydium Perps API（V1）是 Raydium 永续期货前端和集成的配置和元数据服务。它提供：

* **UI 配置** – 当前版本、最低版本支持
* **RPC 端点** – UI 的白名单 Solana RPC 端点
* **市场统计** – 24h/7d/30d 交易量和未平仓利息
* **地区限制** – 按国家/地区提供的可用性检查
* **池元数据** – 活跃的永续合约市场和交易量数据
* **活动数据** – 排行榜、用户统计和奖励
* **P\&L 分享** – 生成可分享的头寸截图

**重要提示**：订单执行本身由 Orderly Network 的 API 处理。该服务专注于前端支持和元数据。

## 架构概览

Perps 系统由两个独立的组件组成：

1. **Raydium Perp 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 读取 `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..."
  }
}
```

### 池端点

永续合约市场配置。

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

返回用户的活动统计（交易量、P\&L、分数、赚取的奖励）。

**用途**：在用户的个人资料或账户仪表板中显示。

**响应**（没有历史记录的用户默认为零数据）：

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

生成已平仓头寸的可分享图像，包含已实现 P\&L。

**用途**：分享具有利润/损失详情的已平仓交易。

**请求**：

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

没有 devnet 版本；永续期货仅在主网上可用。

## 与 Orderly Network 的集成

要放置订单：

1. 调用 `/campaign/user` 或 `/main/info` 来获取元数据并显示给用户
2. 将订单发送到 **Orderly Network 的 API**（不是此 API）
3. Orderly 返回交易确认和头寸状态
4. 稍后再次调用 `/campaign/user` 以查看更新的统计信息

Raydium 的 perp API 不处理订单放置；它完全是只读的元数据和配置。

## 另请参阅

* [OpenAPI 规范](/zh/api-reference/openapi/perp-api-v1.yaml)
* [Raydium 永续期货](/zh/products/perps)
* [Orderly Network](https://orderly.network)