balancing-services-cli 1.6.0__tar.gz

balancing_services_cli-1.6.0/.env.sample

@@ -0,0 +1,15 @@
+# Environment variables for development and publishing
+# Copy this file to .env and fill in your actual tokens
+# Never commit .env to version control!
+
+# API key for Balancing Services API (for running examples/tests)
+# Get your API key from: https://balancing.services
+BALANCING_SERVICES_API_KEY=
+
+# TestPyPI token (for testing releases)
+# Get your token from: https://test.pypi.org/manage/account/token/
+UV_PUBLISH_TOKEN_TESTPYPI=
+
+# Production PyPI token (for production releases)
+# Get your token from: https://pypi.org/manage/account/token/
+UV_PUBLISH_TOKEN_PYPI=

balancing_services_cli-1.6.0/.gitignore

@@ -0,0 +1,72 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# uv
+.uv/
+uv.lock
+
+# Generated from pyproject.toml.draft
+pyproject.toml
+
+# Environment variables (contains secrets)
+.env

balancing_services_cli-1.6.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: balancing-services-cli
+Version: 1.6.0
+Summary: CLI for accessing European electricity balancing market data via the Balancing Services REST API
+Project-URL: Homepage, https://balancing.services
+Project-URL: Documentation, https://api.balancing.services/v1/documentation
+Project-URL: Repository, https://github.com/balancing-services/rest-api
+Author: Balancing Services Team
+License: MIT
+Keywords: api,balancing,cli,electricity,energy,europe,grid,imbalance,market,power
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: balancing-services<1.7.0,>=1.6.0
+Requires-Dist: click<9.0.0,>=8.0.0
+Requires-Dist: pyarrow>=14.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# balancing-services-cli
+
+Command-line interface for the [Balancing Services REST API](https://balancing.services) - access European electricity balancing market data directly from your terminal.
+
+## Installation
+
+```bash
+uv add balancing-services-cli
+```
+
+Or with pip:
+
+```bash
+pip install balancing-services-cli
+```
+
+Or run without installing via `uvx`:
+
+```bash
+uvx balancing-services-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+```
+
+## Authentication
+
+Provide your API token via `--token` or the `BALANCING_SERVICES_API_KEY` environment variable:
+
+```bash
+export BALANCING_SERVICES_API_KEY=your-token-here
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+```
+
+## Usage
+
+```bash
+# CSV to stdout (default)
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+
+# Save to CSV file
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z -o prices.csv
+
+# Save to Parquet
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z -o prices.parquet
+
+# Balancing energy commands (require --reserve-type)
+bs-cli energy-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type aFRR
+bs-cli energy-bids --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type mFRR
+
+# Balancing capacity commands (require --reserve-type)
+bs-cli capacity-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type aFRR
+bs-cli capacity-bids --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type FCR
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `imbalance-prices` | Imbalance prices |
+| `imbalance-volumes` | Imbalance total volumes |
+| `energy-activated` | Balancing energy activated volumes |
+| `energy-offered` | Balancing energy offered volumes |
+| `energy-prices` | Balancing energy prices |
+| `energy-bids` | Balancing energy bids (auto-paginates) |
+| `capacity-bids` | Balancing capacity bids (auto-paginates) |
+| `capacity-prices` | Balancing capacity prices |
+| `capacity-procured` | Balancing capacity procured volumes |
+| `capacity-cross-zonal` | Cross-zonal capacity allocation |
+
+## Output Formats
+
+- **CSV** (default): Written to stdout or file. Use with Excel, DuckDB, Polars, pandas, etc.
+- **Parquet**: Must specify `-o file.parquet`.
+
+
+## Global Options
+
+| Option | Description |
+|---|---|
+| `--token` | API bearer token (or set `BALANCING_SERVICES_API_KEY`) |
+| `-o, --output` | Output file path (auto-detects format from `.csv`/`.parquet` extension) |
+| `-f, --format` | Override output format (`csv`, `parquet`) |

balancing_services_cli-1.6.0/README.md

@@ -0,0 +1,80 @@
+# balancing-services-cli
+
+Command-line interface for the [Balancing Services REST API](https://balancing.services) - access European electricity balancing market data directly from your terminal.
+
+## Installation
+
+```bash
+uv add balancing-services-cli
+```
+
+Or with pip:
+
+```bash
+pip install balancing-services-cli
+```
+
+Or run without installing via `uvx`:
+
+```bash
+uvx balancing-services-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+```
+
+## Authentication
+
+Provide your API token via `--token` or the `BALANCING_SERVICES_API_KEY` environment variable:
+
+```bash
+export BALANCING_SERVICES_API_KEY=your-token-here
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+```
+
+## Usage
+
+```bash
+# CSV to stdout (default)
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z
+
+# Save to CSV file
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z -o prices.csv
+
+# Save to Parquet
+bs-cli imbalance-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z -o prices.parquet
+
+# Balancing energy commands (require --reserve-type)
+bs-cli energy-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type aFRR
+bs-cli energy-bids --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type mFRR
+
+# Balancing capacity commands (require --reserve-type)
+bs-cli capacity-prices --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type aFRR
+bs-cli capacity-bids --area EE --start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --reserve-type FCR
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `imbalance-prices` | Imbalance prices |
+| `imbalance-volumes` | Imbalance total volumes |
+| `energy-activated` | Balancing energy activated volumes |
+| `energy-offered` | Balancing energy offered volumes |
+| `energy-prices` | Balancing energy prices |
+| `energy-bids` | Balancing energy bids (auto-paginates) |
+| `capacity-bids` | Balancing capacity bids (auto-paginates) |
+| `capacity-prices` | Balancing capacity prices |
+| `capacity-procured` | Balancing capacity procured volumes |
+| `capacity-cross-zonal` | Cross-zonal capacity allocation |
+
+## Output Formats
+
+- **CSV** (default): Written to stdout or file. Use with Excel, DuckDB, Polars, pandas, etc.
+- **Parquet**: Must specify `-o file.parquet`.
+
+
+## Global Options
+
+| Option | Description |
+|---|---|
+| `--token` | API bearer token (or set `BALANCING_SERVICES_API_KEY`) |
+| `-o, --output` | Output file path (auto-detects format from `.csv`/`.parquet` extension) |
+| `-f, --format` | Override output format (`csv`, `parquet`) |

balancing_services_cli-1.6.0/balancing_services_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Balancing Services CLI - command-line access to European electricity balancing market data."""
+
+from importlib.metadata import version
+
+__version__ = version("balancing-services-cli")

balancing_services_cli-1.6.0/balancing_services_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m balancing_services_cli."""
+
+from balancing_services_cli.main import cli
+
+cli()

balancing_services_cli-1.6.0/balancing_services_cli/client_factory.py

@@ -0,0 +1,23 @@
+"""Create an authenticated API client from CLI options."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import click
+from balancing_services import AuthenticatedClient
+
+BASE_URL = "https://api.balancing.services/v1"
+
+log = logging.getLogger(__name__)
+
+
+def make_client(ctx: click.Context) -> AuthenticatedClient:
+    """Build an AuthenticatedClient from the Click context's global options."""
+    token: str | None = ctx.obj.get("token")
+    if not token:
+        click.echo("Error: API token is required. Use --token or set BALANCING_SERVICES_API_KEY.", err=True)
+        sys.exit(1)
+    log.debug("Creating client for %s", BASE_URL)
+    return AuthenticatedClient(base_url=BASE_URL, token=token)

balancing_services_cli-1.6.0/balancing_services_cli/commands/capacity.py

@@ -0,0 +1,186 @@
+"""Balancing capacity subcommands: capacity-bids, capacity-prices, capacity-procured, capacity-cross-zonal."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+import click
+from balancing_services.api.default import (
+    get_balancing_capacity_bids,
+    get_balancing_capacity_prices,
+    get_balancing_capacity_procured_volumes,
+    get_cross_zonal_capacity_allocation,
+)
+from balancing_services.models import Area, ReserveType
+
+from balancing_services_cli.client_factory import make_client
+from balancing_services_cli.flatten import (
+    CAPACITY_BIDS,
+    CAPACITY_CROSS_ZONAL,
+    CAPACITY_PRICES,
+    CAPACITY_PROCURED,
+    flatten_response,
+)
+from balancing_services_cli.output import write_rows
+from balancing_services_cli.pagination import fetch_all_pages
+from balancing_services_cli.types import ISO8601
+
+log = logging.getLogger(__name__)
+
+AREA_CHOICES = [a.value for a in Area]
+RESERVE_TYPE_CHOICES = [r.value for r in ReserveType]
+
+
+@click.command("capacity-bids")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def capacity_bids(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing capacity bids (auto-paginates)."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/capacity/bids area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    data = fetch_all_pages(
+        get_balancing_capacity_bids.sync_detailed,
+        verbose=ctx.obj["verbose"],
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    rows = flatten_response(data, CAPACITY_BIDS)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("capacity-prices")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def capacity_prices(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing capacity prices."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/capacity/prices area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_balancing_capacity_prices.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, CAPACITY_PRICES)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("capacity-procured")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def capacity_procured(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing capacity procured volumes."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/capacity/procured-volumes area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_balancing_capacity_procured_volumes.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, CAPACITY_PROCURED)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("capacity-cross-zonal")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def capacity_cross_zonal(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch cross-zonal capacity allocation."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/capacity/cross-zonal-allocation area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_cross_zonal_capacity_allocation.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, CAPACITY_CROSS_ZONAL)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])

balancing_services_cli-1.6.0/balancing_services_cli/commands/energy.py

@@ -0,0 +1,186 @@
+"""Balancing energy subcommands: energy-activated, energy-offered, energy-prices, energy-bids."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+import click
+from balancing_services.api.default import (
+    get_balancing_energy_activated_volumes,
+    get_balancing_energy_bids,
+    get_balancing_energy_offered_volumes,
+    get_balancing_energy_prices,
+)
+from balancing_services.models import Area, ReserveType
+
+from balancing_services_cli.client_factory import make_client
+from balancing_services_cli.flatten import (
+    ENERGY_ACTIVATED,
+    ENERGY_BIDS,
+    ENERGY_OFFERED,
+    ENERGY_PRICES,
+    flatten_response,
+)
+from balancing_services_cli.output import write_rows
+from balancing_services_cli.pagination import fetch_all_pages
+from balancing_services_cli.types import ISO8601
+
+log = logging.getLogger(__name__)
+
+AREA_CHOICES = [a.value for a in Area]
+RESERVE_TYPE_CHOICES = [r.value for r in ReserveType]
+
+
+@click.command("energy-activated")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def energy_activated(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing energy activated volumes."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/energy/activated-volumes area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_balancing_energy_activated_volumes.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, ENERGY_ACTIVATED)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("energy-offered")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def energy_offered(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing energy offered volumes."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/energy/offered-volumes area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_balancing_energy_offered_volumes.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, ENERGY_OFFERED)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("energy-prices")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def energy_prices(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing energy prices."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/energy/prices area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    response = get_balancing_energy_prices.sync_detailed(
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    n_groups = len(response.parsed.data) if response.parsed else 0
+    log.debug("Response: HTTP %d, %d group(s)", response.status_code, n_groups)
+    if response.status_code != 200:
+        raise SystemExit(f"API error (HTTP {response.status_code}): {response.content.decode()}")
+    rows = flatten_response(response.parsed.data, ENERGY_PRICES)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])
+
+
+@click.command("energy-bids")
+@click.option(
+    "--area",
+    required=True,
+    type=click.Choice(AREA_CHOICES, case_sensitive=False),
+    help="Area code.",
+)
+@click.option("--start", required=True, type=ISO8601, help="Period start (ISO 8601).")
+@click.option("--end", required=True, type=ISO8601, help="Period end (ISO 8601).")
+@click.option(
+    "--reserve-type",
+    required=True,
+    type=click.Choice(RESERVE_TYPE_CHOICES, case_sensitive=False),
+    help="Reserve type.",
+)
+@click.pass_context
+def energy_bids(ctx: click.Context, area: str, start: datetime, end: datetime, reserve_type: str) -> None:
+    """Fetch balancing energy bids (auto-paginates)."""
+    client = make_client(ctx)
+    log.debug(
+        "GET /balancing/energy/bids area=%s start=%s end=%s reserve_type=%s",
+        area, start, end, reserve_type,
+    )
+    data = fetch_all_pages(
+        get_balancing_energy_bids.sync_detailed,
+        verbose=ctx.obj["verbose"],
+        client=client,
+        area=Area(area),
+        period_start_at=start,
+        period_end_at=end,
+        reserve_type=ReserveType(reserve_type),
+    )
+    rows = flatten_response(data, ENERGY_BIDS)
+    log.debug("Flattened to %d row(s)", len(rows))
+    write_rows(rows, ctx.obj["output"], ctx.obj["fmt"])