#Connection

#Endpoint

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

An API key is required. See API Keys for how to generate one.

#Authentication

Pass your API key as a query parameter or as a request header.

Query parameter (recommended for browser/browser-like environments):

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 closes the connection with code 1008.

#Connection Lifecycle

#1. WebSocket Upgrade

Open a standard WebSocket connection with your API key:

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

#2. Connection Confirmation

On successful connection, the server sends:

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

scopes reflects the permissions assigned to your API key. You will only receive events matching these scopes.

#3. Initial Snapshot

Immediately after connection, the server sends the current state for each of your scopes:

To skip the snapshot and receive only live updates, append snapshot=false:

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

#4. Live Updates

After the snapshot, incremental updates stream in real-time as new data arrives.

#Keep-Alive

The server sends WebSocket ping frames every 15 seconds. Most WebSocket libraries handle pong responses automatically. If a pong is not received within 30 seconds, the server closes the connection.

#Disconnection & Reconnection

Use exponential backoff when reconnecting:

const API_KEY = 'hydra_k1_abc123...';

function connect(attempt = 0) {
  const ws = new WebSocket(`wss://api.hydra.fast/v1/stream?apiKey=${API_KEY}`);

  ws.onopen = () => {
    console.log('Connected');
    attempt = 0; // Reset on success
  };

  ws.onclose = () => {
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
    console.log(`Reconnecting in ${delay}ms...`);
    setTimeout(() => connect(attempt + 1), delay);
  };

  ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    handleMessage(message);
  };
}

#Error Handling

Connection errors return standard WebSocket close codes:

If rate limited (too many connections from your IP), the upgrade request returns HTTP 429 before the WebSocket handshake completes.