openapi: 3.0.3
info:
  title: Dynamic IPFS API
  description: |
    Regenerates dynamic NFT metadata and images for CLMM positions. Used by dApps to fetch real-time
    position visuals and valuation data, including pool details, amounts, fees, and rewards.

    This service caches position metadata in IPFS and serves computed position state (USD value,
    TVL percentage, unclaimed fees) by position ID. Supports both unlocked and locked positions
    across CLMM and CPMM pool types.
  version: 1.0.0
  contact:
    name: Raydium
    url: https://raydium.io
servers:
  - url: https://dynamic-ipfs.raydium.io
    description: Mainnet
  - url: https://dynamic-ipfs-devnet.raydium.io
    description: Devnet
tags:
  - name: CLMM Position
    description: Retrieve dynamic metadata for Concentrated Liquidity Market Maker positions
  - name: Locked Positions
    description: Retrieve locked position data (CLMM and CPMM)
paths:
  /clmm/position:
    get:
      summary: Get CLMM position metadata
      description: |
        Fetch complete position metadata including pool details, liquidity amounts, unclaimed fees,
        and USD valuation. Returns a dynamic NFT interface object suitable for rendering position visuals.
      operationId: getClmmPosition
      tags:
        - CLMM Position
      parameters:
        - name: id
          in: query
          required: true
          description: Position account public key (base58)
          schema:
            type: string
            example: 4Ygp92zRvl4kCr97V3Zs5xg4k3qX1tN6m8pR2vL9jA1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CLNFTInterface'
        '400':
          description: Invalid position ID
          content:
            text/plain:
              schema:
                type: string
                example: "params error 10001"
        '404':
          description: Position not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Server error
          content:
            text/plain:
              schema:
                type: string

  /lock/clmm/position:
    get:
      summary: Get locked CLMM position metadata
      description: |
        Fetch metadata for a locked CLMM position. Returns position data including lock duration,
        accumulated fees, and current valuation.
      operationId: getLockedClmmPosition
      tags:
        - Locked Positions
      parameters:
        - name: id
          in: query
          required: true
          description: Locked position PDA public key (base58)
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CLNFTInterface'
        '400':
          description: Invalid position ID or owner mismatch
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Position not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Server error
          content:
            text/plain:
              schema:
                type: string

  /lock/cpmm/position:
    get:
      summary: Get locked CPMM position metadata
      description: |
        Fetch metadata for a locked Constant Product Market Maker position. Returns LP token amounts,
        pool share percentage, and claimable fees from locking.
      operationId: getLockedCpmmPosition
      tags:
        - Locked Positions
      parameters:
        - name: id
          in: query
          required: true
          description: Locked CPMM position PDA public key (base58)
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CPNFTInterface'
        '400':
          description: Invalid position ID or owner mismatch
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Position not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Server error
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    CLNFTInterface:
      type: object
      description: Complete CLMM position with pool details and valuation
      properties:
        poolInfo:
          $ref: '#/components/schemas/PoolInfoConcentrated'
        positionInfo:
          $ref: '#/components/schemas/CLPositionInfo'
      required:
        - poolInfo
        - positionInfo

    CPNFTInterface:
      type: object
      description: Complete CPMM locked position with pool details and valuation
      properties:
        poolInfo:
          $ref: '#/components/schemas/PoolInfoCPMM'
        positionInfo:
          $ref: '#/components/schemas/CPPositionInfo'
      required:
        - poolInfo
        - positionInfo

    PoolInfoConcentrated:
      type: object
      description: Concentrated Liquidity Market Maker pool information
      properties:
        id:
          type: string
          description: Pool ID
        programId:
          type: string
          description: Program ID owning the pool
        mintA:
          $ref: '#/components/schemas/MintInfo'
        mintB:
          $ref: '#/components/schemas/MintInfo'
        tvl:
          type: number
          description: Total Value Locked in USD
        rewardDefaultInfos:
          type: array
          description: Reward tokens for this pool
          items:
            $ref: '#/components/schemas/RewardInfo'

    PoolInfoCPMM:
      type: object
      description: Constant Product Market Maker pool information
      properties:
        id:
          type: string
        mintA:
          $ref: '#/components/schemas/MintInfo'
        mintB:
          $ref: '#/components/schemas/MintInfo'
        lpMint:
          $ref: '#/components/schemas/MintInfo'
        lpPrice:
          type: number
          description: LP token price in USD

    MintInfo:
      type: object
      properties:
        address:
          type: string
          description: Token mint address
        decimals:
          type: integer
          description: Token decimals
        symbol:
          type: string
          description: Token symbol

    RewardInfo:
      type: object
      properties:
        mint:
          $ref: '#/components/schemas/MintInfo'

    CLPositionInfo:
      type: object
      description: CLMM position state
      properties:
        tvlPercentage:
          type: number
          description: Position TVL as percentage of pool (0-100)
        usdValue:
          type: number
          description: Position value in USD
        amountA:
          type: number
          description: Token A amount in position
        amountB:
          type: number
          description: Token B amount in position
        unclaimedFee:
          $ref: '#/components/schemas/UnclaimedFeeInfo'
      required:
        - tvlPercentage
        - usdValue
        - amountA
        - amountB
        - unclaimedFee

    CPPositionInfo:
      type: object
      description: CPMM locked position state
      properties:
        tvlPercentage:
          type: number
          description: Pool share as percentage (0-100)
        usdValue:
          type: number
          description: Locked LP value in USD
        amountA:
          type: number
          description: Token A underlying amount
        amountB:
          type: number
          description: Token B underlying amount
        unclaimedFee:
          $ref: '#/components/schemas/CPUnclaimedFeeInfo'
      required:
        - tvlPercentage
        - usdValue
        - amountA
        - amountB
        - unclaimedFee

    UnclaimedFeeInfo:
      type: object
      description: Accumulated but unclaimed fees in CLMM position
      properties:
        amountA:
          type: number
          description: Unclaimed Token A fees
        amountB:
          type: number
          description: Unclaimed Token B fees
        usdFeeValue:
          type: number
          description: Trading fee USD value
        reward:
          type: array
          items:
            type: number
          description: Unclaimed reward amounts per reward token
        usdRewardValue:
          type: number
          description: Reward USD value
        usdValue:
          type: number
          description: Total unclaimed value in USD

    CPUnclaimedFeeInfo:
      type: object
      description: Claimable LP and fees from locked CPMM position
      properties:
        lp:
          type: number
          description: Claimable LP amount
        amountA:
          type: number
          description: Claimable Token A
        amountB:
          type: number
          description: Claimable Token B
        usdValue:
          type: number
          description: Claimable value in USD