bittensor-sdk

name	bittensor-sdk
description	Comprehensive Bittensor blockchain interaction skill with wallet management, staking, subnet operations, neuron registration, and emissions tracking. Use for: bittensor operations, subtensor queries, stake/unstake TAO, register neurons, query subnet info, wallet operations, metagraph analysis, emissions tracking, and weight management.

Bittensor SDK Skill

Comprehensive Bittensor blockchain interaction skill for agents. Enables seamless interaction with the Bittensor decentralized AI network through the Python SDK.

Overview

Bittensor is a decentralized machine learning network where independent subnets compete for TAO token emissions. This skill provides agents with full access to:

• Wallet Management: Coldkey/hotkey operations, proxy relationships
• Staking Operations: Stake/unstake TAO, auto-staking, safe staking
• Subnet Management: Query subnet info, hyperparameters, registration
• Neuron Operations: Register neurons, query metagraphs, weight management
• Emissions & Rewards: Track emissions, claim root dividends, reward distribution

Key Concepts

Core Terminology

• Coldkey: User's main wallet key for transfers and overall wallet management
• Hotkey: Key used for neuron operations (mining/validation)
• Netuid: Unique identifier for a subnet (0 = Root Subnet)
• UID: Unique identifier for a neuron on a specific subnet
• Metagraph: Complete state of a subnet at a given block
• TAO: Base network token (1 TAO = 1e9 Rao)
• Alpha: Subnet-specific token representing staked TAO
• Rao: Smallest unit of TAO

Network Types

• finney: Bittensor mainnet
• test: Bittensor test network
• local: Locally deployed blockchain

Installation

Prerequisites

pip install bittensor>=8.0.0

Opencode Installation

cp -r skills/bittensor-sdk ~/.opencode/skills/

How It Works

1. Initialization

The skill initializes the Subtensor interface for blockchain interaction:

import bittensor as bt

# Connect to mainnet
subtensor = bt.Subtensor(network="finney")

# Connect to testnet
subtensor = bt.Subtensor(network="test")

# Custom network with fallback endpoints
subtensor = bt.Subtensor(
    network="finney",
    fallback_endpoints=["wss://entrypoint-finney.opentensor.ai:443"],
    retry_forever=True
)

2. Wallet Setup

from bittensor import wallet

# Load existing wallet
wallet = bt.Wallet()

# Create new wallet
wallet = bt.Wallet(name="my_wallet", hotkey="miner1")

# Check balances
coldkey_balance = wallet.coldkey_balance
print(f"Coldkey balance: {coldkey_balance}")

3. Core Operations

Query Subnet Information

# Get all subnet netuids
netuids = subtensor.get_all_subnets_netuid()
print(f"Available subnets: {netuids}")

# Get detailed subnet info
subnet_info = subtensor.get_subnet_info(netuid=1)
print(f"Subnet 1 info: {subnet_info}")

Stake TAO

from bittensor import Balance

# Stake TAO to a hotkey
amount = Balance.from_tao(10.0)  # 10 TAO
result = subtensor.add_stake(
    wallet=wallet,
    netuid=1,
    hotkey_ss58="5Hx...",  # Hotkey SS58 address
    amount=amount,
    safe_staking=True,     # Enable price protection
    allow_partial_stake=True
)
print(f"Stake result: {result}")

Register Neuron

# Burned registration (recycle TAO)
result = subtensor.burned_register(
    wallet=wallet,
    netuid=1
)

# POW registration (computational proof)
result = subtensor.register(
    wallet=wallet,
    netuid=1
)

Query Metagraph

# Get metagraph for a subnet
metagraph = subtensor.metagraph(netuid=1)

print(f"Number of neurons: {metagraph.n}")
print(f"Stake per neuron: {metagraph.S}")
print(f"Rewards: {metagraph.R}")
print(f"Hotkeys: {metagraph.hotkeys}")

Set Weights

import numpy as np

# Validator sets weights for miners
uids = np.array([0, 1, 2, 3, 4])  # Miner UIDs
weights = np.array([0.2, 0.3, 0.2, 0.15, 0.15])  # Normalized weights

result = subtensor.set_weights(
    wallet=validator_wallet,
    netuid=1,
    uids=uids,
    weights=weights,
    wait_for_inclusion=True,
    wait_for_finalization=True
)

Usage Examples

Example 1: Complete Miner Setup

