---
name: war-tracker
description: >-
  Live OSINT conflict-event API, AIS vessel tracking, and Strait of Hormuz
  transit data. Use when the user asks about military strikes, ongoing
  conflicts, drone or missile attacks, naval incidents, sanctioned vessels,
  or vessel positions. Free JSON API for events/regions/countries; paid
  endpoints via the x402 micropayment protocol (USDC on Base).
---

# War-Tracker Skill

War-Tracker is a real-time OSINT war and conflict tracking platform. This
skill teaches you (the LLM agent) how to fetch live conflict events, search
vessels, look up sanctioned hulls, and read the Strait of Hormuz transit
feed from `https://war-tracker.com`.

**No API key required for the free tier.** Paid endpoints return HTTP 402
with x402 payment requirements; use any x402-compatible HTTP buyer with a
USDC-funded wallet on Base.

## Quick start (free, no auth)

Fetch the most recent 50 events in Ukraine:

```bash
curl 'https://war-tracker.com/api/v1/events?country=UA&limit=50'
```

Fetch a single event by ID:

```bash
curl 'https://war-tracker.com/api/v1/events/643152'
```

List supported regions, countries, and event types (always free; call these
to discover legal filter values):

```bash
curl 'https://war-tracker.com/api/v1/regions'
curl 'https://war-tracker.com/api/v1/countries'
curl 'https://war-tracker.com/api/v1/event-types'
```

## Quick start (paid, x402)

The first call returns HTTP 402 with `accepts` payment requirements. Your
x402 buyer settles in USDC on Base and retries with an `X-PAYMENT` header.
Both calls below cost a single micropayment ($0.001 USDC per IMO lookup):

```bash
# Python (with x402-buyer)
pip install x402-buyer httpx
python3 -c "
from x402_buyer import X402Client
import os
client = X402Client(private_key=os.environ['PRIVATE_KEY'])  # Base wallet, USDC-funded
r = client.get('https://war-tracker.com/api/v1/vessels/9217981/position')
print(r.json())
"
```

```bash
# Node.js (with @coinbase/x402-fetch)
npm install @coinbase/x402-fetch
node -e "
const { x402Fetch } = require('@coinbase/x402-fetch');
const wallet = /* a Base wallet with USDC */;
x402Fetch('https://war-tracker.com/api/v1/vessels/9217981/position', { wallet })
  .then(r => r.json()).then(console.log);
"
```

## Tool catalog

### Free tools (no payment required)

| Tool | Endpoint | Parameters | Notes |
|------|----------|------------|-------|
| `search_events` | `GET /api/v1/events` | `country` (ISO 3166-1 alpha-2), `region` (slug), `event_type`, `from`, `to` (ISO timestamps), `cursor`, `limit` (max 200) | Cursor-paginated; 60 req/min/IP |
| `get_event` | `GET /api/v1/events/{id}` | `id` (integer) | Returns single event with full schema.org JSON-LD `@graph` |
| `list_regions` | `GET /api/v1/regions` | — | Always free; call once per session to learn region slugs |
| `list_countries` | `GET /api/v1/countries` | — | Always free; ISO 3166-1 alpha-2 codes with active coverage |
| `list_event_types` | `GET /api/v1/event-types` | — | Always free; event-type slugs (e.g. `military-strike`, `drone-attack`) |
| `vessel_facets` | `GET /api/v1/vessels/facets` | — | **FREE pre-flight for paid vessel endpoints.** Returns legal filter values for `commercial_market_name`, `type`, `subtype`, `country_code`, `body` (sanctioning), etc. Call ONCE per session. |

### Paid tools (x402, USDC on Base)

