# WAVE Gateway

> The unified API edge for the WAVE Protocol Plane. One base URL fronts every WAVE product and protocol
> with authentication, scope authorization, entitlement, rate-limiting, and usage metering, then
> reverse-proxies to the origin. Built for BOTH humans (account API keys) and autonomous agents
> (API keys OR x402 pay-per-use).

## Base URL
- Production: https://api.wave.online/v1
- Gateway host: https://gateway.wave.online

## Authentication (choose one)
- API key — send header `Authorization: Bearer <wave_key>` (issued to your WAVE organization).
  Humans and agents that have an account use this.
- x402 pay-per-use — autonomous agents with no account: make the request; on `402 Payment Required`,
  pay the quoted USDC amount and retry with the `X-PAYMENT` header. Settlement is verified by the WAVE hub.

## Authorization
Scopes are `resource:action` (e.g. `streams:read`, `clips:write`). Wildcards: `*` and `resource:*`.
The required scope is enforced per route; an unmapped /v1 route fails closed (403 ROUTE_NOT_MAPPED).

## Conventions for agents
- Responses are JSON. Errors: `{"error":{"code","message"}}` with a matching HTTP status.
- 401 = auth required/invalid · 403 = scope/entitlement · 429 = rate-limit/quota (honor `retry-after`).
- Per-product request/response shapes follow the OpenAPI in the docs.

## Products (API surfaces on this gateway)
streams, clips, voice, captions, chapters, analytics, webhooks, editor, phone (+ more — see docs).

## WAVE products (federated surfaces — jump between them)
Machine-readable registry: GET /.well-known/wave-products.json
- Gateway (live) — https://api.wave.online — unified auth · scope · meter · x402 edge for every WAVE API
- Dispatch (live) — https://dispatch.wave.online — AI model routing — pay-per-use LLM inference (x402 mainnet)
- Clips (live) — https://clips.wave.online — Clip Engine — turn live streams into shareable clips
- MoQ (preview) — https://moq.wave.online — Media-over-QUIC low-latency transport edge
- Bridge (preview) — https://bridge.wave.online — any-to-any contribution gateway
- Realtime (preview) — https://realtime.wave.online — live control & event plane — presence, pub/sub, streaming events (Durable Objects)
- Voice (preview) — https://voice.wave.online — real-time and batch voice — transcription, synthesis, and voice cloning
- Captions (preview) — https://captions.wave.online — live and on-demand captions — multi-language, broadcast-grade, rendered at
- Chapters (preview) — https://chapters.wave.online — auto-chaptering for any recording — segments, titles, and timestamps from
- Editor (preview) — https://editor.wave.online — programmatic timeline editing — cut, splice, and render video by API
- Phone (preview) — https://phone.wave.online — phone numbers, SIP, and PSTN bridging — live audio in and out of WAVE
- Collab (preview) — https://collab.wave.online — multi-user sessions — shared control rooms, presence, and live co-producti
- Podcast (preview) — https://podcast.wave.online — recording-to-podcast — episodes, RSS, and distribution from a single sourc
- Studio AI (preview) — https://studio-ai.wave.online — AI production director — automated switching, framing, and scene calls
- Transcribe (preview) — https://transcribe.wave.online — fast, accurate transcription — streaming and batch, any language
- Sentiment (preview) — https://sentiment.wave.online — real-time sentiment and moderation signals on audio, chat, and video
- Search (preview) — https://search.wave.online — semantic search across your media — transcripts, scenes, and clips, vector

## Protocols (per-protocol edges federate through this gateway)
srt, rtmp, webrtc, hls, dash (live) · ndi, dante, omt (broadcast transports) · moq (low-latency).

## Endpoints
- GET  /health         gateway liveness
- GET  /origin-health  origin liveness through the gateway
- POST /v1/clips        create a clip (scope clips:write) — served by the dedicated clip-engine spoke
- ANY  /v1/<product>    the product/protocol surfaces listed above

## Links
- Docs: https://docs.wave.online
- Threat model: https://gateway.wave.online/threat-model
- Home: https://wave.online