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.
Hyperliquid Streaming Recipes
Critical Rules
- WebSocket URL:
wss://streaming.goldrushdata.com/graphql - Chain enum:
HYPERCORE_MAINNET(SCREAMING_SNAKE_CASE) - HIP-3 and HIP-4 pair address syntax:
<deployer>:<symbol>-<quote>(e.g.xyz:GOLD-USDC) - HIP-3 and HIP-4 token address syntax: plain symbol (e.g.
GOLD,OIL) walletTxsaccepts up to thousands of wallet addresses per subscription- Pre-decoded events:
HypercoreFillTransaction(withliquidation),HypercoreLedgerEvent(20+ subtypes),HypercoreFundingEvent,HypercoreDepositEvent,HypercoreWithdrawalEvent,HypercoreDelegationEvent
Common Recipes
| Goal | Endpoint | Filter |
|---|---|---|
| Wallet firehose | walletTxs | chain_name: HYPERCORE_MAINNET, wallet_addresses: [...] |
| HIP-3 / HIP-4 OHLCV by pair | ohlcvCandlesForPair | pair_addresses: ["xyz:GOLD-USDC", ...] |
| HIP-3 / HIP-4 OHLCV by token | ohlcvCandlesForToken | token_addresses: ["GOLD", "OIL", ...] |
| Liquidation tape | walletTxs → HypercoreFillTransaction.liquidation non-null | filter client-side |
| Vault leaderboard | walletTxs → HypercoreLedgerEvent.delta (LedgerVaultLeaderCommission, LedgerVaultDistribution) | aggregate per vault |
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
liquidationblock is attached directly. - Sub-second latency. Tokyo-colocated, validator-peered ingestion.
Subscribe
GoldRush SDK
Python
Patterns
Copy-trading
Subscribe to a curated list of high-PnL wallets. Filter the incoming stream onHypercoreFillTransaction, 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 onHypercoreFillTransaction 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 periodicclearinghouseState calls to maintain accurate per-wallet position state without polling between fills.
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. |
Related
HypercoreFillTransaction- full type reference.HypercoreLedgerEvent- vault, staking, borrow/lend, rewards subtypes.- Liquidations and vault events - full decoded-event walkthrough.
- Wallet Activity Stream - subscription reference.
HIP-3 lets builders deploy their own perp markets on Hyperliquid - equities, commodities, niche assets - and new ones appear constantly. The public
candleSnapshot is poll-based and effectively limited to mainstream markets, and discovering HIP-3 markets means stitching market IDs by hand.
GoldRush’s ohlcvCandlesForPair and ohlcvCandlesForToken are real-time WebSocket streams that address HIP-3 markets natively with the deployer-prefix syntax. List, chart, or stream any market the moment it goes live.
Address syntax
HIP-3 markets are addressed with a deployer-prefix:| Stream | Address format | Examples |
|---|---|---|
| OHLCV Pairs | : | xyz:GOLD-USDC, flx:OIL-USDH, BTC-USDC |
| OHLCV Tokens | “ (no prefix) | GOLD, OIL, BTC, HYPE |
BTC-USDC-style canonical Hyperliquid markets, no prefix is needed.
Stream OHLCV for a HIP-3 pair
GoldRush SDK
Install
Stream OHLCV for a token (across all markets)
Patterns
”New markets” discovery tab
When a HIP-3 deployer launches a new market, the OHLCV stream picks it up the moment a candle starts forming. CombineohlcvCandlesForPair with periodic listing logic to surface new markets in a “trending” tab.
Deployer-scoped leaderboards
GroupHypercoreFillTransaction events from walletTxs by HIP-3 deployer prefix. Compute per-deployer volume, fee revenue, top traders.
Cross-deployer charting
A single chart widget that “just works” onxyz:GOLD-USDC, BTC-USDC, or any future HIP-3 market without special-casing the request. Pass the address through unchanged.
Reference
- OHLCV Pairs Stream
- OHLCV Tokens Stream
- HyperCore chain page - full HIP-3 example addresses and Hyperliquid Explorer references.
- Live HIP-3 Market Screener - the public app we built on top of these streams.
On the roadmap
AperpDexs Info API type that lists all HIP-3 builder-deployed perp DEXes with metadata. See the Roadmap.
The public Hyperliquid
/info API surfaces raw building blocks; you write the parser. Liquidations are buried inside fills as a thin stub, and vault, staking, and delegation activity arrives as untyped ledger updates you have to classify yourself.
GoldRush ships every one of these pre-decoded and typed.
What’s pre-decoded
Liquidations
Inline with the fill that triggered them, with full context:| Field | Description |
|---|---|
method | Market or Backstop. |
liquidated_user | The wallet whose position was liquidated. |
market_price | Mark price at the moment of liquidation. |
liquidated_positions[] | Every position closed by the liquidation (coin + size). |
account_value | Account value at the time of liquidation. |
leverage_type | Cross or isolated. |
20+ ledger event subtypes
| Subtype | Description |
|---|---|
LedgerLiquidation | Standalone liquidation ledger event with full position list. |
LedgerVaultDeposit | Deposit into a vault. |
LedgerVaultWithdraw | Withdrawal request from a vault, with commission and basis. |
LedgerVaultLeaderCommission | Commission earned by a vault leader. |
LedgerVaultDistribution | Distribution from a vault to depositors. |
LedgerVaultCreate | New vault creation event. |
LedgerCStakingTransfer | Hyperliquid staking deposit/withdrawal. |
LedgerBorrowLend | Borrow or lend operation. |
LedgerRewardsClaim | Validator or program reward claim. |
LedgerDeposit, LedgerWithdraw | Bridge in/out. |
LedgerInternalTransfer | Sub-account transfer. |
LedgerSpotTransfer | Spot token transfer with USDC value. |
LedgerSubAccountTransfer | Sub-account funds movement. |
LedgerSend | Cross-DEX send (with source_dex and destination_dex). |
LedgerAccountClassTransfer | Account-class movement (perp/spot). |
LedgerAccountActivationGas | Activation gas charged on first deposit. |
LedgerSpotGenesis | Spot token genesis allocation. |
LedgerDeployGasAuction | HIP-3 market deployment gas auction. |
LedgerPerpDexClassTransfer | Transfer between HIP-3 perp DEXes and core perp. |
HypercoreLedgerEvent for the full type with all fields.
Funding, deposits, withdrawals, delegations
Each gets its own typed event:HypercoreFundingEvent- funding rate payment with coin, rate, and amount.HypercoreDepositEvent- cross-chain deposit into HyperCore.HypercoreWithdrawalEvent- finalized cross-chain withdrawal.HypercoreDelegationEvent- staking delegation or undelegation with validator address.
Subscribe
Pull liquidations, fills, and ledger events for a wallet (or many) in one stream:Patterns
Live liquidation tape
Filter the stream onHypercoreFillTransaction where liquidation is non-null. Display each liquidation in a chronological feed with the user, mark price, method, and total position value.
”X just got liquidated for $Y” notifications
Push every non-nullliquidation to a notification channel. Use account_value to compute the dollar size and liquidated_positions[] to list the markets.
Position-risk warnings
CombineclearinghouseState (read liquidationPx, marginUsed, accountValue) with live LedgerLiquidation events for similar wallets to flag at-risk positions before they liquidate.
Vault leaderboards
AggregateLedgerVaultLeaderCommission and LedgerVaultDistribution events per vault address. Surface top-performing vaults by commission earned or distribution payout.
Staking and rewards tabs
Subscribe toLedgerCStakingTransfer, HypercoreDelegationEvent, and LedgerRewardsClaim for a user. Display delegation history, current stake, and rewards earned.
Borrow/lend position trackers
Filter onLedgerBorrowLend for operation: "borrow" | "repay" | "open" | "close". Display per-token borrow positions with cumulative interest.
Historical depth
Every fill, funding payment, and ledger event is retained back to HyperCore block 676,607,001 (2025-07-27T01:49:59Z). For warehouse delivery - every ledger event landing in your database continuously - use the Pipeline API (hl_misc_events).
Reference
HypercoreFillTransactionHypercoreLedgerEventHypercoreFundingEventHypercoreDepositEventHypercoreWithdrawalEventHypercoreDelegationEvent- Decoded Events Guide - every type, every subtype.