staking-rewards-api

Staking Rewards API

A powerful SDK for monitoring validator rewards, earnings, and identifying top-performing validators on Ethereum and BSC networks. Built for staking pools, validator operators, and DeFi platforms that need real-time insights into validator performance.

🎯 Overview

The Staking Rewards API provides comprehensive tools for tracking and analyzing validator performance across Ethereum and Binance Smart Chain (BSC) networks. Whether you're running a staking pool, managing multiple validators, or building analytics dashboards, this SDK gives you the data you need to optimize returns and monitor validator earnings.

Key Features

• 📊 Top Validators Discovery: Identify the highest-earning validators on Ethereum and BSC
• 💰 Reward Tracking: Monitor validator rewards and earnings in real-time
• 📈 Historical Analysis: Analyze validator performance over custom time periods
• 🔄 Real-time Streaming: Get live updates via WebSocket subscriptions
• 🌐 Multi-Validator Support: Track single validators, multiple validators, or all validators simultaneously
• ⚡ High Performance: Built on Bitquery's API for fast, reliable data access

🚀 Quick Start

Installation

npm install staking-rewards-api

Basic Usage

import {
    getTopValidatorsETH,
    getValidatorRewardsETH,
    runValidatorRewardsStreamETH
} from 'staking-rewards-api';

const token = 'YOUR_BITQUERY_TOKEN';

// Find top 10 validators on Ethereum (last 24 hours)
const topValidators = await getTopValidatorsETH(token, 24, 10);
console.log('Top Validators:', topValidators);

// Get rewards for a specific validator
const rewards = await getValidatorRewardsETH(
    token,
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    24 // hours ago
);
console.log('Validator Rewards:', rewards);

// Stream live validator rewards
const ws = await runValidatorRewardsStreamETH(token, '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', {
    onData: (data) => {
        console.log('New reward:', data);
    },
    onError: (error) => {
        console.error('Stream error:', error);
    }
});

📚 API Reference

Query Functions

getTopValidatorsETH(token, hoursAgo, limit)

Get the top-performing validators on Ethereum network.

Parameters:

• token (string, required): Your Bitquery OAuth token
• hoursAgo (number, optional): Hours to look back (default: 24)
• limit (number, optional): Number of validators to return (default: 10)

Returns: JSON object containing top validators data with total tips, rewards, and performance metrics

Example:

const topValidators = await getTopValidatorsETH(token, 48, 20);

getTopValidatorsBSC(token, hoursAgo, limit)

Get the top-performing validators on BSC network.

Parameters: Same as getTopValidatorsETH

Example:

const topValidators = await getTopValidatorsBSC(token, 24, 15);

getValidatorRewardsETH(token, address, hoursAgo)

Get historical rewards for a specific Ethereum validator.

Parameters:

• token (string, required): Your Bitquery OAuth token
• address (string, required): The validator address
• hoursAgo (number, optional): Hours to look back (default: 24)

Returns: JSON object containing validator rewards, balance changes, and transaction details

Example:

const rewards = await getValidatorRewardsETH(
    token,
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    72 // last 3 days
);

getValidatorRewardsBSC(token, address, hoursAgo)

Get historical rewards for a specific BSC validator.

Parameters: Same as getValidatorRewardsETH

Example:

const rewards = await getValidatorRewardsBSC(token, '0x...', 24);

Streaming Functions

All streaming functions return a WebSocket connection and accept an options object with:

• onData (function): Callback for incoming data
• onError (function): Callback for errors
• autoCloseMs (number): Automatically close connection after N milliseconds

runValidatorRewardsStreamETH(token, address, options)

Stream live validator rewards for a single Ethereum validator.

Example:

const ws = await runValidatorRewardsStreamETH(token, '0x...', {
    onData: (data) => console.log('Reward update:', data),
    onError: (err) => console.error('Error:', err),
    autoCloseMs: 60000 // close after 1 minute
});

