{"openapi":"3.1.0","info":{"title":"Straits.live premium data","version":"1.0.0","description":"Machine-payable Strait of Hormuz crisis data for AI agents: the live-AIS vessel manifest, single-vessel multi-body sanctions dossiers (OFAC + UK), a shadow-fleet risk screen of the whole vessel population, a flag rollup, bunker & marine-fuel prices, a modeled war-risk transit premium nowcast, full-resolution history, bulk export, a one-call situation snapshot, the complete daily brief, real-time streaming, and threshold-alert webhooks. Settled per request in USDC on Base over the x402 protocol; no key, no account.","x-guidance":"Twelve operations, priced per request ($0.01-$0.50). Most are GET; POST /api/premium/stream/session and POST /api/premium/webhooks take a JSON body. An unpaid request returns HTTP 402 with a machine-readable x402 challenge; sign the USDC authorization and retry (x402-capable clients such as @x402/fetch handle this automatically). Start with GET /api/premium/snapshot for the whole dashboard state in one call. GET /api/premium/history/{feed} serves full-resolution time series (feeds: index-5min, transits, stranded, ais-gaps); GET /api/premium/export bundles every series in one archive. GET /api/premium/vessel/{imo} returns one vessel dossier; GET /api/premium/hormuz/risk-screen ranks the whole live vessel population worst-first with per-hull risk reasons and sanctions matches; GET /api/premium/hormuz/flags rolls it up by flag state; GET /api/premium/bunker returns current bunker & marine-fuel prices with the Fujairah premium over Singapore and Rotterdam; GET /api/premium/risk-premium returns a live modeled war-risk transit premium (Nx over the peace baseline, 1x-16x scale) with the standing JWC multiple as a static reference. Ten of these products are also exposed as paid MCP tools at https://straits.live/api/mcp. A free tier lives at https://straits.live/status and /api/v1/* with summary counts and shorter history windows on some series; human documentation, including an exact free-vs-premium comparison, at https://straits.live/api.","contact":{"email":"hello@straits.live"}},"servers":[{"url":"https://straits.live"}],"paths":{"/api/premium/snapshot":{"get":{"operationId":"getSnapshot","summary":"One-call snapshot: everything the Strait of Hormuz crisis monitor knows","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Full dashboard snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"status":{"type":"string","description":"open | restricted | closed"},"verdict":{"type":"object","description":"Status verdict with basis"},"oilPrices":{"type":"object","description":"Brent and WTI with history"},"dailyTransits":{"type":"object","description":"IMF PortWatch daily transit count vs pre-crisis baseline"},"insurance":{"type":"object","description":"War-risk insurance multiple"},"hormuzIndex":{"type":"object","description":"Crisis Pressure and Escalation Forecast composites with component audit"},"dataHealth":{"type":"object","description":"Per-section freshness: source + verifiedAt"}},"additionalProperties":true,"required":["schema","status"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/vessels":{"get":{"operationId":"getVessels","summary":"Per-vessel intelligence: live-AIS manifest, sanctioned-in-strait, risk bands, raw AIS positions","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Vessel intelligence bundle","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"ais":{"type":"object","description":"Latest raw AIS positions with a trust predicate (source + trusted flag)"},"manifest":{"type":"object","description":"Live-AIS vessel manifest (MMSI-keyed; flag derived from the MMSI MID)","properties":{"count":{"type":"number"},"source":{"type":"string"},"vessels":{"type":"array","items":{"type":"object"}}}},"sanctionedInStrait":{"type":"object","description":"OFAC-sanctioned vessels currently in the strait, with program detail"},"sanctionsReference":{"type":"object","description":"OFAC + UK sanctions reference-list sizes; per-IMO multi-body detail at /api/premium/vessel/{imo}"},"riskBands":{"type":"object","description":"Per-vessel risk bands keyed by MMSI and IMO"},"darkFleet":{"type":"array","description":"AIS-dark (gone dark) vessel list","items":{"type":"object"}}},"additionalProperties":true,"required":["schema","manifest"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/history/{feed}":{"get":{"operationId":"getHistory","summary":"Historical series: year-deep stranded and AIS-gap counts, 5-min index, daily transits","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"feed","in":"path","required":true,"description":"index-5min: both Hormuz indices at 5-minute cadence. transits: complete daily IMF PortWatch history, enriched per day with the 7-day moving average, pre-crisis-baseline deviation, and reopening-threshold headroom. stranded: hourly stranded-vessel counts, up to a year. ais-gaps: hourly AIS-dark counts, up to a year.","schema":{"type":"string","enum":["index-5min","transits","stranded","ais-gaps"]}},{"name":"days","in":"query","required":false,"description":"index-5min only: window in days, 1-30 (default 7)","schema":{"type":"integer","minimum":1,"maximum":30,"default":7}}],"responses":{"200":{"description":"Historical series","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"feed":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"count":{"type":"number"},"points":{"type":"array","items":{"type":"object"}}},"additionalProperties":true,"required":["schema","feed"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/brief":{"get":{"operationId":"getBrief","summary":"AI-assisted daily situation brief as structured JSON, by date or latest","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"date","in":"query","required":false,"description":"YYYY-MM-DD; omit for the latest brief","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Daily situation brief","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"date":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"brent":{"type":["number","null"]},"transitsToday":{"type":["number","null"]},"generatedAt":{"type":["string","null"]}},"additionalProperties":true,"required":["schema","date","bullets"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/vessel/{imo}":{"get":{"operationId":"getVesselDossier","summary":"Single-vessel sanctions + risk dossier by IMO: unified multi-body (OFAC + UK) sanctions, identity, risk band, dark-activity","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"imo","in":"path","required":true,"description":"7-digit IMO number of the vessel","schema":{"type":"string","pattern":"^\\d{7}$"}}],"responses":{"200":{"description":"Single-vessel dossier","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"imo":{"type":"string"},"sanctioned":{"type":"boolean"},"identity":{"type":["object","null"],"description":"Merged name, flag, ship type, tonnage, year built, owner"},"sanctions":{"type":["object","null"],"description":"Unified multi-body view: listedBy plus a bodies[] array (OFAC and/or UK) each with its own detail and listing date"},"riskBand":{"type":["string","null"]},"darkActivity":{"type":["object","null"],"description":"AIS-gap record if the vessel has gone dark"}},"additionalProperties":true,"required":["schema","imo","sanctioned"]}}}},"402":{"description":"Payment Required"},"404":{"description":"IMO not listed by OFAC or the UK and no dark-activity record (not charged)"}}}},"/api/premium/export":{"get":{"operationId":"getExport","summary":"Bulk history export: every requested series at full retained history in one archive","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.250000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"feeds","in":"query","required":false,"description":"Comma-separated subset of index-5min, stranded, ais-gaps, transits; omit for all","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv for a multi-section download","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Multi-series archive (JSON, or CSV when format=csv)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/csv":{"schema":{"type":"string"}}}},"402":{"description":"Payment Required"}}}},"/api/premium/stream/session":{"post":{"operationId":"createStreamSession","summary":"Buy a signed token for a bounded real-time Server-Sent Events window","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Stream session token","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"sid":{"type":"string"},"token":{"type":"string"},"streamUrl":{"type":"string","description":"Open an EventSource GET here within the window"},"expiresAt":{"type":"string","format":"date-time"},"windowSeconds":{"type":"number"}},"additionalProperties":true,"required":["schema","token","streamUrl"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/webhooks":{"post":{"operationId":"subscribeWebhook","summary":"Register a signed threshold-alert webhook (verdict flip, index band cross, threshold breach)","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https:// endpoint to receive signed POSTs"},"events":{"type":"array","description":"Subset of flip, band, breach; omit for all","items":{"type":"string","enum":["flip","band","breach"]}}},"required":["url"]}}}},"responses":{"200":{"description":"Subscription created (funds 30 days or 100 deliveries)","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"id":{"type":"string"},"secret":{"type":"string","description":"HMAC key for X-Straits-Signature; store it"},"events":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"},"deliveriesRemaining":{"type":"number"}},"additionalProperties":true,"required":["schema","id","secret"]}}}},"400":{"description":"Invalid or missing https:// url (not charged)"},"402":{"description":"Payment Required"}}}},"/api/premium/hormuz/flags":{"get":{"operationId":"getHormuzFlags","summary":"Hormuz flag rollup: live-AIS vessel population by flag state, with per-flag sanctioned tallies","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Flag rollup over the live vessel population","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"health":{"type":"object","description":"AIS source + trusted flag; numbers are untrustworthy when not trusted"},"vessel_count":{"type":"number"},"distinct_flags":{"type":"number"},"sanctioned_count":{"type":"number"},"sanctioned_share":{"type":"number","description":"0-1 fraction of the population that is OFAC-listed"},"top_flags":{"type":"array","description":"Top flag states by vessel count; each carries a sanctioned_count","items":{"type":"object"}},"omitted":{"type":"object","description":"Fields intentionally not provided (no source): top_operators, direction"}},"additionalProperties":true,"required":["schema","top_flags"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/hormuz/risk-screen":{"get":{"operationId":"getHormuzRiskScreen","summary":"Shadow-fleet risk screen: the live-AIS vessel population ranked worst-first, each hull with its risk band, typed reasons, and sanctions-body matches (flagged hulls by default; ?all=1 for the whole population)","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"all","in":"query","required":false,"description":"Set to 1 to include the cleared low-band hulls; default returns only the flagged hulls (high + moderate). counts always cover the whole population.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Ranked per-vessel risk screen","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"health":{"type":"object","description":"AIS source + trusted flag; the screen is untrustworthy when not trusted"},"counts":{"type":"object","description":"Whole-population tallies: total, high, moderate, low, sanctioned, dark, spoofed"},"reasonKey":{"type":"object","description":"Human labels for the reason codes (ofac_sdn, ais_dark, foc_tanker, imo_spoofed)"},"vesselsInclude":{"type":"string","enum":["flagged","all"],"description":"Which hulls the vessels array carries (flagged = high + moderate; all with ?all=1)"},"vessels":{"type":"array","description":"Per-hull rows ranked worst-first: mmsi, imo, name, flag, band, reasons[] (codes), sanctionedBy[] (ofac/uk). Flagged hulls only by default; ?all=1 adds the cleared low band.","items":{"type":"object"}}},"additionalProperties":true,"required":["schema","vessels","counts"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/bunker":{"get":{"operationId":"getBunker","summary":"Bunker & marine-fuel prices ($/tonne): current VLSFO/IFO380/MGO for Fujairah, Singapore, Rotterdam, plus the derived Fujairah premium over each benchmark hub","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Current bunker prices with derived Fujairah spreads","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"stale":{"type":"boolean","description":"true when the latest scrape is older than 12 hours"},"ports":{"type":"array","description":"One row per port: portKey, portLabel, vlsfo, ifo380, mgo ($/tonne, null when a grade was unavailable), currency, unit, asOf","items":{"type":"object"}},"spreads":{"type":"object","description":"Fujairah VLSFO premium over each hub: fujairahVsSingaporeVlsfo, fujairahVsRotterdamVlsfo (positive = Fujairah dearer; null when a grade is absent)"}},"additionalProperties":true,"required":["schema","ports"]}}}},"402":{"description":"Payment Required"}}}},"/api/premium/risk-premium":{"get":{"operationId":"getRiskPremium","summary":"War-risk transit premium nowcast: a live modeled war-risk insurance multiple (Nx over the peace baseline, 1x-16x scale) for the strait, recomputed every 5 minutes from throughput, escalation, OVX, and event signals, with the standing Lloyd's JWC multiple carried as a static reference","tags":["Premium"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Live modeled war-risk premium with drivers, a static JWC reference, and confidence","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string"},"asOf":{"type":"string","format":"date-time"},"modeledMultiple":{"type":"number","description":"Live modeled war-risk multiple, 1x (peace) to 16x (closure-consistent). The headline figure."},"band":{"type":"string","enum":["baseline","elevated","uneconomic","severe","closure-level"]},"confidence":{"type":"number","description":"0-1; degrades when driver feeds are stale/missing or escalation-market volume is thin"},"reference":{"type":"object","description":"Static context: jwcMultiple (the standing Lloyd's JWC multiple, manually set and infrequently changed), asOf, source, and a note. NOT a live comparator."},"vlccWarPremiumUsd":{"type":["object","null"],"description":"Modeled VLCC war-premium band (low/high USD per voyage): the JWC reference band rescaled to the modeled multiple"},"drivers":{"type":"object","description":"Per-driver score, raw value, health, and weight: throughput, escalation, ovx, event"},"degraded":{"type":"array","description":"Drivers that were stale or missing and dropped out of the estimate","items":{"type":"object"}}},"additionalProperties":true,"required":["schema","modeledMultiple","band","confidence"]}}}},"402":{"description":"Payment Required"}}}}}}