# aviationapis

Pay-per-call aviation data APIs for AI agents. Paid in USDC on Solana mainnet via the [x402 protocol](https://x402.org) — no accounts, no API keys.

## Endpoints

| Path | Price (USD) | Purpose |
|------|------------:|---------|
| `POST /metar` | $0.01 | Current decoded airport weather observation |
| `POST /taf` | $0.01 | Terminal aerodrome forecast (decoded) |
| `POST /flight-category` | $0.01 | Flight-rules category for an airport |
| `POST /atis` | $0.01 | Live airport terminal information (ATIS) |
| `POST /aircraft-position` | $0.01 | Live aircraft position by flight or tail |
| `POST /flight-status` | $0.01 | Flight status, times, and gates |
| `POST /decode-metar` | $0.01 | Decode a raw METAR string |
| `POST /decode-taf` | $0.01 | Decode a raw TAF string |
| `POST /decode-notam` | $0.01 | Decode a raw NOTAM string |
| `POST /decode-acars` | $0.01 | Decode an ACARS message label and body |
| `POST /crosswind` | $0.01 | Crosswind and headwind components |
| `POST /density-altitude` | $0.01 | Pressure altitude and density altitude |
| `POST /great-circle-distance` | $0.01 | Great-circle distance, bearing, and ETE |
| `POST /airport-sun-times` | $0.01 | Sunrise, sunset, and civil twilight |

All endpoints accept a JSON body and return `application/json`.

### Airport endpoints (`/metar`, `/taf`, `/flight-category`, `/atis`)
Body: `{ "icao": "KSFO" }` — a 4-letter ICAO airport code.

### Flight endpoints (`/aircraft-position`, `/flight-status`)
Body: `{ "flight": "UAL123" }` or `{ "tail": "N12345" }` — provide one.

### Decoder endpoints (`/decode-metar`, `/decode-taf`, `/decode-notam`, `/decode-acars`)
Body: `{ "raw": "<string>" }` for METAR/TAF/NOTAM; `/decode-acars` takes `{ "label": "80", "text": "..." }` (or `{ "raw": "..." }`). Deterministic — you supply the text, no lookup; these never 404.

### Calculator endpoints (`/crosswind`, `/density-altitude`, `/great-circle-distance`, `/airport-sun-times`)
Deterministic aviation math from a JSON body (e.g. `/crosswind` takes `{ runway_heading_deg, wind_direction_deg, wind_speed_kt }`). See `/openapi.json` for each input schema.

## Free endpoints

- `GET /` — service descriptor (prices + schemas + examples)
- `GET /openapi.json` — OpenAPI 3.1 contract
- `GET /health` — liveness probe
- `GET /llms.txt` — agent-discoverability blurb
- `GET /docs.md` — this document

## Payment

First unpaid POST returns HTTP `402` with the payment requirements base64-encoded in the `payment-required` response header. Sign the appropriate USDC transfer and retry with the `PAYMENT-SIGNATURE` header. Use any x402 client library.

## Notes

- Data reflects the freshest values available at request time; results are cached briefly to keep latency low.
- Times are returned as ISO-8601 / Zulu where applicable. Temperatures in °C, distances in statute miles, altitudes in feet, speeds in knots.