openapi: 3.1.0
info:
  title: Ankr Liquid Staking API
  description: |
    The Ankr Liquid Staking RESTful API surfaces staking metrics, the trustless
    exchange ratio, and validator metadata across Ankr's liquid staking tokens
    (ankrETH, ankrBNB, ankrPOL, ankrAVAX, ankrFTM, ankrDOT, etc.). It complements
    the on-chain Smart Contract API exposed on Avalanche, Binance Smart Chain,
    Ethereum, Fantom, and Polygon.
  version: "1.0.0"
  contact:
    name: Ankr
    url: https://www.ankr.com
    email: support@ankr.com
  license:
    name: Ankr Terms of Service
    url: https://www.ankr.com/terms/
servers:
  - url: https://api.staking.ankr.com
    description: Ankr Staking RESTful API.
tags:
  - name: Metrics
    description: Liquid staking pool statistics (TVL, APR, holders, supply).
  - name: Ratio
    description: Trustless exchange ratio between native and liquid staking tokens.
  - name: Validators
    description: Validator metadata, unbond times, reward release windows.
paths:
  /v1.0/metrics:
    get:
      summary: Ankr Get Staking Metrics
      description: Returns Ankr Liquid Staking metrics across all supported tokens.
      operationId: getStakingMetrics
      tags:
        - Metrics
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingMetricsList'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /v1.0/metrics/{token}:
    get:
      summary: Ankr Get Staking Metrics By Token
      description: Returns staking metrics for a single liquid staking token.
      operationId: getStakingMetricsByToken
      tags:
        - Metrics
      parameters:
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingMetrics'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /v1.0/ratio/{token}:
    get:
      summary: Ankr Get Trustless Ratio
      description: Returns the trustless exchange ratio between the native asset and its liquid staking token.
      operationId: getTrustlessRatio
      tags:
        - Ratio
      parameters:
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustlessRatio'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
  /v1.0/validators/{chain}:
    get:
      summary: Ankr Get Validators
      description: Returns Ankr-operated validators on a given chain, including unbond windows and reward release schedules.
      operationId: getValidators
      tags:
        - Validators
      parameters:
        - $ref: '#/components/parameters/Chain'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatorList'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    Token:
      name: token
      in: path
      required: true
      schema:
        type: string
        enum:
          - ankrETH
          - ankrBNB
          - ankrPOL
          - ankrAVAX
          - ankrFTM
          - ankrDOT
          - ankrFLOW
      description: Liquid staking token symbol.
    Chain:
      name: chain
      in: path
      required: true
      schema:
        type: string
        enum:
          - ethereum
          - bsc
          - polygon
          - avalanche
          - fantom
          - polkadot
  schemas:
    StakingMetrics:
      type: object
      properties:
        token:
          type: string
        tvlUsd:
          type: string
        apr:
          type: string
        supply:
          type: string
        holders:
          type: integer
        exchangeRatio:
          type: string
    StakingMetricsList:
      type: array
      items:
        $ref: '#/components/schemas/StakingMetrics'
    TrustlessRatio:
      type: object
      properties:
        token:
          type: string
        ratio:
          type: string
        updatedAt:
          type: string
          format: date-time
    Validator:
      type: object
      properties:
        address:
          type: string
        chain:
          type: string
        active:
          type: boolean
        unbondPeriodSeconds:
          type: integer
        rewardReleaseSeconds:
          type: integer
    ValidatorList:
      type: array
      items:
        $ref: '#/components/schemas/Validator'
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  responses:
    ErrorResponse:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'