userIsolatedMarginUpdates

Stream live isolated margin updates for specific users.

Every live data message includes both routing identifiers with the same value:

{"type": "userIsolatedMarginUpdates", "channel": "userIsolatedMarginUpdates"}

Other payload fields are omitted above. Existing clients may continue routing on either field.

New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

Subscribe

{
    "method": "subscribe",
    "subscription": {
        "type": "userIsolatedMarginUpdates",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
    }
}

Unsubscribe

{
    "method": "unsubscribe",
    "subscription": {
        "type": "userIsolatedMarginUpdates",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
    }
}

Update data format

Updates are batched per block. There are two update types: isolated_margin and top_up_isolated_margin.

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

For cross/isolated leverage changes (updateLeverage action), see userLeverageUpdates.

Isolated margin update

Sent when a user adds or removes isolated margin on a position (updateIsolatedMargin action). Specifies the USDC delta.

{
  "type": "userIsolatedMarginUpdates",
  "channel": "userIsolatedMarginUpdates",
  "seq": 1,
  "cursor": 1704067201000,
  "updates": [
    {
      "update_type": "isolated_margin",
      "time": 1704067201000,
      "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      "coin": "BTC",
      "is_buy": true,
      "ntli": "500.00",
      "tx_index": 0
    }
  ]
}

Top-up isolated margin update

Sent when a user adjusts their isolated margin to reach a target leverage (topUpIsolatedOnlyMargin action). Unlike isolated_margin which specifies a USDC delta, this specifies the desired leverage directly.

{
  "type": "userIsolatedMarginUpdates",
  "channel": "userIsolatedMarginUpdates",
  "seq": 2,
  "cursor": 1704067202000,
  "updates": [
    {
      "update_type": "top_up_isolated_margin",
      "time": 1704067202000,
      "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      "coin": "ETH",
      "target_leverage": "8.0",
      "tx_index": 0
    }
  ]
}

Field reference

Field	Type	Description
update_type	string	"isolated_margin" or "top_up_isolated_margin"
time	number	Block timestamp (milliseconds since epoch)
user	string	User address (lowercase)
coin	string	Coin/market name (e.g. "ETH", "xyz:GOLD")
is_buy	bool	Side of the margin change (isolated_margin only)
ntli	string	Amount of margin added or removed (isolated_margin only)
target_leverage	string	Target leverage as float string (top_up_isolated_margin only)
tx_index	number	Transaction index within the 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') {
        ws.send(JSON.stringify({
            method: 'subscribe',
            subscription: {
                type: 'userIsolatedMarginUpdates',
                addresses: ['0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2']
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'userIsolatedMarginUpdates') {
        for (const update of msg.updates) {
            if (update.update_type === 'isolated_margin') {
                console.log(`${update.coin} is_buy=${update.is_buy} ntli=${update.ntli}`);
            } else if (update.update_type === 'top_up_isolated_margin') {
                console.log(`${update.coin} target_leverage=${update.target_leverage}`);
            }
        }
    }
});

Python

import websocket
import json
import os

def on_message(ws, message):
    msg = json.loads(message)

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {
                "type": "userIsolatedMarginUpdates",
                "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
            }
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'userIsolatedMarginUpdates':
        for update in msg['updates']:
            if update['update_type'] == 'isolated_margin':
                print(f"{update['coin']} is_buy={update['is_buy']} ntli={update['ntli']}")
            elif update['update_type'] == 'top_up_isolated_margin':
                print(f"{update['coin']} target_leverage={update['target_leverage']}")
    elif msg['type'] == 'subscriptionUpdate':
        print(f"Subscription update: {msg}")
    elif msg['type'] == 'error':
        print(f"Error: {msg}")

ws = websocket.WebSocketApp(
    f"wss://api.hydromancer.xyz/ws?token={os.environ.get('HYDROMANCER_API_KEY')}",
    on_message=on_message
)
ws.run_forever()

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