{"data":{"name":"Global Energy Flow API","network":"eip155:8453","payment_protocol":"x402","endpoints":[{"path":"/api/v1/index","method":"GET","price_usd":0,"description":"Machine-readable catalog of every endpoint on this API.","update_frequency":"static (changes only when endpoints change)","response_schema":{"type":"object","properties":{"endpoints":{"type":"array"}}},"example":{"note":"This document is the example — call it."}},{"path":"/api/v1/preview/:dataset","method":"GET","price_usd":0,"description":"One truncated, 24h-delayed record for the named dataset, so agents can evaluate quality before paying. dataset ∈ {hormuz, alerts, risk-summary}.","update_frequency":"follows the underlying dataset, delayed 24h","response_schema":{"type":"object","properties":{"preview":{"type":"boolean"},"delayed_hours":{"type":"number"}}},"example":{"preview":true,"delayed_hours":24}},{"path":"/api/v1/chokepoints/hormuz","method":"GET","price_usd":0.02,"description":"Single JSON verdict answering 'is the Strait of Hormuz open right now' — status, day count, transit rate, latest events, toll status.","update_frequency":"multiple times daily during active crises; at least daily otherwise","response_schema":{"type":"object","properties":{"status":{"enum":["open","restricted","critical","closed"]},"day_count":{"type":"number"},"transits_per_day":{"type":"number","nullable":true},"latest_events":{"type":"array","maxItems":5},"toll_pct":{"type":"number","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"example":{"status":"critical","day_count":138,"transits_per_day":null,"latest_events":[{"date":"2026-07-16","summary":"US blockade disables first vessel under reinstated blockade."}],"toll_pct":0,"updated_at":"2026-07-16T00:00:00Z"}},{"path":"/api/v1/alerts","method":"GET","price_usd":0.01,"description":"All currently active shortage/disruption pins as structured events.","update_frequency":"daily, more often during acute escalation","response_schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"type":{"type":"string"},"severity":{"enum":["shortage","watch"]},"summary":{"type":"string"},"started_at":{"type":"string"},"status":{"type":"string"},"source_confidence":{"enum":["high","medium","low"]}}}}}},"example":{"events":[{"country":"Myanmar","type":"multi-fuel","severity":"shortage","summary":"Confirmed physical rationing (odd-even + digital QR quotas) since March; stations shut for enforcement.","started_at":"2026-03-04","status":"active","source_confidence":"high"}]}},{"path":"/api/v1/shortages/:country","method":"GET","price_usd":0.005,"description":"Current status snapshot for one country — day-count vs. threshold, disruption count, one-line summaries.","update_frequency":"daily","response_schema":{"type":"object","properties":{"country":{"type":"string"},"found":{"type":"boolean"},"pins":{"type":"array"}}},"example":{"country":"Myanmar","found":true,"pins":[{"severity":"shortage","summary":"Nationwide fuel rationing in force since March."}]}},{"path":"/api/v1/risk/summary","method":"GET","price_usd":0.05,"description":"The day's cross-system connection as structured JSON — GEF's highest-value editorial synthesis: how a disruption in one part of the energy system propagates through the rest.","update_frequency":"daily","response_schema":{"type":"object","properties":{"headline":{"type":"string"},"affected_systems":{"type":"array","items":{"type":"string"}},"severity":{"enum":["low","moderate","elevated","critical"]},"reasoning":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"headline":"US blockade disables its first vessel; the domestic buffer that would absorb the shock is thinner than ever.","affected_systems":["hormuz","us-spr","retail-fuel-prices"],"severity":"critical","reasoning":"The SPR falls to its lowest level since April 1983 just as the blockade escalates — a war outrunning the reserve built to buffer it.","updated_at":"2026-07-16T00:00:00Z"}},{"path":"/api/v1/fuel-prices/:country","method":"GET","price_usd":0.001,"description":"Current petrol/diesel status for one country.","update_frequency":"daily","response_schema":{"type":"object","properties":{"country":{"type":"string"},"found":{"type":"boolean"},"petrol":{"type":"object"},"road":{"type":"object"}}},"example":{"country":"Thailand","found":true,"petrol":{"status":"disrupted"},"road":{"status":"disrupted"}}},{"path":"/api/v1/storage/gas/eu","method":"GET","price_usd":0.002,"description":"Current EU gas storage % (GIE AGSI+) plus GEF's trajectory verdict vs. the seasonal target — the verdict is the paid part; raw AGSI+ is free elsewhere.","update_frequency":"daily (AGSI+ publishes daily)","response_schema":{"type":"object","properties":{"fill_pct":{"type":"number"},"verdict":{"enum":["on-track","at-risk","critical"]},"note":{"type":"string"},"updated_at":{"type":"string"}}},"example":{"fill_pct":51.8,"verdict":"at-risk","note":"Injection pace below the rate needed for the relaxed 80% Nov 1 target.","updated_at":"2026-07-16"}},{"path":"/api/v1/storage/oil/us","method":"GET","price_usd":0.002,"description":"Latest EIA snapshot (commercial crude, SPR, gasoline/distillate, week-over-week change) plus GEF's one-line read.","update_frequency":"weekly (EIA WPSR, Wednesdays)","response_schema":{"type":"object","properties":{"commercial_crude_mbbl":{"type":"number"},"commercial_crude_wow_mbbl":{"type":"number"},"spr_mbbl":{"type":"number"},"spr_wow_mbbl":{"type":"number"},"gasoline_mbbl":{"type":"number"},"distillate_mbbl":{"type":"number"},"one_line_read":{"type":"string"},"as_of":{"type":"string"}}},"example":{"commercial_crude_mbbl":409.7,"commercial_crude_wow_mbbl":-1.7,"spr_mbbl":316.5,"spr_wow_mbbl":-3,"gasoline_mbbl":210.6,"distillate_mbbl":108.2,"one_line_read":"SPR at its lowest level since April 1983; the emergency reserve is thinning just as the crisis re-escalates.","as_of":"2026-07-10"}}]},"meta":{"timestamp":"2026-07-16T20:03:32.066Z","source":"Global Energy Flow API catalog","license":"This catalog is free to read and redistribute."}}