Hydra
Docs

How API key scopes control which data streams you receive.

Scopes & Streams

Unlike traditional pub/sub WebSockets, the Hydra stream does not require you to send subscribe/unsubscribe commands. Your API key's scopes determine which events you receive automatically on connect.

How It Works

  1. Create an API key in the Platform dashboard and assign it one or more scopes.
  2. Connect to /v1/stream with that key.
  3. The server immediately begins forwarding all matching events — no subscribe step needed.

Available Scopes

Scope Event types received Description
aircraft aircraft Military aircraft positions from ADS-B
vessels vessel Global vessel positions from AIS
signals signal Intelligence signals (general category)
alerts alert, signal (MISSILE_ALERT) Missile/rocket alerts
markets market, market_correlation Prediction market data and signal correlations
social x_post OSINT social media posts
airspace signal (AIRSPACE) Airspace restrictions, SIGMETs, NOTAMs
cyber signal (CYBER) Cyber threat pulses
earthquakes signal (EARTHQUAKE) Seismic events

Signal Category Filtering

Signal events are filtered by category. Some signal categories map to specific scopes rather than the base signals scope:

Signal category Required scope
MISSILE_ALERT alerts
AIRSPACE airspace
CYBER cyber
EARTHQUAKE earthquakes
All others signals

For example, if your key has scopes ["signals", "cyber"], you'll receive general signals and cyber threat signals, but not airspace or earthquake signals.

Checking Your Scopes

Your active scopes are returned in the connected message when you first connect:

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

To change your scopes, update your API key in the Platform dashboard and reconnect.

Example — Filtered Processing

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

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

  switch (msg.type) {
    case 'connected':
      console.log('Scopes:', msg.data.scopes)
      break
    case 'aircraft':
      handleAircraftUpdate(msg.data)
      break
    case 'signal':
      handleIntelSignal(msg.data)
      break
    case 'alert':
      handleMissileAlert(msg.data)
      break
    case 'market':
      handleMarketUpdate(msg.data)
      break
    case 'x_post':
      handleSocialPost(msg.data)
      break
  }
})