import bittensor as bt
from bittensor import Balance
import numpy as np

# Initialize
subtensor = bt.Subtensor(network="finney")
wallet = bt.Wallet(name="miner_wallet", hotkey="miner1")

# Check balance
balance = subtensor.get_balance(wallet.coldkey.ss58_address)
print(f"Balance: {balance.tao} TAO")

# Register on subnet 1
print("Registering neuron...")
result = subtensor.register(
    wallet=wallet,
    netuid=1,
    wait_for_inclusion=True
)

# Get metagraph info
metagraph = subtensor.metagraph(netuid=1)
print(f"Neurons on subnet 1: {metagraph.n}")

# Check my neuron
my_uid = metagraph.hotkeys.index(wallet.hotkey.ss58_address)
my_neuron = metagraph.neurons[my_uid]
print(f"My UID: {my_uid}")
print(f"My stake: {my_neuron.stake}")
print(f"My emission: {my_neuron.emission}")

Example 2: Validator Operations

import bittensor as bt
from bittensor import Balance
import numpy as np

# Initialize
subtensor = bt.Subtensor(network="finney")
validator_wallet = bt.Wallet(name="validator", hotkey="val1")

# Get metagraph
metagraph = subtensor.metagraph(netuid=1)
print(f"Total miners: {metagraph.n}")

# Calculate weights based on performance
weights = np.zeros(metagraph.n)
for i in range(metagraph.n):
    weights[i] = metagraph.R[i] * 0.7 + metagraph.S[i] * 0.3

# Normalize weights
weights = weights / weights.sum()

# Set weights
result = subtensor.set_weights(
    wallet=validator_wallet,
    netuid=1,
    uids=np.arange(metagraph.n),
    weights=weights,
    wait_for_inclusion=True,
    wait_for_finalization=True
)

print(f"Weights set: {result.success}")

Troubleshooting

Connection Issues

Problem: Unable to connect to network Solution:

# Use fallback endpoints
subtensor = bt.Subtensor(
    network="finney",
    fallback_endpoints=[
        "wss://entrypoint-finney.opentensor.ai:443",
        "wss://finney.opentensor.io:443"
    ],
    retry_forever=True
)

Rate Limiting

Problem: Too many requests error Solution:

import time
time.sleep(1)  # Rate limit delays

Registration Failures

Problem: Registration fails repeatedly Solutions:

1. Check balance (need > 1 TAO for burn registration)
2. Verify POW solution is correct
3. Check network connectivity
4. Try different registration method

Wallet Issues

Problem: Wallet not found Solution:

# Create new wallet
wallet = bt.Wallet(name="new_wallet", hotkey="new_hotkey")
wallet.create_if_non_existing()

Best Practices

1. Always close connections: Use subtensor.close() when done
2. Handle errors gracefully: Use try-except blocks
3. Implement rate limiting: Don't exceed network limits
4. Use MEV protection: Enable for large transactions
5. Monitor emissions: Track network health
6. Use safe staking: Enable price protection
7. Keep keys secure: Never expose private keys

Security Considerations

1. Private keys: Never expose or log private keys
2. Seed phrases: Store securely, never share
3. Transaction signing: Always verify before signing
4. MEV protection: Enable for large transactions
5. Proxy permissions: Understand proxy types before delegating
6. Rate limiting: Prevent DoS by respecting limits

Present Results to Users

When presenting Bittensor SDK results to users:

1. Format TAO amounts clearly: Show both TAO and Rao when relevant
2. Explain network concepts: Clarify coldkey/hotkey, netuid, UID for non-technical users
3. Highlight key metrics: Emphasize important values like stake, emission, registration costs
4. Include relevant links: Link to documentation for deeper exploration
5. Note risks: Highlight potential issues like deregistration risk, rate limits

Example output format:

=== Subnet 1 Status ===
Neurons: 256 registered
Total Stake: 125,450.5 TAO
Emission: 0.123 TAO/block
Registration Cost: 5.2 TAO
Validator Take: 18%
═══════════════════════════════════

References

• Bittensor Documentation
• Bittensor SDK Reference
• Learn Bittensor
• Taostats API
• Bittensor GitHub

Detailed Documentation

For complete API reference, extended examples, and comprehensive troubleshooting, see:

• API Reference - Complete method documentation
• Extended Examples - Advanced usage patterns
• Quick Reference - Common operations summary