# ELEC Finance — US National Electricity Price Index API

> $ELEC is a real-time, pay-per-use API feed delivering a single composite US wholesale electricity price in USD/MWh, updated every 0.5 seconds. Liquidity-weighted across 12 major ICE power hub contracts. No accounts or API keys — access is purchased per session in USDC via the x402 protocol.

## What This API Does

$ELEC publishes a proprietary index price that blends bid/ask mid-prices from 12 US power hub futures contracts traded on ICE: PJM West, PJM AEP-Dayton, ERCOT North, ERCOT Houston, CAISO NP15, CAISO SP15, MISO Indiana, MISO Minnesota, NYISO Zone A, NYISO Zone J (NYC), ISO-NE Mass Hub, and SPP South Hub.

The result is a single normalized USD/MWh price representing the real-time blended cost of wholesale electricity across the US. It is a calculated derivative index — not redistributed ICE data.

Use cases: algorithmic energy trading, real-time risk management, electricity derivatives pricing, energy cost hedging, automated portfolio rebalancing.

## How to Access the API (x402 Payment Flow)

Access is purchased per session using the x402 protocol — an open HTTP standard that settles payments in USDC on the Base network. The flow takes three steps:

1. POST /api/elec/stream/access with your EVM wallet address and desired session window ("1h", "4h", or "24h"). Server returns HTTP 402 with a USDC payment challenge.
2. Complete the on-chain payment using an x402 client library (npm: coinbase/x402 | Python: x402-python). The Coinbase x402 facilitator confirms settlement.
3. Server issues a signed JWT session token. Use it to call the price or stream endpoints.

No registration, no API keys, no invoicing. Payment is traceable to your wallet address.

## Endpoints

Base URL: https://api.elec.finance
Sandbox (mock data, no payment required): https://sandbox.elec.finance
Full OpenAPI 3.1 spec: https://elec.finance/openapi.json

### POST /api/elec/stream/access
Initiate x402 payment to obtain a JWT session token.
Request body: { "session_window": "1h", "wallet_address": "0x..." }
Returns HTTP 402 (payment challenge) → client pays → returns 200 with JWT.

### GET /api/elec/price?token=<JWT>
JSON snapshot of the current $ELEC index price. Best for agents that need a single price value without a persistent connection.
Returns: PriceMessage object (see Schema section below).

### GET /api/elec/stream?token=<JWT>
Server-Sent Events (SSE) stream. Delivers a PriceMessage every 0.5 seconds plus heartbeat events every 30 seconds. Best for human-facing dashboards and low-latency trading systems.

### GET /api/elec/status
Unauthenticated. Returns feed health: contracts_active, is_provisional, last_tick_at, latency_ms. Use to check feed availability before purchasing a session.

## Authentication

All price endpoints require a JWT session token in one of two ways:
- Authorization header: Authorization: Bearer <token>
- Query parameter: ?token=<token>

Tokens are time-bounded. Session windows: 1 hour, 4 hours, 24 hours. Pricing TBD. An expiry_warning SSE event fires 5 minutes before expiry on the stream endpoint; re-pay to continue without interruption.

## Response Schema

Every price response contains two blocks:

feed:
- provider: "ELEC"
- version: "1.0"
- published_at: ISO 8601 UTC with 4-decimal sub-second precision
- interval_start_utc / interval_end_utc: boundaries of the 0.5-second interval
- interval_type: "0.5SEC"
- message_id: unique tick ID for deduplication

elec_index:
- price: float, USD/MWh, 4 decimal precision — this is the headline value
- unit: "USD/MWh"
- currency: "USD"
- contracts_included: integer 1–12, number of hubs contributing this tick
- is_provisional: boolean, true if fewer than 10 hubs contributed

Example response:
{
  "feed": {
    "provider": "ELEC",
    "version": "1.0",
    "published_at": "2026-07-01T14:05:00.0000Z",
    "interval_start_utc": "2026-07-01T14:04:59.5000Z",
    "interval_end_utc": "2026-07-01T14:05:00.0000Z",
    "interval_type": "0.5SEC",
    "message_id": "elec-20260701-140500-001"
  },
  "elec_index": {
    "price": 44.3021,
    "unit": "USD/MWh",
    "currency": "USD",
    "contracts_included": 12,
    "is_provisional": false
  }
}

## Pricing

Sessions are purchased per-use in USDC on Base (mainnet). Pricing TBD at launch. x402 supports sub-cent transactions, enabling aggressive per-session pricing.

Session windows available at launch: 1 hour.
Planned (v1.1): 4-hour and 24-hour sessions.

## Provisional Data

is_provisional is set to true when fewer than 10 of the 12 hub contracts contribute to a tick. This occurs when an individual ICE feed is stale or unavailable. The feed continues publishing; clients should flag provisional prices appropriately for trading systems.

## SSE Event Types

Clients connected to /api/elec/stream will receive these event types:
- price — $ELEC index tick (every 0.5 seconds)
- heartbeat — session keep-alive with expiry timestamp (every 30 seconds)
- expiry_warning — fired 5 minutes before token expiry
- session_ended — token expired; re-pay to reconnect
- maintenance — planned maintenance; retry after delay

## Agent Integration Notes

For AI agents: use the snapshot endpoint (/api/elec/price) rather than the SSE stream. It returns a single JSON response per request — no persistent connection required.

The x402 payment flow is fully automatable. Use the coinbase/x402 npm package or x402-python library to complete payment programmatically. Both libraries handle the HTTP 402 challenge, on-chain signing, and token retrieval in a single function call.

Test against the sandbox (https://sandbox.elec.finance) first — no payment required, returns realistic mock data.

## Links

- Website: https://elec.finance
- OpenAPI spec: https://elec.finance/openapi.json
- Agent manifest: https://elec.finance/.well-known/agents.json
- Documentation: https://elec.finance/docs
- Status page: https://elec.finance/status
- x402 protocol: https://docs.cdp.coinbase.com/x402/
- x402 npm library: https://www.npmjs.com/package/x402
- Contact: api@elec.finance