Hands-On for Beginners

API Key

If you have not already done so, check out the Quick Start Guide to learn how to get your API Key

With an API Key in hand, the power of the Staking Data API lies before you. But perhaps terms like JSON or GraphQL still feel like jargon, or worse, instill a sense of fear inside of you.

Fear not!

This section is crafted specially for you, breaking down these concepts in a user-friendly manner. In this section, we will guide you through the labyrinth of tech speak and have you querying data in no time.

API Playground

Designed specifically for those who want to get their hands dirty asap, the Staking Rewards Playground guides you along the 7 Steps from novice to Staking Data Expert.

Try it for yourself

Head over to the Playground now to take your first 7 Steps with the Staking Rewards Staking Data API.

Find more detailed information on each of the queries below.

Step 1

query Step1 {
    assets(limit: 10) {
        id
        slug
        logoUrl
        metrics(where: {metricKeys: ["reward_rate"]}, limit: 1) {
            defaultValue
        }
    }
}

• In the above query, we are querying for 10 assets as can be seen by the limit being set to 10.

isActive

isActive is by default always true, even when you do not include where: {isActive: True} in your query.

• The query retrieves four fields for each asset: id, slug, logoUrl, and metrics.

• The metrics field provides an array of metrics associated with each asset.

showAll Metrics

showAll is by default set to False.
This means that if you query metrics without explicitly including showAll:true you will only receive metrics which are deemed standard; such as reward_rate, price, etc.
For the majority of users we recommend to not use showAll:true to avoid overusing your credits.

• We can specify conditions for the metrics query. In this case, query up to 1 metric limit: 1 with metricKey set to 'reward_rate'.
  metricKeys:["reward_rate"]

• Try this query out yourself in the Playground

Step 2

query Step2 {
    assets(where: { slugs: ["polkadot"] }, limit: 1) {
        id
        slug
        logoUrl
        metrics(
            where: { metricKeys: ["reward_rate"], createdAt_lt: "2023-06-28" }
            limit: 10
            order: { createdAt: desc }
        ) {
            defaultValue
            createdAt
        }
    }
}

• In the above query we are fetching 1 active asset which has the slug polkadot.
  slugs:["polkadot"]

limit

It's a strict requirement to always include a limit. Even if you are explicitly querying for only 1 slug, you still need to set the limit to 1 or higher.

• Similar to Step 1, we are querying 4 fields per asset; id, slug, logoUrl and an array of metrics.

  • In this case we are fetching up to 10 metrics.
    limit:10

• We have stated that the metrics we want returned should have the metricKey equal to reward_rate
  metricKeys:["reward_rate"]

and that the metrics should be created before a certain date
created_at_lt:"2023-06-28"

• The query sorts the metrics by the createdAt time in a descending order order: {createdAt:desc} and the first 10 are returned.

• Each element within the metric array gets returned as an object containing a defaultValue and createdAt timestamp.

• Try this query out yourself in the Playground

Step 3

query Step3 {
    providers( limit: 10) {
        name
        logoUrl
        metrics(where: {metricKeys: ["assets_under_management"]}, limit: 1) {
            defaultValue
        }
    }
}

• This query is very similar to Step 1, but instead of querying an asset we are querying a Provider

Providers

A provider with regards to the API is an entity that offers 1 or more rewardOption across any of our assets.

Reward Options

A Reward Option is a strategy, contract, mechanism, or other that a user can interact with to lock up their tokens and in return receive some sort of value or reward.
An example of a Reward Option is Delegating your ATOM tokens to 1 of our Verified Staking Providers.

• The query fetches up to 10 active Providers.

• For each, we retrieve 3 fields; name, logoUrl, and an array for metrics.

• We are querying for 1 metric which has metricKey equal to assets_under_management.
  where:{metricKeys: ["assets_under_management"]}

• For each element in the metric array we return an object containing the defaultValue.

• Try this query out yourself in the Playground

Step 4

query Step4 {
    providers(
        where: {rewardOptions: {inputAsset: {slugs: ["cosmos"]},}, isVerified: true}
        order: {metricKey_desc: "assets_under_management"}
        limit: 10
    ) {
        slug
        rewardOptions(
          where: {inputAsset: {slugs: ["cosmos"]}}
          limit: 1
        ) {
            metrics(
                where: {metricKeys: ["reward_rate"]}
                limit: 1
            ) {
                defaultValue
            }
        }
    }
}

• The query above fetches Verified Staking Providers which have at least 1 active rewardOption for Cosmos.
  where: {rewardOptions: {inputAsset: {slugs: ["cosmos"]}}, isVerified: true}

• We want to return the 10 Providers which have the highest Assets under Management using the sort functionality..
  order: {metricKey_desc: "assets_under_management"}
limit: 10

VSP AuM

Did you know that the Staking Rewards VSP covers over 50 Providers with combined over $10 Billion in Assets under Management.

• We retrieve 1 active rewardOption for Cosmos per Provider
  rewardOptions: {inputAsset: {slugs: ["cosmos"]}}, limit: 1

