userLeverageUpdates

Stream live leverage updates for specific users.

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

{"type": "userLeverageUpdates", "channel": "userLeverageUpdates"}

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": "userLeverageUpdates",
        "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
    }
}

Unsubscribe

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

Update data format

Updates are batched per block, sorted by tx_index. This stream includes all three update types: leverage changes, isolated margin updates, and top-up isolated margin updates — combined and interleaved in block order for the subscribed addresses.

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 isolated margin updates only (without leverage changes), see userIsolatedMarginUpdates.

Leverage update

Sent when a user changes their leverage setting (updateLeverage action).

{
  "type": "userLeverageUpdates",
  "channel": "userLeverageUpdates",
  "seq": 1,
  "cursor": "500:1704067200000:0",
  "updates": [
    {
      "update_type": "leverage",
      "time": 1704067200000,
      "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      "coin": "ETH",
      "is_cross": true,
      "leverage": 10,
      "tx_index": 0
    }
  ]
}

Isolated margin update

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

{
  "type": "userLeverageUpdates",
  "channel": "userLeverageUpdates",
  "seq": 2,
  "cursor": "500:1704067201000:0",
  "updates": [
    {
      "update_type": "isolated_margin",
      "time": 1704067201000,
      "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      "coin": "BTC",
      "is_buy": false,
      "ntli": "0.223223",
      "tx_index": 0
    }
  ]
}

Top-up isolated margin update

Sent when a user adjusts their isolated margin to reach a target leverage (topUpIsolatedOnlyMargin action).

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

Field reference

Fields vary by update_type:

Field	Type	Present in	Description
update_type	string	all	"leverage", "isolated_margin", or "top_up_isolated_margin"
time	number	all	Block timestamp (milliseconds since epoch)
user	string	all	User address (lowercase)
coin	string	all	Coin/market name (e.g. "ETH", "BTC")
tx_index	number	all	Transaction index within the block
is_cross	bool	leverage	Whether cross margin mode
leverage	number	leverage	New leverage value
is_buy	bool	isolated_margin	Side of the margin change
ntli	string	isolated_margin	Amount of margin added or removed
target_leverage	string	top_up_isolated_margin	Target leverage as float string

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: 'userLeverageUpdates',
                addresses: ['0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2']
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'userLeverageUpdates') {
        for (const update of msg.updates) {
            if (update.update_type === 'leverage') {
                console.log(`${update.coin} leverage=${update.leverage} is_cross=${update.is_cross}`);
            } else 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": "userLeverageUpdates",
                "addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f7F2e2"]
            }
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'userLeverageUpdates':
        for update in msg['updates']:
            if update['update_type'] == 'leverage':
                print(f"{update['coin']} leverage={update['leverage']} is_cross={update['is_cross']}")
            elif 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