openapi: 3.1.0
info:
  title: Idle Finance API
  description: >-
    The Idle Finance REST API provides programmatic access to Best Yield and
    Yield Tranches vault pools, total value locked (TVL) metrics, historical
    yield rates for underlying token addresses, and protocol-level data across
    supported networks (Ethereum, Polygon zkEVM, Optimism). Authentication is
    via Bearer token obtained by request.
  version: 1.0.0
  contact:
    name: Idle Finance Developer Access
    url: https://idlefinance.typeform.com/to/CzRkDH
  termsOfService: https://idle.finance/terms
  license:
    name: Proprietary
    url: https://idle.finance/terms
externalDocs:
  description: Idle Finance Developer Documentation
  url: https://docs.idle.finance/developers/api
servers:
  - url: https://api.idle.finance
    description: Ethereum mainnet endpoint
  - url: https://api-zkevm.idle.finance
    description: Polygon zkEVM endpoint
  - url: https://api-optimism.idle.finance
    description: Optimism endpoint
security:
  - BearerAuth: []
tags:
  - name: Pools
    description: Best Yield and Yield Tranches vault pool data
  - name: TVL
    description: Total value locked metrics per underlying token
  - name: Rates
    description: Historical daily yield rate data for Best Yield vaults
paths:
  /pools:
    get:
      operationId: getPools
      summary: Get all pools
      description: >-
        Retrieves all network pools for Best Yield and Yield Tranches vaults on
        the target network.
      tags:
        - Pools
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Array of pool objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pool'
        '401':
          description: Unauthorized — missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway
  /tvls:
    get:
      operationId: getTVLs
      summary: Get TVL per underlying token
      description: >-
        Returns total value locked (TVL) per underlying token for all vaults on
        the target network.
      tags:
        - TVL
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Map of token address to TVL string value
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  description: TVL value as a decimal string
              example:
                '0x6B175474E89094C44Da98b954EedeAC495271d0F': '15234567.89'
                '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': '8901234.56'
        '401':
          description: Unauthorized — missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway
  /rates/{address}:
    get:
      operationId: getRatesByAddress
      summary: Get historical rates for an underlying token
      description: >-
        Provides historical daily APY/rate data for Best Yield vaults filtered
        by the underlying token address and an optional calendar range.
      tags:
        - Rates
      security:
        - BearerAuth: []
      parameters:
        - name: address
          in: path
          required: true
          description: >-
            Underlying token contract address (e.g. DAI, USDC, USDT, WETH on
            Ethereum).
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
          example: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
        - name: start
          in: query
          required: false
          description: Unix timestamp to filter results from (inclusive).
          schema:
            type: integer
            format: int64
          example: 1672531200
        - name: end
          in: query
          required: false
          description: Unix timestamp to filter results to (inclusive).
          schema:
            type: integer
            format: int64
          example: 1704067200
        - name: isRisk
          in: query
          required: false
          description: >-
            Filter by strategy risk type. true returns risk-adjusted strategy
            data, false returns the default Best Yield strategy data.
          schema:
            type: boolean
          example: false
        - name: frequency
          in: query
          required: false
          description: >-
            Number of seconds between data records. Defaults to 86400 (one
            day).
          schema:
            type: integer
            default: 86400
          example: 86400
        - name: order
          in: query
          required: false
          description: Sort order for results.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          example: asc
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return.
          schema:
            type: integer
            minimum: 1
          example: 30
      responses:
        '200':
          description: Array of historical rate records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RateRecord'
        '400':
          description: Bad Request — invalid address or query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token obtained via https://idlefinance.typeform.com/to/CzRkDH.
        Include as "Authorization: Bearer <token>" on all requests.
  schemas:
    Pool:
      type: object
      description: >-
        Represents a single Best Yield or Yield Tranches vault pool on the
        target network.
      properties:
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Smart contract address of the pool/vault.
          example: '0xc8c64CC8c15D9aa1F4dD40933f3eF742A7c62478'
        name:
          type: string
          description: Human-readable pool name.
          example: 'idleDAIYield'
        token:
          type: string
          description: Underlying token symbol.
          example: 'DAI'
        tokenAddress:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Contract address of the underlying token.
          example: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
        type:
          type: string
          description: Pool/vault type.
          enum:
            - best-yield
            - yield-tranches-senior
            - yield-tranches-junior
          example: 'best-yield'
        apy:
          type: string
          description: Current annualised percentage yield as a decimal string.
          example: '4.52'
        tvl:
          type: string
          description: Total value locked in the pool as a decimal string (USD).
          example: '5234567.89'
        underlying:
          type: array
          description: List of underlying protocol allocations.
          items:
            $ref: '#/components/schemas/UnderlyingAllocation'
      required:
        - address
        - name
        - token
        - tokenAddress
        - type
    UnderlyingAllocation:
      type: object
      description: Allocation of pool assets to an underlying yield protocol.
      properties:
        protocol:
          type: string
          description: Name of the underlying protocol.
          example: 'Aave'
        allocation:
          type: string
          description: Percentage allocation as a decimal string.
          example: '62.5'
        apy:
          type: string
          description: APY from this protocol as a decimal string.
          example: '3.91'
    RateRecord:
      type: object
      description: Historical daily APY/rate record for a Best Yield vault.
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the record.
          example: 1704067200
        date:
          type: string
          format: date
          description: ISO 8601 date string corresponding to the record.
          example: '2024-01-01'
        apy:
          type: string
          description: Annualised percentage yield at the given timestamp.
          example: '4.12'
        tvl:
          type: string
          description: Total value locked at the given timestamp (USD).
          example: '5001234.00'
      required:
        - timestamp
        - apy
    Error:
      type: object
      description: Standard error response.
      properties:
        error:
          type: string
          description: Short error code or message.
          example: 'Unauthorized'
        message:
          type: string
          description: Detailed error description.
          example: 'A valid Bearer token is required.'
      required:
        - error