• For each rewardOption, get 1 metric with the metricKey equal to reward_rate
  where: {metricKeys: ["reward_rate"]}

• For each metric, retrieve defaultValue.

• Try this query out yourself in the Playground

Step 5

query Step5 {
    rewardOptions(
        where: {
          inputAsset: { slugs: ["ethereum-2-0"] }
          typeKeys: ["liquid-staking"]
        }
        limit: 5
        order: { metricKey_desc: "staked_tokens" }
      ) {
        providers(limit: 1) {
          name
          slug
          logoUrl
          isVerified
        }
        metrics(
          where: {
            metricKeys: [
              "commission"
              "staking_wallets"
              "staked_tokens"
              "reward_rate"
              "staking_share"
              "net_staking_flow_7d"
            ]
          }
          limit: 6
        ) {
          label
          metricKey
          defaultValue
        }
    }
}

• The above query fetches 5 Reward Options which take you can deposit Ethereum into.
  inputAsset: { slugs: ["ethereum-2-0"] }

inputAsset vs outputAsset

An inputAsset is the token that you utilize with a specific rewardOption to earn something in return. For example, if you want earn rewards with Lido, you need to deposit ETH into the Lido Staking Pool.

In contrast, an outputAsset is one which you get as proof of deposit for interacting with the rewardOption. Once you deposit ETH into the Lido Staking Pool, you receive stETH in return. In this case, stETH would be the outputAsset.

New Feature

outputAsset is a brand new feature we are working on and as such, not many reward options have been updated to include it. Keep an eye out though, as this will be a feature you will not want to miss out on.

• This query also specifies that the rewardOptions we want to be returned have the type liquid-staking.
  typeKeys: ["liquid-staking"]

• The reward Options will be returned sorted by how many tokens are staked with them in a descending manner. Meaning, the most popular will be first.
  order: {metricKey_desc: "staked_tokens"}

• For each reward option, we retrieve a single provider, including name, slug, logoUrl and isVerified.

• We get up to 6 metrics for each reward option with keys one of commission, staking_wallets, staked_tokens, reward_rate, staking_share, and net_staking_flow_7d.

• For each metric, we retrieve label, metricKey, and defaultValue.

• Try this query out yourself in the Playground

Step 6

query Step6 {
    rewardOptions(
        where: { providers: { slugs: ["allnodes"] } }
        limit: 5
        order: { metricKey_desc: "reward_rate" }
      ) {
        inputAssets(limit: 1) {
          slug
        }
        metrics(where: { metricKeys: ["reward_rate"] }, limit: 1) {
          defaultValue
        }
        validators(limit: 500) {
          address
          metrics(
            where: {
              metricKeys: [
                "commission"
                "staking_wallets"
                "self_staked_tokens"
                "staked_tokens"
                "reward_rate"
                "staking_share"
                "net_staking_flow_7d"
              ]
            }
            limit: 7
          ) {
            label
            metricKey
            defaultValue
          }
        }
    }
}

• This query fetches up to 5 active reward Options for a provider. In this case we specify we only want reward Options that belong to Allnodes.
  `where: {providers: {slugs: ["allnodes"]}, limit: 5}

• The reward options are sorted by the 'reward_rate' metric in descending order.
  order: {metricKey_desc: "reward_rate"}

• We retrieve a single input asset for each reward option and request only the slug.

slug

The slug is a unique identifer for our assets and providers. It's the same unique identifier you can find in the URL when you go to the asset/provider profile on our website.

• The query gets the defaultValue for one reward_rate metric for each reward option.

defaultvalue

The defaultValue of a metric is the value you see on our website as well as the value that we believe makes the most sense to display for this metric. Some metrics have potential variations, which you can find in the metric field variations.

• We fetch up to 500 active validators and their addresses for each reward option
  validators: {limit: 500

• Get up to 7 metrics for each validator with keys one of commission, staking_wallets, self_staked_tokens, staked_token, reward_rate, staking_share, and net_staking_flow_7d.

• For each metric, we retrieve label, metricKey, and defaultValue.

• Try this query out yourself in the Playground

Step 7

query Step7a {
    metrics(limit: 20) {
        label
        metricKey
        defaultValue
    }
}

• Fetch up to 20 global metrics.

Global metrics

Global Metrics are those which cover the whole crypto ecosystem.
Examples include, combined Market Cap of all Proof of Stake Assets, or USD value of all tokens that are currently being staked across all PoS Ecosystems.

• We can get global metrics by querying the metrics table directly, without filtering for any asset, provider, validator or reward option.

• For each metric, the query above retrieves label, metricKey, and defaultValue.

• Try this query out yourself in the Playground

Run the following query to get the historical values for the global 'net_staking_flow_7d'.
This query can be used for any of the metricKeys that were returned in the query above.

query Step7b{
    {
        metrics(
            where: { metricKeys: ["net_staking_flow_7d"], createdAt_lt: "2023-07-01" }
            limit: 500
            order: { createdAt: desc }
        ) {
            defaultValue
            createdAt
        }
    }
}