userNonFundingLedgerEvents

Stream specific users' non funding ledger events

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

{"type": "userNonFundingLedgerEvents", "channel": "userNonFundingLedgerEvents"}

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

Subscribe

{ 
    "type": "subscribe",
    "subscription": {
        "type": "userNonFundingLedgerEvents",
        "addresses": ["0x574bafce69d9411f662a433896e74e4f153096fa"],
        "dex": "dex_name", // optional; "main" (alias "hyperliquid") = native dex, or a HIP-3 dex name. Leave out for all events
        "addStakingEvents": bool // optional false by default
    }
} 

Unsubscribe

{ 
    "type": "unsubscribe",
    "subscription": {
        "type": "userNonFundingLedgerEvents",
        "addresses": ["0x574bafce69d9411f662a433896e74e4f153096fa"],
        "dex": "dex_name", // optional; "main" (alias "hyperliquid") = native dex, or a HIP-3 dex name. Leave out for all events
        "addStakingEvents": bool // optional false by default
    }
}

userNonFundingLedgerEvents data format

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

Each ledger event represents a balance change from a specific user's perspective. Key fields:

• user: The primary address this event affects (always matches one of your subscribed addresses)

• role: The user's role in the event:

  • "user" - Single-party events (deposits, withdrawals, account class transfers, liquidations)

  • "sender" - User is sending funds to another party

  • "receiver" - User is receiving funds from another party

• counterparty: The other address involved in transfers (only present for bilateral transactions)

• counterpartyDex: The DEX/chain of the counterparty (omitted when "hyperliquid")

Important: For transfers, you only receive the perspective where user matches your subscribed address. For example, if Alice sends funds to Bob and you're subscribed to Alice, you receive the sender perspective with Alice as user and Bob as counterparty. You do NOT receive Bob's receiver perspective unless you're also subscribed to Bob's address.

Each event contains a timestamp, hash, and delta fields describing the ledger change. Events are batched per block.

{
  "type": "userNonFundingLedgerEvents",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "events": [
    {
     "time": "1704067200000",
     "hash": "0xabc123...",
     "eventType": "SpotTransfer",
     "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
     "counterparty": "0x123456...",
     "role": "sender",
     "amount": "1000.0",
     "token": "USDC",
     "usdcValue": "1000.0",
     "fee": "1.5",
     "feeToken": "USDC",
     "nativeTokenFee": "0.1",
     "nonce": 12345
    }
  ]
}

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 ledger events
        ws.send(JSON.stringify({
            type: 'subscribe',
            subscription: {
                type: 'userNonFundingLedgerEvents',
                addresses: ["0x574bafce69d9411f662a433896e74e4f153096fa"]
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'userNonFundingLedgerEvents') {
        console.log(`Received ${msg}`);
    }
});

Python

import websocket
import json
import os

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

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "type": "subscribe",
            "subscription": {
                "type": "userNonFundingLedgerEvents",
                "addresses": ["0x574bafce69d9411f662a433896e74e4f153096fa"]
            }
        }))
    elif msg['type'] == 'ping':
        print("Received ping, sending pong")
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'userNonFundingLedgerEvents':
        print(f"Received {msg}")
    elif msg['type'] == 'subscriptionUpdate':
        print(f"Subscription update: {msg}")
    elif msg['type'] == 'error':
        print(f"Error: {msg}")
    else:
        print(f"Unknown message type: {msg}")

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

All possible ledger event types

spotTransfer

{
    "time": "1704067200000",
    "hash": "0xabc123...",
    "eventType": "SpotTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0x123456...",
    "role": "sender",
    "amount": "1000.0",
    "token": "USDC",
    "usdcValue": "1000.0",
    "fee": "1.5",
    "feeToken": "USDC",
    "nativeTokenFee": "0.1",
    "nonce": 12345
}

accountClassTransfer

{
    "time": "1704067200000",
    "hash": "0xdddeeef...",
    "eventType": "AccountClassTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "1500.0",
    "toPerp": true
}

withdraw

{
    "time": "1704067200000",
    "hash": "0xbbbccc...",
    "eventType": "Withdraw",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "2000.0",
    "fee": "5.0",
    "nonce": 12347
}

deposit

{
    "time": "1704067200000",
    "hash": "0x999aaa...",
    "eventType": "Deposit",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "5000.0",
    "isDeposit": true
}

vaultCreate

{
    "time": "1704067200000",
    "hash": "0xfff111...",
    "eventType": "VaultCreate",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0xvault123...",
    "role": "sender",
    "vault": "0xvault123...",
    "amount": "10000.0",
    "fee": "10.0"
 }

vaultDeposit

  {
    "time": "1704067200000",
    "hash": "0x222333...",
    "eventType": "VaultDeposit",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0xvault123...",
    "role": "sender",
    "vault": "0xvault123...",
    "amount": "5000.0"
  }

vaultWithdraw

{
    "time": "1704067200000",
    "hash": "0x444555...",
    "eventType": "VaultWithdraw",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0xvault123...",
    "role": "receiver",
    "vault": "0xvault123...",
    "requestedUsd": "3000.0",
    "commission": "50.0",
    "closingCost": "100.0",
    "basis": "2900.0",
    "netWithdrawnUsd": "2850.0"
  }

