openapi: 3.0.3
info:
  title: "API de Perps Raydium V1"
  version: 1.0.0
  description: |
    Serviço de configuração e metadados para Raydium Perpetual Futures. Esta API fornece configuração de frontend, disponibilidade de ativos, restrições regionais e endpoints RPC. O placement de ordens é delegado à API do Orderly Network.

    Todos os endpoints retornam um envelope padrão:
    - **Sucesso**: `{ id: string, success: true, data: {...} }`
    - **Erro**: `{ id: string, success: false, msg: string }`
  contact:
    name: Raydium
    url: https://raydium.io

servers:
  - url: https://api-perps-v1.raydium.io
    description: Production

tags:
  - name: Main
    description: "Informações do serviço principal (versão, RPCs, estatísticas, verificação de região)."
  - name: Pool
    description: "Configuração de pool de mercado de perps."
  - name: Campaign
    description: "Dados de campanhas e leaderboard."
  - name: Share
    description: "Endpoints de compartilhamento de posição e P&L."

paths:
  /main/info:
    get:
      summary: "Obter estatísticas do mercado de perps"
      description: "Retorna volume de negociação e juros em aberto de 24h/7d/30d (long/short/total)."
      operationId: getMarketInfo
      tags:
        - Main
      responses:
        "200":
          description: "Informações de mercado recuperadas."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketInfoResponse"

  /pool/default-list:
    get:
      summary: "Obter lista padrão de pools de perps"
      description: "Retorna lista de pools de negociação perpétua padrão com volume e estatísticas."
      operationId: getPoolList
      tags:
        - Pool
      responses:
        "200":
          description: "Lista de pools recuperada."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PoolListResponse"

components:
  schemas:
    VersionResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            latest:
              type: string
              description: "Versão estável atual da UI."
              example: "1.2.0"
            least:
              type: string
              description: "Versão mínima da UI necessária."
              example: "1.0.0"

    RpcListResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            rpcs:
              type: array
              description: "Lista de URLs RPC disponíveis."
              items:
                type: string

    MarketInfoResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            volume:
              type: object
              properties:
                "24h":
                  type: number
                  description: "Volume de negociação de 24 horas."
                "7d":
                  type: number
                  description: "Volume de negociação de 7 dias."
                "30d":
                  type: number
                  description: "Volume de negociação de 30 dias."
            openInterest:
              type: object
              properties:
                long:
                  type: number
                  description: "Total de juros em aberto long."
                short:
                  type: number
                  description: "Total de juros em aberto short."
                all:
                  type: number
                  description: "Juros em aberto combinados."

    AvailabilityResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            available:
              type: boolean
              description: "Se a negociação de perps é permitida na região do usuário."
            country:
              type: string
              description: "Código de país detectado (do header cf-ipcountry)."

    TempKeyResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            key:
              type: string
              description: "Chave pública Ed25519 no formato \"ed25519:<chave-codificada-em-base58>\"."
              example: "ed25519:AAAA..."

    PoolListResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              symbol:
                type: string
                description: "Símbolo do pool (ex: BTC/USDC)."
                example: "BTC/USDC"
              volume24h:
                type: string
                description: "Volume de negociação de 24 horas."
              volume7d:
                type: string
                description: "Volume de negociação de 7 dias."
              volume30d:
                type: string
                description: "Volume de negociação de 30 dias."

    CampaignConfigResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          description: "Objeto de configuração da campanha com regras e parâmetros."

    UserCampaignResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            userInfo:
              type: object
              properties:
                index:
                  type: string
                  description: "Classificação ou posição do leaderboard do usuário."
                walletAddress:
                  type: string
                  description: "Endereço de wallet mascarado."
                volume:
                  type: number
                  description: "Volume de negociação total da campanha."
                pnl:
                  type: number
                  description: "Lucro/perda realizado."
                pnlW:
                  type: number
                  description: "P&L ponderado para pontuação."
                score:
                  type: number
                  description: "Pontuação da campanha."
                rewards:
                  type: array
                  description: "Lista de recompensas obtidas."
                  items:
                    type: object

    LeaderboardResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            updateTime:
              type: integer
              description: "Timestamp da última atualização do leaderboard (ms)."
            rows:
              type: array
              description: "Usuários principais nesta página do leaderboard."
              items:
                type: object
                properties:
                  rank:
                    type: integer
                  wallet:
                    type: string
                  volume:
                    type: number
                  pnl:
                    type: number
                  score:
                    type: number

    SharePositionRequest:
      type: object
      description: "Payload para geração de screenshot de posição atual."
      properties:
        symbol:
          type: string
          example: "BTC/USDC"
        side:
          type: string
          enum: [long, short]
        size:
          type: string
        entryPrice:
          type: string
        markPrice:
          type: string
        pnl:
          type: string
        leverage:
          type: string

    ShareHistoryPositionRequest:
      type: object
      description: "Payload para geração de screenshot de posição fechada."
      properties:
        symbol:
          type: string
          example: "BTC/USDC"
        side:
          type: string
          enum: [long, short]
        size:
          type: string
        entryPrice:
          type: string
        exitPrice:
          type: string
        realizedPnl:
          type: string

    ShareResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            imgFileName:
              type: string
              description: "ID do arquivo de imagem gerado."
            msg:
              type: string
              description: "Mensagem de status."

    ErrorResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
          example: false
        msg:
          type: string
          description: "Mensagem de erro ou código."