openapi: 3.0.3
info:
  title: "Raydium API v3"
  version: "3.0.0"
  description: "The Raydium API v3 provides REST endpoints for querying liquidity pools, mint information, farm details, IDO pools, and chain metadata for the Solana blockchain. Used by wallets, aggregators, and traders to source price feeds, pool data, and routing information."

servers:
  - url: "https://api-v3.raydium.io"
    description: "Production (Mainnet)"
  - url: "https://api-v3-devnet.raydium.io"
    description: "Development (Devnet)"

tags:
  - name: "Main"
    description: "Core API endpoints for chain info, TVL, and configuration"
  - name: "Mint"
    description: "Token mint information and pricing"
  - name: "Pools"
    description: "Liquidity pool info, keys, and historical data"
  - name: "Farms"
    description: "Farm pool information and keys"
  - name: "IDO"
    description: "IDO pool information and keys"

components:
  schemas:
    ApiResponse:
      type: object
      description: "Common response envelope. The `data` field is supplied by each endpoint's response schema via `allOf` and is therefore not declared on the base envelope."
      required:
        - id
        - success
      properties:
        id:
          type: string
          description: "Request ID (UUID)"
        success:
          type: boolean
          description: "Whether the request was successful"
        msg:
          type: string
          description: "Error message if success is false"

    ApiV3MintItem:
      type: object
      properties:
        chainId:
          type: number
        address:
          type: string
        programId:
          type: string
        logoURI:
          type: string
        symbol:
          type: string
        name:
          type: string
        decimals:
          type: number
        tags:
          type: array
          items:
            type: string
        extensions:
          type: object

    MintListResponse:
      type: object
      properties:
        blockList:
          type: array
          items:
            type: string
        mintList:
          type: array
          items:
            $ref: "#/components/schemas/ApiV3MintItem"

    PoolInfoItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        programId:
          type: string
        lpMint:
          type: string
        mint1:
          type: object
        mint2:
          type: object
        tvl:
          type: number
        lpPrice:
          type: number
        farmOngoingCount:
          type: number
        day:
          type: object
        week:
          type: object
        month:
          type: object

    PoolListResponse:
      type: object
      properties:
        count:
          type: number
        data:
          type: array
          items:
            $ref: "#/components/schemas/PoolInfoItem"
        hasNextPage:
          type: boolean

    PoolListV2Response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PoolInfoItem"
        nextPageId:
          type: string
          nullable: true

    FarmInfoItem:
      type: object
      properties:
        id:
          type: string
        lpMint:
          type: string
        rewardMints:
          type: array
          items:
            type: string
        apr:
          type: number

    FarmListResponse:
      type: object
      properties:
        count:
          type: number
        data:
          type: array
          items:
            $ref: "#/components/schemas/FarmInfoItem"
        hasNextPage:
          type: boolean

    LiquidityLineResponse:
      type: object
      properties:
        count:
          type: number
        line:
          type: array
          items:
            type: object

    PositionLineResponse:
      type: object
      properties:
        count:
          type: number
        line:
          type: array
          items:
            type: object

