# Voltcast

> Voltcast is the accuracy-accountable European electricity price API: day-ahead spot prices for 46 European bidding zones — EU-27 markets plus Norway, Switzerland, the Western Balkans (incl. Albania, Kosovo, Bosnia grid data) and Ukraine (UAH prices) — at native 15-minute resolution with history to 2015 (GB imbalance/grid data via Elexon), intraday auction prices for 9 zones (IDA1/2/3: ES + PT via OMIE, all 7 Italian zones via GME — auctions, not exchange-proprietary continuous trading) with an ML spread forecast (volt-spread-1, scored daily against a disclosed climatology baseline), EXAA auction prices (AT + DE-LU), cross-border physical flows, P10/P50/P90 price forecasts whose accuracy is published daily against a naive-persistence baseline, wind/solar generation forecasts (our own volt-res-1 model scored head-to-head against the TSO's official forecast in every response), zone-centroid weather with ensemble bands, station-exact probabilistic daily Tmax/Tmin temperature forecasts (Volt Temp: full distributions and 1°C bucket probabilities on the named airport gauges markets and CME weather contracts settle on, e.g. Paris-Le Bourget, verified daily against METAR observations), CME-city degree-day settle-index trackers (HDD/CAT for Amsterdam, Essen, London, Paris), population-weighted zone temperature (the RTE/Enedis-style demand metric), imbalance and FCR/aFRR/mFRR reserve prices, load, generation mix, carbon intensity, outage events, optimization tools (cheapest window, charge schedule, battery arbitrage), PPA capture analytics, point-in-time ML feature matrices, a bitemporal as-of API, a vintages API (the revision archive: every TSO forecast, load, generation, flow and price value as first published plus every upstream correction, with observation timestamps — ENTSO-E overwrites these at the source, so this history exists only because Voltcast records it live), Monte Carlo price scenarios, and webhooks that fire within seconds of the 13:00 CET day-ahead auction and each IDA session. If the forecast fails to beat the free baseline in a zone for a month, that zone is credited automatically — a contractual commitment, not marketing.

Key facts: REST JSON API at https://voltcast.com/api/v1 (Bearer API-key auth; free tier at /register, no credit card). Native MCP server for AI agents at https://voltcast.com/api/mcp (streamable HTTP; tools: list_zones, get_prices, get_forecast, get_carbon, get_renewables, cheapest_window; list_zones needs no key). Python SDK: `pip install voltcast`. TypeScript SDK: `npm install @voltcast/sdk`. Data sources: ENTSO-E Transparency Platform, SMARD (CC BY 4.0), Elexon BMRS, netztransparenz.de, regelleistung.net, Open-Meteo — always attributed. Plans: Free (1 zone) · Home €9/mo (1 zone of choice) · Starter €49/mo · Pro €199/mo (adds P10–P90, wind/solar + weather forecasts, population-weighted zone temperature, imbalance/ancillary/outages, optimization, SSE) · Volt Temp €99/mo (station temperature distributions, degree-day indices, zone temperature) · Scale €499/mo (adds analytics, as-of, scenarios, station temperature) · Balancing €299/mo (balancing dataset + RES forecasts + zone temperature) · Quant €999/mo (ML feature matrices + training exports + temperature feature matrices).

## Docs

- [API reference](https://voltcast.com/docs): every endpoint with examples — prices, forecasts, renewables & weather, imbalance, ancillary, load, generation, carbon, outages, optimization, battery simulator, PPA analytics, retailer simulation, ML features, as-of, scenarios, webhooks, SSE stream, MCP, integrations
- [OpenAPI specification](https://voltcast.com/openapi.json): machine-readable API schema
- [Live forecast accuracy](https://voltcast.com/accuracy): daily MAE/pinball per zone vs baseline — the accountability page
- [Ingestion status](https://voltcast.com/status): source health, measured uptime, webhook latency

## API endpoints (base https://voltcast.com/api/v1, Bearer key unless marked public)

- Public, no key: GET /zones · GET /accuracy · GET /status/ingestion · GET /briefing/{zone} · GET /widget/{zone} · GET /indices/flex/{zone} · GET /bench/leaderboard · GET /telemetry/flex/stats · GET /demo/prices · GET /demo/savings · GET /temperature/stations · GET /demo/temperature
- Prices & auctions: GET /prices/{zone} · GET /intraday/{zone} · GET /intraday/{zone}/spread · GET /exaa/{zone} · GET /history/export
- Forecasts & risk: GET /forecasts/{zone} · GET /renewables/{zone} · GET /weather/{zone} · GET /risk/negative/{zone} · GET /imbalance/{zone}/forecast
- Temperature (Volt Temp): GET /temperature/{station} (probabilistic Tmax/Tmin, 1°C buckets) · GET /degree-days/{city} (CME HDD/CAT trackers + settle projections) · GET /temperature/zone/{zone} (population-weighted demand metric) · GET /features/temperature/{station} (Quant training matrix)
- Grid & balancing: GET /load/{zone} · GET /generation/{zone} · GET /carbon/{zone} · GET /flows/{zone} · GET /imbalance/{zone} · GET /ancillary/{zone} · GET /outages/{zone}
- Optimization & analytics: POST /optimize/cheapest-window · POST /optimize/schedule · POST /optimize/battery · GET /capture/{zone} · POST /ppa/value · POST /simulate/retailer · POST /scenarios
- Quant & audit: GET /features/{zone} · GET /features/{zone}/export · GET /features/temperature/{station} · GET /asof/{zone}
- Events: GET /stream (SSE) · GET/POST/DELETE /webhooks (events: auction_published, ida_published, unavailability_published, price_below, price_above, negative_prices) · POST /bench/submissions
- Agents: POST https://voltcast.com/api/mcp (MCP streamable HTTP)

## Data & analysis

- [Live power map (Terminal)](https://voltcast.com/terminal): interactive map of all bidding zones with 9 data layers (price, P50 forecast preview, carbon intensity, green score, renewables, animated wind field, population-weighted temperature with settlement-station pins, negative-price risk, IDA spreads), cross-border flow overlay, hour scrubbing, time travel over the 2015+ archive, shareable view links, and a 3D globe mode (toggle bottom-right or press G, `?proj=globe`) rendering the whole earth with idle auto-rotation — free, no login. The carbon and renewables layers extend worldwide with Ember monthly per-country estimates (clearly labeled ESTIMATED, `/api/v1/public/terminal/global`), and the "Carbon story" (`?story=carbon`) animates the world's power-sector carbon intensity month by month since 2015
- [European temperature outlook](https://voltcast.com/temperature): station-exact Tmax/Tmin distributions on the named settlement gauges (resolution-station registry with integrity monitoring), CME-city degree-day trackers, record watch — free teaser, no login. Informational/analytical use only, never wagering advice
- [Voltcast Research](https://voltcast.com/research): data-backed publications where every figure is computed live from the production database — monthly European power roundups, event post-mortems (including our own forecast misses), per-zone explainers (43 zones, German twins for DE/AT), methodology papers, global carbon annuals (one per year since 2015, `/research/global-carbon-{year}`), and country energy profiles for every Ember-tracked country worldwide (`/research/countries/{iso}`). Free to cite with attribution
- World markets (G3): day-ahead/spot prices now extend beyond Europe — Australia's NEM (AU-NSW, AU-QLD, AU-SA, AU-TAS, AU-VIC — 5-minute dispatch prices in AUD, attribution: Source: AEMO) and California's CAISO trading hubs (US-NP15, US-SP15, US-ZP26 — day-ahead hourly LMPs in USD, credit: California ISO), served through the same `/api/v1/prices/{zone}` endpoint with zone-native currency; see `/api/v1/zones` for the full registry with region and currency fields
- [Daily guides](https://voltcast.com/guides): one worked example per day computed from that week's real auction data — EV charging windows and yearly savings, home-battery arbitrage, solar capture rates, negative-price watches with forward risk, forecasting baselines, station week-in-reviews — from hobbyist to quant, numbers frozen at publication
- [Voltcast Desk demo](https://voltcast.com/desk/demo): the Quant-tier trading desk on yesterday's data — zone board with model-vs-market gaps, event tape (auctions/outages/negative clears with measured arrival times), auction clock, station desk with live METAR trajectories, run drift, percentile context vs 2015+, degree-day settle desk, BE 1-minute imbalance monitor. Decision support only, no order execution
- [Zone index](https://voltcast.com/zones): all 43 bidding zones with live price summaries and daily briefings
- [Monthly market reports](https://voltcast.com/reports): auto-generated per-zone statistics (averages, negative-price hours, spreads, volatility)
- [Voltcast Forecast Bench](https://voltcast.com/bench): open forward-blind day-ahead price forecasting leaderboard — any key can compete, scoring code published
- [Negative-price tracker](https://voltcast.com/negative-prices): live counters, records and monthly history of negative electricity prices per zone — free, no login, citable with attribution, per-zone CSV downloads
- [Voltcast Flex Index](https://voltcast.com/indices): daily per-zone value of load-shifting, versioned methodology
- [Renewables forecasts vs the TSO](https://voltcast.com/accuracy): our volt-res-1 wind/solar model scored against the TSO's A69 forecast on identical slots — wins and losses both published
- [Daily briefing API](https://voltcast.com/api/v1/briefing/DE-LU): public "why is tomorrow priced this way" explanations per zone, free to quote with attribution

## Integration

- [Use Voltcast inside ChatGPT & Claude](https://voltcast.com/ai): connector setup for claude.ai (custom connector + authorization header), ChatGPT (Apps & Connectors / GPT Actions via https://voltcast.com/openapi-gpt.json), Cursor/VS Code mcp.json, and `npx voltcast-mcp` for local stdio
- [llms-full.txt](https://voltcast.com/llms-full.txt): the full documentation in one file, sized for context windows
- [MCP server config](https://voltcast.com/docs#mcp): connect Claude, Cursor or custom agents in one config block
- [Embeddable price widget](https://voltcast.com/docs#widget): one script tag, free
- [Home Assistant, evcc, Grafana, n8n, Google Sheets](https://voltcast.com/docs#integrations)

## Legal

- [Data licensing](https://voltcast.com/legal/data-licensing): what is redistributed and under which terms
- [Terms](https://voltcast.com/legal/terms): including the automatic beat-the-baseline credit (§4)

## Optional

- [For temperature-market analysts](https://voltcast.com/prediction-markets): why the settlement station is the edge — station-exact distributions, bucket probabilities, uncertainty signals. Analytics only, never wagering advice
- [Comparison: ENTSO-E API alternative](https://voltcast.com/entsoe-api-alternative)
- [Comparison: electricity price APIs](https://voltcast.com/electricity-price-api)
- [Comparison: aWATTar alternative](https://voltcast.com/awattar-api-alternative)
- [Comparison: Electricity Maps alternative](https://voltcast.com/electricity-maps-alternative): prices + forecasts + carbon in one API vs a carbon-only feed
- [German: Strompreise heute](https://voltcast.com/de/strompreise), [morgen](https://voltcast.com/de/strompreise-morgen), [negative Strompreise](https://voltcast.com/de/negative-strompreise), [Prognose](https://voltcast.com/de/strompreis-prognose), [Capture-Preise](https://voltcast.com/de/capture-preise)
- [Pricing](https://voltcast.com/#pricing)


---

# Full API documentation (docs.md)

# Voltcast API — Markdown reference for agents

> European electricity data: day-ahead prices (46 European zones incl.
> Ukraine/Albania/Kosovo, GB grid data via Elexon, 15-minute
> native, history to 2015), forecasts with publicly benchmarked accuracy,
> intraday auctions, imbalance & reserve prices, load, generation, carbon,
> outages, station-exact temperature, optimization and ML feature matrices.
> Base URL: `https://voltcast.com/api/v1` · Auth: `Authorization: Bearer <key>`
> · OpenAPI: https://voltcast.com/openapi.json · MCP: https://voltcast.com/api/mcp

All timestamps are UTC ISO-8601. Prices are EUR/MWh unless a `currency` field
says otherwise (GB imbalance = GBP). Every response includes attribution in
`meta`. `resolution_flag` marks 15-minute (`PT15M`) vs hourly (`PT60M`) periods.

## Quickstart (runnable)

Get a free key at https://voltcast.com/register (30 seconds, no card), then:

```bash
# Tomorrow's day-ahead prices for Germany-Luxembourg, 15-minute native
curl -s "https://voltcast.com/api/v1/prices/DE-LU" \
  -H "Authorization: Bearer YOUR_KEY" -H "Accept: application/json"
```

```json
{
  "data": [
    {"delivery_start": "2026-07-14T22:00:00Z", "delivery_end": "2026-07-14T22:15:00Z",
     "price_eur_mwh": 84.51, "resolution_flag": "PT15M", "source": "entsoe"}
  ],
  "meta": {"zone": "DE-LU", "count": 96,
           "attribution": "Data source: ENTSO-E Transparency Platform (transparency.entsoe.eu)."}
}
```

```bash
# Probabilistic forecast (P50 free; P10/P90 on Pro+), model accuracy public at /accuracy
curl -s "https://voltcast.com/api/v1/forecasts/DE-LU?horizon=48h" \
  -H "Authorization: Bearer YOUR_KEY"
# → {"data":[{"target_start":"...","q50":92.4,"model_version":"volt-2026.07.13"}], ...}
```

SDKs: `pip install voltcast` · `npm install @voltcast/sdk`.

## Errors & rate limits

Errors are JSON: `{"error": {"code": "...", "message": "..."}}` (401 returns
Laravel's `{"message": "Unauthenticated."}`).

| HTTP | code | meaning |
|------|------|---------|
| 401 | — | missing/invalid API key |
| 403 | `zone_not_in_tier` / `history_beyond_tier` | your plan doesn't include this zone / history depth |
| 404 | `zone_not_found` | zone code doesn't exist or is inactive |
| 422 | `invalid_range` / `range_too_large` | bad parameters; ranges cap at 100 days |
| 429 | — | per-minute limit hit — check `Retry-After` header |

Rate limits per plan (requests/min): Free 30 · Home 60 · Starter 120 ·
Volt Temp 300 · Pro 600 · Balancing 600 · Scale 1500 · Quant 3000.
Time-range queries are capped at 100 days per request — page with
`from`/`to` windows, or use `/history/export` for bulk.

## Public endpoints (no key)

- `GET /zones` — all zones with region, currency, EIC codes and capabilities. Beyond Europe: Australia's NEM regions (AU-NSW/QLD/SA/TAS/VIC, real-time 5-minute dispatch prices, AUD, Source: AEMO), CAISO trading hubs (US-NP15/SP15/ZP26, day-ahead hourly LMPs, USD, Credit: California ISO), New Zealand island reference nodes (NZ-NI/NZ-SI, half-hourly final energy prices, NZD, Source: Electricity Authority NZ CC BY 4.0) and Ontario (CA-ON, day-ahead hourly zonal price, CAD, Source: IESO) serve through the same price endpoints in the zone's native currency
- `GET /accuracy` — the daily forecast scorecard vs naive-persistence baseline
- `GET /status/ingestion` — source health, measured uptime
- `GET /briefing/{zone}` — daily "why is tomorrow priced this way" + recap
- `GET /widget/{zone}` — today+tomorrow prices for the embeddable widget
- `GET /demo/savings?zone=&use_case=ev|battery|shift` — realized 30-day savings
- `GET /indices/flex/{zone}` — daily Flex Index (value of load flexibility, EUR/MWh)
- `GET /bench/leaderboard` — the open Forecast Bench leaderboard
- `GET /temperature/stations` — the resolution-station registry (ICAO, tags)
- `GET /demo/temperature` — tomorrow's Tmax distribution for one station

## Prices & forecasts (key required)

- `GET /prices/{zone}?from&to&resolution=native|hourly` — day-ahead prices,
  source-collapsed (ENTSO-E preferred, SMARD fallback), gap-honest
- `GET /forecasts/{zone}?horizon=48h|7d` — P50 curve (P10/P90 on Pro+);
  accuracy for every model version is public at /accuracy
- `GET /risk/negative/{zone}?days=14` — P(price < 0) per 15-minute period
- `GET /history/export?zone=&from=&to=&format=parquet|csv` — bulk zone-year
  files via signed URLs (Pro+)

## Intraday & spreads (key required)

- `GET /intraday/{zone}?session=IDA1|IDA2|IDA3` — intraday auction results
  (ES/PT via OMIE, IT via GME, plus SDAC-coupled IDAs)
- `GET /intraday/{zone}/spread` — DA-vs-IDA1 spread history + the spread
  forecast (volt-spread), issued before the gate closes
- `GET /exaa/{zone}` — EXAA 10:15 auction prices (AT, DE-LU)
- `GET /flows/{zone}` — cross-border physical flows (ENTSO-E A11)

## Balancing & grid (key required)

- `GET /imbalance/{zone}?price_type=short|long|imbalance|imbalance-nrt&revisions=latest|all`
  — revision-aware imbalance prices: DE-LU (reBAP), BE, NL, AT, FR, GB + BE 1-min NRT (Pro+, beta)
- `GET /imbalance/{zone}/forecast` — short-horizon imbalance price forecast (Balancing/Quant)
- `GET /ancillary/{zone}?product=FCR|aFRR|mFRR&market=capacity|energy` — reserve
  prices, avg + marginal (Pro+, beta; DE-LU via regelleistung.net)
- `GET /load/{zone}?kind=actual|forecast_da|all` — total load + day-ahead forecast
- `GET /generation/{zone}` — actual generation mix by fuel (MW)
- `GET /carbon/{zone}` — gCO2eq/kWh + green score from the live mix (IPCC AR5
  lifecycle factors, method disclosed)
- `GET /outages/{zone}?type=planned|forced&min_mw=` — unit unavailability events,
  revision-aware

## Fuels & cross-border (Pro+)

- `GET /gas/storage/{area}?days=90` — GIE AGSI+ gas storage per country (or
  EU aggregate): fill %, TWh, injection/withdrawal, and the 5-year band for
  today's day-of-year. Gas storage is the winter power-price driver.
- `GET /gas/lng/{area}?days=90` — GIE ALSI LNG terminal inventory + daily
  send-out (regasification into the grid), per terminal country or EU.

## Weather & renewables (Pro+ / Volt Temp)

- `GET /renewables/{zone}` — our wind/solar forecasts (volt-res), scored
  head-to-head vs the TSO forecast in every response
- `GET /weather/{zone}` — zone-centroid weather series
- `GET /temperature/zone/{zone}` — population-weighted zone temperature
- `GET /temperature/{station}` — station-exact probabilistic daily Tmax/Tmin
  (P05–P95 + 1°C buckets) on the stations markets settle on (Volt Temp/Quant)
- `GET /degree-days/{city}` — CME-city HDD/CAT settle-index tracking + projection

## Optimization & analytics (Pro+/Scale)

- `POST /optimize/cheapest-window` `{zone, duration_minutes, from?, to?, count?}`
- `POST /optimize/schedule` `{zone, energy_kwh, max_power_kw, deadline}`
- `POST /optimize/battery` `{zone, capacity_kwh, max_power_kw,
  round_trip_efficiency?, max_cycles_per_day?, from?, to?}` — past windows =
  backtest over realized prices (perfect foresight, disclosed)
- `GET /capture/{zone}?technology=solar|wind|wind_onshore|wind_offshore&months=` —
  monthly capture prices/rates (Scale; Pro teaser)
- `POST /ppa/value` `{zone, technology, strike_eur_mwh, from?, to?}` — PPA backcast (Scale)
- `POST /simulate/retailer` `{zone, profile, hedge_ratio, fixed_price_eur_mwh?}` —
  procurement-risk distribution (Scale, white-label with attribution)

## Quant (ML-grade, point-in-time correct)

- `GET /features/{zone}?date=` + `GET /features/{zone}/export` — the exact
  training matrices our own models eat, anti-lookahead semantics per column
- `GET /features/temperature/{station}` — temperature feature matrices
- `GET /asof/{zone}?at=` — bitemporal market reconstruction ("what was known at time T")
- `POST /scenarios` — Monte Carlo price paths (day-block residual bootstrap)

## Push

- `POST /webhooks` `{event, url, zone?, threshold_eur_mwh?}` — events:
  `auction_published`, `price_below`, `price_above`, `negative_prices`,
  `unavailability_published`. HMAC-signed (`X-Voltcast-Signature`), retries.
- `GET /stream?zones=` — SSE: `auction_published` + heartbeats (Pro+)

## Plans

Free (1 zone, 7d history) · Home €9/mo (1 zone of choice, 7d P50) · Starter
€49/mo (all zones, 1y history) · Volt Temp €99/mo (station-exact temperature +
degree days) · Pro €199/mo (full history, P10–P90, optimization, renewables,
export, stream) · Balancing €299/mo (imbalance + reserve + imbalance
forecasts) · Scale €499/mo (analytics, SLA, white-label) · Quant €999/mo
(everything + feature matrices, as-of, scenarios, the Voltcast Desk).
Guarantee: if the forecast fails to beat the free baseline in a zone for a
month, that zone is credited automatically (terms §4).

## More

- Human docs: https://voltcast.com/docs
- LLM overview: https://voltcast.com/llms.txt
- Accuracy methodology: https://voltcast.com/accuracy
- Data licensing: https://voltcast.com/legal/data-licensing


---

# Authentication guide (auth.md)

# Authenticating with the Voltcast API

Voltcast uses simple Bearer API keys — no OAuth dance required.

## Get a key (30 seconds, no credit card)

1. Create a free account at https://voltcast.com/register — a key is generated
   automatically at signup and shown once on the dashboard.
2. Additional keys: dashboard → API keys → Create key.

## Use it

Send the key on every request:

```
Authorization: Bearer vk_live_xxxxxxxxxxxxxxxx
```

Example:

```bash
curl -H "Authorization: Bearer $VOLTCAST_KEY" \
  "https://voltcast.com/api/v1/prices/DE-LU"
```

## MCP server (AI agents)

Streamable HTTP endpoint: `https://voltcast.com/api/mcp`
Server card: `https://voltcast.com/.well-known/mcp.json`

Pass the same key as an `Authorization: Bearer <key>` header. The `list_zones`
tool works without authentication; all other tools run through the same
entitlements and rate limits as the REST API.

## SSE stream

`GET /api/v1/stream` accepts the header, or `?token=<key>` for EventSource
clients that cannot set headers (prefer the header — query strings can be logged).

## Scopes, tiers and limits

Keys inherit the account's plan (free / home / starter / pro / scale). Every
response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; exceeding the
limit returns `429` with `Retry-After`. Plan details: https://voltcast.com/docs#rate-limits

## Errors

Missing or invalid keys return `401` with a JSON error body. Zone or feature
entitlement failures return `403` with a machine-readable `error.code`.