What does a Bittensor mining app actually need from RPC infrastructure?

A Bittensor mining app is not a downloadable program with a start button. It is a small stack of processes that talk to the Bittensor chain, and the part that most people underestimate is the RPC layer underneath it. If your miner can register a hotkey but cannot read the metagraph reliably, or if your validator loses its WebSocket subscription mid-epoch, the app looks broken even though the mining logic is fine.

This page explains what the stack actually contains, how to point it at Bittensor Finney, and how to decide whether a shared public endpoint, a managed RPC API, or a dedicated node is the right base for your workload.

Start here: what kind of Bittensor app are you building?

Before you pick an endpoint, decide which of these three shapes matches your project. They have different RPC profiles, and mixing them up is the most common source of avoidable downtime.

If you are building a miner, you can often start on a shared endpoint and move later. If you are running a validator or a dashboard that other people depend on, plan for a dedicated connection from the beginning, because a dropped subscription during weight-setting is expensive to debug after the fact.

The components behind a "mining app"

Most guides skip this and jump straight to installation commands. It helps to name the pieces first:

• Subtensor client — the library that speaks to the Bittensor chain. It needs an RPC endpoint, a wallet, and a network name.
• Wallet — coldkey and hotkey. The coldkey holds stake; the hotkey signs miner or validator actions.
• Subnet logic — your model, your scoring function, or your incentive mechanism. This runs off-chain.
• Axon server — the endpoint other participants call to query your miner.
• Chain reader — the loop that pulls metagraph state, block number, and subnet parameters.

The RPC endpoint sits under the subtensor client and the chain reader. Everything else is local. That is why RPC problems look like miner problems: the miner process is healthy, but the chain reader is stale.

Chain settings at a glance

Bittensor mainnet is Finney. Use these values when configuring a client, a wallet, or a monitoring probe.

OnFinality exposes Bittensor Finney as a managed RPC API with both HTTP and WebSocket transports, so the same endpoint family can serve your miner's one-off reads and your validator's subscription loop. See the Bittensor Finney network page for the current endpoint details, and RPC pricing if you need to size a plan.

Connecting a miner or validator over HTTP

Most subtensor clients accept an endpoint string. A quick way to confirm the endpoint is reachable and returning chain data is a JSON-RPC call. Bittensor uses Substrate-style methods, so the method names differ from EVM chains.

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

A healthy response returns a header object with a block number. If you get a timeout or an empty result, the problem is the connection, not your miner logic. Check the endpoint, then check whether your client is pointed at the right network name.

For a JavaScript client, the pattern is the same: create a provider with the endpoint, then read the header or the metagraph. Keep the provider instance long-lived rather than creating a new one per call, because reconnecting on every request adds latency and hides real failures.

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

const provider = new WsProvider('wss://bittensor-finney.api.onfinality.io/public-ws');
const api = await ApiPromise.create({ provider });

const header = await api.rpc.chain.getHeader();
console.log('current block', header.number.toNumber());

// read subnet state without polling the whole chain
const meta = await api.query.subtensorModule.subnetInfo(1);
console.log(meta.toHuman());

Why WebSocket matters more than you think

Polling chain_getHeader in a loop works for a dashboard. It is a poor fit for a validator that needs to react to new blocks or epoch changes. Substrate clients expose subscriptions, and a WebSocket endpoint lets you subscribe once and receive updates as they happen.

const unsub = await api.rpc.chain.subscribeNewHeads((header) => {
  console.log('new head', header.number.toNumber());
  // trigger metagraph refresh or weight-setting logic here
});

The failure mode to watch for is a silent subscription drop. The client stays connected, no error is thrown, and your miner stops reacting to new blocks. Add a heartbeat: track the last block number you saw, and if it has not advanced within a few blocks, tear down the provider and reconnect. This single check prevents most "my miner stopped earning" incidents.

When a shared endpoint is enough, and when it is not

A shared public endpoint is fine for development, for a single miner with modest read volume, and for exploratory scripts. It is a weaker fit when:

• You run a validator that sets weights every epoch and cannot tolerate a dropped subscription.
• You operate several miners and want per-process isolation so one noisy loop does not affect the others.
• You need predictable throughput for a dashboard with many concurrent readers.
• You want logs and metrics tied to your own traffic rather than a shared pool.

