Hands-On for Beginners

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

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

On this page