# AgentDataAPI

> Open-data feeds for operations agents in one API and one MCP server: wholesale power prices and grid data (energy), open environmental sensors (air, water, tides, earthquakes), weather alerts and forecasts for the United States and Australia, and news-derived sentiment and trend signals. Every response carries source, as_of and status. One key, or pay per request in USDC over x402.

## Authentication
Send `X-API-Key: adk_live_...` (one key covers every slice). Free key: `POST https://agentdataapi.com/api/v1/auth/keys` with `{"email": "..."}`. No key? GET any data endpoint and you receive a 402 with the USDC price (x402).
Free at volume: the same endpoints are on RealtimeAPI.ai as the feeds `griddata`, `sensordata`, `weatherdata`, `newssignals`. A free RealtimeAPI key (`POST https://api.realtimeapi.ai/keys/free`) gives 1,000 calls a month across every feed, served from its edge cache. Setup prompt for any agent: https://agentdataapi.com/realtimeapi/prompt.txt

## Slices
- Grid and energy data (`/energy/api/v1`, RealtimeAPI feed `griddata`): Wholesale power prices, grid demand, generation mix, carbon intensity and cheapest charging windows across NEM, GB, EU and US markets, plus EIA weekly petroleum stocks. OpenAPI: https://agentdataapi.com/energy/api/openapi.json
- Environmental sensors (`/sensors/api/v1`, RealtimeAPI feed `sensordata`): Air quality, river gauges, tides and earthquakes from open public sensor networks, one schema and nearest-station lookup. OpenAPI: https://agentdataapi.com/sensors/api/openapi.json
- Weather alerts and forecasts (`/weather/api/v1`, RealtimeAPI feed `weatherdata`): Weather alerts, current observations and forecasts for the United States and Australia from public-domain sources. OpenAPI: https://agentdataapi.com/weather/api/openapi.json
- News signals and trends (`/news/api/v1`, RealtimeAPI feed `newssignals`): GDELT-derived sentiment and attention signals per entity and ticker, trending people and topics, and the most-covered stories. OpenAPI: https://agentdataapi.com/news/api/openapi.json

## First calls
1. `GET /energy/api/v1/power/prices/nem/NSW1` (MCP: `grid_price`): the latest wholesale price and demand for a region
2. `GET /energy/api/v1/power/windows/nem/NSW1?hours=4` (MCP: `grid_cheapest_window`): the cheapest 4-hour window in the next 24 h
3. `GET /sensors/api/v1/air/near?lat=-33.87&lon=151.21&radius_km=10` (MCP: `sensors_air_near`): air quality monitors and AQI around a point
4. `GET /sensors/api/v1/water/gauge/01646500` (MCP: `sensors_water_gauge`): river level, flow and flood stage at a USGS gauge
5. `GET /weather/api/v1/alerts?region=TX` (MCP: `weather_alerts`): every active alert for a state or zone, severity first
6. `GET /weather/api/v1/current?lat=-33.87&lon=151.21` (MCP: `weather_current`): conditions at the nearest reporting station
7. `GET /news/api/v1/tickers/NVDA/news-score?window=24h` (MCP: `news_ticker_score`): how unusual today's news volume and tone are for a ticker
8. `GET /news/api/v1/entities/trending?window=24h` (MCP: `news_trending`): which entities have the most unusual coverage right now