At that point, the choice is between a managed RPC API and a dedicated node. A managed API gives you a stable endpoint, WebSocket support, and someone else handling upgrades and chain sync. A dedicated node gives you a private instance with your own resources, which matters when your read pattern is heavy or when you want to control the upgrade window around a runtime change.

Registration, nonces, and other write-side pitfalls

Reads are the easy part. Writes — registering a hotkey, setting weights, transferring stake — are where mining apps break in ways that look like RPC failures but are not.

• Nonce collisions. If two processes share a coldkey and submit extrinsics at the same time, one will fail with a stale nonce. Serialize writes or use separate keys per process.
• Registration cost changes. Subnet registration cost is dynamic. A transaction that succeeded yesterday can fail today because the cost moved. Read the current cost before submitting.
• Mortality and finality. Extrinsics have a limited lifetime. If your endpoint is lagging, the transaction can expire before it is included. Confirm the block you are building against is current.
• Weight-setting windows. Validators must set weights within the allowed window. A slow or stale chain reader can cause you to miss it.

None of these are solved by a faster endpoint alone, but a stable endpoint makes them easier to diagnose, because you can trust that the block data you are reading is current.

A minimal monitoring probe

Whatever endpoint you choose, add a probe that runs independently of your miner. It should answer one question: is the chain data I am reading fresh?

#!/usr/bin/env bash
ENDPOINT="https://bittensor-finney.api.onfinality.io/public"
BLOCK=$(curl -s "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}' \
  | grep -o '"number":"0x[0-9a-f]*"' | head -1)
echo "probe block: $BLOCK"

Run it on a schedule, log the block number, and alert if it stops advancing. This is more useful than a simple uptime check, because an endpoint can be up and still be behind.

Debug path when your miner stops working

Work through these in order. Most incidents resolve in the first three steps.

1. Is the endpoint responding? Run the curl probe above. If it times out, the issue is connectivity or the endpoint itself.
2. Is the block number advancing? If it responds but the block is stale, you may be on a lagging node. Switch endpoints and re-check.
3. Is your WebSocket subscription alive? If you use subscriptions, confirm you are still receiving heads. Reconnect if not.
4. Is your wallet loaded and unlocked? A locked coldkey produces signing errors that look like RPC errors in some clients.
5. Is the registration cost still valid? Re-read the current cost before resubmitting.
6. Is another process using the same key? Check for nonce collisions across your miner and validator processes.

If steps one through three pass and the miner still does not earn, the problem is in your subnet logic, not your RPC connection.

Key Takeaways

• A Bittensor mining app is a stack: subtensor client, wallet, subnet logic, axon server, and a chain reader. The RPC endpoint sits under the last two.
• Bittensor mainnet is Finney, with TAO as the native currency. OnFinality serves it over both HTTP and WebSocket.
• Use HTTP for one-off reads and WebSocket for subscriptions. Add a heartbeat so a silent subscription drop does not stop your miner.
• Shared endpoints are fine for development and single miners. Validators, multi-miner setups, and dashboards should use a managed RPC API or a dedicated node.
• Most "RPC failures" in mining apps are actually nonce collisions, stale registration costs, or expired extrinsics. Check those before blaming the endpoint.
• Browse supported RPC networks and RPC pricing when you are ready to move off a shared endpoint.

Frequently Asked Questions

Do I need a special app to mine on Bittensor? No. There is no single official mining app. You assemble a stack from a subtensor client, a wallet, and your own subnet logic, then connect it to a Bittensor RPC endpoint.

Which endpoint should I use for Bittensor Finney? OnFinality exposes Bittensor Finney over HTTP and WebSocket. Use https://bittensor-finney.api.onfinality.io/public for reads and wss://bittensor-finney.api.onfinality.io/public-ws for subscriptions. Current details are on the Bittensor Finney network page.

Can I run a miner on a shared public endpoint? Yes, for development and low-volume single-miner setups. If you run a validator or several miners, a managed RPC API or dedicated node reduces the chance that someone else's traffic affects your reads.

Why does my miner stop earning even though the process is running? Usually a stale chain reader or a dropped WebSocket subscription. Add a heartbeat that checks whether the block number is advancing, and reconnect if it is not.

What causes failed extrinsics on Bittensor? Common causes are nonce collisions when two processes share a key, registration cost changes, and extrinsics expiring before inclusion. Read current chain state before submitting.

When should I move to a dedicated node? When you need predictable throughput, per-process isolation, or control over the upgrade window around a runtime change. A dedicated node is the usual next step after a managed RPC API.