# GridHub

> Real-time and historical electricity market data across 25 grids (US, UK, Australia, Europe). Demand, generation mix, wholesale prices, carbon intensity, interconnector flows, installed capacity. Free API key (500 requests/day, instant email signup) or x402 pay-per-call on Base ($0.001–$0.02), plus a free ?sample=true mode on every endpoint. MCP server for AI agents at https://api.grid-hub.app/mcp.

Access, three ways:
1. Free API key — POST https://api.grid-hub.app/v1/keys/signup with {"email": "..."}; 500 requests/day;
   send as 'Authorization: Bearer <ghk_key>'. No card, no wallet.
2. x402 pay-per-call (USDC on base, chain eip155:8453). Request any
   paid endpoint without credentials to receive a 402 with payment requirements,
   then retry with a signed X-PAYMENT header.
3. Free sample mode — append ?sample=true to any endpoint for real, truncated data
   with no credentials at all.

## MCP server (for AI agents and assistants)

Endpoint: https://api.grid-hub.app/mcp (Streamable HTTP, stateless; MCP 2026-07-28 and 2025-xx clients).
Tools: list_zones, get_status, get_latest, get_zone_brief, get_history, get_map_snapshot.
Pass the API key as an 'Authorization: Bearer' header on the connection, or as the
optional api_key tool argument. Without credentials tools run in sample mode.

Machine-readable catalog: https://api.grid-hub.app/catalog
OpenAPI spec: https://api.grid-hub.app/openapi.json
x402 manifest: https://api.grid-hub.app/.well-known/x402.json
Receiving address: 0x7ca97aE70E38736a94eEa00427D50846Bab978DD

## Free endpoints

- [List all covered zones](https://api.grid-hub.app/v1/zones): Coverage list with per-zone licence and attribution info. — free
- [Ingestion freshness per source/zone](https://api.grid-hub.app/v1/status): Ingestion freshness per source/zone — free
- [Zone boundary polygons](https://api.grid-hub.app/v1/geo/zones): GeoJSON FeatureCollection of covered zone boundaries. — free
- [Interconnector lines](https://api.grid-hub.app/v1/geo/interconnectors): GeoJSON LineStrings for tracked interconnector pairs, with from/to zone ids. — free
- [Power plants ≥250MW](https://api.grid-hub.app/v1/geo/plants): Power plants ≥250MW — free

## Paid endpoints

- [Full current-state snapshot](https://api.grid-hub.app/v1/map/snapshot): Every covered zone's latest metrics in one call. — $0.002 USDC
- [Zone brief — current state with historical context](https://api.grid-hub.app/v1/brief/{zone}): Composite snapshot for one zone: current price, demand, carbon intensity and generation mix, each ranked against that zone's own trailing 30-day distribution (percentile, median, min/max), plus 24h trend direction and a plain-language summary. One call replaces the four-to-five separate requests otherwise needed, and returns the interpretation rather than raw series. Context blocks are omitted for metrics a zone does not publish; each reports its actual data window and sample count. — $0.02 USDC
- [Latest snapshot for one zone](https://api.grid-hub.app/v1/latest/{zone}): Most recent demand, price, generation mix, carbon intensity, and interchange for a single zone. — $0.001 USDC
- [Historical demand](https://api.grid-hub.app/v1/demand/{zone}): Demand (MW) time series for one zone. — $0.01 USDC
- [Historical generation mix](https://api.grid-hub.app/v1/generation/{zone}): Generation by fuel type (MW or %) time series for one zone. — $0.01 USDC
- [Historical wholesale price](https://api.grid-hub.app/v1/price/{zone}): Wholesale price time series for one zone, in local currency per MWh. — $0.01 USDC
- [Historical carbon intensity](https://api.grid-hub.app/v1/carbon-intensity/{zone}): Grid carbon intensity (gCO2/kWh) time series for one zone. — $0.01 USDC
- [Historical interconnector flows](https://api.grid-hub.app/v1/interchange/{zone}): Cross-border power flow (MW) time series for one zone. — $0.01 USDC
- [Historical installed capacity](https://api.grid-hub.app/v1/capacity/{zone}): Annual installed generation capacity (MW) by fuel type. European zones only. — $0.01 USDC

## Data sources

EIA, ENTSO-E, NESO, Elexon, AEMO — 25 zones. See https://api.grid-hub.app/v1/zones for
per-zone licensing and attribution.