Skip to content

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.

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

    Built on aiohttp — ideal for Home Assistant and other async Python applications. Full async/await support with connection pooling.

  • Sync wrapper

    SyncRainbowMinerClient provides a blocking interface for scripts and non-async callers — no asyncio.run() needed.

  • Fully typed

    Pydantic v2 models for every endpoint, with py.typed (PEP 561) marker. Full type annotations on all public APIs.

  • Monitoring

    Miners, pools, balances, earnings, profit, devices, stats, activity, and more — all parsed into structured models.

  • Control

    Pause, stop, reboot, update, toggle miner/pool, save config — full remote control of your RainbowMiner instance.

  • Error hierarchy

    Typed exceptions for auth, connection, and API errors. Catch library errors with a single except clause or handle specific cases.

Quick install

pip install rainbowminer-api-client

uv add rainbowminer-api-client

Quick start

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}")

Explore

  • Getting started

    Install the client and run your first request in minutes.

    Installation

  • Quick start

    Walk through async, sync, and authenticated usage examples.

    Quick start

  • Monitoring endpoints

    Browse all monitoring endpoints with return types and examples.

    Monitoring

  • Control endpoints

    Pause, reboot, toggle miners, save config, and more.

    Control

  • API reference

    Auto-generated reference for every class, method, and model.

    RainbowMinerClient

  • Error handling

    Exception hierarchy and practical error-handling strategies.

    Error handling