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

# Descripción general de la API de Perps

> Servicio de configuración y metadatos para Raydium Perpetual Futures.

<Info>
  **Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.**

  [Ver versión en inglés →](/api-reference/perp-api-v1/overview)
</Info>

## ¿Qué es la API de Perps?

La API de Raydium Perps (V1) es un servicio de configuración y metadatos para la interfaz y las integraciones de Raydium Perpetual Futures. Proporciona:

* **Configuración de UI** – versión actual, soporte de versión mínima
* **Puntos finales RPC** – puntos finales RPC de Solana incluidos en la lista blanca para la UI
* **Estadísticas de mercado** – volumen de trading y interés abierto de 24h/7d/30d
* **Restricciones regionales** – comprobaciones de disponibilidad por país
* **Metadatos de pools** – mercados perp activos y datos de volumen
* **Datos de campañas** – tabla de posiciones, estadísticas de usuario y recompensas
* **Intercambio de P\&L** – generar capturas de pantalla de posiciones compartibles

**Importante**: La colocación de órdenes en sí es manejada por la API de Orderly Network. Este servicio se enfoca en el soporte de la interfaz y metadatos.

## Descripción general de la arquitectura

El sistema de Perps consta de dos componentes independientes:

1. **API de Raydium Perp (este servicio)** – Lee configuración, proporciona datos de UI, genera imágenes
2. **Orderly Network** – Ejecuta órdenes, gestiona posiciones y liquidación

Cuando un usuario coloca una orden perp a través de la UI de Raydium:

1. La UI obtiene la configuración del mercado de esta API (pools, RPCs, disponibilidad)
2. La UI envía la orden a la API de Orderly Network
3. Orderly ejecuta la orden y mantiene el estado de la posición
4. La UI recupera los datos de posición y estadísticas de la API de Orderly o nuestro punto final de campaña

Esta separación permite que Raydium gestione metadatos y marca mientras que Orderly maneja el trabajo pesado de emparejamiento de órdenes y liquidación.

## Puntos finales de API por categoría

### Puntos finales principales

Información del servicio principal y comprobaciones de disponibilidad.

#### `GET /main/version`

Devuelve la versión estable actual de la UI y la versión mínima admitida.

**Uso**: Comprueba si la versión de la UI del cliente todavía es compatible.

**Respuesta**:

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

#### `GET /main/rpcs`

Devuelve los puntos finales RPC de Solana incluidos en la lista blanca para que los use la UI.

**Uso**: Rellena el selector de RPC en la UI; asegura que los clientes se conecten a puntos finales estables y aprobados por Raydium.

#### `GET /main/info`

Devuelve estadísticas de mercado general.

**Uso**: Muestra volumen de 24h, volumen de 7d, volumen de 30d e interés abierto total/long/short en el panel.

**Respuesta**:

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

Comprueba si el trading de perp está disponible en la región del usuario.

**Uso**: Advierte o restringe el acceso en regiones restringidas (p. ej., EE. UU.).

**Cómo funciona**:

* Lee el encabezado `cf-ipcountry` de Cloudflare (si está detrás de Cloudflare)
* Vuelve a una configuración predeterminada si el encabezado está ausente
* Devuelve el estado de disponibilidad por región

**Respuesta**:

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

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

Genera un par de claves Ed25519 temporal para autenticación inicial o firma temporal.

**Uso**: Generación de claves temporales sin custodia para ciertos flujos de autenticación.

**Respuesta**:

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

### Puntos finales de Pool

Configuración del mercado de futuros.

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

Devuelve una lista de mercados perp predeterminados con volumen de 24h/7d/30d.

**Uso**: Rellena el selector de mercado o widget de panel con pares perp disponibles.

**Respuesta**:

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

### Puntos finales de campaña

Tabla de posiciones, estadísticas de usuario y datos de recompensas.

#### `GET /campaign/configs`

Devuelve parámetros de campaña activos y reglas.

**Uso**: Muestra términos de campaña y requisitos de participación en la UI.

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

Devuelve las estadísticas de campaña de un usuario (volumen, P\&L, puntuación, recompensas ganadas).

**Uso**: Muestra en el perfil o panel de control de la cuenta del usuario.

**Respuesta** (usuario sin historial por defecto con datos en cero):

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

Devuelve la tabla de posiciones para un índice de campaña dado (paginado).

**Uso**: Muestra los mejores traders y clasificaciones.

**Respuesta**:

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

### Puntos finales de intercambio

Genera capturas de pantalla de posiciones compartibles.

#### `POST /share/position`

Genera una imagen compartible de la posición perp actual del usuario.

**Uso**: Intercambio social (Twitter, Discord) de posiciones activas.

**Solicitud**:

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

**Respuesta**:

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

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

Genera una imagen compartible de una posición cerrada con P\&L realizado.

**Uso**: Comparte operaciones cerradas con detalles de ganancia/pérdida.

**Solicitud**:

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

**Respuesta**: Igual que `/share/position`.

## Envolvente de respuesta

Todos los puntos finales devuelven una envolvente estándar:

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

En caso de error:

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

## Almacenamiento en caché

La mayoría de los puntos finales devuelven un encabezado `cache-control: max-age=60`, lo que significa:

* Los resultados se almacenan en caché del lado del servidor y se actualizan cada 60 segundos
* Los clientes también pueden almacenar en caché durante 60 segundos para reducir la carga
* Los datos en tiempo real no están garantizados; espera 0-60 segundos de antigüedad

## Disponibilidad regional

Las restricciones regionales se manejan a través del encabezado `cf-ipcountry` (Cloudflare). Las regiones admitidas y las restricciones se configuran del lado del servidor y se actualizan periódicamente.

## Puntos finales de red

| Entorno    | Host                     |
| ---------- | ------------------------ |
| Producción | `api-perp-v1.raydium.io` |

No hay versión de devnet disponible; el trading de perp es solo para mainnet.

## Integración con Orderly Network

Para colocar una orden:

1. Llama a `/campaign/user` o `/main/info` para obtener metadatos y mostrarlos al usuario
2. Envía la orden a la **API de Orderly Network** (no a esta API)
3. Orderly devuelve una confirmación de transacción y estado de posición
4. Llama a `/campaign/user` nuevamente más tarde para ver las estadísticas actualizadas

La API de perp de Raydium no maneja la colocación de órdenes; es puramente metadatos y configuración de solo lectura.

## Ver también

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