> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# userNonFundingLedgerUpdates | Hyperliquid WebSocket API

> Hyperliquid userNonFundingLedgerUpdates: stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or more…

> [card] Credit Cost
>
> 1 per minute

> [card] Processing
>
> Realtime

> [!TIP]
>
> Estimate your monthly cost for this API using the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-non-funding-ledger-updates).

> [!NOTE]
>
> * Wire-compatible with `wss://api.hyperliquid.xyz/ws` `userNonFundingLedgerUpdates`subscription - same channel name, same `delta` shape per event.
> * Up to 1,000 wallet addresses per subscription. Use `addresses` (string\[]); aliases `user`(string) and `users` (string\[]) are also accepted.
> * Covers everything that moves USDC or token balances except funding payments - deposits, withdrawals, transfers, liquidations, vault actions, staking, rewards.
> * Live-only: `isSnapshot` is always `false` on this transport. For windowed history, use the Info API [`userNonFundingLedgerUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-non-funding-ledger-updates).

Subscribe to one or more wallets and receive every non-funding ledger event in real time: deposits, withdrawals, transfers, liquidations, vault deposits/withdrawals, staking, rewards, and more. Each push carries a list of `{time, hash, delta}` entries where `delta.type` identifies the event class and the remaining `delta` fields are type-specific.

**Supports up to 1,000 wallet addresses per subscription.**

## Endpoint

```
wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>
```

**key** `string` *required*

Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.

## Subscribe

Send this JSON message after the connection is established:

**method** `string` *required*

Always `"subscribe"`.

**subscription** `object` *required*

**properties**

**type** `string` *required*

Always `"userNonFundingLedgerUpdates"`.

**addresses** `string[]` *required*

One or more wallet addresses (lowercase `0x`-prefixed hex) to stream events for. Aliases `user` (string) and `users` (string\[]) are also accepted.

### Example

```bash wscat theme={null}
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"userNonFundingLedgerUpdates","addresses":["0x31ca8395cf837de08b24da3f660e77761dfb974b"]}}
```

```typescript TypeScript theme={null}
import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: {
      type: "userNonFundingLedgerUpdates",
      addresses: ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "userNonFundingLedgerUpdates") {
    const { user, nonFundingLedgerUpdates } = msg.data;
    for (const update of nonFundingLedgerUpdates) {
      console.log(user, update.delta.type, update.delta);
    }
  }
});
```

```python Python theme={null}
import asyncio, json, os
import websockets

async def main():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {
                "type": "userNonFundingLedgerUpdates",
                "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "userNonFundingLedgerUpdates":
                data = msg["data"]
                for update in data["nonFundingLedgerUpdates"]:
                    print(data["user"], update["delta"]["type"], update["delta"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json theme={null}
{
  "method": "unsubscribe",
  "subscription": {
    "type": "userNonFundingLedgerUpdates",
    "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"]
  }
}
```

> [!NOTE]
>
> Unsubscribe matches subscriptions by **exact body**. To narrow the wallet set, unsubscribe the original `addresses` list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "userNonFundingLedgerUpdates"` and a `data` object keyed to a single wallet. Multi-wallet subscriptions receive one push per affected wallet.

```json theme={null}
{
  "channel": "userNonFundingLedgerUpdates",
  "data": {
    "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
    "isSnapshot": false,
    "nonFundingLedgerUpdates": [
      {
        "time": 1781560864370,
        "hash": "0xd49c1a45a99fa0b4d615043dce4a050000d7322b4492bf867864c59868937a9f",
        "delta": {
          "type": "send",
          "amount": "0.012417",
          "destination": "0x6043daf4fbd6bd60601d277312a0664551302e70",
          "usdcValue": "0.012417",
          "nativeTokenFee": "0.0"
        }
      }
    ]
  }
}
```

**channel** `string`

Always `"userNonFundingLedgerUpdates"`.

**data** `object`

**properties**

**user** `string`

The wallet address this batch of updates belongs to.

**isSnapshot** `boolean`

Always `false` on this live stream. The field is preserved for parity with the public Hyperliquid WebSocket contract.

**nonFundingLedgerUpdates** `array\<object\>`

One entry per ledger event in the current block.

**update properties**

**time** `int`

Unix timestamp in milliseconds when the event was recorded.

**hash** `string`

L1 transaction hash that produced the event.

**delta** `object`

Event payload. `delta.type` identifies the event class; remaining `delta` fields are type-specific - see [Delta types](#delta-types) below.

### Delta types

`delta.type` is one of:

| Value | Description |
| - | - |
| `deposit` | USDC deposit into the perp account from an external chain. |
| `withdraw` | USDC withdrawal to an external chain. |
| `internalTransfer` | USDC transfer between Hyperliquid accounts. |
| `subAccountTransfer` | Transfer between a master account and one of its sub-accounts. |
| `accountClassTransfer` | Transfer between perp and spot accounts on the same wallet. |
| `spotTransfer` | Spot token transfer between wallets. |
| `liquidation` | Position closed by liquidation. |
| `vaultCreate` | Vault was created. |
| `vaultDeposit` | Deposit into a vault. |
| `vaultWithdraw` | Withdrawal from a vault. |
| `vaultDistribution` | Vault PnL distribution to depositors. |
| `vaultLeaderCommission` | Commission paid to a vault leader. |
| `spotGenesis` | Initial token allocation at spot deployment. |
| `rewardsClaim` | Claim of accrued rewards. |
| `accountActivationGas` | Gas fee paid to activate a new account. |
| `perpDexClassTransfer` | Transfer between different perp DEXes on the same wallet. |
| `deployGasAuction` | Gas-auction settlement for HIP-3 / HIP-4 deployments. |
| `send` | Native HYPE / token send. |
| `cStakingTransfer` | Transfer of staked HYPE between wallets. |
| `borrowLend` | Borrow or lend operation in the spot borrow-lend market. |

The remaining keys on `delta` vary by `type` and follow the public Hyperliquid `info` API `userNonFundingLedgerUpdates` payload. Common fields include `amount` (decimal string), `usdcValue` (decimal string), `coin` (string), `destination` / `source` (address strings), and `nativeTokenFee` (decimal string).

## Related endpoints

> [card] [userFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills.md)
>
> stream real-time trade fills for one or more wallets as they execute on HyperCore.

> [card] [orderUpdates](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/order-updates.md)
>
> stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or more wallets on HyperCore.

> [card] [l4BookUpdates](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/l4-book-updates.md)
>
> subscribe to a strictly-ordered, diff-only order-level (L4) book stream with per-coin sequence numbers and a server epoch for gap detection.

See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [WebSocket API reference](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/overview.md)

*Last reviewed: 2026-06-17*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.