openapi: 3.0.0
info:
  title: Pendle V2 API Docs Assets Dashboard API
  description: "\n## Terms used in the documentation/API\n\nBelow are some terms used in the documentation/API:\n\n- Pendle Assets/Tokens: PT, YT, LP, SY\n- Non-Pendle Assets: other tokens that are not Pendle assets, such as USDC, USDT, DAI, etc.\n- Asset ID/Token Id: Is the combination of chain id and token address, e.g. 1-0x5fe30ac5cb1abb0e44cdffb2916c254aeb368650\n- Computing unit: Cost of an API call, this is use to rate limit the API calls. More on it at [our document](https://docs.pendle.finance/pendle-v2/Developers/Backend/ApiOverview#rate-limiting)\n- APY/APR/ROI Format: All APY, APR, and ROI values are returned as decimals. For example, 0.5 means 50%, 0.05 means 5%, 1.2 means 120%\n- Percentage Change Format: All percentage change values (e.g., 24h changes) are returned as decimals. For example, 0.05 means 5% change\n- Logarithmic Values: Some fields like `lnImpliedRate` are natural logarithms. To get the actual rate, use e^(value)\n\n## Recommended way to fetch data\n\nWe have a lot of markets, if you call an API for each market, it will be very slow and you will likely get rate limited. Therefore, in some APIs we support fetch all data at once (example the get all markets data, get all assets data/prices), you could use that to fetch all data at once. They also support filter by asset id, type, so if you don't want to fetch, you can filter it down to the specific ones you want.\n\nFor detailed documentation, visit:\n\n[https://docs.pendle.finance/pendle-v2/Developers/Backend/ApiOverview](https://docs.pendle.finance/pendle-v2/Developers/Backend/ApiOverview)\n\n## Support\n\n- We have a telegram for developers to ask about the API at [https://t.me/peepo_the_engineer_bot](https://t.me/peepo_the_engineer_bot)\n- We have an announcement channel for API updates at [https://t.me/pendledevelopers](https://t.me/pendledevelopers), follow it to get the latest updates on the API.\n\n## FAQ\n\n- How to fetch prices for assets?\n  * Use [Get asset prices by IDs](#tag/assets/get/v1/prices/assets)\n\n- What if i want real time prices?\n  * Price in our systems are calculate every 15 seconds. However, if you want real time prices, use [Swapping price](#tag/sdk/get/v1/sdk/{chainId}/markets/{market}/swapping-prices), it return price for PT/YT when swapping with underlying token and vice versa, we don't have real time prices for other assets.\n\n- Can i use the SDK to get price, instead of using the `swapping-price` endpoint?\n  * **Don't use the SDK to get price**, we don't recommend it. SDK endpoints are designed for you to get the calldata for **sending transaction**, not for getting the price. Also, SDK endpoints are very costly and will get rate limited easily if you use it to get price of many tokens. \n\n- How to get token names, expiries, etc?\n  * Use [Get asset metadata by IDs](#tag/assets/get/v1/assets/all)\n\n- Do you have historical data, breakdown to minutes?\n  * No we don't, all historical data is aggregated to hourly/daily/weekly data.\n"
  version: '1.0'
  contact: {}
servers:
- url: http://127.0.0.1:9000
tags:
- name: Dashboard
paths:
  /v1/dashboard/positions/database/{user}:
    get:
      description: 'Returns a complete snapshot of a user''s Pendle positions across all supported chains, including PT, YT, LP, and SY holdings.


        For each position the response includes token amounts, USD valuations, and claimable interest/reward amounts.


        **Caching**: claimable reward amounts are cached for up to 24 hours. For real-time claimable data, read directly from the reward contracts via RPC.


        Use the `chainId` query parameter to filter results to a specific chain.'
      operationId: DashboardController_getUserPositions
      parameters:
      - name: user
        required: true
        in: path
        schema:
          type: string
      - name: filterUsd
        required: false
        in: query
        description: Minimum USD value threshold to filter positions
        schema:
          example: 0.1
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPositionsCrossChainResponse'
      summary: Get user positions by address
      tags:
      - Dashboard
      x-computing-unit: '4'
      x-retail-api-rank: 6969
  /v1/dashboard/merkle-claimed-rewards/{user}:
    get:
      description: 'Returns the historical record of all merkle rewards that a user has already claimed.


        Useful for displaying claim history in a dashboard or verifying that a specific reward distribution has been collected.'
      operationId: DashboardController_getMerkleClaimedRewards
      parameters:
      - name: user
        required: true
        in: path
        description: Ethereum address of the user
        schema:
          type: string
      responses:
        '200':
          description: List of merkle claimed rewards for the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerkleClaimedRewardsResponse'
      summary: Get all merkle claimed rewards for a user
      tags:
      - Dashboard
      x-computing-unit: '2'
      x-retail-api-rank: 6969
