open-octopus 0.3.0

Modern async Python client for the Octopus Energy GraphQL API

🐙 open-octopus

An Octopus Energy API client built for AI.

pip install open-octopus

Features · Quick Start · CLI · AI Agent · API Reference

---

Features

⚡ Live Power Real-time consumption from Home Mini. See exactly what you're using right now. Updates every 10-30 seconds. Calculate cost per hour at current rates.	🔌 Smart Charging Intelligent Octopus dispatch slots. Know when your EV is charging. See upcoming charge windows. Never miss off-peak rates again.
🎁 Saving Sessions Free electricity events. Get notified about upcoming free power events. Track rewards in Octopoints. Never miss free energy.	🔥 Dual Fuel Electricity + gas support. Track both meters. Get consumption history. See tariff details for gas and electric.
🤖 AI Agent Ask questions in plain English. "What's my current rate?" "How much did I use yesterday?" Powered by Claude.	🖥️ Menu Bar macOS status bar app. Live power, current rate, charging status, and balance. Always visible. One click away.

---

Quick Start

⚡ Basic Usage import asyncio from open_octopus import OctopusClient async def main(): async with OctopusClient( api_key="sk_live_xxx", account="A-XXXXXXXX" ) as client: # Account balance account = await client.get_account() print(f"Balance: £{account.balance:.2f}") # Current rate tariff = await client.get_tariff() rate = client.get_current_rate(tariff) print(f"Rate: {rate.rate}p/kWh") # Live power (Home Mini) power = await client.get_live_power() if power: print(f"Power: {power.demand_kw:.2f} kW") asyncio.run(main())

🔥 With Gas async with OctopusClient( api_key="sk_live_xxx", account="A-XXXXXXXX", gas_mprn="1234567890", gas_meter_serial="G4A12345" ) as client: # Gas consumption gas = await client.get_daily_gas_usage(days=7) for date, kwh in gas.items(): print(f"{date}: {kwh:.1f} kWh") # Gas tariff tariff = await client.get_gas_tariff() print(f"Rate: {tariff.unit_rate}p/kWh")

---

💻 CLI

octopus status      # Full overview
octopus rate        # Current rate (off-peak/peak)
octopus power       # Live consumption
octopus dispatch    # Charging windows
octopus usage       # Electricity usage
octopus gas         # Gas usage
octopus sessions    # Saving sessions
octopus watch       # Live monitoring

---

🤖 AI Agent

Ask questions about your energy in plain English.

pip install 'open-octopus[agent]'
export ANTHROPIC_API_KEY="sk-ant-xxx"

octopus-ask "What's my current rate?"
octopus-ask "How much gas did I use this week?"
octopus-ask "When is my next charging window?"
octopus-ask "Am I on off-peak rates right now?"

Or use in Python:

from open_octopus import OctopusAgent

agent = OctopusAgent()
response = await agent.ask("What's my balance?")
print(response)

---

🖥️ Menu Bar (macOS)

pip install 'open-octopus[menubar]'
octopus-menubar

⚡ Live Power Real-time kW

🌙 Rate Status Off-peak/peak

🔌 Charging EV dispatch

💰 Balance Account credit

---

📚 API Reference

Account & Billing get_account() # Balance, status, address get_tariff() # Electricity tariff get_gas_tariff() # Gas tariff get_current_rate() # Current rate + off-peak	Consumption get_consumption() # Half-hourly readings get_daily_usage() # Daily totals get_gas_consumption() # Gas readings get_daily_gas_usage() # Daily gas totals
Smart Features get_live_power() # Real-time watts get_dispatches() # Charge windows get_dispatch_status() # Currently charging? get_saving_sessions() # Free power events	Models Account # Balance, name, status Tariff / GasTariff # Rates, standing charge Rate # Current rate, period Dispatch # Charge window LivePower # Real-time demand SavingSession # Free power event

---

⚙️ Configuration

Environment Variables

# Required
OCTOPUS_API_KEY=sk_live_xxx
OCTOPUS_ACCOUNT=A-XXXXXXXX

# Electricity meter (optional)
OCTOPUS_MPAN=1234567890123
OCTOPUS_METER_SERIAL=12A3456789

# Gas meter (optional)
OCTOPUS_GAS_MPRN=1234567890
OCTOPUS_GAS_METER_SERIAL=G4A12345

# AI agent (optional)
ANTHROPIC_API_KEY=sk-ant-xxx

Getting Your API Key

1. Log in to Octopus Energy
2. Go to Developer Settings
3. Copy your API key (starts with sk_live_)

Finding Your MPAN/MPRN

Your MPAN (electricity) and MPRN (gas) are on your energy bills.

Or discover them via the API:

account = await client.get_account()
print(account)  # Includes meter info

---

How It Works

┌────────────────────────────────────────────────────────────────┐
│  Octopus Energy GraphQL API (Kraken)                           │
│  ↓                                                             │
│  open-octopus async client                                     │
│  • Account balance, tariffs                                    │
│  • Consumption data (electricity + gas)                        │
│  • Intelligent Octopus dispatches                              │
│  • Live power (Home Mini telemetry)                            │
│  • Saving Sessions                                             │
│  ↓                                                             │
│  Your choice of interface                                      │
│  • Python library (async/await)                                │
│  • CLI tool (octopus)                                          │
│  • AI agent (octopus-ask)                                      │
│  • Menu bar app (octopus-menubar)                              │
└────────────────────────────────────────────────────────────────┘

---

Built for Octopus Energy customers 🐙

Report Bug · Request Feature

MIT License · Octopus Energy · GraphQL API