openapi: 3.1.0
info:
  title: Liquity Protocol V1 Supply V2 Website Data API
  description: 'The Liquity static JSON API at api.liquity.org covers circulating supplies, protocol stats, stability pool data, prices, governance epochs, yield opportunities, borrow rates, and a points leaderboard. Data is generated on-chain and published as flat files to GitHub Pages. Liquity V1 issues LUSD stablecoin backed by ETH. Liquity V2 (BOLD) supports multi-collateral borrowing with WETH, wstETH, and rETH.

    '
  version: 1.0.0
  contact:
    name: Liquity Team
    url: https://www.liquity.org/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.liquity.org/terms
servers:
- url: https://api.liquity.org
  description: Liquity API (GitHub Pages)
tags:
- name: V2 Website Data
  description: Data feeds for the Liquity website including yield venues, leaderboard, and borrow rates.
paths:
  /v2/website/bold-venues.json:
    get:
      operationId: getBoldYieldVenues
      summary: BOLD Yield Venues
      description: 'Returns an array of yield opportunities for BOLD across DeFi protocols (e.g., Euler, Yearn, Asymmetry). Each entry includes protocol name, asset/vault name, link, weekly APR, total APR range, and TVL.

        '
      tags:
      - V2 Website Data
      responses:
        '200':
          description: List of BOLD yield opportunities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YieldVenue'
              example:
              - protocol: Euler
                asset: BOLD Vault
                link: https://app.euler.finance/vault/0xC1C51C5c9EfaF0c485Aa1097AE9690B5e102975A
                weekly_apr: 0.10333863505351129
                total_apr: 21.5% - 103.1%
                tvl: 148921.61027224179
  /v2/website/fork-venues.json:
    get:
      operationId: getForkVenues
      summary: Fork Venues
      description: Returns data on Liquity protocol fork deployments and venues.
      tags:
      - V2 Website Data
      responses:
        '200':
          description: List of Liquity protocol fork venues.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YieldVenue'
  /v2/website/leaderboard.json:
    get:
      operationId: getPointsLeaderboard
      summary: Points Leaderboard
      description: 'Returns a ranked leaderboard of Ethereum addresses by accumulated Liquity points, including rank, address, points earned, and percentage share. Contains up to 1,900+ entries.

        '
      tags:
      - V2 Website Data
      responses:
        '200':
          description: Points leaderboard with ranked Ethereum addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
              example:
                total_row_count: 1907
                rows:
                - rank: 1
                  address: '0xc83aa8e0da4ffc388fdbfc1cb111d8d625b5b8e7'
                  points: 632014.0793235414
                  percent: 0.05085206108535175
                - rank: 2
                  address: '0xceb63486c7ec2896b399e2d967c567d8c05f673a'
                  points: 451653.63560210326
                  percent: 0.036340200350666235
  /v2/website/borrow-rates.json:
    get:
      operationId: getBorrowRatesComparison
      summary: Borrow Rates Comparison
      description: 'Returns average borrow rate comparison per collateral type (WETH, wstETH, rETH) between Liquity V2 and DeFi-wide averages.

        '
      tags:
      - V2 Website Data
      responses:
        '200':
          description: Borrow rate comparison by collateral type.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BorrowRateComparison'
              example:
              - collateral: WETH
                defi_avg_borrow_rate: 0.04535838926497226
                liquity_avg_borrow_rate: 0.022137661065511436
              - collateral: wstETH
                defi_avg_borrow_rate: 0.039
                liquity_avg_borrow_rate: 0.018
              - collateral: rETH
                defi_avg_borrow_rate: 0.041
                liquity_avg_borrow_rate: 0.019
components:
  schemas:
    BorrowRateComparison:
      type: object
      description: Borrow rate comparison between Liquity V2 and DeFi average for a collateral.
      properties:
        collateral:
          type: string
          description: Collateral token identifier (e.g., WETH, wstETH, rETH).
          example: WETH
        defi_avg_borrow_rate:
          type: number
          format: float
          description: Average borrow rate across DeFi protocols as decimal.
          example: 0.04535838926497226
        liquity_avg_borrow_rate:
          type: number
          format: float
          description: Average borrow rate on Liquity V2 as decimal.
          example: 0.022137661065511436
      required:
      - collateral
      - defi_avg_borrow_rate
      - liquity_avg_borrow_rate
    Leaderboard:
      type: object
      description: Paginated leaderboard of Ethereum addresses by Liquity points.
      properties:
        total_row_count:
          type: integer
          description: Total number of entries in the leaderboard.
          example: 1907
        rows:
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardEntry'
          description: List of leaderboard entries.
      required:
      - total_row_count
      - rows
    LeaderboardEntry:
      type: object
      description: A single entry in the Liquity points leaderboard.
      properties:
        rank:
          type: integer
          description: Leaderboard ranking position.
          example: 1
        address:
          type: string
          description: Ethereum wallet address.
          example: '0xc83aa8e0da4ffc388fdbfc1cb111d8d625b5b8e7'
        points:
          type: number
          description: Total Liquity points accumulated.
          example: 632014.0793235414
        percent:
          type: number
          description: Percentage share of total points (0-1 range).
          example: 0.05085206108535175
      required:
      - rank
      - address
      - points
      - percent
    YieldVenue:
      type: object
      description: A yield opportunity for BOLD in a DeFi protocol.
      properties:
        protocol:
          type: string
          description: Name of the DeFi protocol.
          example: Euler
        asset:
          type: string
          description: Asset or vault identifier.
          example: BOLD Vault
        link:
          type: string
          format: uri
          description: URL to access the yield opportunity.
          example: https://app.euler.finance/vault/0xC1C51C5c9EfaF0c485Aa1097AE9690B5e102975A
        weekly_apr:
          type: number
          description: Weekly annualized percentage rate as decimal.
          example: 0.10333863505351129
        total_apr:
          type: string
          description: Range of total APR as formatted string.
          example: 21.5% - 103.1%
        tvl:
          type: number
          description: Total value locked in USD.
          example: 148921.61027224179
      required:
      - protocol
      - asset
      - link
      - weekly_apr
      - total_apr
      - tvl
externalDocs:
  description: Liquity API GitHub Repository
  url: https://github.com/liquity/api.liquity.org