Skip to main content

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

  1. WebSocket URL: wss://streaming.goldrushdata.com/graphql
  2. Chain enum: HYPERCORE_MAINNET (SCREAMING_SNAKE_CASE)
  3. HIP-3 and HIP-4 pair address syntax: <deployer>:<symbol>-<quote> (e.g. xyz:GOLD-USDC)
  4. HIP-3 and HIP-4 token address syntax: plain symbol (e.g. GOLD, OIL)
  5. walletTxs accepts up to thousands of wallet addresses per subscription
  6. Pre-decoded events: HypercoreFillTransaction (with liquidation), HypercoreLedgerEvent (20+ subtypes), HypercoreFundingEvent, HypercoreDepositEvent, HypercoreWithdrawalEvent, HypercoreDelegationEvent

Common Recipes

GoalEndpointFilter
Wallet firehosewalletTxschain_name: HYPERCORE_MAINNET, wallet_addresses: [...]
HIP-3 / HIP-4 OHLCV by pairohlcvCandlesForPairpair_addresses: ["xyz:GOLD-USDC", ...]
HIP-3 / HIP-4 OHLCV by tokenohlcvCandlesForTokentoken_addresses: ["GOLD", "OIL", ...]
Liquidation tapewalletTxsHypercoreFillTransaction.liquidation non-nullfilter client-side
Vault leaderboardwalletTxsHypercoreLedgerEvent.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 liquidation block is attached directly.
  • Sub-second latency. Tokyo-colocated, validator-peered ingestion.

Subscribe

GoldRush SDK
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
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())

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.

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.
  • 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:
StreamAddress formatExamples
OHLCV Pairs:xyz:GOLD-USDC, flx:OIL-USDH, BTC-USDC
OHLCV Tokens“ (no prefix)GOLD, OIL, BTC, HYPE
For BTC-USDC-style canonical Hyperliquid markets, no prefix is needed.

Stream OHLCV for a HIP-3 pair

GoldRush SDK
import {
  GoldRushClient,
  StreamingChain,
  StreamingInterval,
  StreamingTimeframe,
} from "@covalenthq/client-sdk";

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

client.StreamingService.subscribeToOHLCVPairs(
  {
    chain_name: StreamingChain.HYPERCORE_MAINNET,
    pair_addresses: ["xyz:GOLD-USDC", "flx:OIL-USDH"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => console.log("OHLCV:", data),
    error: (err) => console.error(err),
    complete: () => console.log("done"),
  }
);
Install
npm install @covalenthq/client-sdk

Stream OHLCV for a token (across all markets)

client.StreamingService.subscribeToOHLCVTokens(
  {
    chain_name: StreamingChain.HYPERCORE_MAINNET,
    token_addresses: ["GOLD", "OIL", "HYPE"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => console.log("Token OHLCV:", data),
    error: (err) => console.error(err),
  }
);
This aggregates across all DEXes and HIP-3 deployers carrying that token.

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. Combine ohlcvCandlesForPair with periodic listing logic to surface new markets in a “trending” tab.

Deployer-scoped leaderboards

Group HypercoreFillTransaction 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” on xyz: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

A perpDexs 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:
FieldDescription
methodMarket or Backstop.
liquidated_userThe wallet whose position was liquidated.
market_priceMark price at the moment of liquidation.
liquidated_positions[]Every position closed by the liquidation (coin + size).
account_valueAccount value at the time of liquidation.
leverage_typeCross or isolated.

20+ ledger event subtypes

SubtypeDescription
LedgerLiquidationStandalone liquidation ledger event with full position list.
LedgerVaultDepositDeposit into a vault.
LedgerVaultWithdrawWithdrawal request from a vault, with commission and basis.
LedgerVaultLeaderCommissionCommission earned by a vault leader.
LedgerVaultDistributionDistribution from a vault to depositors.
LedgerVaultCreateNew vault creation event.
LedgerCStakingTransferHyperliquid staking deposit/withdrawal.
LedgerBorrowLendBorrow or lend operation.
LedgerRewardsClaimValidator or program reward claim.
LedgerDeposit, LedgerWithdrawBridge in/out.
LedgerInternalTransferSub-account transfer.
LedgerSpotTransferSpot token transfer with USDC value.
LedgerSubAccountTransferSub-account funds movement.
LedgerSendCross-DEX send (with source_dex and destination_dex).
LedgerAccountClassTransferAccount-class movement (perp/spot).
LedgerAccountActivationGasActivation gas charged on first deposit.
LedgerSpotGenesisSpot token genesis allocation.
LedgerDeployGasAuctionHIP-3 market deployment gas auction.
LedgerPerpDexClassTransferTransfer between HIP-3 perp DEXes and core perp.
See 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:
import { GoldRushClient } from "@covalenthq/client-sdk";

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

const SUBSCRIPTION_QUERY = `
  subscription {
    walletTxs(
      wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"]
      chain_name: HYPERCORE_MAINNET
    ) {
      tx_hash
      block_signed_at
      decoded_details {
        ... on HypercoreFillTransaction {
          coin side price size closed_pnl
          liquidation {
            method
            liquidated_user
            market_price
          }
        }
        ... on HypercoreLedgerEvent {
          ledger_type
          time
          delta {
            ... on LedgerLiquidation {
              account_value
              leverage_type
              liquidated_ntl_pos
              liquidated_positions { coin szi }
            }
            ... on LedgerVaultDeposit { vault user usdc }
            ... on LedgerVaultWithdraw {
              vault user requested_usd commission basis closing_cost
            }
            ... on LedgerVaultLeaderCommission { vault usdc }
            ... on LedgerVaultDistribution { vault usdc }
            ... on LedgerCStakingTransfer { token amount is_deposit }
            ... on LedgerBorrowLend { token amount interest_amount operation }
            ... on LedgerRewardsClaim { amount }
          }
        }
      }
    }
  }
`;

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

Patterns

Live liquidation tape

Filter the stream on HypercoreFillTransaction 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-null liquidation to a notification channel. Use account_value to compute the dollar size and liquidated_positions[] to list the markets.

Position-risk warnings

Combine clearinghouseState (read liquidationPx, marginUsed, accountValue) with live LedgerLiquidation events for similar wallets to flag at-risk positions before they liquidate.

Vault leaderboards

Aggregate LedgerVaultLeaderCommission and LedgerVaultDistribution events per vault address. Surface top-performing vaults by commission earned or distribution payout.

Staking and rewards tabs

Subscribe to LedgerCStakingTransfer, HypercoreDelegationEvent, and LedgerRewardsClaim for a user. Display delegation history, current stake, and rewards earned.

Borrow/lend position trackers

Filter on LedgerBorrowLend 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

  • HypercoreFillTransaction
  • HypercoreLedgerEvent
  • HypercoreFundingEvent
  • HypercoreDepositEvent
  • HypercoreWithdrawalEvent
  • HypercoreDelegationEvent
  • Decoded Events Guide - every type, every subtype.