Hydra
Docs

How to establish a WebSocket connection to the Hydra stream.

Connecting

The Hydra WebSocket endpoint delivers real-time stream data to connected clients. Authentication is handled via your JWT on connect.

Endpoint

wss://api.hydra.app/stream

Authentication

Pass your JWT as a query parameter or in the initial handshake:

wss://api.hydra.app/stream?token=eyJhbGci...

Connecting — JavaScript

const jwt = 'eyJhbGci...'
const ws = new WebSocket(`wss://api.hydra.app/stream?token=${jwt}`)

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

ws.addEventListener('message', (event) => {
  const msg = JSON.parse(event.data)
  console.log(msg.stream, 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

JWT = "eyJhbGci..."

async def connect():
    uri = f"wss://api.hydra.app/stream?token={JWT}"
    async with websockets.connect(uri) as ws:
        # Subscribe to desired streams
        await ws.send(json.dumps({
            "action": "subscribe",
            "streams": ["signals", "alerts", "cyber"]
        }))

        async for message in ws:
            msg = json.loads(message)
            print(f"[{msg['stream']}] {msg['type']}: {msg['data']}")

asyncio.run(connect())

Connection Lifecycle

After connecting you will receive a connected message:

{
  "type": "connected",
  "ts": 1710000000000,
  "data": {
    "sessionId": "sess-abc123",
    "address": "0xYourWalletAddress",
    "availableStreams": ["signals", "alerts", "cyber"],
    "serverTime": 1710000000000
  }
}

availableStreams reflects the streams in your JWT scope. You can only subscribe to streams listed here.

Heartbeat

The server sends a heartbeat every 30 seconds:

{ "type": "heartbeat", "ts": 1710000000000, "data": null }

If you miss three consecutive heartbeats, assume the connection is dead and reconnect.

Close Codes

Code Meaning
1000 Normal closure
1001 Server going away (maintenance)
4001 Invalid or expired JWT
4002 Insufficient token balance
4003 Rate limit exceeded
4004 Subscription not in JWT scope