How to Set Up Bittensor Subnet Mining with Wallet Management in CloddsBot

CloddsBot provides a full-stack TypeScript integration that automates Bittensor wallet creation, subnet registration, and TAO token mining through a unified CLI and REST API.

CloddsBot is an open-source automation framework that ships with a complete Bittensor integration, allowing operators to mine TAO tokens on any subnet while managing cryptographic wallets and GPU miner orchestration from a single interface. This guide walks through the technical architecture and practical setup steps for Bittensor subnet mining with wallet management in CloddsBot, referencing the actual source implementation in the alsk1992/CloddsBot repository.

Interactive Setup and Configuration

The setup phase handles environment detection, dependency installation, and wallet initialization through an interactive wizard or manual configuration.

Automated Environment Detection

The setup wizard in src/bittensor/python-runner.ts automatically detects Python 3 and the btcli sidecar binary, installing them if missing. This module wraps Python-only Bittensor CLI commands in a TypeScript execution layer with input sanitization.

clodds bittensor setup

Running this command triggers the wizard to generate a cold-key and hot-key pair using the Bittensor wallet API. The src/bittensor/service.ts file then writes the configuration to ~/.clodds/clodds.json or injects values via environment variables, storing the wallet path and network endpoints.

Configuration Verification

Before mining, verify the installation and connectivity:

clodds bittensor check

This command validates Python availability, btcli functionality, wallet file integrity, and Bittensor network connectivity.

Wallet Management Architecture

CloddsBot implements a sophisticated wallet layer that abstracts Substrate chain interactions for balance monitoring and key management.

Polkadot API Integration

The src/bittensor/wallet.ts module implements a Polkadot API wrapper using @polkadot/api to query the Bittensor Substrate chain directly. This file handles:

• Address derivation from cold keys and hot keys
• Balance queries (free, staked, and total TAO)
• Periodic refresh cycles to keep earnings data current

The wallet layer exposes methods to fetch real-time balances without spawning Python processes, reducing latency for balance-dependent automation.

Secure Key Storage

Wallet files are stored in the standard Bittensor directory structure (~/.bittensor/wallets/), while CloddsBot maintains only the wallet names and metadata in its JSON configuration. The application never persists unencrypted private keys in its own database.

Subnet Registration and Mining Orchestration

Once wallets are configured, CloddsBot handles subnet discovery, on-chain registration, and miner lifecycle management.

Chutes GPU Subnet Support

For compute-intensive subnets like Chutes (SN 64), the src/bittensor/chutes.ts module implements a Docker-based GPU miner orchestrator. This file manages:

• GPU node discovery and allocation
• Container lifecycle for miner processes
• Health monitoring and automatic restarts

The Chutes integration specifically targets GPU compute mining, spinning up containerized miners on configured NVIDIA nodes.

SQLite Persistence Layer

The src/bittensor/persistence.ts module provides SQLite helpers that persist miner earnings, health status, and configuration data. This database stores historical earnings per subnet, allowing operators to track profitability over time without querying the blockchain repeatedly.

REST API Endpoints

The src/bittensor/server.ts file exposes an Express router at /api/bittensor/* that maps HTTP requests to the underlying service layer. Key endpoints include:

• GET /api/bittensor/subnets - Lists available subnets
• POST /api/bittensor/register - Registers wallet on specified subnet
• POST /api/bittensor/start - Initiates mining process
• GET /api/bittensor/wallet - Returns balance and address data

CLI Commands and REST API Reference

CloddsBot provides equivalent functionality through both CLI commands and REST endpoints for flexible automation.

Wallet Operations

Display wallet details and balances:

clodds bittensor wallet show
clodds bittensor wallet balance

Equivalent HTTP request:

curl -H "Authorization: Bearer $CLODDS_TOKEN" \
     http://localhost:18789/api/bittensor/wallet

Subnet Registration

Register your hotkey on a specific subnet (e.g., Chutes SN 64):

clodds bittensor register 64

Programmatic equivalent:

curl -X POST -H "Authorization: Bearer $CLODDS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"subnetId":64}' \
     http://localhost:18789/api/bittensor/register

Mining Operations

Start the miner for a registered subnet:

clodds bittensor start 64

Monitor status and earnings:

clodds bittensor status
clodds bittensor miners
clodds bittensor earnings

To start mining via HTTP:

curl -X POST -H "Authorization: Bearer $CLODDS_TOKEN" \
     -d '{"subnetId":64}' \
     http://localhost:18789/api/bittensor/start

Summary

• CloddsBot centralizes Bittensor mining operations through TypeScript modules located in src/bittensor/.
• Wallet management uses src/bittensor/wallet.ts with native Polkadot API integration for real-time balance tracking.
• Setup automation is handled by src/bittensor/python-runner.ts and src/bittensor/service.ts, which configure btcli and generate cold/hot key pairs.
• GPU mining for subnets like Chutes is orchestrated by src/bittensor/chutes.ts using Docker containers.
• Data persistence occurs in SQLite via src/bittensor/persistence.ts, storing earnings and miner health history.
• Dual interfaces allow operation through either the clodds CLI or REST API endpoints defined in src/bittensor/server.ts.

Frequently Asked Questions

What dependencies are required to run Bittensor mining in CloddsBot?

CloddsBot requires Python 3 and the btcli binary installed on the host system. The setup wizard in src/bittensor/python-runner.ts automatically detects and installs these dependencies if missing. You also need a valid Bittensor wallet with sufficient TAO balance for subnet registration and staking.

How does CloddsBot handle wallet security?

CloddsBot stores wallet metadata in ~/.clodds/clodds.json but delegates key storage to the standard Bittensor wallet directory (~/.bittensor/wallets/). The application interacts with keys through the btcli interface and Polkadot API read-only methods, never persisting unencrypted private keys in its SQLite database or configuration files.

Can I mine on multiple subnets simultaneously?

Yes. The src/bittensor/service.ts orchestrator supports concurrent miner processes across different subnets. Each subnet registration is stored separately in the persistence layer, and you can start independent mining processes for each subnet ID using clodds bittensor start <subnet_id> or the corresponding REST endpoint.

What is the difference between cold keys and hot keys in CloddsBot?

Cold keys are the master wallet keys used for high-security operations like storing large TAO balances and root-level subnet registration. Hot keys are subnet-specific operational keys that miners use to perform work and receive rewards. The setup wizard generates both key types, storing the cold key encrypted while the hot key handles daily mining operations on specific subnets like Chutes SN 64.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}