runMultipleValidatorRewardsStreamETH(token, addresses, options)

Stream rewards for multiple Ethereum validators simultaneously.

Example:

const addresses = [
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    '0x8ba1f109551bD432803012645Hac136c22C92900'
];
const ws = await runMultipleValidatorRewardsStreamETH(token, addresses, {
    onData: (data) => console.log('Multi-validator update:', data)
});

runAllValidatorRewardsStreamETH(token, options)

Stream rewards for all Ethereum validators (use with caution - high volume).

Example:

const ws = await runAllValidatorRewardsStreamETH(token, {
    onData: (data) => console.log('All validators update:', data)
});

BSC Streaming Functions

• runValidatorRewardsStreamBSC(token, address, options)
• runMultipleValidatorRewardsStreamBSC(token, addresses, options)
• runAllValidatorRewardsStreamBSC(token, options)

Usage is identical to Ethereum functions, but for BSC network.

🏗️ Use Cases

For Staking Pools

• Performance Benchmarking: Compare your validators against top performers
• Reward Optimization: Identify which validators generate the highest returns
• Real-time Monitoring: Track validator performance as rewards are distributed
• Portfolio Management: Monitor multiple validators across different networks

For Validator Operators

• Earnings Tracking: Monitor your validator's rewards in real-time
• Performance Analysis: Analyze historical performance to optimize operations
• Competitive Intelligence: See how you rank against other validators
• Alert Systems: Set up automated monitoring for reward events

For DeFi Platforms

• Analytics Dashboards: Build comprehensive validator analytics
• APY Calculations: Calculate accurate APY based on real validator performance
• Risk Assessment: Evaluate validator reliability and performance
• Data Integration: Integrate validator data into your platform

🔑 Getting Your API Token

This SDK uses Bitquery's Transaction Balance API for Ethereum and BSCto fetch blockchain data. To get started:

• Visit Bitquery IDE to create an account
• Generate your Access Token by following these instructions
• Start querying validator data immediately

Bitquery provides comprehensive blockchain data APIs for Ethereum, BSC, and 40+ other networks. Perfect for building analytics, monitoring tools, and data-driven applications.

📊 Data Structure

Top Validators Response

{
  "data": {
    "EVM": {
      "TransactionBalances": [
        {
          "TokenBalance": {
            "Address": "0x...",
            "Currency": {
              "Name": "Ethereum",
              "Symbol": "ETH"
            }
          },
          "Total_tip_native": "1.23456789",
          "Total_tip_usd": "2345.67",
          "number_of_tips": 42
        }
      ]
    }
  }
}

Validator Rewards Response

{
  "data": {
    "EVM": {
      "TransactionBalances": [
        {
          "Post": "100.5",
          "Pre": "99.2",
          "Total_tip_native": "1.3",
          "Total_tip_usd": "2345.67",
          "number_of_tips": 5
        }
      ]
    }
  }
}

⚙️ Configuration

Environment Variables

You can set your Bitquery token as an environment variable:

export BITQUERY_TOKEN=your_token_here

Then use it in your code:

const token = process.env.BITQUERY_TOKEN;

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📝 License

MIT License - see LICENSE file for details

🔗 Resources

• Bitquery Documentation
• Bitquery IDE
• Ethereum Validator Documentation
• BSC Validator Documentation

💬 Support

• Bitquery Community: Join our Telegram

🌟 Why Choose This SDK?

• Built for Staking: Designed specifically for staking pools and validator operators
• Real-time Data: Get instant updates on validator performance
• Multi-Network: Support for both Ethereum and BSC
• Production Ready: Ready to use for staking pools and DeFi platforms
• Well Documented: Comprehensive API documentation and examples
• Active Maintenance: Regularly updated with new features and improvements

Made with ❤️ by the Bitquery Team

Empowering staking pools and validator operators with actionable blockchain insights.