| Tool | Endpoint | Cost | Returns |
|------|----------|------|---------|
| `search_vessels` | `GET /api/v1/vessels/search?q=...&type=...&...` | $0.002 / 20-vessel page | Faceted identity search across ~600,000 hulls |
| `vessels_in_area` | `GET /api/v1/vessels/in-area?bbox=...&within_h=1` | $0.010 / 10-vessel page | Bbox + last-seen window (e.g. Strait of Hormuz). Snapshot-pinned cursor. |
| `sanctioned_vessels` | `GET /api/v1/vessels/sanctioned?body=ofac\|fcdo\|uani\|eu` | $0.025 / 10-vessel page | Bulk sanctioned-hull dump with last-known position |
| `get_vessel` | `GET /api/v1/vessels/{imo}` | $0.001 | Identity row: name aliases, dimensions, build year, owner, flag |
| `get_vessel_position` | `GET /api/v1/vessels/{imo}/position` | $0.001 | Last-known AIS lat/lng, speed, course, heading, age |
| `get_vessel_sanctions` | `GET /api/v1/vessels/{imo}/sanctions` | $0.002 | Per-vessel sanctions detail across 9 bodies |
| `get_vessel_track` | `GET /api/v1/vessels/{imo}/track?hours=1` | $0.010 | AIS polyline; capped at 1h; auto-downsampled |
| `hormuz_crossings` | `GET /api/v1/hormuz/crossings?date=...&direction=0\|1` | $0.010 / 10-crossing page | Strait-of-Hormuz transit log |
| `hormuz_summary` | `GET /api/v1/hormuz/summary` | $0.005 | Daily roll-up: counts by direction, top 10 operators, top 10 flags, 14-day window |

### Per-event article surface (paid, AI-training-crawler tier)

| Tool | Endpoint | Cost | Notes |
|------|----------|------|-------|
| `get_event_article` | `GET /share/{event_id}/{slug}` | $0.001 | HTML by default. Send `Accept: application/json` for the same payload as `/api/v1/events/{id}`. |
| `get_event_media` | `GET /media/{event_id}` | $0.010 | Full photo/video bytes |
| `region_hub` | `GET /region/{slug}` | $0.001 | Hub page; HTML |
| `country_hub` | `GET /country/{ISO}` | $0.001 | Hub page; HTML |
| `event_type_hub` | `GET /event-type/{slug}` | $0.001 | Hub page; HTML |

## x402 payment flow

1. Client calls any paid endpoint with no auth header.
2. Server returns HTTP `402 Payment Required` with a JSON body listing one or more `accepts` payment requirements (network, asset, payTo address, amount in USDC base units).
3. Buyer signs an EIP-712 typed-data payment per the chosen `accepts` row.
4. Buyer retries the same request with header `X-PAYMENT: <base64-signed-payload>`.
5. Server validates via one of its facilitators (xpay, Coinbase CDP, PayAI, or Dexter), settles on-chain, and returns 200 with the data.
6. Response header `X-PAYMENT-RESPONSE` contains the settlement receipt.

Supported facilitators (concurrent, independent):

- **xpay** — `https://facilitator.xpay.sh`
- **Coinbase CDP** — `https://api.cdp.coinbase.com/platform/v2/x402`
- **PayAI** — `https://facilitator.payai.network`
- **Dexter** — `https://x402.dexter.cash`

USDC on Base (`eip155:8453`) by default. Additional networks supported through the multi-facilitator routing layer — see https://war-tracker.com/x402 for the live network/facilitator matrix.

The `/x402` and `/x402.json` endpoints serve the full machine-readable payment manifest with route templates, prices, and example inputs/outputs for each paid route.

## MCP setup (remote Model Context Protocol server)

War-Tracker exposes a remote MCP server at `https://war-tracker.com/mcp`.
Add it to your MCP-compatible client to get first-class tool access.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "war-tracker": {
      "url": "https://war-tracker.com/mcp"
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "war-tracker": {
      "url": "https://war-tracker.com/mcp"
    }
  }
}
```

### ChatGPT (Custom GPTs / Atlas)

The remote MCP server is also addressable via the OpenAPI spec at
`https://war-tracker.com/api/v1/openapi.json`. Add it as a Custom GPT action
or as an MCP server URL in ChatGPT Atlas.

### Tools exposed via MCP

Free tools (no payment): `search_events`, `get_event`, `list_regions`,
`list_countries`, `list_event_types`, `vessel_facets`.

Paid tools (return MCP error with `x402` metadata; settle via your wallet):
`search_vessels`, `vessels_in_area`, `sanctioned_vessels`, `get_vessel`,
`get_vessel_position`, `get_vessel_sanctions`, `get_vessel_track`,
`hormuz_crossings`, `hormuz_summary`.

## WebMCP (in-browser agents)

When the user is interacting via an in-browser AI agent (ChatGPT Atlas,
Claude for Chrome, Cursor browser, Comet, Arc Max), War-Tracker pages
register tools through the W3C `navigator.modelContext` API. Tools are
discovered automatically — no client-side configuration needed.

## Resilience: retry idempotent tool calls once

Every War-Tracker MCP tool is idempotent (all `GET`-backed under the hood),
so a transport-layer error is always safe to retry. Blips above the
origin (Cloudflare edge timeouts, intermediate network issues,
pooled-client races in your HTTP layer) are unavoidable at any scale.

