Endpoints

Machine-readable spec

Full route catalog as OpenAPI 3.1 — load into Postman, generate clients, or feed to an agent’s discovery layer.

curl -O https://grid402.climatebrain.xyz/openapi.json

Download openapi.json

Base URL: https://grid402.climatebrain.xyz/api

All routes return JSON. Paid routes return 402 until x402-signed.

Hierarchy — the mix endpoints are the primary product. Emissions are computed from the mix using IPCC AR6 lifecycle factors. Spot price is bundled alongside as a commodity signal. Combined packs all three into a single HTTP round-trip — the natural unit for an agent making a carbon-aware load-shift decision.

Mix — generation breakdown + carbon intensity (primary)

The crown-jewel signal. Sub-hourly fuel mix per ISO region, with self-computed gCO₂/kWh embedded.

Route	ISO	Granularity	Cost
`GET /mix/CAISO/live`	California, USA	5 min	$0.005
`GET /mix/ERCOT/live`	Texas, USA	5 min	$0.005
`GET /mix/GB/live`	Great Britain (NESO)	30 min	$0.005
`GET /mix/KPX/live`	Korea	5–60 min	$0.005
`GET /mix/AEMO/live?region=:r`	Australia (NEM)	5 min	$0.005

:r for AEMO is one of NSW1, QLD1, SA1, TAS1, VIC1. Each NEM region is dispatched independently and has a distinct CI profile (TAS1 is hydro-clean, QLD1 is coal-heavy).

GB uses the NESO Carbon Intensity API — no key required, real upstream.

History (for time-series scrubbing)

Route	Description
`GET /mix/{ISO}/history?hours=24&step=30`	Time-series, 30-min slots over the last 24 hours

Returns { iso, source, step_minutes, series: [{ ts, ci_g_per_kwh, generation_mw, pct }] }.

Emissions — self-computed gCO₂/kWh (derived from mix)

Route	Method	Cost
`GET /emissions/CAISO/live`	Σ (fuel_MW × IPCC AR6 lifecycle factor) / total_MW	$0.010
`GET /emissions/ERCOT/live`	same	$0.010
`GET /emissions/GB/live`	same (with NESO’s published intensity as override when available)	$0.010
`GET /emissions/KPX/live`	same	$0.010
`GET /emissions/AEMO/live?region=:r`	same	$0.010

Every response includes factor_source (URL to the IPCC AR6 WG3 Annex III table) and method: "self_computed" so auditors can trace the assumption. We do not redistribute Electricity Maps’ carbon-intensity numbers — every figure is independently derivable.

Spot price — wholesale clearing price (bundled)

Route	Currency	Granularity	Cost
`GET /spot/CAISO/:zone/live`	USD/MWh (LMP)	5–15 min	$0.005
`GET /spot/ERCOT/:hub/live`	USD/MWh (LMP)	5–15 min	$0.005
`GET /spot/GB/:zone/live`	GBP + USD/MWh	30 min	$0.005
`GET /spot/KPX/:zone/live`	KRW + USD/MWh (SMP)	hourly	$0.005
`GET /spot/AEMO/:region/live`	AUD + USD/MWh (RRP)	5 min	$0.005

Native-currency price + USD-converted price both returned, with the FX rate cited.

Combined — one call, three signals (recommended for agents)

Route	Cost
`GET /combined/CAISO/:zone/live`	$0.015
`GET /combined/ERCOT/:hub/live`	$0.015
`GET /combined/GB/:zone/live`	$0.015
`GET /combined/KPX/:zone/live`	$0.015
`GET /combined/AEMO/:region/live`	$0.015

One HTTP request → one USDC tx → mix + emissions + spot. Saves a round-trip; price equals the sum of the underlying signals (no bundling discount yet). Use this for dashboards, carbon-aware schedulers, and any agent that’s making a decision per tick.

Free routes (no payment)

GET / — service info + endpoint catalog
GET /health — { ok: true, ts }
GET /schema/:iso — JSON schema for that ISO’s responses

Demo tier vs production tier

The endpoints under https://grid402.climatebrain.xyz/api are the free demo tier — unmetered, rate-limited at the CDN edge, and deployed as Cloudflare Pages Functions. They exist so the live map and this documentation work without forcing first-time visitors through a wallet handshake.

The x402-gated production API (the prices in the tables above) lives in api/ of the repo and runs locally / on Railway / on Cloudflare Workers. Same data, real billing, real on-chain settlement. Production deploy URL is being staged.