Reading Bittensor Metagraph State: Weights, Emissions, and Dividends from a Subtensor Node

What the Metagraph Is and Where It Lives

Bittensor is a Substrate-based blockchain (the Finney network) that maintains a registry of subnets, each identified by a netuid. Within each subnet, registered entities are called neurons and are identified by a unique UID. The metagraph is the aggregated, observable view of this per-subnet registry: it includes each neuron's stake, stake-from (delegated TAO), weights, trust, consensus ranks, incentive, and dividends. This state is not stored as a single JSON blob; it is derived from the runtime storage of the subtensor pallet. The official Bittensor documentation describes the network's incentive mechanism, and the subtensor source code (available on GitHub) implements the exact formulas.

When you connect to a subtensor endpoint (such as one provided by OnFinality's Bittensor RPC guide), you are accessing the Finney chain's JSON-RPC interface. The metagraph is not exposed as a single RPC method; instead, you query the underlying storage maps for the subnet's neurons and then compute the derived fields. Community tools and indexers (e.g., taostats, or the bittensor Python SDK) do this aggregation for you, but they are third-party convenience layers. To trust the data, you should verify it against chain state, as described in this article.

• Metagraph state is stored in the subtensor pallet's storage maps, keyed by netuid and UID or hotkey.
• The canonical way to read it is via Substrate state queries (e.g., state_getStorage or the subnetInfo RPC surface).
• Third-party APIs are derived views; always cross-check with a local or trusted subtensor node.

The Economic Model: From Weights to Emissions and Dividends

Each subnet runs a competitive incentive game. Validators periodically set weights for miners—a vector of values, one per UID—based on their own quality scores. These weights are stored on-chain and are used to compute consensus scores. The consensus mechanism is a Schelling-style game: validators who set weights close to the network's weighted median are rewarded, while those who deviate are penalized. The exact algorithm is implemented in the subtensor source code and is described in the official Bittensor documentation on validating.

Emissions are distributed per epoch according to a subnet's alpha/link budget. Each subnet receives a share of the total TAO emission, and that share is divided among miners based on their incentive scores. Validators receive dividends—a share of the subnet's emission that reflects their consensus-weighted stake. Importantly, dividends are not the same as the validator's own mining reward; they are the validator's claim on the subnet's emission based on how well their weights align with the network. The stake-from field tracks delegated TAO, and rewards are split between the validator's own stake and delegated stake. Thus, when you see a reported 'APR' or 'rewards' figure, you must decompose it into the validator's own return and the delegator's share.

The precise emission interval and reward cadence evolve over time. Always confirm the current parameters in the official docs or by reading the chain's runtime constants. Never assume a fixed daily number without checking.

• Weights are a per-UID vector set by validators each epoch.
• Consensus scores determine the ordering of incentive payouts.
• Dividends are the validator's share from consensus over miners' incentive.
• Stake-from returns flow to delegators, so rewards must be split.

Practical Read Surfaces: Subtensor RPC and Off-Chain Indexers

There are two practical ways to read the metagraph. The first is to query a subtensor node directly. A synced full node exposes the raw storage via Substrate RPC methods. For example, you can use the state_getStorage method with the appropriate storage key, or use the subnetInfo RPC surface that some node implementations provide. The community bittensor Python SDK wraps these calls and offers a metagraph object that fetches and computes the state. The second approach is to use an off-chain indexer or block explorer that already computes consensus and emissions. These are convenient but should be validated against chain state.

When using a subtensor RPC endpoint, be aware that the node must be synchronized and not lagging behind the chain tip. A lagging node will return stale data. See our guide on detecting an RPC node lagging the chain tip for methods to check. Also, different providers may have different rate limits and supported methods; check the RPC pricing and API service pages for details.

• Direct node query: use state_getStorage or the subnetInfo RPC surface.
• Community SDKs (e.g., bittensor Python package) provide a metagraph object.
• Indexers like taostats are third-party; always cross-check with chain state.

Reproducible Example: Reading Stake and Weights for a Specific Hotkey

The following example uses the bittensor Python SDK to connect to a subtensor endpoint and read the metagraph for a specific subnet. Replace wss://your-subtensor-endpoint with your actual endpoint (e.g., from OnFinality's Bittensor RPC guide). The script fetches the metagraph for subnet 1 and prints the stake, weights, incentive, and dividends for a given hotkey.

import bittensor as bt

# Connect to a subtensor node
subtensor = bt.subtensor(network="wss://your-subtensor-endpoint")

# Fetch the metagraph for subnet 1
metagraph = subtensor.metagraph(netuid=1)

# Specify a hotkey to inspect
hotkey = "5C..."  # replace with actual hotkey

# Find the UID for this hotkey
uid = metagraph.hotkeys.index(hotkey)

print(f"UID: {uid}")
print(f"Stake: {metagraph.S[uid]}")
print(f"Weights: {metagraph.W[uid]}")
print(f"Incentive: {metagraph.I[uid]}")
print(f"Dividends: {metagraph.D[uid]}")
print(f"Trust: {metagraph.T[uid]}")
print(f"Stake-from: {metagraph.ST[uid]}")

Expected Output and How to Reconcile Reported Rewards

The output will show the raw values from the chain. For example, stake is in Tao (with 10^9 precision), weights are normalized, and incentive/dividends are also in Tao. To reconcile a reported 'APR' or 'rewards' figure, you need to understand the emission schedule. The total emission per subnet is determined by the network's emission rate and the subnet's alpha. The incentive for a miner is the product of the subnet's emission and the miner's incentive score. For a validator, dividends are the sum of the incentive of miners they stake on, weighted by their stake. The table below provides a template to fill in with your own data to verify a reward claim.

Note that the exact emission interval and alpha values change over time. Always check the current parameters in the official docs or by reading the chain's runtime constants. The following table is a template for your own verification.

• Stake is in Tao with 10^9 precision (u64).
• Weights are a vector of floats, normalized to sum to 1.
• Incentive and dividends are in Tao per epoch.
• To compute APR, you need the epoch duration and the emission rate.

| Field | Value from chain | Reported value | Difference |
|-------|------------------|----------------|------------|
| Stake (Tao) | 123.456 | 123.456 | 0 |
| Incentive (Tao/epoch) | 0.001 | 0.001 | 0 |
| Dividends (Tao/epoch) | 0.0005 | 0.0005 | 0 |
| APR (calculated) | 12.3% | 12.3% | 0 |

Troubleshooting Checklist for Metagraph Reads

When reading the metagraph, you may encounter several common issues. First, if you are reading from a non-finalized local node, the data may lag the chain tip. Use the methods in our detecting lag guide to check. Second, a 'hotkey not found' error often means the UID has been deregistered or the hotkey has changed. Third, weights only update each epoch window, so a stale read is normal if you query between updates. Fourth, be aware of the encoding of u64/u128 amounts: TAO amounts are stored with 10^9 precision, so divide by 10^9 to get Tao. Finally, different node implementations (archive vs. requests/state_query) may have different behavior and rate limits; check your provider's documentation.

• Node lag: verify the node is at the latest block.
• Hotkey not found: check if the UID is still registered.
• Weights update per epoch: expect staleness between updates.
• Amount encoding: divide by 10^9 to get Tao.
• Provider differences: archive nodes may have different RPC methods and limits.

Limitations and Tradeoffs of On-Chain Reads

Reading the metagraph directly from a subtensor node gives you the most authoritative data, but it requires a synced node and some computational effort to derive the metagraph. Third-party indexers provide convenience but may introduce latency or aggregation errors. Also, the subtensor RPC surface is not standardized across all node implementations; some methods may be deprecated or version-specific. Always refer to the official subtensor source code and documentation for the exact storage keys and formulas.

For production applications, consider using a reliable RPC provider like OnFinality's Bittensor RPC guide to ensure uptime and performance. See our performance and latency guide for benchmarks and best practices. If you encounter timeouts or errors, refer to our timeout and errors guide.

Next Steps: Validate, Monitor, and Build

Now that you understand how to read the metagraph, you can build tools that verify validator performance, track emissions, or create dashboards. Start by validating a few hotkeys against a trusted source. Then, set up monitoring for your RPC endpoints to ensure they are not lagging; see our monitoring guide. For a deeper dive into the Bittensor network, explore the Bittensor Finney network overview.

If you are building applications that rely on metagraph data, consider using a dedicated API service to handle the load. Check our API service and RPC pricing for options. Finally, always cross-reference with the official Bittensor documentation and the subtensor source code for the latest mechanism changes.

• Validate your reads against a second source.
• Monitor your RPC endpoints for lag and health.
• Explore the Bittensor Finney network for more context.
• Use OnFinality Learn hub for more guides.