|
| 1 | +--- |
| 2 | +title: Subtensor API |
| 3 | +--- |
| 4 | + |
| 5 | +# Subtensor API |
| 6 | + |
| 7 | +The SubtensorApi is a high-level, unified interface to interact with the Bittensor blockchain. It wraps both the synchronous and asynchronous Subtensor implementations, providing modular access to chain subsystems like wallets, delegates, neurons, and more. |
| 8 | + |
| 9 | +Reference docs: [SubtensorApi](pathname:///python-api/html/autoapi/bittensor/core/subtensor_api/index.html) |
| 10 | + |
| 11 | +:::tip |
| 12 | +Upgrade to the [latest Bittensor release](https://pypi.org/project/bittensor/). |
| 13 | +```shell |
| 14 | +pip install bittensor |
| 15 | +``` |
| 16 | +::: |
| 17 | + |
| 18 | +## Basic Usage |
| 19 | + |
| 20 | +### Synchronous Usage (Default) |
| 21 | + |
| 22 | +```python |
| 23 | +import bittensor as bt |
| 24 | + |
| 25 | +sub = bt.SubtensorApi() |
| 26 | + |
| 27 | +print(sub.block) # Get current block number |
| 28 | +print(sub.delegates.get_delegate_identities()) |
| 29 | +sub.chain.tx_rate_limit() |
| 30 | +``` |
| 31 | + |
| 32 | +### Asynchronous Usage |
| 33 | + |
| 34 | +```python |
| 35 | +import bittensor as bt |
| 36 | +import asyncio |
| 37 | + |
| 38 | +async def main(): |
| 39 | + sub = bt.SubtensorApi(async_subtensor=True) |
| 40 | + async with sub: |
| 41 | + print(await sub.block) |
| 42 | + print(await sub.delegates.get_delegate_identities()) |
| 43 | + await sub.chain.tx_rate_limit() |
| 44 | + |
| 45 | +asyncio.run(main()) |
| 46 | +``` |
| 47 | + |
| 48 | +## Legacy Method Support |
| 49 | + |
| 50 | +You can enable all legacy methods from the original `Subtensor` class directly on this interface: |
| 51 | + |
| 52 | +```python |
| 53 | +import bittensor as bt |
| 54 | + |
| 55 | +sub = bt.SubtensorApi(legacy_methods=True) |
| 56 | +print(sub.bonds(0)) # Classic method usage |
| 57 | +``` |
| 58 | + |
| 59 | +## Retry and Fallback RPC Nodes |
| 60 | + |
| 61 | +Enable redundancy and resilience with fallback chains and retry logic: |
| 62 | + |
| 63 | +```python |
| 64 | +import bittensor as bt |
| 65 | + |
| 66 | +sub = bt.SubtensorApi( |
| 67 | + "local", |
| 68 | + fallback_chains=[ |
| 69 | + "wss://fallback1.taonetwork.com:9944", |
| 70 | + "wss://lite.sub.latent.to:443", |
| 71 | + ], |
| 72 | + retry_forever=True, |
| 73 | +) |
| 74 | +print(sub.block) |
| 75 | +``` |
| 76 | + |
| 77 | +## Mock Mode for Testing |
| 78 | + |
| 79 | +Use `mock=True` to simulate the interface without connecting to the blockchain: |
| 80 | + |
| 81 | +```python |
| 82 | +import bittensor as bt |
| 83 | + |
| 84 | +sub = bt.SubtensorApi(mock=True) |
| 85 | +print(sub) # Output: "<Network: None, Chain: Mock, Sync version>" |
| 86 | +``` |
| 87 | + |
| 88 | +## Subsystem Overview |
| 89 | + |
| 90 | +All methods are grouped into logical modules for better organization and readability. Some methods may belong to more than one group if they span multiple functional areas. This does not compromise the internal logic — rather, it enhances discoverability and cohesion. Method equivalence between `SubtensorApi` and the original `Subtensor` is automatically verified by test coverage on every pull request (PR). |
| 91 | + |
| 92 | +The following properties are modular access points for specialized subsystems: |
| 93 | + |
| 94 | +| Property | Description | |
| 95 | +|----------|-------------| |
| 96 | +| chain | Blockchain interaction methods | |
| 97 | +| commitments | Commitment and reveal logic | |
| 98 | +| delegates | Delegate management tools | |
| 99 | +| extrinsics | Transaction construction and signing | |
| 100 | +| metagraphs | Metagraph data and operations | |
| 101 | +| neurons | Neuron-level APIs | |
| 102 | +| queries | General query endpoints | |
| 103 | +| stakes | Staking operations | |
| 104 | +| subnets | Subnet access and management | |
| 105 | +| wallets | Wallet creation, import/export | |
| 106 | + |
| 107 | +## Custom Configuration Support |
| 108 | + |
| 109 | +You can pass a pre-built `Config` object: |
| 110 | + |
| 111 | +```python |
| 112 | +import argparse |
| 113 | +import bittensor as bt |
| 114 | + |
| 115 | +parser = argparse.ArgumentParser('Miner') |
| 116 | +bt.SubtensorApi.add_args(parser) |
| 117 | +config = bt.config(parser) |
| 118 | +sub = bt.SubtensorApi(config=config) |
| 119 | + |
| 120 | +print(sub) |
| 121 | +``` |
| 122 | + |
| 123 | +## Context Manager Usage |
| 124 | + |
| 125 | +### Synchronous Context Manager |
| 126 | + |
| 127 | +```python |
| 128 | +import bittensor as bt |
| 129 | + |
| 130 | +with bt.SubtensorApi() as sub: |
| 131 | + print(sub.block) |
| 132 | +``` |
| 133 | + |
| 134 | +### Asynchronous Context Manager |
| 135 | + |
| 136 | +```python |
| 137 | +import bittensor as bt |
| 138 | +import asyncio |
| 139 | + |
| 140 | +async def main(): |
| 141 | + async with bt.SubtensorApi(async_subtensor=True) as sub: |
| 142 | + print(await sub.block) |
| 143 | + |
| 144 | +asyncio.run(main()) |
| 145 | +``` |
0 commit comments