vaultDistribution

  {
    "time": "1704067200000",
    "hash": "0x666777...",
    "eventType": "VaultDistribution",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0xvault123...",
    "role": "receiver",
    "vault": "0xvault123...",
    "amount": "500.0"
  }

vaultLeaderCommission

  {
    "time": "1704067200000",
    "hash": "0x888999...",
    "eventType": "VaultLeaderCommission",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "amount": "100.0"
  }

liquidation

  {
    "time": "1704067200000",
    "hash": "0xaaabbb...",
    "eventType": "Liquidation",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "liquidatedNtl": "50000.0",
    "accountValue": "45000.0",
    "leverageType": "cross",
    "liquidatedPositions": [
      ["BTC", "0.5"],
      ["ETH", "10.0"]
    ]
  }

internalTransfer

{
    "time": "1704067200000",
    "hash": "0x111222...",
    "eventType": "InternalTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0x333444...",
    "role": "sender",
    "amount": "250.0",
    "fee": "0.5"
 }

subAccountTransfer

{
    "time": "1704067200000",
    "hash": "0x555666...",
    "eventType": "SubAccountTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "counterparty": "0x777888...",
    "role": "sender",
    "amount": "100.0"
 }

rewardsClaim

{
    "time": "1704067200000",
    "hash": "0x111222...",
    "eventType": "RewardsClaim",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "amount": "50.0"
}

accountActivationGas

{
    "time": "1704067200000",
    "hash": "0xeeefff...",
    "eventType": "AccountActivationGas",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "amount": "0.001",
    "token": "ETH"
  }

deployGasAuction

  {
    "time": "1704067200000",
    "hash": "0x555666...",
    "eventType": "DeployGasAuction",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "0.5",
    "token": "ETH"
  }

cStakingTransfer

  {
    "time": "1704067200000",
    "hash": "0x333444...",
    "eventType": "CStakingTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "1000.0",
    "token": "USDC",
    "isDeposit": true
  }

spotGenesis

  {
    "time": "1704067200000",
    "hash": "0xcccdddd...",
    "eventType": "SpotGenesis",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "role": "user",
    "amount": "1000000.0",
    "token": "USDC"
  }

send

  {
    "time": "1704067200000",
    "hash": "0xdef456...",
    "eventType": "Send",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "userDex": "hyperliquid",
    "counterparty": "0x789abc...",
    "counterpartyDex": "vertex",
    "role": "sender",
    "amount": "500.0",
    "token": "USDC",
    "usdcValue": "500.0",
    "fee": "2.0",
    "feeToken": "USDC",
    "nativeTokenFee": "0.05",
    "nonce": 12346
  }

perpDexClassTransfer

{
    "time": "1704067200000",
    "hash": "0xaaa111...",
    "eventType": "PerpDexClassTransfer",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "amount": "1000.0",
    "token": "USDC",
    "dex": "hyperliquid",
    "toPerp": true
}

activateDexAbstraction

{
    "time": "1704067200000",
    "hash": "0xbbb222...",
    "eventType": "ActivateDexAbstraction",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "dex": "hyperliquid",
    "token": "USDC",
    "amount": "10.0"
}

borrowLend

{
    "time": "1704067200000",
    "hash": "0xccc333...",
    "eventType": "BorrowLend",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "token": "USDC",
    "operation": "deposit",
    "amount": "5000.0",
    "interestAmount": "12.5"
}

borrowLendBackstopLiquidation

{
    "time": "1704067200000",
    "hash": "0xddd444...",
    "eventType": "BorrowLendBackstopLiquidation",
    "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
    "role": "user",
    "token": "USDC",
    "balanceChange": "-500.0"
}

If addStakingEvents is true also includes

Delegation

  {
    "time": "1704067200000",
    "hash": "0xbbbccc...",
    "eventType": "Delegation",
    "user": "0xa101544878fbf89a7393d44acceafa70820aa809",
    "validator": "0x5e8e92e7bebe1b69b975b4aeee57b09a04d1783b",
    "amount": "202.09235863",
    "currency": "USDC",
    "isUndelegate": true
  }

cDeposit

  {
    "time": "1704067200000",
    "hash": "0x777888...",
    "eventType": "CDeposit",
    "user": "0x037d8cef56de0f70f7870d4d9dd41974efa9f94b",
    "amount": "0.079789",
    "currency": "USDC"
  }

cWithdrawal

  {
    "time": "1704067200000",
    "hash": "0x999aaa...",
    "eventType": "CWithdrawal",
    "user": "0x426c3dad1de7e4b6fde4ee1d2daefb0589612c22",
    "amount": "50.0",
    "currency": "USDC",
    "isFinalized": false
  }

Error messages:

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

Common errors

1. Connection timeout - Respond to ping messages

2. Too many subscriptions - Maximum addresses exceeded

3. Invalid address format - Use valid Ethereum addresses

4. Invalid API key