subnetInfo_getMechagraph - Bittensor RPC Method

Overview

The subnetInfo_getMechagraph method returns the SCALE-encoded mechagraph for a specific subnet (netuid) and mechanism ID (mecid) on the Bittensor network. The mechagraph is a more granular view of subnet topology that captures mechanism-specific data -- how neurons perform within a particular evaluation mechanism running on the subnet.

While the metagraph provides the overall subnet state, the mechagraph drills down into the individual mechanisms that a subnet uses to evaluate miners. A subnet can run multiple mechanisms (each identified by a mecid), and the mechagraph captures the incentive and consensus data specific to that mechanism.

This method is used by advanced analytics tools, subnet operators fine-tuning their evaluation mechanisms, and researchers studying how different mechanisms affect incentive distribution.

Metagraph vs. Mechagraph

Understanding the distinction between metagraph and mechagraph is important:

• Metagraph: Aggregated subnet-level view. Contains the combined scores, emissions, and weights across all mechanisms. This is what most users interact with.
• Mechagraph: Mechanism-level view. Contains scores and weights specific to a single evaluation mechanism. Subnets that run multiple evaluation criteria (e.g., latency + accuracy) expose separate mechagraphs for each.

For subnets with a single mechanism (mecid=0), the mechagraph is essentially identical to the metagraph. Multi-mechanism subnets reveal how each individual mechanism contributes to the final aggregated scores.

Parameters

Response

The result is a JSON array of SCALE bytes. When decoded, the mechagraph contains mechanism-specific topology data:

SCALE Decoding

The response decodes to a MechagraphInfo struct using Bittensor's custom type registry.

Using @polkadot/api: Register Bittensor types including MechagraphInfo. The struct layout is similar to MetagraphInfo but includes the additional mecid field and may have fewer fields (no axon info, no coldkeys, depending on runtime version).

Using bittensor Python SDK: Use sub.get_mechagraph(netuid=N, mecid=M) if available in your SDK version. For older SDK versions, use the raw JSON-RPC call and decode with the scalecodec library.

Key decoding notes:

• Score fields (trust, consensus, incentive, dividends) are u16 scaled to 0--65535. Divide by 65535 for float values
• Mechanism-specific scores may differ from the aggregated metagraph scores. A miner might score high on mechanism 0 but low on mechanism 1
• The weights matrix in a mechagraph reflects how validators evaluate miners specifically for this mechanism
• Emissions in the mechagraph represent the portion of total subnet emissions allocated to this mechanism

Code Examples

Using SubstrateExamples

Decode with Python

import requests
import json

url = 'https://api-bittensor-mainnet.n.dwellir.com/YOUR_API_KEY'

# Fetch mechagraph for subnet 1, mechanism 0
payload = {
    'jsonrpc': '2.0',
    'method': 'subnetInfo_getMechagraph',
    'params': [1, 0, None],
    'id': 1
}

response = requests.post(url, json=payload)
result = response.json()

if result.get('result'):
    scale_bytes = result['result']
    print(f'Mechagraph SCALE data size: {len(scale_bytes)} bytes')
else:
    print('No mechagraph found for this subnet/mechanism')

# To decode with bittensor SDK:
# import bittensor as bt
# sub = bt.subtensor(network='finney')
# mechagraph = sub.get_mechagraph(netuid=1, mecid=0)
# print(f"Mechanism 0: {mechagraph.n} neurons")

Full Python mechanism comparison

import requests
import json

url = 'https://api-bittensor-mainnet.n.dwellir.com/YOUR_API_KEY'
netuid = 1

# Fetch mechagraphs for multiple mechanisms and compare
for mecid in range(3):  # Try mechanisms 0, 1, 2
    payload = {
        'jsonrpc': '2.0',
        'method': 'subnetInfo_getMechagraph',
        'params': [netuid, mecid, None],
        'id': mecid + 1
    }
    response = requests.post(url, json=payload)
    result = response.json()

    if result.get('result'):
        data_size = len(result['result']) // 2
        print(f"Mechanism {mecid}: {data_size:,} bytes of data")
    else:
        print(f"Mechanism {mecid}: not found (subnet may have fewer mechanisms)")
        break

# With bittensor SDK for deeper analysis:
# import bittensor as bt
# import numpy as np
# sub = bt.subtensor(network='finney')
#
# mech0 = sub.get_mechagraph(netuid=1, mecid=0)
# mech1 = sub.get_mechagraph(netuid=1, mecid=1)
#
# # Compare incentive scores across mechanisms
# for uid in range(min(mech0.n, mech1.n, 10)):
#     print(f"UID {uid}: mech0 incentive={mech0.I[uid]:.4f}, "
#           f"mech1 incentive={mech1.I[uid]:.4f}")
#
# # Find neurons that perform well on one mechanism but poorly on another
# divergent = np.abs(mech0.I - mech1.I) > 0.1
# print(f"Neurons with divergent mechanism scores: {divergent.sum()}")

Decode with JavaScript

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-bittensor-mainnet.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

// Fetch mechagraph for subnet 1, mechanism 0
const mechagraph = await api.rpc.subnetInfo.getMechagraph(1, 0);
console.log('Raw data size:', mechagraph.toHex().length, 'bytes');

// With Bittensor type definitions registered:
// console.log('Mechanism:', mechagraph.mecid.toNumber());
// console.log('Neurons:', mechagraph.n.toNumber());

await api.disconnect();

Query with cURL

curl -X POST https://api-bittensor-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "subnetInfo_getMechagraph",
    "params": [1, 0, null],
    "id": 1
  }'

Error Handling

Common Use Cases

• Advanced subnet analytics — Analyze how individual mechanisms within a subnet distribute incentives and evaluate miners differently.
• Mechanism tuning — Subnet operators use mechagraph data to understand how their evaluation mechanisms are performing and adjust parameters.
• Performance monitoring — Track mechanism-specific trust and incentive scores for individual neurons to identify strengths across different tasks.
• Research — Study how multi-mechanism subnets allocate rewards and whether different mechanisms produce different consensus outcomes.
• Validator tooling — Build tools that help validators understand how their weights and evaluations affect mechanism-level outcomes.
• Miner optimization — Miners can use mechagraph data to identify which mechanisms they perform well on and optimize accordingly.

Related Methods

• subnetInfo_getAllMechagraphs — Get mechagraphs for all subnets
• subnetInfo_getSelectiveMechagraph — Get filtered mechagraph data for specific neuron UIDs
• subnetInfo_getMetagraph — Get the overall metagraph for a subnet (aggregated view)
• subnetInfo_getDynamicInfo — Get dynamic economic info for a subnet
• neuronInfo_getNeuron — Get detailed info for a specific neuron