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

# Visão Geral da API Perps

> Serviço de configuração e metadados para Raydium Perpetual Futures.

<Info>
  **Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.**

  [Ver versão em inglês →](/api-reference/perp-api-v1/overview)
</Info>

## O que é a API Perps?

A API Raydium Perps (V1) é um serviço de configuração e metadados para o frontend de Perpetual Futures do Raydium e integrações. Fornece:

* **Configuração de UI** – versão atual, suporte a versão mínima
* **Endpoints RPC** – endpoints RPC Solana da lista de permissões para a UI
* **Estatísticas de mercado** – volume de negociação e open interest em 24h/7d/30d
* **Restrições regionais** – verificações de disponibilidade por país
* **Metadados de pool** – mercados perp ativos e dados de volume
* **Dados de campanha** – leaderboard, estatísticas de usuário e recompensas
* **Compartilhamento de P\&L** – gera capturas de tela de posições compartilháveis

**Importante**: A colocação de ordens em si é tratada pela API da Orderly Network. Este serviço concentra-se no suporte ao frontend e metadados.

## Visão Geral da Arquitetura

O sistema Perps consiste em dois componentes independentes:

1. **API Raydium Perp (este serviço)** – Lê configuração, fornece dados de UI, gera imagens
2. **Orderly Network** – Executa ordens, gerencia posições e liquidação

Quando um usuário coloca uma ordem perp através da UI do Raydium:

1. A UI busca configuração de mercado desta API (pools, RPCs, disponibilidade)
2. A UI envia a ordem para a API da Orderly Network
3. Orderly executa a ordem e mantém o estado da posição
4. A UI recupera dados de posição e estatísticas da API da Orderly ou nosso endpoint de campanha

Esta separação permite ao Raydium gerenciar metadados e branding enquanto Orderly faz o trabalho pesado de correspondência de ordens e liquidação.

## Endpoints de API por Categoria

### Endpoints Principais

Informações de serviço core e verificações de disponibilidade.

#### `GET /main/version`

Retorna a versão estável atual da UI e a versão mínima suportada.

**Uso**: Verificar se a versão da UI do cliente ainda é suportada.

**Resposta**:

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

#### `GET /main/rpcs`

Retorna endpoints RPC Solana da lista de permissões para a UI usar.

**Uso**: Preencher seletor de RPC na UI; garante que clientes se conectem a endpoints estáveis e aprovados pelo Raydium.

#### `GET /main/info`

Retorna estatísticas de mercado amplo.

**Uso**: Exibir volume 24h, volume 7d, volume 30d e open interest total/long/short no dashboard.

**Resposta**:

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

Verifica se a negociação de perp está disponível na região do usuário.

**Uso**: Avisar ou restringir acesso em regiões restritas (ex: EUA).

**Como funciona**:

* Lê o header `cf-ipcountry` do Cloudflare (se atrás do Cloudflare)
* Recua para uma configuração padrão se o header estiver ausente
* Retorna status de disponibilidade por região

**Resposta**:

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

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

Gera um par de chaves Ed25519 temporário para autenticação inicial ou assinatura temporária.

**Uso**: Geração de chave temporária não-custodial para certos fluxos de autenticação.

**Resposta**:

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

### Endpoints de Pool

Configuração de mercado perpétuo.

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

Retorna lista de mercados perp padrão com volume 24h/7d/30d.

**Uso**: Preencher seletor de mercado ou widget do dashboard com pares perp disponíveis.

**Resposta**:

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

### Endpoints de Campanha

Leaderboard, estatísticas de usuário e dados de recompensas.

#### `GET /campaign/configs`

Retorna parâmetros de campanha ativa e regras.

**Uso**: Exibir termos de campanha e requisitos de participação na UI.

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

Retorna estatísticas de campanha de um usuário (volume, P\&L, pontuação, recompensas ganhas).

**Uso**: Exibir no perfil do usuário ou dashboard de conta.

**Resposta** (usuário sem histórico usa padrão de dados zerados):

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

Retorna leaderboard para um índice de campanha dado (paginado).

**Uso**: Exibir principais traders e rankings.

**Resposta**:

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

### Endpoints de Compartilhamento

Gera capturas de tela de posições compartilháveis.

#### `POST /share/position`

Gera uma imagem compartilhável da posição perp atual do usuário.

**Uso**: Compartilhamento em redes sociais (Twitter, Discord) de posições ao vivo.

**Requisição**:

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

**Resposta**:

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

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

Gera uma imagem compartilhável de uma posição fechada com P\&L realizado.

**Uso**: Compartilhar trades fechadas com detalhes de lucro/perda.

**Requisição**:

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

**Resposta**: Igual a `/share/position`.

## Envelope de Resposta

Todos os endpoints retornam um envelope padrão:

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

Em caso de erro:

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

## Cache

A maioria dos endpoints retorna um header `cache-control: max-age=60`, significando:

* Resultados são cacheados no servidor e atualizados a cada 60 segundos
* Clientes também podem cachear por 60 segundos para reduzir carga
* Dados em tempo real não são garantidos; espere staleness de 0–60 segundos

## Disponibilidade Regional

Restrições regionais são tratadas via header `cf-ipcountry` (Cloudflare). Regiões suportadas e restrições são configuradas no servidor e atualizadas periodicamente.

## Endpoints de Rede

| Ambiente | Host                     |
| -------- | ------------------------ |
| Produção | `api-perp-v1.raydium.io` |

Nenhuma versão devnet está disponível; negociação perp é apenas mainnet.

## Integração com Orderly Network

Para colocar uma ordem:

1. Chame `/campaign/user` ou `/main/info` para buscar metadados e exibir ao usuário
2. Envie a ordem para **API da Orderly Network** (não para esta API)
3. Orderly retorna uma confirmação de trade e estado da posição
4. Chame `/campaign/user` novamente depois para ver estatísticas atualizadas

A API perp do Raydium não trata colocação de ordens; é puramente metadados e configuração somente leitura.

## Veja Também

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