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

# Track Every Hyperliquid Wallet: the Wallet Firehose

> Hyperliquid has no public leaderboard or all-users API. GoldRush surfaces every active trader instead - stream fills from every wallet on HyperCore, then follow any set of addresses in one connection with zero rate limits. Powers copy-trade, whale alerts, and live trader dashboards.

The public Hyperliquid WebSocket caps you at **1000 subscriptions per IP**, and every REST endpoint is weight-rate-limited per IP and per address. That's nowhere near enough to track every active trader on Hyperliquid in real time - exactly what copy-trade, whale alerts, and "follow the flow" features need.

GoldRush's `walletTxs` subscription has **zero rate limits** and scales to thousands of concurrent wallet subscriptions on a single connection.

## No public "all users" or leaderboard endpoint

Hyperliquid's public `/info` API has no endpoint that lists every user, and the leaderboard you see in the frontend is backed by an internal endpoint that isn't part of the documented API - so there's no supported way to enumerate or scrape all addresses upstream. GoldRush gives you two supported paths instead:

* **Discover active traders in real time.** The [`allFills`](/api-reference/hyperliquid-websocket/all-fills) channel streams every fill on HyperCore across every wallet - each entry carries the trader's address, so the live tape doubles as a rolling census of who is active right now. [`liquidationFills`](/api-reference/hyperliquid-websocket/liquidation-fills) does the same for every liquidation.
* **Follow a cohort at scale.** Once you have a set of addresses (top traders, whales, a copy-trade list), the `walletTxs` firehose below streams all of their activity over a single connection with no per-IP or per-address limit - something the public 1000-subscription cap makes impossible.

For bulk historical address data - every fill and ledger event for a large wallet set landed in your own warehouse - use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore).

## What you get

* **One connection, many wallets.** Pass an array of wallet addresses; updates for any of them come through the same stream.
* **Pre-decoded events.** Fills, funding, vault actions, ledger events, deposits, withdrawals, and delegations come through as typed GraphQL union members - no parsing.
* **Liquidation context inline.** When a fill is part of a liquidation, the `liquidation` block is attached directly.
* **Sub-second latency.** Tokyo-colocated, validator-peered ingestion.

## Subscribe

<CodeGroup>
  ```typescript GoldRush SDK theme={null}
  import { GoldRushClient } from "@covalenthq/client-sdk";

  const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

  const SUBSCRIPTION_QUERY = `
    subscription {
      walletTxs(
        wallet_addresses: [
          "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
          "0x5078c2fbea2b2ad61bc840bc023ecb5df8b5ecaf",
          "0xba1ad77b1c46a7c2c43cf5e10c14e8f0d7d6d5e3"
        ]
        chain_name: HYPERCORE_MAINNET
      ) {
        tx_hash
        block_signed_at
        from_address
        decoded_details {
          ... on HypercoreFillTransaction {
            coin
            side
            price
            size
            closed_pnl
            fee
            fee_token
            builder
            builder_fee
            liquidation {
              method
              liquidated_user
              market_price
            }
          }
          ... on HypercoreFundingEvent {
            coin
            funding_rate
            funding_amount
          }
          ... on HypercoreDepositEvent { amount }
          ... on HypercoreWithdrawalEvent { amount }
          ... on HypercoreDelegationEvent {
            validator
            amount
            is_undelegate
          }
        }
      }
    }
  `;

  client.StreamingService.rawQuery(
    SUBSCRIPTION_QUERY,
    {},
    {
      next: (data) => console.log(JSON.stringify(data, null, 2)),
      error: (err) => console.error(err),
      complete: () => console.log("done"),
    }
  );
  ```

  ```python Python theme={null}
  import asyncio
  import os
  from gql import gql, Client
  from gql.transport.websockets import WebsocketsTransport

  WS_URL = "wss://streaming.goldrushdata.com/graphql"

  SUBSCRIPTION = gql("""
  subscription {
    walletTxs(
      wallet_addresses: [
        "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
        "0x5078c2fbea2b2ad61bc840bc023ecb5df8b5ecaf"
      ]
      chain_name: HYPERCORE_MAINNET
    ) {
      tx_hash
      block_signed_at
      from_address
      decoded_details {
        ... on HypercoreFillTransaction {
          coin side price size closed_pnl fee
          liquidation { method liquidated_user market_price }
        }
        ... on HypercoreFundingEvent { coin funding_rate funding_amount }
      }
    }
  }
  """)

  async def main():
      transport = WebsocketsTransport(
          url=WS_URL,
          init_payload={"GOLDRUSH_API_KEY": os.environ["GOLDRUSH_API_KEY"]},
      )
      async with Client(transport=transport, fetch_schema_from_transport=False) as session:
          async for result in session.subscribe(SUBSCRIPTION):
              print(result)

  asyncio.run(main())
  ```
