Docs

delegateInfo_getDelegated - Bittensor RPC Method

Retrieve SCALE-encoded delegations for a specific account on Bittensor. Essential for portfolio tracking, staking analytics, and nomination monitoring.

Overview

The delegateInfo_getDelegated method returns SCALE-encoded information about all delegations made by a specific account (coldkey). While delegateInfo_getDelegates lists delegate profiles, this method answers the question: "Where has this account delegated its TAO?"

This is the primary method for building portfolio views and staking dashboards that show a user's active delegations, the delegates they have nominated, and how much TAO they have staked with each.

Parameters

PositionNameTypeRequiredDescription
0delegator_account_idnumber[]YesRaw 32-byte coldkey public key as a JSON byte array
1atBlockHashNoOptional block hash to query at a specific block. Pass null for the latest state

Working with addresses: Most client libraries let you start from an SS58 address or a hex public key, then convert it into the 32 raw bytes that the underlying JSON-RPC call expects.

Response

The result is a JSON array of SCALE bytes. When decoded, it contains a list of delegation entries. Each entry is a tuple of (DelegateInfo, (netuid, alpha_stake)) that ties a delegate profile to this account's delegation on a specific subnet:

FieldTypeDescription
delegate_ss58AccountId32The delegate hotkey this account has staked with
takeCompact<u16>The delegate take stored as a normalized u16 value
nominatorsVec<(AccountId32, Vec<(NetUid, stake)>)>Full nominator list for the delegate, grouped by subnet
owner_ss58AccountId32The coldkey that owns the delegate hotkey
registrationsVec<Compact<u16>>Subnet netuids where the delegate is registered
validator_permitsVec<Compact<u16>>Subnet netuids where the delegate has validator permits
return_per_1000Compact<u64>Estimated delegator return per 1000 TAO staked
total_daily_returnCompact<u64>Estimated total daily delegator return
netuid / alpha_stake(u16, Compact<u64>)The subnet identifier and this delegator's stake on that subnet

Returns an empty list if the account has no active delegations.

SCALE Decoding

The raw response requires SCALE decoding with Bittensor-specific type definitions.

Using @polkadot/api: Register the DelegateInfo type definition before creating the API instance. The result decodes to Vec<(DelegateInfo, (u16, Compact<u64>))>.

Using scalecodec (Python): The bittensor SDK provides sub.get_delegated() helpers. For manual decoding, parse the response as a vector pairing DelegateInfo with subnet-specific stake data.

Key decoding notes:

  • Each entry pairs a full DelegateInfo struct with the queried account's specific stake amount
  • The nominators list within each DelegateInfo includes all nominators, not just the queried account -- use this to see your share relative to other nominators
  • To find your specific stake amount for each delegation, look up the queried AccountId32 within the nominators vector, or use the second tuple element
  • Amounts are in RAO (divide by 1e9 for TAO)

Code Examples

Using SubstrateExamples

Decode with Python

Python
import requests
import json

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

# Replace with the coldkey bytes you want to inspect
coldkey_pubkey = [0] * 32

payload = {
    'jsonrpc': '2.0',
    'method': 'delegateInfo_getDelegated',
    'params': [coldkey_pubkey, None],
    'id': 1
}

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

if result.get('result'):
    print(f"SCALE byte count: {len(result['result'])}")
else:
    print('No delegations found for this account')

# To decode with bittensor SDK:
# import bittensor as bt
# sub = bt.subtensor(network='finney')
# delegated = sub.get_delegated(coldkey_ss58)
# for delegation in delegated:
#     print(f"Delegate: {delegation[0].hotkey_ss58}, Amount: {delegation[1]}")

Full Python portfolio analysis

Python
import bittensor as bt

sub = bt.subtensor(network='finney')

coldkey_ss58 = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
delegations = sub.get_delegated(coldkey_ss58)

if not delegations:
    print(f"No delegations found for {coldkey_ss58}")
else:
    total_staked = 0
    total_daily_yield = 0

    print(f"Delegations for {coldkey_ss58[:18]}...\n")
    print(f"{'Delegate':<20} {'Staked (TAO)':>15} {'Take %':>8} {'Subnets':>10} {'Est. Daily':>12}")
    print("-" * 70)

    for delegate_info, staked_amount in delegations:
        staked_tao = staked_amount.tao
        take_pct = delegate_info.take * 100
        subnets = len(delegate_info.registrations)
        daily_return = delegate_info.total_daily_return.tao

        # Estimate your share of daily return
        if delegate_info.total_stake.tao > 0:
            your_share = (staked_tao / delegate_info.total_stake.tao) * daily_return * (1 - delegate_info.take)
        else:
            your_share = 0

        total_staked += staked_tao
        total_daily_yield += your_share

        print(f"{delegate_info.hotkey_ss58[:18]}.. {staked_tao:>14,.2f} {take_pct:>7.1f}% {subnets:>10} {your_share:>11,.4f}")

    print("-" * 70)
    print(f"{'Total':>20} {total_staked:>14,.2f} {'':>8} {'':>10} {total_daily_yield:>11,.4f}")
    print(f"\nEstimated annual yield: {total_daily_yield * 365:,.2f} TAO ({(total_daily_yield * 365 / total_staked * 100):.2f}%)")

Decode with JavaScript

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 });

const coldkey = '0x0000000000000000000000000000000000000000000000000000000000000000';
const result = await api.rpc.delegateInfo.getDelegated(coldkey);

if (result.isEmpty) {
  console.log('No delegations found');
} else {
  console.log('Raw SCALE result:', result.toHex().slice(0, 80), '...');
}

await api.disconnect();

Historical delegation tracking

Python
import requests

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

# Get delegation state at two different blocks to track changes
block_hashes = [
    '0xabc...',  # earlier block
    '0xdef...',  # later block
]

for block_hash in block_hashes:
    payload = {
        'jsonrpc': '2.0',
        'method': 'delegateInfo_getDelegated',
        'params': [coldkey_pubkey, block_hash],
        'id': 1
    }
    response = requests.post(url, json=payload)
    result = response.json()
    print(f"Block {block_hash[:10]}...: {len(result.get('result', '')) // 2} bytes")

Error Handling

Error ScenarioBehaviorRecommended Action
Invalid AccountId32 formatReturns JSON-RPC error -32602Send the coldkey as a 32-byte JSON array or use an SDK helper that handles encoding for you
Account with no delegationsReturns empty result (not an error)Handle the empty case in your UI
Invalid block hashReturns JSON-RPC errorVerify the block hash exists on chain
Node not syncedMay return incomplete delegation dataCheck system_health for sync status
Rate limit exceededHTTP 429Cache results; delegations change infrequently

Common Use Cases

  • Portfolio tracking — Show a user all their active TAO delegations and the amount staked with each delegate.
  • Staking analytics — Calculate total staked TAO, weighted average take rate, and estimated daily yield for a wallet.
  • Nomination monitoring — Track which delegates an account has nominated and alert on changes (e.g., delegate deregistration).
  • Tax reporting — Build delegation history by querying at sequential block hashes for staking income calculations.
  • Whale tracking — Monitor large accounts' delegation patterns to understand network stake distribution.
  • Yield optimization — Compare your current delegation spread against optimal allocation based on delegate performance metrics.