List

GET /stake-pools

status: stable

List all known stake pools ordered by descending non_myopic_member_rewards. The non_myopic_member_rewards — and thus the ordering — depends on the ?stake query parameter.

Some pools may also have metadata attached to them.

Query parameters

  • stake integer Required

    The stake the user intends to delegate in Lovelace. Required.

    Minimum value is 0, maximum value is 45000000000000000.

Responses

  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • message string Required

      May occur when an endpoint requires the presence of a query parameter that is missing.

    • code string Required

      Value is query_param_missing.

  • 200 application/json

    Ok

    Hide response attributes Show response attributes object
    • id string(hex|bech32) Required

      A unique identifier for the pool.

    • metrics object Required
      Hide metrics attributes Show metrics attributes object
      • The rewards the wallet can expect to receive at the end of an epoch, in the long term, if delegating to this pool.

        For more details, see the Design Specification for Delegation and Incentives in Cardano document.

        Hide non_myopic_member_rewards attributes Show non_myopic_member_rewards attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is lovelace.

      • relative_stake object Required

        The live pool stake relative to the total stake.

        For more details, see the section "Relative Stake: Active vs Total" in Design Specification for Delegation and Incentives in Cardano.

        Hide relative_stake attributes Show relative_stake attributes object
        • quantity number Required

          Minimum value is 0, maximum value is 100.

        • unit string Required

          Value is percent.

      • saturation number Required

        Saturation-level of the pool based on the desired number of pools aimed by the network. A value above 1 indicates that the pool is saturated.

        The non_myopic_member_rewards take oversaturation into account, as specified by the specs.

        The saturation is based on the live relative_stake. The saturation at the end of epoch e, will affect the rewards paid out at the end of epoch e+3.

        Minimum value is 0.

      • produced_blocks object Required

        Number of blocks produced by a given stake pool in its lifetime.

        Hide produced_blocks attributes Show produced_blocks attributes object
        • quantity integer Required

          Minimum value is 0.

        • unit string Required

          Value is block.

    • cost object Required

      Estimated cost set by the pool operator when registering his pool. This fixed cost is taken from each reward earned by the pool before splitting rewards between stakeholders.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

      Hide cost attributes Show cost attributes object
      • quantity integer Required

        Minimum value is 0.

      • unit string Required

        Value is lovelace.

    • margin object Required

      Variable margin on the total reward given to an operator before splitting rewards between stakeholders.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

      Hide margin attributes Show margin attributes object
      • quantity number Required

        Minimum value is 0, maximum value is 100.

      • unit string Required

        Value is percent.

    • pledge object Required

      Minimal stake amount that a stake pool is willing to honor.

      May be omitted if the wallet hasn't found the pool's registration cerificate yet.

      Hide pledge attributes Show pledge attributes object
      • quantity integer Required

        Minimum value is 0.

      • unit string Required

        Value is lovelace.

    • metadata object

      Information about the stake pool.

      Hide metadata attributes Show metadata attributes object
    • The epoch in which a stake pool retires.

      May be omitted if the wallet hasn't yet found a retirement certificate for this stake pool.

      Hide retirement attributes Show retirement attributes object
      • epoch_number integer Required

        An epoch is a time period which is divided into slots.

        Minimum value is 0.

      • epoch_start_time string(iso-8601-date-and-time) Required
    • flags array[string] Required

      Various flags applicable to stake pools. Possible flags:

      flag description
      delisted The pool is marked as delisted on a configured SMASH server; metadata for this pool have therefore been dropped.

      Value is delisted.

GET /stake-pools
curl \
 --request GET https://localhost:8090/v2/stake-pools?stake=42
Response examples (400)
{
  "message": "string",
  "code": "query_param_missing"
}
Response examples (200)
[
  {
    "id": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm",
    "metrics": {
      "non_myopic_member_rewards": {
        "quantity": 42000000,
        "unit": "lovelace"
      },
      "relative_stake": {
        "quantity": 42,
        "unit": "percent"
      },
      "saturation": 0.74,
      "produced_blocks": {
        "quantity": 1337,
        "unit": "block"
      }
    },
    "cost": {
      "quantity": 42000000,
      "unit": "lovelace"
    },
    "margin": {
      "quantity": 42,
      "unit": "percent"
    },
    "pledge": {
      "quantity": 42000000,
      "unit": "lovelace"
    },
    "metadata": {
      "ticker": "IOHK",
      "name": "string",
      "description": "string",
      "homepage": "https://iohk.io"
    },
    "retirement": {
      "epoch_number": 14,
      "epoch_start_time": "2019-02-27T14:46:45Z"
    },
    "flags": [
      "delisted"
    ]
  }
]