userFills

Stream live fills of many users from a single connection.

Subscribe

{ 
    "type": "subscribe",
    "subscription": {
        "type": "userFills",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"],
        "aggregateByTime": true // optional
    }
} 

Unsubscribe

{ 
    "type": "unsubscribe",
    "subscription": {
        "type": "userFills",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"],
        "aggregateByTime": true // optional
    }
}

Fill data format

Each fill contains an address and fill details, fills will be batched per block like:

Reconnection Note: When reconnecting with a session, replay and live events may overlap. Deduplicate using (time, txIndex) - skip fills where this tuple is at or before your last processed fill. See Session Management for details.

{
  "type": "userFills",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",              // price
        "sz": "1.5",                  // size
        "side": "B",                  // B=buy, A=sell
        "time": 1704067200000,        // timestamp (ms)
        "startPosition": "1.5",       // position before fill
        "dir": "Open Long",           // direction
        "closedPnl": "125.5",         // realized PnL (normalized)
        "hash": "0xabc...def",        // fill hash
        "oid": 12345678,              // order ID
        "crossed": false,             // was crossed
        "fee": "2.5",                 // fee amount (normalized)
        "tid": 87654321,              // trade ID
        "cloid": "client-123",        // client order ID (optional)
        "builderFee": "0.1",          // builder fee (normalized, optional)
        "deployerFee": "0.05",        // deployer fee (optional, HIP-3 only)
        "priorityGas": null,          // priority gas fee in HYPE (optional)
        "feeToken": "USDC",           // fee token
        "builder": "0x...",           // builder
        "twapId": 942341,             // Or null if not a twap
        "txIndex": 3                  // transaction index within block
      }
    ]
  ]
}

Examples

Javascript

const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

ws.on('message', (data) => {
    const msg = JSON.parse(data);

    if (msg.type === 'connected') {
        // Subscribe to fills
        ws.send(JSON.stringify({
            type: 'subscribe',
            subscription: {
                type: 'userFills',
                addresses: ['0x010461c14e146ac35fe42271bdc1134ee31c703a']
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'userFills') {
        console.log(`Received ${msg.fills.length} fills`);
    }
});

Python

Error messages:

{
    "type": "error",
    "message": "Invalid API key"
}

Common errors

1. Connection timeout - Respond to ping messages

2. Too many subscriptions - Maximum 1000 addresses

3. Invalid address format - Use valid Ethereum addresses

4. Invalid API key