</CodeGroup>

## Patterns

### Copy-trading

Subscribe to a curated list of high-PnL wallets. Filter the incoming stream on `HypercoreFillTransaction`, then mirror the `coin`, `side`, and `size` to your own execution layer.

### Live whale feed

Subscribe to the top-N wallets by balance or notional position. Display every fill, liquidation, and large transfer in a chronological tape.

### Liquidation alerts

Filter the stream on `HypercoreFillTransaction` events where `liquidation` is non-null. Push the event payload to a notification channel (Discord, Telegram, push). Each event includes the liquidated user, mark price, and method (`Market` vs `Backstop`).

### Position monitoring

Pair the stream with periodic [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) calls to maintain accurate per-wallet position state without polling between fills.

## Production considerations

The happy-path example above is enough to prototype. Three things to add before shipping:

* **Reconnect on close or error.** The `complete` callback fires on a clean stream close; `error` fires on transport errors. In both cases, re-invoke the subscribe function with backoff so the firehose self-heals after network blips:

```typescript TypeScript theme={null}
function subscribe() {
  client.StreamingService.rawQuery(
    SUBSCRIPTION_QUERY,
    {},
    {
      next: (data) => handleEvent(data),
      error: (err) => { console.error(err); setTimeout(subscribe, 1000); },
      complete: () => setTimeout(subscribe, 1000),
    },
  );
}

subscribe();
```

* **Validate addresses up front.** Malformed wallet addresses can surface via `error` and tear down the whole subscription. Pre-filter the input list with `/^0x[a-fA-F0-9]{40}$/` (or your library's validator) before passing it in.
* **No gap-fill on reconnect.** The subscription delivers events from the moment it opens - events that occurred during a disconnect are not replayed. For continuity across the gap, query [`userFillsByTime`](/api-reference/hyperliquid-info/user-fills-by-time) over the disconnect window after reconnecting.

## Scaling

| Scale                   | Approach                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Up to \~1,000 wallets   | One subscription with the full address list.                                                 |
| 1,000 – 10,000+ wallets | Shard across multiple subscriptions on the same connection. The SDK reuses one WebSocket.    |
| Live cohort changes     | Unsubscribe and resubscribe with the new address list - no need to tear down the connection. |

For very high fan-out, contact us about dedicated capacity.

## Pair address format

Hyperliquid markets use a **deployer-prefix naming scheme**. The exact string differs by surface, so pass the value each API expects - matching is case- and format-sensitive.

| Where it's used                                                       | Format                                                                   | Examples                                    |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| WebSocket `coin` (`l2Book`, `l2BookDiff`, `l4Book`) - canonical perps | `<symbol>`                                                               | `BTC`, `ETH`, `HYPE`                        |
| WebSocket `coin` - HIP-3 builder markets                              | `<deployer>:<symbol>`                                                    | `xyz:GOLD`, `flx:OIL`                       |
| Streaming `pair_addresses` (`ohlcvCandlesForPair`)                    | `<deployer>:<symbol>-<quote>`, or `<symbol>-<quote>` for canonical pairs | `xyz:GOLD-USDC`, `flx:OIL-USDH`, `BTC-USDC` |
| Streaming `token_addresses` (`ohlcvCandlesForToken`)                  | `<symbol>` (no prefix)                                                   | `GOLD`, `OIL`, `BTC`                        |

* `deployer` - wallet address of the HIP-3 builder that deployed the market. Omitted for canonical Hyperliquid markets.
* `symbol` - market ticker (e.g. `GOLD`, `OIL`).
* `quote` - the margin / quote currency, usually `USDC` (some HIP-3 markets use `USDH`).

<Note>HIP-4 outcome markets use a separate `#<encoding>` scheme (e.g. `#1230`), not the deployer-prefix - see [HIP-4 Markets](/goldrush-hyperliquid/streaming/hip4-markets).</Note>

**Discovering markets:** a dedicated market-list endpoint (the `perpDexs` Info API type) is on the roadmap. Until it ships, call [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) - the `name` field on each `universe` entry is the canonical pair address.

## Related

* [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) - full type reference.
* [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) - vault, staking, borrow/lend, rewards subtypes.
* [Liquidations and vault events](/goldrush-hyperliquid/streaming/liquidations-vaults) - full decoded-event walkthrough.
* [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - subscription reference.