README.md
# hormuz-strait
Real-time Strait of Hormuz monitoring for energy market and geopolitical risk research via the [Hormuz Strait Monitor](https://hormuzstraitmonitor.com) dashboard API.
## What it does
Fetches the current status of the Strait of Hormuz and presents a risk briefing covering:
- **Strait status** — open, restricted, or closed, with duration and description
- **Ship traffic** — current transits, 24h count, and percent of normal baseline
- **Oil price impact** — Brent crude price with 24h change and trend
- **Stranded vessels** — count by type (tankers, bulk, other) with daily change
- **Insurance risk** — war risk premium level, percentage, and multiplier vs. normal
- **Cargo throughput** — daily DWT vs. average with 7-day trend
- **Diplomatic status** — current situation, parties involved, and headline
- **Global trade impact** — percent of world oil/LNG at risk, daily cost, affected regions, alternative routes, and supply chain disruption
- **Crisis timeline** — chronological events (military, diplomatic, economic)
- **Tanker freight rates** — VLCC benchmark rate vs. pre-crisis baseline with trend
- **Latest news** — recent articles with sources and links
**This skill is read-only.** No authentication required — uses the public dashboard API.
## Triggers
- "Hormuz status", "Strait of Hormuz", "is Hormuz open"
- "shipping through the Gulf", "Persian Gulf tanker traffic"
- "oil chokepoint", "war risk premium", "Hormuz crisis"
- "energy supply chain risk", "oil transit disruption", "Middle East shipping"
- Any mention of Hormuz or Persian Gulf in context of oil, shipping, or geopolitical risk
## Platform
Works on **all platforms** (Claude Code, Claude.ai, and other agents). Only requires `curl` for the API call.
## Setup
```bash
# Choose finance-data-providers when prompted.
npx plugins add himself65/finance-skills
# Or install just this skill
npx skills add himself65/finance-skills --skill hormuz-strait
```
See the [main README](../../../../README.md) for more installation options.
## Reference files
- `references/api_schema.md` — Complete API response schema with field descriptions and data types
references/api_schema.md
# Hormuz Strait Monitor — Dashboard API Schema
**Endpoint:** `GET https://hormuzstraitmonitor.com/api/dashboard`
**Authentication:** None (public API)
**Response format:** JSON
---
## Top-level response
| Field | Type | Description |
|---|---|---|
| `success` | boolean | Whether the API call succeeded |
| `data` | object | Dashboard data (see sections below) |
| `timestamp` | string (ISO datetime) | Server response timestamp |
---
## `data.straitStatus`
Current operational status of the strait.
| Field | Type | Description |
|---|---|---|
| `status` | string | Current status enum (observed: "OPEN", "RESTRICTED", "CLOSED") |
| `since` | string (ISO date) | Date the current status began |
| `description` | string | Human-readable status description |
---
## `data.shipCount`
Ship transit statistics.
| Field | Type | Description |
|---|---|---|
| `currentTransits` | number | Ships currently transiting the strait |
| `last24h` | number | Total transits in the last 24 hours |
| `normalDaily` | number | Normal daily transit count (baseline) |
| `percentOfNormal` | number | Current traffic as percentage of normal |
---
## `data.oilPrice`
Brent crude oil price and recent movement.
| Field | Type | Description |
|---|---|---|
| `brentPrice` | number | Current Brent crude price (USD/barrel) |
| `change24h` | number | Absolute price change in last 24 hours |
| `changePercent24h` | number | Percentage price change in last 24 hours |
| `sparkline` | number[] | 24-hour price history (array of prices) |
---
## `data.strandedVessels`
Vessels unable to transit the strait.
| Field | Type | Description |
|---|---|---|
| `total` | number | Total stranded vessels |
| `tankers` | number | Stranded tanker vessels |
| `bulk` | number | Stranded bulk carriers |
| `other` | number | Other stranded vessels |
| `changeToday` | number | Change in stranded vessel count today |
---
## `data.insurance`
Marine insurance and war risk premium levels.
| Field | Type | Description |
|---|---|---|
| `level` | string | Risk level enum (observed: "NORMAL", "ELEVATED", "HIGH", "CRITICAL", "EXTREME") |
| `warRiskPercent` | number | Current war risk premium as percentage |
| `normalPercent` | number | Normal (baseline) insurance rate percentage |
| `multiplier` | number | Current rate as multiplier of normal rate |
---
## `data.throughput`
Cargo throughput in deadweight tonnage (DWT).
| Field | Type | Description |
|---|---|---|
| `todayDWT` | number | Today's cargo throughput in DWT |
| `averageDWT` | number | Average daily throughput in DWT |
| `percentOfNormal` | number | Today's throughput as percentage of average |
| `last7Days` | number[] | Daily DWT values for the last 7 days |
---
## `data.diplomacy`
Current diplomatic situation affecting the strait.
| Field | Type | Description |
|---|---|---|
| `status` | string | Diplomatic status enum (uppercase snake case; e.g., "TALKS_IN_PROGRESS") |
| `headline` | string | Current diplomatic headline |
| `date` | string (ISO date) | Date of the latest diplomatic development |
| `parties` | string[] | Parties involved |
| `summary` | string | Summary of the diplomatic situation |
---
## `data.globalTradeImpact`
Estimated impact on global trade if the strait is disrupted.
| Field | Type | Description |
|---|---|---|
| `percentOfWorldOilAtRisk` | number | Percentage of global oil supply at risk |
| `estimatedDailyCostBillions` | number | Estimated daily cost of disruption in billions USD |
| `affectedRegions` | object[] | List of affected regions (see below) |
| `lngImpact` | object | LNG-specific impact (see below) |
| `alternativeRoutes` | object[] | Available alternative shipping routes (see below) |
| `supplyChainImpact` | object | Broader supply chain impact (see below) |
### `affectedRegions[]`
| Field | Type | Description |
|---|---|---|
| `name` | string | Region name |
| `severity` | string | Impact severity enum (observed: "MODERATE", "HIGH", "CRITICAL") |
| `oilDependencyPercent` | number | Region's dependency on strait-transiting oil |
| `description` | string | Description of impact on this region |
### `lngImpact`
| Field | Type | Description |
|---|---|---|
| `percentOfWorldLngAtRisk` | number | Percentage of global LNG at risk |
| `estimatedLngDailyCostBillions` | number | Estimated daily LNG disruption cost (billions USD) |
| `topAffectedImporters` | string[] | Countries most affected by LNG disruption |
| `description` | string | Description of LNG impact |
### `alternativeRoutes[]`
| Field | Type | Description |
|---|---|---|
| `name` | string | Route name |
| `additionalDays` | number | Extra transit days vs. Hormuz route |
| `additionalCostPerVessel` | number | Extra cost per vessel (USD) |
| `currentUsageStatus` | string | Whether this route is currently in use |
### `supplyChainImpact`
| Field | Type | Description |
|---|---|---|
| `shippingRateIncreasePercent` | number | Percentage increase in shipping rates |
| `consumerPriceImpactPercent` | number | Estimated consumer price impact |
| `sprStatusDays` | number | Strategic Petroleum Reserve coverage in days |
| `keyDisruptions` | string[] | Key supply chain disruptions |
---
## `data.crisisTimeline`
Timeline of events related to the current situation.
### `events[]`
| Field | Type | Description |
|---|---|---|
| `date` | string (ISO date) | Event date |
| `type` | string | Event type enum (observed: "MILITARY", "DIPLOMATIC", "ESCALATION", "ECONOMIC") |
| `title` | string | Event title |
| `description` | string | Event description |
---
## `data.tankerRates`
VLCC tanker freight rate tracker for the Hormuz-adjacent benchmark route.
| Field | Type | Description |
|---|---|---|
| `currentRate` | number | Current freight rate on the benchmark route |
| `preCrisisRate` | number | Pre-crisis baseline rate on the same route |
| `changePercent` | number | Percentage change vs. the pre-crisis baseline |
| `route` | string | Benchmark route code (e.g., "AG-East (TD3C)") |
| `vesselType` | string | Vessel class (e.g., "VLCC") |
| `trend` | number[] | Recent rate history points (aligned with `unit`) |
| `unit` | string | Rate unit (e.g., "WS" for Worldscale, "USD/day" for time-charter equivalent) |
---
## `data.news`
Latest news articles related to the strait.
| Field | Type | Description |
|---|---|---|
| `title` | string | Article title |
| `source` | string | News source name |
| `url` | string | Link to the article |
| `publishedAt` | string (ISO datetime) | Publication timestamp |
| `description` | string | Article summary |
---
## `data.lastUpdated`
String (ISO datetime) — when the dashboard data was last updated. Appears directly on `data`, not as a nested object.
SKILL.md
---
name: hormuz-strait
description: >
Check the current status of the Strait of Hormuz — shipping transit data, oil price impact,
stranded vessels, insurance risk levels, diplomatic developments, and global trade impact.
Use this skill whenever the user asks about the Strait of Hormuz, Hormuz chokepoint, Persian Gulf
shipping risk, oil transit disruption, war risk premium in the Gulf, Middle East shipping routes,
tanker traffic through Hormuz, oil supply chain risk, or geopolitical risk affecting energy markets.
Triggers include: "Hormuz status", "Strait of Hormuz", "is Hormuz open", "shipping through the Gulf",
"oil chokepoint", "Persian Gulf tanker traffic", "war risk premium", "Hormuz crisis",
"energy supply chain risk", "oil transit disruption", "Middle East shipping",
any mention of Hormuz or Persian Gulf in context of oil, shipping, or geopolitical risk.
---
# Hormuz Strait Monitor Skill
Fetches real-time status of the Strait of Hormuz from the [Hormuz Strait Monitor](https://hormuzstraitmonitor.com) dashboard API. Covers shipping transits, oil prices, stranded vessels, insurance risk, diplomatic status, global trade impact, and crisis timeline.
**This skill is read-only.** It fetches public dashboard data — no authentication required.
---
## Step 1: Fetch Dashboard Data
Use `curl` to fetch the dashboard API:
```bash
curl -s https://hormuzstraitmonitor.com/api/dashboard
```
Parse the JSON response. The API returns `{ "success": true, "data": { ... }, "timestamp": "..." }`.
If `success` is `false` or the request fails, inform the user the monitor is temporarily unavailable and suggest checking https://hormuzstraitmonitor.com directly.
---
## Step 2: Identify What the User Needs
Match the user's request to the relevant data sections. If the user asks for a general status update, present all sections. If they ask about something specific, focus on the relevant section(s).
| User Request | Data Section | Key Fields |
|---|---|---|
| General status / "is Hormuz open?" | `straitStatus` | `status`, `since`, `description` |
| Ship traffic / transit count | `shipCount` | `currentTransits`, `last24h`, `normalDaily`, `percentOfNormal` |
| Oil price impact | `oilPrice` | `brentPrice`, `change24h`, `changePercent24h`, `sparkline` |
| Stranded / stuck vessels | `strandedVessels` | `total`, `tankers`, `bulk`, `other`, `changeToday` |
| Insurance / war risk | `insurance` | `level`, `warRiskPercent`, `normalPercent`, `multiplier` |
| Cargo throughput | `throughput` | `todayDWT`, `averageDWT`, `percentOfNormal`, `last7Days` |
| Diplomatic situation | `diplomacy` | `status`, `headline`, `parties`, `summary` |
| Global trade impact | `globalTradeImpact` | `percentOfWorldOilAtRisk`, `estimatedDailyCostBillions`, `affectedRegions`, `lngImpact`, `alternativeRoutes`, `supplyChainImpact` |
| Crisis timeline / events | `crisisTimeline` | `events[]` with `date`, `type`, `title`, `description` |
| Tanker freight rates / VLCC rates | `tankerRates` | `currentRate`, `preCrisisRate`, `changePercent`, `route`, `vesselType`, `trend`, `unit` |
| Latest news | `news` | `title`, `source`, `url`, `publishedAt`, `description` |
---
## Step 3: Present the Data
Format the results clearly for financial research. Adapt the presentation based on what the user asked for.
### General status briefing (default)
When the user asks for a general update, present a concise briefing covering all key sections:
1. **Strait Status** — lead with the current status (e.g., "OPEN", "RESTRICTED", "CLOSED"), how long it's been in that state, and the description
2. **Ship Traffic** — current transits, last 24h count, and percent of normal
3. **Oil Price** — Brent price with 24h change
4. **Stranded Vessels** — total count broken down by type, with today's change
5. **Insurance Risk** — risk level, war risk premium percentage, and multiplier vs. normal
6. **Cargo Throughput** — today's DWT vs. average, percent of normal
7. **Diplomatic Status** — current status, headline, and brief summary
8. **Global Trade Impact** — percent of world oil at risk, estimated daily cost, and top affected regions
9. **Tanker Freight Rates** — current VLCC rate on the benchmark route vs. pre-crisis baseline, with trend direction
### Formatting guidelines
- Use tables for structured data (vessel counts, affected regions, alternative routes)
- Highlight abnormal values — if `percentOfNormal` is below 80% or above 120%, call it out
- For `oilPrice.sparkline`, describe the trend (rising, falling, stable) rather than listing raw numbers
- For `throughput.last7Days`, describe the trend direction
- Show `lastUpdated` timestamp so the user knows data freshness
- For news items, include the source and link
- For crisis timeline events, present chronologically with event type labels
### Risk assessment
Based on the data, provide a brief risk assessment:
Values are returned uppercase.
| Insurance Level | Interpretation |
|---|---|
| `NORMAL` | No elevated risk — shipping operating normally |
| `ELEVATED` | Some disruption concerns — monitor closely |
| `HIGH` | Significant risk — active disruption or credible threat |
| `CRITICAL` | Severe disruption — major impact on global oil supply |
| `EXTREME` | Effective closure — war risk premiums at multi-decade highs, most commercial traffic halted |
If the strait status is anything other than fully open, highlight:
- The estimated daily cost to global trade
- Which regions are most affected and their oil dependency
- Available alternative routes with additional transit days and cost
- LNG impact if applicable
- SPR (Strategic Petroleum Reserve) status in days
---
## Step 4: Respond to the User
- Lead with the most important information: strait status and any active disruption
- Include data freshness (`lastUpdated` timestamp)
- If the situation is elevated or worse, proactively include the global trade impact summary
- Keep the response concise for routine "all clear" statuses; expand for active incidents
- Add a disclaimer: data is sourced from Hormuz Strait Monitor and may have delays
---
## Reference Files
- `references/api_schema.md` — Complete API response schema with field descriptions and data types
Read the reference file when you need exact field names or data type details.