rainbowminer-api-client

A typed Python API client for RainbowMiner, the multipool cryptominer. This library provides a clean, async-first interface to monitor and control a RainbowMiner server from Python applications — including Home Assistant integrations.

📚 Documentation

The client is a pure communication interface: it sends HTTP requests to the RainbowMiner local API and parses the responses into typed Pydantic models. It does not execute anything on the RainbowMiner server itself.

Features

• Async-first with aiohttp — ideal for Home Assistant and other async Python apps
• Sync wrapper (SyncRainbowMinerClient) for non-async callers — no asyncio.run() needed
• Fully typed — Pydantic v2 models for every endpoint, with py.typed (PEP 561) marker
• Monitoring endpoints — miners, pools, balances, earnings, profit, devices, stats, activity
• Control endpoints — pause, stop, reboot, update, toggle miner/pool, save config
• Binary endpoints — download debug ZIPs, miner stats archives, CSV exports
• Error hierarchy — typed exceptions for auth, connection, and API errors

Installation

pip install rainbowminer-api-client

Quick start

Async (recommended for Home Assistant)

import asyncio
from rainbowminer_api_client import RainbowMinerClient

async def main() -> None:
    async with RainbowMinerClient("192.168.1.50", 4000) as client:
        profit = await client.get_current_profit()
        print(f"Current profit: {profit.ProfitBTC} BTC")

        miners = await client.get_active_miners()
        for miner in miners:
            print(f"  {miner.Name}: {miner.Speed}")

asyncio.run(main())

Sync (for scripts and non-async apps)

from rainbowminer_api_client import SyncRainbowMinerClient

with SyncRainbowMinerClient("192.168.1.50", 4000) as client:
    profit = client.get_current_profit()
    print(f"Current profit: {profit.ProfitBTC} BTC")

With authentication

from rainbowminer_api_client import RainbowMinerClient

# RainbowMiner uses HTTP Basic auth when APIauth is enabled
async with RainbowMinerClient("192.168.1.50", 4000, username="admin", password="secret") as client:
    status = await client.get_status()
    print(f"Paused: {status.Pause}")

Monitoring endpoints

All methods are async on RainbowMinerClient and sync on SyncRainbowMinerClient.

Control endpoints

Binary endpoints

BinaryResponse has .data (bytes), .content_type (str), and .filename (str | None).

Sync / async parity

Every public async method on RainbowMinerClient has a corresponding sync method on SyncRainbowMinerClient with the same name and signature. This parity is enforced by an automated test. When a new async method is added, the sync counterpart is added in the same change.

Error handling

All exceptions derive from RainbowMinerError:

from rainbowminer_api_client import RainbowMinerError, RainbowMinerAuthError, RainbowMinerConnectionError

try:
    profit = await client.get_current_profit()
except RainbowMinerAuthError:
    print("Authentication failed — check your username/password")
except RainbowMinerConnectionError:
    print("Cannot connect to RainbowMiner — is it running?")
except RainbowMinerError as e:
    print(f"API error: {e}")

Compatibility

• Python 3.14+
• RainbowMiner 4.x+ (API server must be enabled in config)
• IPv4 and IPv6 host addresses are supported (host accepts IPv6 literals with or without brackets)

License

MIT