Skip to main content
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.

​
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

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"),
  }
);

​
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 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
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 over the disconnect window after reconnecting.

​
Scaling

ScaleApproach
Up to ~1,000 walletsOne subscription with the full address list.
1,000 – 10,000+ walletsShard across multiple subscriptions on the same connection. The SDK reuses one WebSocket.
Live cohort changesUnsubscribe 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 usedFormatExamples
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 pairsxyz: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).
HIP-4 outcome markets use a separate #<encoding> scheme (e.g. #1230), not the deployer-prefix - see HIP-4 Markets.
Discovering markets: a dedicated market-list endpoint (the perpDexs Info API type) is on the roadmap. Until it ships, call metaAndAssetCtxs - the name field on each universe entry is the canonical pair address.