openapi: 3.0.3
info:
  title: Raydium Perps API V1
  version: 1.0.0
  description: |
    Configuration and metadata service for Raydium Perpetual Futures. This API provides frontend configuration, asset availability, regional restrictions, and RPC endpoints. Order placement is delegated to Orderly Network's API.

    All endpoints return a standard envelope:
    - **Success**: `{ id: string, success: true, data: {...} }`
    - **Error**: `{ id: string, success: false, msg: string }`
  contact:
    name: Raydium
    url: https://raydium.io

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

tags:
  - name: Main
    description: Core service information (version, RPCs, stats, region check).
  - name: Pool
    description: Perp market pool configuration.
  - name: Campaign
    description: Campaign and leaderboard data.
  - name: Share
    description: Position and P&L sharing endpoints.

paths:
  /main/info:
    get:
      summary: Get perp market statistics
      description: Returns 24h/7d/30d trading volume and open interest (long/short/total).
      operationId: getMarketInfo
      tags:
        - Main
      responses:
        "200":
          description: Market info retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketInfoResponse"

  /pool/default-list:
    get:
      summary: Get default perp pool list
      description: Returns list of default perpetual trading pools with volume and stats.
      operationId: getPoolList
      tags:
        - Pool
      responses:
        "200":
          description: Pool list retrieved.
          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: Current stable UI version.
              example: "1.2.0"
            least:
              type: string
              description: Minimum required UI version.
              example: "1.0.0"

    RpcListResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            rpcs:
              type: array
              description: List of available RPC URLs.
              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: 24-hour trading volume.
                "7d":
                  type: number
                  description: 7-day trading volume.
                "30d":
                  type: number
                  description: 30-day trading volume.
            openInterest:
              type: object
              properties:
                long:
                  type: number
                  description: Total long open interest.
                short:
                  type: number
                  description: Total short open interest.
                all:
                  type: number
                  description: Combined open interest.

    AvailabilityResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            available:
              type: boolean
              description: Whether perp trading is allowed in user region.
            country:
              type: string
              description: Detected country code (from cf-ipcountry header).

    TempKeyResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            key:
              type: string
              description: Ed25519 public key in format "ed25519:<base58-encoded-key>".
              example: "ed25519:AAAA..."

    PoolListResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              symbol:
                type: string
                description: Pool symbol (e.g., BTC/USDC).
                example: "BTC/USDC"
              volume24h:
                type: string
                description: 24-hour trading volume.
              volume7d:
                type: string
                description: 7-day trading volume.
              volume30d:
                type: string
                description: 30-day trading volume.

    CampaignConfigResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          description: Campaign configuration object with rules and parameters.

    UserCampaignResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            userInfo:
              type: object
              properties:
                index:
                  type: string
                  description: User's rank or leaderboard position.
                walletAddress:
                  type: string
                  description: Masked wallet address.
                volume:
                  type: number
                  description: Total campaign trading volume.
                pnl:
                  type: number
                  description: Realized profit/loss.
                pnlW:
                  type: number
                  description: Weighted P&L for scoring.
                score:
                  type: number
                  description: Campaign score.
                rewards:
                  type: array
                  description: List of earned rewards.
                  items:
                    type: object

    LeaderboardResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
        data:
          type: object
          properties:
            updateTime:
              type: integer
              description: Leaderboard last update timestamp (ms).
            rows:
              type: array
              description: Top users on this leaderboard page.
              items:
                type: object
                properties:
                  rank:
                    type: integer
                  wallet:
                    type: string
                  volume:
                    type: number
                  pnl:
                    type: number
                  score:
                    type: number

    SharePositionRequest:
      type: object
      description: Payload for current position screenshot generation.
      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 for closed position screenshot generation.
      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: Generated image file ID.
            msg:
              type: string
              description: Status message.

    ErrorResponse:
      type: object
      properties:
        id:
          type: string
        success:
          type: boolean
          example: false
        msg:
          type: string
          description: Error message or code.