allUserNonFundingLedgerEvents

Stream all user non funding ledger events.

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

{"type": "allUserNonFundingLedgerEvents", "channel": "allUserNonFundingLedgerEvents"}

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

{ 
    "type": "subscribe",
    "subscription": {
        "type": "allUserNonFundingLedgerEvents",
        "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": "allUserNonFundingLedgerEvents",
        "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
    }
}

allUserNonFundingLedgerEvents 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 event contains a timestamp, hash, and delta object describing the ledger change. Events are batched per block.

{
  "type": "allUserNonFundingLedgerEvents",
  "channel": "allUserNonFundingLedgerEvents",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "events": [
    {
      "time": "1704067200000",
      "hash": "0xabc...def",
      "delta": {
        "type": "spotTransfer",
        "token": "USDC",
        "amount": "1000.0",
        "usdcValue": "1000.0",
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
        "destination": "0x123...456",
        "fee": "1.5",
        "nativeTokenFee": "0.1",
        "nonce": 12345,
        "feeToken": "USDC",
        "users": ["0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"]
      }
    }
  ]
}

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: 'allUserNonFundingLedgerEvents'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'allUserNonFundingLedgerEvents') {
        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": "allUserNonFundingLedgerEvents"
            }
        }))
    elif msg['type'] == 'ping':
        print("Received ping, sending pong")
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'allUserNonFundingLedgerEvents':
        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()

Delta types

spotTransfer

{
  "type": "spotTransfer",
  "token": "USDC",
  "amount": "1000.0",
  "usdcValue": "1000.0",
  "user": "0x...",
  "destination": "0x...",
  "fee": "1.5",
  "nativeTokenFee": "0.1",
  "nonce": 12345,
  "feeToken": "USDC",
  "users": ["0x..."]
}

accountClassTransfer

{
  "type": "accountClassTransfer",
  "usdc": "1000.0",
  "toPerp": true,
  "users": ["0x..."]
}

withdraw

{
  "type": "withdraw",
  "usdc": "1000.0",
  "nonce": 12345,
  "fee": "1.5",
  "users": ["0x..."]
}

deposit

{
  "type": "deposit",
  "usdc": "1000.0",
  "users": ["0x..."]
}

vaultCreate

{
  "type": "vaultCreate",
  "vault": "0x...",
  "usdc": "10000.0",
  "fee": "10.0",
  "users": ["0x..."]
}

vaultDeposit

{
  "type": "vaultDeposit",
  "vault": "0x...",
  "usdc": "5000.0",
  "users": ["0x..."]
}

vaultWithdraw

{
  "type": "vaultWithdraw",
  "vault": "0x...",
  "user": "0x...",
  "requestedUsd": "1000.0",
  "commission": "10.0",
  "closingCost": "5.0",
  "basis": "995.0",
  "netWithdrawnUsd": "985.0",
  "users": ["0x..."]
}

vaultDistribution

{
  "type": "vaultDistribution",
  "vault": "0x...",
  "usdc": "100.0",
  "users": ["0x..."]
}

vaultLeaderCommission

{
  "type": "vaultLeaderCommission",
  "user": "0x...",
  "usdc": "50.0",
  "users": ["0x..."]
}

liquidation

{
  "type": "liquidation",
  "liquidatedNtlPos": "10000.0",
  "accountValue": "-500.0",
  "leverageType": "Cross",
  "liquidatedPositions": [
    {
      "coin": "ETH",
      "szi": "-5.0"
    }
  ],
  "users": ["0x..."]
}

internalTransfer

{
  "type": "internalTransfer",
  "usdc": "1000.0",
  "user": "0x...",
  "destination": "0x...",
  "fee": "0.0",
  "users": ["0x...", "0x..."]
}

subAccountTransfer

{
  "type": "subAccountTransfer",
  "usdc": "500.0",
  "user": "0x...",
  "destination": "0x...",
  "users": ["0x...", "0x..."]
}

rewardsClaim

{
  "type": "rewardsClaim",
  "amount": "100.0",
  "users": ["0x..."]
}

accountActivationGas

{
  "type": "accountActivationGas",
  "amount": "0.1",
  "token": "ETH",
  "users": ["0x..."]
}

deployGasAuction

{
  "type": "deployGasAuction",
  "token": "ETH",
  "amount": "0.5",
  "users": ["0x..."]
}

cStakingTransfer

{
  "type": "cStakingTransfer",
  "amount": "1000.0",
  "isDeposit": true,
  "token": "HYPE",
  "users": ["0x..."]
}

spotGenesis

{
  "type": "spotGenesis",
  "token": "HYPE",
  "amount": "1000000.0",
  "users": ["0x..."]
}

send

{
  "type": "send",
  "user": "0x...",
  "destination": "0x...",
  "amount": "100.0",
  "usdcValue": "100.0",
  "fee": "1.0",
  "token": "USDC",
  "sourceDex": "",
  "destinationDex": "",
  "feeToken": "USDC",
  "nativeTokenFee": "0.1",
  "nonce": 12345,
  "users": ["0x..."]
}

perpDexClassTransfer

{
  "type": "perpDexClassTransfer",
  "amount": "1000.0",
  "token": "USDC",
  "dex": "hyperliquid",
  "toPerp": true,
  "users": ["0x..."]
}

activateDexAbstraction

{
  "type": "activateDexAbstraction",
  "dex": "hyperliquid",
  "token": "USDC",
  "amount": "10.0",
  "users": ["0x..."]
}

borrowLend

{
  "type": "borrowLend",
  "token": "USDC",
  "operation": "deposit",
  "amount": "5000.0",
  "interestAmount": "12.5",
  "users": ["0x..."]
}

borrowLendBackstopLiquidation

{
  "type": "borrowLendBackstopLiquidation",
  "token": "USDC",
  "balanceChange": "-500.0",
  "users": ["0x..."]
}

If addStakingEvents is true also includes

Delegation

{
  "type": "delegation",
  "user": "0xfe70356dd23cec3888f87f271000829b84fcab3c",
  "validator": "0xb8f45222a3246a2b0104696a1df26842007c5bc5",
  "amount": "0.92777075",
  "isUndelegate": true
}

cDeposit

{
  "type": "cDeposit",
  "amount": "634.70878203",
  "user": "0x4aeb81f12cbfdd605a8c9c395f4f097250eebb1a"
}

cWithdrawal

{
  "type": "cWithdrawal",
  "amount": "5.0",
  "isFinalized": true,
  "user": "0x0df3dc2eb13ab4784a17d7bfa19ad61585117554"
}

Error messages:

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

Common errors

1. Connection timeout - Respond to ping messages

2. Too many subscriptions - Maximum subscriptions per API key exceeded

3. Invalid API key