paths:
  /main/info:
    get:
      operationId: getMainInfo
      tags:
        - "Main"
      summary: "Get main statistics"
      description: "Retrieve TVL and 24-hour volume for all Raydium pools. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          tvl:
                            type: number
                          volume24:
                            type: number

  /main/chain-time:
    get:
      operationId: getMainChainTime
      tags:
        - "Main"
      summary: "Get chain time offset"
      description: "Get offset between local UTC time and Solana chain time. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          offset:
                            type: integer

  /main/auto-fee:
    get:
      operationId: getMainAutoFee
      tags:
        - "Main"
      summary: "Get estimated transaction fees"
      description: "Retrieve estimated on-chain costs (lamports). Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object

  /main/stake-pools:
    get:
      operationId: getMainStakePools
      tags:
        - "Main"
      summary: "Get RAY stake pools"
      description: "Retrieve RAY token staking pools. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /main/clmm-config:
    get:
      operationId: getMainClmmConfig
      tags:
        - "Main"
      summary: "Get CLMM pool configurations"
      description: "Retrieve allowed configurations for concentrated liquidity pools. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object

  /main/cpmm-config:
    get:
      operationId: getMainCpmmConfig
      tags:
        - "Main"
      summary: "Get CPMM pool configurations"
      description: "Retrieve allowed configurations for constant-product pools. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object

  /main/clmm-dynamic-config:
    get:
      operationId: getMainClmmDynamicConfig
      tags:
        - "Main"
      summary: "Get CLMM dynamic-fee configurations"
      description: |
        Retrieve the calibrated `DynamicFeeConfig` tiers a new CLMM pool can opt into when
        `enableDynamicFee=true` is passed to `CreateCustomizablePool`. Each entry exposes the
        per-tier parameters (filter period, decay period, reduction factor, dynamic-fee
        control, max volatility accumulator) that govern the volatility-tracking surcharge.
        Cached 60 seconds.
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: "DynamicFeeConfig PDA"
                            index:
                              type: integer
                            filterPeriod:
                              type: integer
                              description: "Seconds; volatility decays toward zero after this window"
                            decayPeriod:
                              type: integer
                              description: "Seconds; full half-life of accumulator decay"
                            reductionFactor:
                              type: integer
                              description: "Per-step decay numerator (denominator = 10000)"
                            maxFeeRateNumerator:
                              type: integer
                              description: "Cap on dynamic-fee surcharge (denominator = 1_000_000)"
                            dynamicFeeControl:
                              type: integer
                              description: "Tick-distance scaling numerator (denominator = 100_000)"

  /main/clmm-limit-order-config:
    get:
      operationId: getMainClmmLimitOrderConfig
      tags:
        - "Main"
      summary: "Get CLMM limit-order configurations"
      description: |
        Retrieve the per-pool limit-order configuration (whether limit orders are enabled,
        the minimum order size, and the keeper public key) for pools that support limit
        orders. Used by SDKs and UIs before calling `OpenLimitOrder`. Cached 60 seconds.
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            poolId:
                              type: string
                            enabled:
                              type: boolean
                            minOrderInputAmount:
                              type: string
                              description: "u64 stringified — minimum input the pool will accept"
                            limitOrderAdmin:
                              type: string
                              description: "Off-chain operational keeper authorized to settle/close orders on behalf of owners"

  /mint/list:
    get:
      operationId: getMintList
      tags:
        - "Mint"
      summary: "Get default mint list"
      description: "Retrieve UI's default mint list with metadata and logos. Cached 60 seconds."
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/MintListResponse"

  /mint/ids:
    get:
      operationId: getMintIds
      tags:
        - "Mint"
      summary: "Get mint info by IDs"
      description: "Retrieve metadata for specific mint addresses. Cached 20 seconds."
      parameters:
        - name: mints
          in: query
          required: true
          schema:
            type: string
          description: "Comma-separated mint addresses"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ApiV3MintItem"

  /mint/price:
    get:
      operationId: getMintPrice
      tags:
        - "Mint"
      summary: "Get mint prices"
      description: "Retrieve current USD prices for mint tokens. Cached 5 seconds."
      parameters:
        - name: mints
          in: query
          required: false
          schema:
            type: string
          description: "Comma-separated mint addresses"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        additionalProperties:
                          type: string

  /pools/info/ids:
    get:
      operationId: getPoolsInfoIds
      tags:
        - "Pools"
      summary: "Get pool info by IDs"
      description: "Retrieve detailed pool information by pool IDs. Cached 60 seconds."
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: "Comma-separated pool IDs"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/PoolInfoItem"

  /pools/info/lps:
    get:
      operationId: getPoolsInfoLps
      tags:
        - "Pools"
      summary: "Get pools by LP mint"
      description: "Retrieve pool info by LP token addresses. Cached 60 seconds."
      parameters:
        - name: lps
          in: query
          required: true
          schema:
            type: string
          description: "Comma-separated LP mint addresses"
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/PoolInfoItem"

  /pools/info/list:
    get:
      operationId: getPoolsInfoList
      tags:
        - "Pools"
      summary: "List pools with pagination"
      deprecated: true
      description: "**Legacy endpoint.** Retrieve paginated pool list with filtering and sorting. Cached 60 seconds. pageSize limited to 1000. Kept live for existing integrations; new integrations should query pools by ID, mint pair, or LP mint via the other `/pools/info/*` endpoints, or use the indexer-backed routing surface in the Transaction API."
      parameters:
        - name: poolType
          in: query
          required: true
          schema:
            type: string
            enum: [all, concentrated, standard, allFarm, concentratedFarm, standardFarm]
        - name: poolSortField
          in: query
          required: true
          schema:
            type: string
            enum: [default, liquidity, volume24h, fee24h, apr24h, volume7d, fee7d, apr7d, volume30d, fee30d, apr30d]
        - name: sortType
          in: query
          required: true
          schema:
            type: string
            enum: [desc, asc]
        - name: pageSize
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 1000
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/PoolListResponse"

  /pools/info/mint:
    get:
      operationId: getPoolsInfoMint
      tags:
        - "Pools"
      summary: "Get pools by token mint"
      description: "Filter pools by one or two token mints. Mint ordering normalized internally. Cached 60 seconds."
      parameters:
        - name: mint1
          in: query
          required: true
          schema:
            type: string
        - name: mint2
          in: query
          required: false
          schema:
            type: string
        - name: poolType
          in: query
          required: true
          schema:
            type: string
            enum: [all, concentrated, standard, allFarm, concentratedFarm, standardFarm]
        - name: poolSortField
          in: query
          required: true
          schema:
            type: string
            enum: [default, liquidity, volume24h, fee24h, apr24h, volume7d, fee7d, apr7d, volume30d, fee30d, apr30d]
        - name: sortType
          in: query
          required: true
          schema:
            type: string
            enum: [desc, asc]
        - name: pageSize
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 1000
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/PoolListResponse"

  /pools/info/list-v2:
    get:
      operationId: getPoolsInfoListV2
      tags:
        - "Pools"
      summary: "List pools with advanced filters (v2)"
      description: "Advanced pool listing with cursor-based pagination. Cached 60–90 seconds."
      parameters:
        - name: poolType
          in: query
          required: false
          schema:
            type: string
            enum: [Concentrated, Standard]
        - name: mintFilter
          in: query
          required: false
          schema:
            type: string
        - name: hasReward
          in: query
          required: false
          schema:
            type: boolean
        - name: sortField
          in: query
          required: false
          schema:
            type: string
            enum: [liquidity, volume24h, fee24h, apr24h, volume7d, fee7d, apr7d, volume30d, fee30d, apr30d]
        - name: sortType
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: size
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 1000
        - name: nextPageId
          in: query
          required: false
          schema:
            type: string
        - name: mint1
          in: query
          required: false
          schema:
            type: string
        - name: mint2
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/PoolListV2Response"

  /pools/key/ids:
    get:
      operationId: getPoolsKeyIds
      tags:
        - "Pools"
      summary: "Get pool on-chain keys"
      description: "Retrieve on-chain account keys for pools. Cached 60 seconds."
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object

  /pools/line/liquidity:
    get:
      operationId: getPoolsLineLiquidity
      tags:
        - "Pools"
      summary: "Get pool liquidity history"
      description: "Retrieve historical TVL data for a pool (up to 30 days). Cached 300 seconds."
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/LiquidityLineResponse"

  /pools/line/position:
    get:
      operationId: getPoolsLinePosition
      tags:
        - "Pools"
      summary: "Get CLMM position history"
      description: "Retrieve historical price and liquidity data for CLMM pools. Cached 30 seconds."
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/PositionLineResponse"

  /farms/info/ids:
    get:
      operationId: getFarmsInfoIds
      tags:
        - "Farms"
      summary: "Get farm info by IDs"
      description: "Retrieve farm pool details by farm IDs. Cached 60 seconds."
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/FarmInfoItem"

  /farms/info/lp:
    get:
      operationId: getFarmsInfoLp
      tags:
        - "Farms"
      summary: "Get farms by LP mint"
      description: "Search for farms by LP token stake address. Paginated. Cached 60 seconds."
      parameters:
        - name: lp
          in: query
          required: true
          schema:
            type: string
        - name: pageSize
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/FarmListResponse"

  /farms/key/ids:
    get:
      operationId: getFarmsKeyIds
      tags:
        - "Farms"
      summary: "Get farm on-chain keys"
      description: "Retrieve on-chain account keys for farms. Cached 60 seconds."
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object

  /ido/key/ids:
    get:
      operationId: getIdoKeyIds
      tags:
        - "IDO"
      summary: "Get IDO pool keys"
      description: "Retrieve on-chain structure for IDO pools. Cached 20 seconds."
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object