A step-by-step guide through the API Playground, building progressively more complex queries from novice to expert level.

Hands-On for Beginners

The power of the Staking Data API lies before you. If terms like JSON or GraphQL seem intimidating, don't worry — this guide will walk you through the labyrinth of tech speak.

The Playground contains seven progressive steps from novice to expert. Each step builds complexity.

Step 1: Query Assets

Query 10 assets with their IDs, slugs, logos, and reward rates.

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

Key concepts:

limit parameter is required on every query level
isActive defaults to true (only active assets are returned)
showAll for metrics defaults to false

Step 2: Historical Reward Rates

Query a specific asset (Polkadot) with historical reward rate metrics, filtered by creation date and ordered chronologically.

{
  assets(where: { slugs: ["polkadot"] }, limit: 1) {
    name
    metrics(
      where: { metricKeys: ["reward_rate"], createdAt_lt: "2023-06-01" }
      order: { createdAt: asc }
      limit: 10
    ) {
      defaultValue
      createdAt
    }
  }
}

This introduces:

slugs parameter for filtering specific assets
Historical data queries with createdAt_lt (created at less than)
Ordering results with order parameter

Step 3: Query Providers

Query providers instead of assets, fetching assets under management metrics.

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

Key terms:

Provider = entity offering one or more reward options
Reward Option = strategy/mechanism for locking tokens to earn rewards (example: delegating ATOM to a validator)

Step 4: Verified Staking Providers

Query verified staking providers for Cosmos with highest AUM, including nested reward option metrics.

{
  providers(
    where: { isVerified: true }
    order: { metricKey_desc: "assets_under_management" }
    limit: 10
  ) {
    name
    metrics(where: { metricKeys: ["assets_under_management"] }, limit: 1) {
      defaultValue
    }
    rewardOptions(
      where: { inputAsset: { slugs: ["cosmos"] } }
      limit: 5
    ) {
      metrics(where: { metricKeys: ["staked_tokens"] }, limit: 1) {
        defaultValue
      }
    }
  }
}

The VSP (Verified Staking Provider) program covers over 50 Providers with combined over $10 Billion in Assets under Management.

Step 5: Liquid Staking Reward Options

Query liquid-staking reward options for Ethereum 2.0, retrieving provider details and multiple metrics.

{
  rewardOptions(
    where: {
      inputAsset: { slugs: ["ethereum-2-0"] }
      typeKeys: ["liquid-staking"]
    }
    limit: 10
  ) {
    providers(limit: 1) {
      name
    }
    metrics(
      where: {
        metricKeys: [
          "commission"
          "staking_wallets"
          "staked_tokens"
          "reward_rate"
          "staking_share"
          "net_staking_flow_7d"
        ]
      }
      limit: 10
    ) {
      metricKey
      defaultValue
    }
  }
}

Input vs Output Assets:

inputAsset = token deposited (e.g., ETH)
outputAsset = proof of deposit received (e.g., stETH)

Step 6: Provider Reward Options with Validators

Query a specific provider's reward options with associated validators and their comprehensive metrics.

{
  providers(where: { slugs: ["allnodes"] }, limit: 1) {
    name
    rewardOptions(limit: 10) {
      inputAssets(limit: 1) {
        name
      }
      validators(limit: 5) {
        address
        metrics(
          where: { metricKeys: ["staked_tokens", "commission"] }
          limit: 5
        ) {
          metricKey
          defaultValue
        }
      }
    }
  }
}

Slug is a unique identifier for assets and providers, visible in website URLs. For example, in stakingrewards.com/earn/ethereum-2-0, the slug is ethereum-2-0.

Step 7a: Global Metrics

Query global metrics directly without filtering by specific entities.

{
  metrics(
    where: {
      asset: null
      provider: null
      rewardOption: null
      validator: null
      metricKeys: ["marketcap"]
    }
    limit: 20
  ) {
    metricKey
    defaultValue
    changePercentages
  }
}

Global Metrics are ecosystem-wide measurements like combined market cap of PoS assets or total staked value across all networks.

Step 7b: Historical Global Metrics

Retrieve historical global metrics (example: net staking flow 7-day) with time-based filtering.

{
  metrics(
    where: {
      asset: null
      provider: null
      rewardOption: null
      validator: null
      metricKeys: ["net_staking_flow_7d"]
      createdAt_gt: "2023-01-01"
    }
    order: { createdAt: asc }
    limit: 100
  ) {
    metricKey
    defaultValue
    createdAt
  }
}

Key Takeaways

Always include a limit parameter at every level of your query
isActive is true by default — you only get active items unless you specify otherwise
Use slugs to filter specific assets or providers
Use metricKeys to request specific metrics
The defaultValue field contains the current/latest metric value
For historical data, use createdAt_gt or createdAt_lt with date strings

Next Steps

Now that you've walked through the basics, explore the full API:

Schema — Understand how all objects relate to each other
Objects — Deep dive into Assets, Providers, Validators, and more
Queries — Learn advanced query techniques

Hands-On for Beginners

On this page