Delegator Tracker

Overview

Delegator Tracker is a Python tool for tracking validator delegators and stake amounts across Cosmos SDK-based blockchains. For each configured validator it reports the number of delegators and the total stake in the native denomination — and in USD when a CoinMarketCap API key is provided.

The same data is available three ways: as a table in the terminal, as Prometheus metrics for Grafana dashboards, or in a browser through a small web interface.

Key Features

• Three operating modes — CLI table, Prometheus exporter, and FastAPI web interface.
• Delegator and stake summary — Validator ID, number of delegators and total stake in the native denomination.
• USD values — Optional stake value in USD using CoinMarketCap pricing.
• Multi-chain configuration — Any number of chains and validators defined in one YAML file.

Installation

Optional: USD pricing

• Set COINMARKETCAP_API_URL and COINMARKETCAP_API_KEY in a .env file in the project root to enable USD values.

git clone https://github.com/ChainTools-Tech/delegator_tracker.git
cd delegator_tracker
pip install .

Usage

Choose the mode on the command line. Log verbosity is set with --log-level (DEBUG, INFO, WARNING).

python -m delegator_tracker --mode cli --chain all --config config.yaml --log-level INFO

python -m delegator_tracker --mode exporter --config config.yaml --interval 60 --log-level INFO

python -m delegator_tracker --mode web --config config.yaml --log-level INFO

Configuration

Each chain entry defines the REST API endpoint, denominations and the validators to track:

nodes:
  - name: "MyChain"
    api_url: "https://api.mychain.example.com:443/"
    cmc_api_id: "1234"        # CoinMarketCap ID, optional
    base_denom: "umychain"
    display_denom: "MYCHAIN"
    exponent: 6
    validators:
      - validator_id: "mychainvaloper1..."

Related Resources

• Full documentation — Requirements, installation and usage on docs.chaintools.tech
• Prometheus documentation — Scraping the exporter mode metrics
• Grafana documentation — Dashboards on top of Prometheus
• CoinMarketCap API — API key for USD pricing