# war-tracker-client

Official lightweight Python client for the [War-Tracker](https://war-tracker.com) public API.

## Install

The War-Tracker source repository is private; install directly from the hosted sdist tarball:

```bash
pip install https://war-tracker.com/sdk/python/war-tracker-client-latest.tar.gz
```

To pin a specific version:

```bash
pip install https://war-tracker.com/sdk/python/war-tracker-client-0.1.0.tar.gz
```

Requires Python `>=3.10`. The only runtime dependency is `httpx`.

## Quick start

Taxonomy endpoints are always free (60 req/min per IP):

```python
from war_tracker import WarTrackerClient

client = WarTrackerClient()
for region in client.list_regions():
    print(region["slug"], region["name"])
```

Event list/detail via direct HTTP from scripts require [x402](https://war-tracker.com/x402)
payment (automation User-Agents are paywalled on `/api/v1/events*`). Use an
x402 buyer library or the remote MCP server at `https://war-tracker.com/mcp`.

```python
# Returns 402 for a typical httpx User-Agent unless you integrate an x402 buyer:
# client.list_events(country="UA", limit=10)
```

## Rate limit headers

After each request, inspect `client.last_rate_limit` for `X-RateLimit-Limit`,
`Remaining`, and `Reset`.