Bittensor RPC and Node Access: Running a Node and Connecting to Finney

Direct Answer: How to Connect to Bittensor Finney RPC

To connect to the Bittensor Finney network, you can either run your own Substrate node or use a hosted RPC endpoint. The official public WSS endpoint is wss://entrypoint-finney.opentensor.ai:443, but it is rate-limited and not recommended for production. For reliable access, consider using a managed service like OnFinality's Bittensor Finney network page or run your own node. This guide walks you through both options, with a focus on running a node via Docker and verifying its health using standard JSON-RPC calls.

If you are a miner or validator, you must run your own node to participate in consensus and submit weights. For simple queries like checking balances or reading chain state, a hosted RPC endpoint is sufficient. The choice depends on your use case, as detailed in the decision guide later in this article.

Understanding Bittensor's Architecture: Substrate and Finney

Bittensor is a decentralized machine learning network built on Substrate, a blockchain framework that powers many Polkadot and Kusama parachains. The mainnet is called Finney, named after the AI pioneer. The network uses a custom consensus mechanism called Yuma Consensus, which rewards miners and validators based on the quality of their machine learning contributions.

Nodes on Bittensor communicate via JSON-RPC over WebSocket (WSS) or HTTP. The RPC interface exposes standard Substrate methods like system_health, system_syncState, and chain_getBlock, as well as Bittensor-specific pallets for staking, registration, and subnet management. For a full list of available methods, refer to the Bittensor official documentation.

When you run a node, it synchronizes with the Finney network by downloading and verifying blocks. The node can operate in two modes: lite (also called full) and archive. A lite node stores only the latest state and recent blocks, while an archive node stores the entire history of state changes, enabling historical queries. The choice affects disk space and sync time, as detailed in the next section.

Lite vs Archive Node: Which One Do You Need?

The primary difference between lite and archive nodes is the amount of historical data stored. A lite node prunes old state and keeps only the latest state, which is sufficient for most operations like submitting transactions and reading current balances. An archive node retains all historical state, allowing queries like 'what was the balance of this account at block 1,000,000?' This is essential for analytics, indexers, and applications that need historical data.

For Bittensor, most miners and validators run lite nodes because they only need the current state to participate in consensus. However, if you are building a dApp that requires historical data, you should run an archive node or use a hosted archive endpoint. OnFinality provides both options; see our archive vs full node differences guide for a deeper comparison.

Disk space requirements vary: a lite node for Finney currently requires around 100-200 GB, while an archive node can exceed 1 TB. These figures are approximate and will grow over time. Always check the latest requirements in the Bittensor official documentation.

Hardware Requirements for Running a Bittensor Node

Running a Bittensor node is resource-intensive. The official documentation recommends a machine with at least 8 CPU cores, 16 GB of RAM, and an SSD with 500 GB of free space for a lite node. For an archive node, you will need more RAM (32 GB or more) and significantly more disk space (1 TB+). A fast internet connection with low latency is also crucial for syncing and participating in consensus.

These are minimum recommendations; production nodes should have redundant power and network connections. If you are running a validator, you may need additional resources to handle the computational load of validating machine learning models. Always refer to the Bittensor official documentation for the most up-to-date hardware guidance.

Running a Bittensor Node via Docker

The easiest way to run a Bittensor node is using Docker, as it encapsulates all dependencies. The official Docker image is opentensorfdn/bittensor on Docker Hub. Below is a step-by-step guide to run a lite node.

First, ensure Docker is installed on your machine. Then, pull the latest image and run a container with the appropriate ports exposed. The default RPC port is 9944 for WebSocket and 9933 for HTTP. You can also specify the chain (Finney) and the node name.

docker pull opentensorfdn/bittensor:latest

docker run -d --name bittensor-node \
  -p 9944:9944 \
  -p 9933:9933 \
  -v /path/to/data:/root/.local/share/node-subtensor \
  opentensorfdn/bittensor:latest \
  --chain finney \
  --name my-bittensor-node \
  --rpc-external \
  --ws-external \
  --rpc-cors all

