builderApprovedNonFundingLedgerEvents

Stream every non-funding ledger update of users who had an active fee approval for your builder at the block.

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

{"type": "builderApprovedNonFundingLedgerEvents", "channel": "builderApprovedNonFundingLedgerEvents"}

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.

What it streams

Deposits, withdrawals, transfers, vault activity, liquidations and every other non-funding ledger update of users who held an active fee approval for your builder at the block of the update. Funding is excluded here and served by builderApprovedFundings.

Each event is delivered per participant: a transfer between two users who both approved your builder arrives twice, once with role: "sender" and once with role: "receiver", each naming that side's user. Events with a single participant carry role: "user". This is the same view userNonFundingLedgerEvents gives each of them, and the delta object is the one allUserNonFundingLedgerEvents sends for the same event, so the ledger wire shape is shared across channels.

It follows the rules of builderApprovedFills:

• Attribution comes from approval state at the block, not from anything on the event itself, and revoking an approval does not retract past events.

• A user may hold approvals from several builders. Each subscribed builder receives its own copy.

• An approval is treated as revoked only when its max fee rate is set to exactly 0%.

Subscribe

{
    "type": "subscribe",
    "subscription": {
        "type": "builderApprovedNonFundingLedgerEvents",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
    }
}

builder is required and must be a 20-byte hex address. It is matched case-insensitively.

Unsubscribe

{
    "type": "unsubscribe",
    "subscription": {
        "type": "builderApprovedNonFundingLedgerEvents",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
    }
}

Ledger event data format

Each entry names the attributed participant and their role, the block time in milliseconds, the transaction hash, the txIndex within the block, and the delta describing the ledger change. Events are batched per block; both sides of a transfer share one txIndex and always arrive in the same message.

This channel is always chunked. Messages carry chunk, totalChunks and batchId on every connection, whether or not you passed liveFormat=chunked-v1, so a large batch never arrives as one oversized frame. Group by batchId, order by chunk, and you have the block's complete batch when you hold totalChunks of them. See Live Message Chunking.

Reconnection Note: When reconnecting with a session, replay and live events may overlap. Deduplicate using (time, txIndex, user, role) - skip entries whose tuple you have already processed. See Session Management for details.

{
  "type": "builderApprovedNonFundingLedgerEvents",
  "channel": "builderApprovedNonFundingLedgerEvents",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "ledgerEvents": [
    {
      "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      "role": "sender",                 // "user", "sender" or "receiver"
      "time": 1704067200000,            // block time (ms)
      "hash": "0xabc...def",
      "txIndex": 3,
      "delta": {
        "type": "internalTransfer",
        "usdc": "1000.0",
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
        "destination": "0x123...456",
        "fee": "0.0",
        "users": ["0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"]
      }
    },
    {
      "user": "0x123...456",
      "role": "receiver",
      "time": 1704067200000,
      "hash": "0xabc...def",
      "txIndex": 3,
      "delta": {
        "type": "internalTransfer",
        "usdc": "1000.0",
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
        "destination": "0x123...456",
        "fee": "0.0",
        "users": ["0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"]
      }
    }
  ]
}

The delta variants (deposit, withdraw, internalTransfer, spotTransfer, vaultDeposit, liquidation, ...) are documented on allUserNonFundingLedgerEvents.

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({
            type: 'subscribe',
            subscription: {
                type: 'builderApprovedNonFundingLedgerEvents',
                builder: '0xb84168cf3be63c6b8dad05ff5d755e97432ff80b'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'builderApprovedNonFundingLedgerEvents') {
        console.log(`Received ${msg.ledgerEvents.length} approved ledger events`);
    }
});

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": "builderApprovedNonFundingLedgerEvents",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
            }
        }))
    elif msg['type'] == 'ping':
        print("Received ping, sending pong")
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'builderApprovedNonFundingLedgerEvents':
        print(f"Received {len(msg['ledgerEvents'])} approved ledger events")
    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()

Error messages:

{
    "type": "error",
    "message": "Builder address required for builderApprovedNonFundingLedgerEvents subscription"
}

Common errors

1. Builder address required for builderApprovedNonFundingLedgerEvents subscription

2. Invalid address format

3. Too many subscriptions - Maximum builder subscriptions per API key

4. Invalid API key