Visão Geral da API Perps

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

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:

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

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

A UI busca configuração de mercado desta API (pools, RPCs, disponibilidade)
A UI envia a ordem para a API da Orderly Network
Orderly executa a ordem e mantém o estado da posição
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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

{
  "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. 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:

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

Resposta:

{
  "id": "...",
  "success": true,
  "data": {
    "imgFileName": "abc123def456",
    "msg": "Position image generated"
  }
}

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:

{
  "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:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "data": { ... }
}

Em caso de erro:

{
  "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:

Chame /campaign/user ou /main/info para buscar metadados e exibir ao usuário
Envie a ordem para API da Orderly Network (não para esta API)
Orderly retorna uma confirmação de trade e estado da posição
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.

Overview

API v3

Transaction API

Perps API

LaunchLab APIs

Dynamic IPFS API

Owner API

API v1

Temp API

Visão Geral da API Perps

O que é a API Perps?

Visão Geral da Arquitetura

Endpoints de API por Categoria

Endpoints Principais

`GET /main/version`

`GET /main/rpcs`

`GET /main/info`

`GET /main/availability-check`

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

Endpoints de Pool

`GET /pool/default-list`

Endpoints de Campanha

`GET /campaign/configs`

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

`GET /campaign/list?index=0`

Endpoints de Compartilhamento

Envelope de Resposta

Cache

Disponibilidade Regional

Endpoints de Rede

Integração com Orderly Network

Veja Também

Overview

API v3

Transaction API

Perps API

LaunchLab APIs

Dynamic IPFS API

Owner API

API v1

Temp API

Documentation Index

​O que é a API Perps?

​Visão Geral da Arquitetura

​Endpoints de API por Categoria

​Endpoints Principais

​GET /main/version

​GET /main/rpcs

​GET /main/info

​GET /main/availability-check

​GET /main/temp-key?wallet=...

​Endpoints de Pool

​GET /pool/default-list

​Endpoints de Campanha

​GET /campaign/configs

​GET /campaign/user?wallet=...&index=0

​GET /campaign/list?index=0

​Endpoints de Compartilhamento

​POST /share/position

​POST /share/history-position

​Envelope de Resposta

​Cache

​Disponibilidade Regional

​Endpoints de Rede

​Integração com Orderly Network

​Veja Também

O que é a API Perps?

Visão Geral da Arquitetura

Endpoints de API por Categoria

Endpoints Principais

`GET /main/version`

`GET /main/rpcs`

`GET /main/info`

`GET /main/availability-check`

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

Endpoints de Pool

`GET /pool/default-list`

Endpoints de Campanha

`GET /campaign/configs`

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

`GET /campaign/list?index=0`

Endpoints de Compartilhamento

`POST /share/position`

`POST /share/history-position`

Envelope de Resposta

Cache

Disponibilidade Regional

Endpoints de Rede

Integração com Orderly Network

Veja Também