components:
  schemas:
    ClaimTokenAmount:
      type: object
      properties:
        token:
          type: string
          description: Token id
          example: 1-0x123...
        amount:
          type: string
          description: Amount of tokens
          example: '1000000000000000000'
      required:
      - token
      - amount
    MerkleUserCampaignResponse:
      type: object
      properties:
        user:
          type: string
        token:
          type: string
        merkleRoot:
          type: string
        chainId:
          type: number
        assetId:
          type: string
        amount:
          type: string
        toTimestamp:
          format: date-time
          type: string
        fromTimestamp:
          format: date-time
          type: string
      required:
      - user
      - token
      - merkleRoot
      - chainId
      - assetId
      - amount
      - toTimestamp
      - fromTimestamp
    UserPositionsCrossChainResponse:
      type: object
      properties:
        positions:
          description: Array of user positions
          type: array
          items:
            $ref: '#/components/schemas/UserPositionsResponse'
      required:
      - positions
    UserPositionsResponse:
      type: object
      properties:
        chainId:
          type: number
          description: Chain ID
          example: 1
        totalOpen:
          type: number
          description: Total number of open positions
          example: 100
        totalClosed:
          type: number
          description: Total number of closed positions
          example: 100
        totalSy:
          type: number
          description: Total number of SY positions
          example: 100
        openPositions:
          description: Array of user token positions
          type: array
          items:
            $ref: '#/components/schemas/MarketPosition'
        closedPositions:
          description: Array of closed user token positions
          type: array
          items:
            $ref: '#/components/schemas/MarketPosition'
        syPositions:
          description: Array of user SY positions
          type: array
          items:
            $ref: '#/components/schemas/SyPosition'
        updatedAt:
          format: date-time
          type: string
          description: Date time of the last update
          example: '2021-01-01T00:00:00.000Z'
        errorMessage:
          type: string
          description: Error message when there is something wrong
          example: Error message
      required:
      - chainId
      - totalOpen
      - totalClosed
      - totalSy
      - openPositions
      - closedPositions
      - syPositions
      - updatedAt
    CrossPtPosition:
      type: object
      properties:
        spokePt:
          type: string
          description: Spoke PT
          example: 0x123...
        balance:
          type: string
          description: Balance of the position
          example: '1000000000000000000'
      required:
      - spokePt
      - balance
    MarketPosition:
      type: object
      properties:
        marketId:
          type: string
          description: Unique identifier of the market
          example: 1-0xabc...
        pt:
          description: Principal token (PT) position
          allOf:
          - $ref: '#/components/schemas/Position'
        yt:
          description: Yield token (YT) position
          allOf:
          - $ref: '#/components/schemas/Position'
        lp:
          description: Liquidity provider (LP) token position
          allOf:
          - $ref: '#/components/schemas/Position'
        crossPtPositions:
          description: Array of cross PT positions
          type: array
          items:
            $ref: '#/components/schemas/CrossPtPosition'
      required:
      - marketId
      - pt
      - yt
      - lp
      - crossPtPositions
    MerkleClaimedRewardsResponse:
      type: object
      properties:
        claimedRewards:
          description: Array of claimed merkle campaigns
          type: array
          items:
            $ref: '#/components/schemas/MerkleUserCampaignResponse'
      required:
      - claimedRewards
    SyPosition:
      type: object
      properties:
        syId:
          type: string
          description: Unique identifier of the market
          example: 1-0xabc
        balance:
          type: string
          description: Sy token (SY) balance in wei
          example: '1000000000000000000'
        claimTokenAmounts:
          description: Array of claimable rewards
          type: array
          items:
            $ref: '#/components/schemas/ClaimTokenAmount'
      required:
      - syId
      - balance
    Position:
      type: object
      properties:
        balance:
          type: string
          description: Balance of the position
          example: '1000000000000000000'
        activeBalance:
          type: string
          description: Active balance of the position (for LP only)
          example: '1000000000000000000'
        valuation:
          type: number
          description: Valuation of the position in USD
          example: 10
        claimTokenAmounts:
          description: Array of claimable rewards
          type: array
          items:
            $ref: '#/components/schemas/ClaimTokenAmount'
      required:
      - balance
      - valuation