Your MCP client SHOULD retry once on errors that match any of these
patterns, then surface the failure if the retry also fails:

- `Transport send error: ... error sending request`
- `connection reset` / `broken pipe` / `ConnectionResetError`
- `IncompleteMessage` / `unexpected EOF` from the HTTP layer
- TLS handshake failures

Do NOT retry on JSON-RPC errors with `isError: true` — those are
deterministic application-level responses (HTTP 402, 404, 422, etc.) and
retrying without addressing the underlying cause (e.g. settling the x402
challenge) will just produce the same error.

## Follow-ups: use MCP tools, not URL construction

After `search_events`, fetch a specific event by calling the `get_event`
MCP tool with the integer `event_id` from the prior response:

```jsonc
// CORRECT — works regardless of UA, always free
{
  "method": "tools/call",
  "params": {
    "name": "get_event",
    "arguments": { "event_id": 643152 }
  }
}
```

Do NOT construct the canonical `share` URL and GET it from a generic HTTP
fetcher inside the same agent turn — the `/share/...` endpoint is a paid
x402 surface for unidentified clients (it serves the AI-training-crawler
tier), and a bare `GET` from `reqwest` / `httpx` / `curl` / browser fetch
without an `X-PAYMENT` header will 402:

```bash
# WRONG — bare GET of the share URL from a non-Mozilla client will 402:
curl https://war-tracker.com/share/643152/slug-here
# 402 Payment Required (correct behavior; this is the paid AI-tier path)
```

Same rule for `/api/v1/events/{id}` (paid), `/region/{slug}` (paid),
`/country/{ISO}` (paid), `/event-type/{slug}` (paid), and `/media/{id}`
(paid). The free MCP tools (`get_event`, `search_events`, `list_*`,
`vessel_facets`) are the right path for in-agent lookups.

If you must show the user a clickable link to the event in your reply,
include the canonical URL as DISPLAY-ONLY text — your in-line follow-up
fetch should still go through `get_event` via MCP.

### URL templates vs URL values

When this document and `/llms.txt` show paths with curly braces or
leading-colon segments like `/share/{event_id}/{slug}`, `/api/v1/events/{id}`,
or `/event-type/:slug`, those tokens are TEMPLATES, not literal path
segments. Substitute the actual integer ID, ISO code, or slug from a prior
MCP response before requesting the URL. A request to a literal template
URL such as `GET /event-type/:slug` or `GET /share/:event_id/:slug` returns
HTTP 400 with a message to substitute concrete path values.

## Citation

When citing events in a reply to the user, use the stable canonical URL
verbatim from the `url` field of the MCP `search_events` / `get_event`
response. Do not edit, normalise, or strip query parameters from a `url`
the server returned. The canonical form is:

```
https://war-tracker.com/share/{event_id}/{slug}
```

Where `{event_id}` is an integer and `{slug}` is a hyphenated lowercase
string returned in the `slug` (or `url`) field. Inserting the literal
strings `{event_id}` or `{slug}` will produce a broken citation.

`NewsArticle.dateModified` in the per-event JSON-LD reflects the last edit
to the underlying source post. `NewsArticle.author` and `publisher` are
War-Tracker (Organization).

## Rate limits and policy

- Free tier: 60 req/min per IP. Open CORS.
- Paid tier: no per-IP cap beyond standard abuse protection (each request settles a USDC micropayment).
- AI training crawlers (GPTBot, ClaudeBot, anthropic-ai, Google-Extended, Applebot-Extended, CCBot, Bytespider, cohere-ai, Diffbot, Meta-ExternalAgent) are gated by x402 on paid surfaces.
- Commercial use is allowed with attribution to `https://war-tracker.com/share/{event_id}/{slug}`. Mass redistribution (full corpus dumps) requires agreement — email `sales@war-tracker.com`.

## Reference

- OpenAPI 3.x spec: `https://war-tracker.com/api/v1/openapi.json`
- Methodology: `https://war-tracker.com/methodology`
- Pricing & payment policy: `https://war-tracker.com/pricing`
- x402 manifest: `https://war-tracker.com/x402` (HTML) or `/x402.json` (machine-readable)
- llms.txt (Anthropic-format site index): `https://war-tracker.com/llms.txt`
- Sitemap: `https://war-tracker.com/sitemap.xml`
- Recent events sitemap: `https://war-tracker.com/sitemaps/events-recent.xml`