## Endpoints and prices (USDC per request without a key)
### Grid and energy data
- `GET /energy/api/v1/regions`: Every market region we serve: code, market, timezone, currency, source and price cadence. $0.005. Refreshes every 24 hours. Tier: free.
- `GET /energy/api/v1/power/prices/{market}/{region}`: Latest settled wholesale electricity price for a region (NEM 5-minute RRP, GB half-hourly market index, EU hourly day-ahead), in micro units of the local currency with a USD conversion, plus demand and a negative-price flag. $0.010. Refreshes every 5 minutes. Tier: free.
- `GET /energy/api/v1/power/prices/{market}/{region}/day-ahead`: Forecast prices per interval for a local calendar day: ENTSO-E day-ahead auction for EU zones, AEMO pre-dispatch for NEM regions. $0.010. Refreshes every 30 minutes. Tier: free.
- `GET /energy/api/v1/power/prices/{market}/{region}/history`: Settled prices per interval for the last 7 days, optionally downsampled to 30 or 60 minute averages. $0.020. Refreshes every 5 minutes. Tier: pro.
- `GET /energy/api/v1/power/load/{market}/{region}`: Latest grid demand for a region in MW (NEM total demand, GB initial demand outturn, ENTSO-E actual load, EIA hourly demand). $0.010. Refreshes every 5 minutes. Tier: free.
- `GET /energy/api/v1/power/generation/{market}/{region}`: Latest generation mix for a region: MW per fuel, total, and the renewables share in basis points. $0.010. Refreshes every 5 minutes. Tier: free.
- `GET /energy/api/v1/power/windows/{market}/{region}`: The cheapest contiguous window of N hours (default 4) within the next horizon (default 24 h), from day-ahead or pre-dispatch prices, for charging and demand-response agents. $0.015. Refreshes every 30 minutes. Tier: free.
- `GET /energy/api/v1/carbon/{region}`: Grid carbon intensity in gCO2 per kWh for Great Britain (GB, actual and forecast) or a NESO region id 1 to 17 (forecast and generation mix). $0.005. Refreshes every 30 minutes. Tier: free.
- `GET /energy/api/v1/petroleum/weekly`: EIA weekly US petroleum inventories: crude stocks (excluding SPR), gasoline and distillate stocks, refinery crude inputs and crude imports, with the week-over-week change. $0.010. Refreshes every 7 days. Tier: free.
### Environmental sensors
- `GET /sensors/api/v1/stations/near`: Stations of every open network within a radius of a point, nearest first, with network, parameters and distance. $0.005. Refreshes every 24 hours. Tier: free.
- `GET /sensors/api/v1/air/{station_id}`: Latest air quality readings at one monitor (PM2.5, PM10, O3, NO2, SO2, CO) with the US EPA AQI value and category. $0.005. Refreshes every 60 minutes. Tier: free.
- `GET /sensors/api/v1/air/near`: Air quality monitors within a radius of a point with their latest readings and AQI, nearest first. $0.010. Refreshes every 60 minutes. Tier: free.
- `GET /sensors/api/v1/water/gauge/{site}`: Latest river gauge height, discharge and water temperature at a USGS site, with the NWS flood stage status. $0.005. Refreshes every 15 minutes. Tier: free.
- `GET /sensors/api/v1/water/gauge/{site}/history`: Gauge readings for the last 7 days at a USGS site, newest first, with observed and ingested times for point-in-time use. $0.020. Refreshes every 15 minutes. Tier: pro.
- `GET /sensors/api/v1/tides/{station}`: Latest observed water level at a NOAA tide station (metres above MLLW) with the next predicted high and low. $0.005. Refreshes every 6 minutes. Tier: free.
- `GET /sensors/api/v1/tides/{station}/predictions`: Predicted high and low tides for a day at a NOAA tide station (metres above MLLW, UTC). $0.005. Refreshes every 24 hours. Tier: free.
- `GET /sensors/api/v1/quakes/recent`: Earthquakes in the last N hours from the USGS feed, optionally above a magnitude and within a radius of a point. $0.005. Refreshes every 60 seconds. Tier: free.
### Weather alerts and forecasts
- `GET /weather/api/v1/alerts`: Active weather alerts for a US state, NWS zone or county code, or an Australian state, with severity, urgency, onset and expiry. US alerts from the National Weather Service; Australian warnings from the Bureau of Meteorology where licensed. $0.002. Refreshes every 60 seconds. Tier: free.
- `GET /weather/api/v1/alerts/{alert_id}`: One alert by id with its description, instruction, areas, zone codes and polygon. $0.002. Refreshes every 60 seconds. Tier: free.
- `GET /weather/api/v1/current`: Current conditions at the nearest reporting station within 150 km of a coordinate in the United States or Australia: temperature, dew point, wind, gust, visibility, pressure, sky cover, present weather. $0.003. Refreshes every 5 minutes. Tier: free.
- `GET /weather/api/v1/forecast/hourly`: Hourly forecast for a coordinate in the contiguous United States or Australia from the NOAA GFS 0.25 degree model: temperature, humidity, wind, gust, precipitation and cloud cover, up to 120 hours. $0.005. Refreshes every 60 minutes or on a new model cycle. Tier: free.
- `GET /weather/api/v1/forecast/daily`: Daily forecast summary for a coordinate in the contiguous United States or Australia (min and max temperature, mean humidity and cloud, max wind and gust, precipitation total), up to 5 days, aggregated from the hourly GFS series. $0.005. Refreshes every 60 minutes or on a new model cycle. Tier: free.
- `GET /weather/api/v1/stations/near`: Reporting stations (METAR) within a radius of a coordinate in the United States or Australia, nearest first, with distance. $0.001. Refreshes every 24 hours. Tier: free.
### News signals and trends
- `GET /news/api/v1/entities`: The tracked entities: organisations, tickers, crypto assets, central banks, governments and topics, with ids, aliases and baselines. $0.005. Refreshes every 24 hours. Tier: free.
- `GET /news/api/v1/sentiment/{entity}`: News tone and volume for one entity over a window: mentions, 30-day baseline, volume ratio, novelty, tone in basis points and top themes. $0.010. Refreshes every 15 minutes. Tier: free.
- `GET /news/api/v1/tickers/{symbol}/news-score`: News score for a ticker or crypto symbol: mentions against baseline, volume ratio, novelty, tone and tone change, top themes. $0.010. Refreshes every 15 minutes. Tier: free.
- `GET /news/api/v1/entities/trending`: Entities with the most unusual news volume in the window, ranked by novelty against their 30-day baseline. $0.015. Refreshes every 15 minutes. Tier: free.
- `GET /news/api/v1/events`: GDELT-coded events (CAMEO) newest first: actors, event code, Goldstein scale, mentions, tone, country and the source URL. $0.010. Refreshes every 15 minutes. Tier: free.
- `GET /news/api/v1/sentiment/{entity}/history`: Mentions and tone per 15-minute window (last 90 days) or per day for one entity, newest first, for backtests. $0.020. Refreshes every 15 minutes. Tier: pro.
- `GET /news/api/v1/trending/people`: Public figures with the biggest attention spike against their 30-day baseline (Wikipedia pageviews and news coverage), by category: celebrity, politics, sport, business. $0.015. Refreshes every 60 minutes. Tier: free.
- `GET /news/api/v1/trending/topics`: Trending topics for a region: top daily searches with approximate traffic and three headlines each, plus trending Mastodon tags and shared links. $0.015. Refreshes every 60 minutes. Tier: free.
- `GET /news/api/v1/top-stories`: The most-covered stories in the window (up to 50): title, link, publisher, tone and how many GDELT records cited the URL. No article text. $0.010. Refreshes every 15 minutes. Tier: free.

## Tiers
- Free: 10/min, 5/day across every slice.
- Pro: 60/min, 20000/day. Passes: 1h $1.00, 1d $3.00, 7d $8.00, one pass for every slice. No subscriptions.
- Pay per request (x402): no key, no account. Prices above. `POST /api/v1/payments/agent-subscribe` with `{"plan": "pass_1d"}` buys a pass and returns a key.
- RealtimeAPI.ai: 1,000 free calls a month on these feeds and every other feed with one `rta_live_` key. MCP: https://mcp.realtimeapi.ai/mcp.

## Response envelope
Numbers are integers in a declared scale (`_milli`, `_micro`, `_bps`) or decimal strings, never floats. Every data response carries `source` (publisher, licence, url, retrieved_at), `as_of` (the data's own timestamp), `next_update`, `status` (fresh, stale or pending) and `data_age_s`. A late upstream is a 200 with status stale, never an error.