#Connecting

The Hydra WebSocket delivers real-time intelligence data to connected clients.

#Endpoint

wss://api.hydra.fast/v1/stream

wss://api.hydra.fast/v1/stream?apiKey=hydra_k1_abc123...

#Authentication

The /v1/stream endpoint requires a valid API key. Pass it as a query parameter or header:

Query parameter:

wss://api.hydra.fast/v1/stream?apiKey=hydra_k1_abc123...

Header (where your WebSocket client supports custom headers):

x-api-key: hydra_k1_abc123...

If the key is missing, revoked, or expired, the server responds with an error and closes the connection with code 1008.

#Connecting — JavaScript

const apiKey = 'hydra_k1_abc123...'
const ws = new WebSocket(`wss://api.hydra.fast/v1/stream?apiKey=${apiKey}`)

ws.addEventListener('open', () => {
  console.log('Connected to Hydra stream')
})

ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data)
  console.log(msg.type, msg.data)
})

ws.addEventListener('close', (event) => {
  console.log('Disconnected:', event.code, event.reason)
})

ws.addEventListener('error', (error) => {
  console.error('WebSocket error:', error)
})

#Connecting — Python

import asyncio
import json
import websockets

API_KEY = "hydra_k1_abc123..."

async def connect():
    uri = f"wss://api.hydra.fast/v1/stream?apiKey={API_KEY}"
    async with websockets.connect(uri) as ws:
        async for message in ws:
            msg = json.loads(message)
            print(f"[{msg['type']}] {msg['data']}")

asyncio.run(connect())

#Connection Lifecycle

After connecting you will receive a connected message confirming your scopes:

{
  "type": "connected",
  "data": {
    "scopes": ["signals", "aircraft", "alerts", "cyber"],
    "ts": 1710000000000
  }
}

scopes reflects the scopes assigned to your API key. You will only receive events matching these scopes — no subscription step is needed.

#Initial Snapshot

On connect, the server automatically sends the current state for each of your scopes (active aircraft, vessels, recent signals, etc.) so you don't need separate REST calls.

To skip the initial snapshot (useful for bots that only want live updates), append snapshot=false:

wss://api.hydra.fast/v1/stream?apiKey=hydra_k1_abc123...&snapshot=false

#Keep-Alive

The server sends WebSocket protocol-level ping frames every 15 seconds. Most WebSocket libraries respond to these automatically. If you stop receiving pings, assume the connection is dead and reconnect.

#Rate Limiting

Each IP is limited to 10 concurrent WebSocket connections. Exceeding this limit returns HTTP 429 Too Many Connections and the upgrade is rejected.

#Close Codes