> ## 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 wallets.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per minute</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-non-funding-ledger-updates).
</Tip>

<Info>
  * 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 <a href="https://goldrush.dev/docs/api-reference/hyperliquid-info/user-non-funding-ledger-updates" target="_blank" rel="noopener noreferrer">`userNonFundingLedgerUpdates`</a>.
</Info>

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>
```

<ParamField query="key" type="string" required>
  Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.
</ParamField>

## Subscribe

Send this JSON message after the connection is established:

<ParamField body="method" type="string" required>
  Always `"subscribe"`.
</ParamField>

<ParamField body="subscription" type="object" required>
  <Expandable title="properties">
    <ResponseField name="type" type="string" required>Always `"userNonFundingLedgerUpdates"`.</ResponseField>

    <ResponseField name="addresses" type="string[]" required>
      One or more wallet addresses (lowercase `0x`-prefixed hex) to stream events for. Aliases `user` (string) and `users` (string\[]) are also accepted.
    </ResponseField>
  </Expandable>
</ParamField>

### Example

<CodeGroup>
  ```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())
  ```
</CodeGroup>

## 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.
</Note>

## 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"
        }
      }
    ]
  }
}
```

<ResponseField name="channel" type="string">Always `"userNonFundingLedgerUpdates"`.</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="user" type="string">The wallet address this batch of updates belongs to.</ResponseField>
    <ResponseField name="isSnapshot" type="boolean">Always `false` on this live stream. The field is preserved for parity with the public Hyperliquid WebSocket contract.</ResponseField>

    <ResponseField name="nonFundingLedgerUpdates" type="array<object>">
      One entry per ledger event in the current block.

      <Expandable title="update properties">
        <ResponseField name="time" type="int">Unix timestamp in milliseconds when the event was recorded.</ResponseField>
        <ResponseField name="hash" type="string">L1 transaction hash that produced the event.</ResponseField>

        <ResponseField name="delta" type="object">
          Event payload. `delta.type` identifies the event class; remaining `delta` fields are type-specific - see [Delta types](#delta-types) below.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 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

<CardGroup cols={2}>
  <Card title="orderUpdates" href="/api-reference/hyperliquid-websocket/order-updates">stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or more wallets…</Card>
  <Card title="userFills" href="/api-reference/hyperliquid-websocket/user-fills">stream real-time trade fills for one or more wallets as they execute on HyperCore.</Card>
</CardGroup>

*Last reviewed: 2026-06-17*