Connecting to the Finney Network RPC (WSS)

Once your node is running, it will expose a WebSocket RPC endpoint at ws://localhost:9944. You can connect to this endpoint using any WebSocket client, such as wscat or a programming library like polkadot-js. For external access, you would need to configure a reverse proxy and secure the connection with TLS.

If you prefer not to run your own node, you can use a public RPC endpoint. The official public endpoint is wss://entrypoint-finney.opentensor.ai:443, but it is rate-limited. For production use, consider a hosted service like OnFinality's Bittensor RPC Assistant, which provides dedicated endpoints with higher throughput and reliability.

Verifying Node Health with JSON-RPC Calls

After starting your node, you should verify that it is syncing and healthy. The standard Substrate RPC methods system_health and system_syncState provide this information. system_health returns a boolean indicating if the node is healthy, and system_syncState shows the current block height and the target block height.

You can call these methods using curl with a JSON-RPC payload. Below is an example using a public WSS endpoint. Note that curl works with HTTP endpoints; for WSS, you need a WebSocket client. However, many public endpoints also expose HTTP on port 9933. For demonstration, we use the OnFinality public endpoint (replace with your own node's HTTP endpoint if running locally).

curl -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_health","params":[],"id":1}' \
  https://bittensor-finney.api.onfinality.io/public

# Expected output:
# {"jsonrpc":"2.0","result":{"peers":12,"isSyncing":false,"shouldHavePeers":true},"id":1}

curl -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_syncState","params":[],"id":2}' \
  https://bittensor-finney.api.onfinality.io/public

# Expected output:
# {"jsonrpc":"2.0","result":{"startingBlock":0,"currentBlock":1234567,"highestBlock":1234567},"id":2}

Common Failures and How to Fix Them

When running a Bittensor node, you may encounter several common issues. The first is a failure to sync, often due to insufficient disk space or network connectivity. Ensure you have enough free space and that your firewall allows outbound connections on port 30333 (P2P) and inbound on 9944/9933 if you want external RPC access.

Another issue is the node crashing due to memory exhaustion. This can happen if your RAM is below the recommended 16 GB. Consider increasing swap space or upgrading your hardware. If you see 'RPC error: -32000' when making calls, it usually means the node is still syncing or the RPC method is not supported. Wait until sync completes and verify the method name.

For hosted endpoints, rate limiting is a common problem. If you hit rate limits, consider upgrading to a dedicated endpoint via OnFinality's pricing page.

Tradeoffs: Running Your Own Node vs Using a Hosted RPC

Running your own node gives you full control, privacy, and no rate limits, but it requires significant hardware, maintenance, and time to sync. It is essential for miners and validators who must submit transactions and participate in consensus. For dApp developers and users who only need to read chain data, a hosted RPC endpoint is more cost-effective and reliable.

Hosted services like OnFinality's API service offer high availability, automatic upgrades, and dedicated endpoints with SLAs. They also provide archive nodes for historical queries. The tradeoff is a potential dependency on a third party, but for most use cases, the benefits outweigh the costs.

Use the following decision guide: if you are a miner or validator, run your own node. If you are building an application that requires high throughput or historical data, consider a hosted archive endpoint. If you are just experimenting, use a public endpoint or a lite node.

Next Steps and Further Resources

Now that you understand how to run and connect to a Bittensor node, you can explore more advanced topics like registering as a miner or validator, staking TAO, and interacting with subnets. The Bittensor official documentation is the primary source for these topics.

For managed RPC solutions, visit the OnFinality Bittensor Finney network page to get an endpoint in minutes. You can also use the RPC Assistant to generate code snippets for your preferred language. If you need to understand the differences between node types, read our archive vs full node differences guide. For pricing details, see OnFinality pricing.