> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/websocket.md).

# Websocket

### Websocket URL

#### Mainnet

```url
wss://api.hydromancer.xyz/ws
```

#### Testnet

```
wss://api-testnet.hydromancer.xyz/ws
```

### Authentication

Include your API key as a query parameter in the connection URL:

```
wss://api.hydromancer.xyz/ws?token=your-api-key-here
```

### Subscribe

```
{ 
    "type": "subscribe",
    "subscription": {
        "type": "userFills",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
    }
} 
```

### Unsubscribe

```
{ 
    "type": "unsubscribe",
    "subscription": {
        "type": "userFills",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
    }
} 
```

### Live Message Chunking

For improved connection stability during high-volume periods, enable chunked message delivery by adding `liveFormat=chunked-v1` to your connection URL:

```
wss://api.hydromancer.xyz/ws?token=your-api-key&liveFormat=chunked-v1
```

For `chunked-v1` connections, large batched live messages (fills, orders, trades, etc.) are split by item count into smaller chunks with metadata (`chunk`, `totalChunks`, `batchId`) for reassembly. This is fully backward compatible — existing clients without `liveFormat` see no change.

See [Live Message Chunking](/readme/websocket/live-message-chunking.md) for full details.

### Heartbeats

To see if a client is still active the server will send a ping message every 60 seconds, please make sure to respond with a pong to keep the connection alive.

Server sends:

```json
{ 
    "type": "ping"
} 
```

Respond with:

```json
{ 
    "type": "pong"
} 
```