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

> Configuration and metadata service for Raydium Perpetual Futures.

## What is the Perps API?

The Raydium Perps API (V1) is a configuration and metadata service for the Raydium Perpetual Futures frontend and integrations. It provides:

* **UI configuration** – current version, minimum version support
* **RPC endpoints** – whitelisted Solana RPC endpoints for the UI
* **Market statistics** – 24h/7d/30d trading volume and open interest
* **Regional restrictions** – per-country availability checks
* **Pool metadata** – active perp markets and volume data
* **Campaign data** – leaderboard, user stats, and rewards
* **P\&L sharing** – generate shareable position screenshots

**Important**: Order placement itself is handled by Orderly Network's API. This service focuses on frontend support and metadata.

## Architecture Overview

The Perps system consists of two independent components:

1. **Raydium Perp API (this service)** – Reads configuration, provides UI data, generates images
2. **Orderly Network** – Executes orders, manages positions, and settlement

When a user places a perp order through the Raydium UI:

1. The UI fetches market configuration from this API (pools, RPCs, availability)
2. The UI sends the order to Orderly Network's API
3. Orderly executes the order and maintains position state
4. The UI retrieves position data and stats from Orderly's API or our campaign endpoint

This separation allows Raydium to manage metadata and branding while Orderly handles the heavy lifting of order matching and settlement.

## API Endpoints by Category

### Main Endpoints

Core service information and availability checks.

#### `GET /main/version`

Returns current stable UI version and minimum supported version.

**Use**: Check if the client's UI version is still supported.

**Response**:

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

#### `GET /main/rpcs`

Returns whitelisted Solana RPC endpoints for the UI to use.

**Use**: Populate RPC selector in the UI; ensures clients connect to stable, Raydium-approved endpoints.

#### `GET /main/info`

Returns market-wide statistics.

**Use**: Display 24h volume, 7d volume, 30d volume, and total/long/short open interest on the 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`

Checks if perp trading is available in the user's region.

**Use**: Warn or restrict access in restricted regions (e.g., USA).

**How it works**:

* Reads the `cf-ipcountry` header from Cloudflare (if behind Cloudflare)
* Falls back to a default config if the header is absent
* Returns availability status per region

**Response**:

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

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

Generates a temporary Ed25519 keypair for initial authentication or temporary signing.

**Use**: Non-custodial temporary key generation for certain auth flows.

**Response**:

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

### Pool Endpoints

Perpetual market configuration.

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

Returns list of default perp markets with 24h/7d/30d volume.

**Use**: Populate market selector or dashboard widget with available perp pairs.

**Response**:

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

### Campaign Endpoints

Leaderboard, user stats, and reward data.

#### `GET /campaign/configs`

Returns active campaign parameters and rules.

**Use**: Display campaign terms and participation requirements in the UI.

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

Returns a user's campaign stats (volume, P\&L, score, earned rewards).

**Use**: Display in user's profile or account dashboard.

**Response** (user with no history defaults to zeroed data):

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

Returns leaderboard for a given campaign index (paginated).

**Use**: Display top traders and rankings.

**Response**:

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

### Share Endpoints

Generate shareable position screenshots.

#### `POST /share/position`

Generates a shareable image of the user's current perp position.

**Use**: Social sharing (Twitter, Discord) of live positions.

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

Generates a shareable image of a closed position with realized P\&L.

**Use**: Share closed trades with profit/loss details.

**Request**:

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

**Response**: Same as `/share/position`.

## Response Envelope

All endpoints return a standard envelope:

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

On error:

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

## Caching

Most endpoints return a `cache-control: max-age=60` header, meaning:

* Results are cached server-side and updated every 60 seconds
* Clients may also cache for 60 seconds to reduce load
* Real-time data is not guaranteed; expect 0–60 second staleness

## Regional Availability

Regional restrictions are handled via the `cf-ipcountry` header (Cloudflare). Supported regions and restrictions are configured server-side and updated periodically.

## Network Endpoints

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

No devnet version is available; perp trading is mainnet-only.

## Integration with Orderly Network

To place an order:

1. Call `/campaign/user` or `/main/info` to fetch metadata and display to the user
2. Send the order to **Orderly Network's API** (not this API)
3. Orderly returns a trade confirmation and position state
4. Call `/campaign/user` again later to see updated stats

Raydium's perp API does not handle order placement; it is purely read-only metadata and configuration.

## See Also

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