> ## 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. # Overview # GoldRush Hyperliquid API Overview ## Quick Reference | Item | Value | | ------------------------------ | ---------------------------------------------------------------------------------------- | | **Info API URL** | `https://hypercore.goldrushdata.com/info` | | **Method** | `POST` | | **Authentication** | `Authorization: Bearer ` (same key as Foundational/Streaming/Pipeline) | | **Rate Limit** | None | | **Wire compatibility** | Byte-for-byte with `POST api.hyperliquid.xyz/info` for implemented types | | **Networks** | Mainnet only | | **HyperCore historical depth** | Block 676,607,001 onward (2025-07-27T01:49:59Z) | | **HyperEVM historical depth** | Genesis | ## Surfaces | Surface | What it provides | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Info API | Drop-in replacement for `POST /info` (18 current types, including `outcomeMeta` and GoldRush-native `batchClearinghouseState`/`batchSpotClearinghouseState`; unsupported types return a JSON error) | | WebSocket API | Drop-in replacement for `wss://api.hyperliquid.xyz/ws` at `wss://hypercore.goldrushdata.com/ws?key=`. No 1000-subscription-per-IP cap. Channels: `l2Book` (aggregated, optional `coin`), `l2BookDiff` (GoldRush-native L2 snapshot + per-block diffs, single coin / list / wildcard), `l4Book` (GoldRush-native order-level snapshot + per-block diffs) | | Streaming API | Real-time `walletTxs`, `ohlcvCandlesForPair`, `ohlcvCandlesForToken` | | Pipeline API | `hl_fills`, `hl_trades`, `hl_orders`, `hl_funding`, `hl_misc_events` to your warehouse | | Foundational API | HyperEVM (chain `999`) token balances, transfers, NFTs, gas | *** GoldRush is the **complete data layer for Hyperliquid**. It aggregates everything you need to build on Hyperliquid - HyperCore, HIP-3, HIP-4, and HyperEVM - under one API key. ### Drop-in Hyperliquid API replacement Drop-in replacement for both the public `/info` REST API and `/ws` WebSocket. Change one URL to remove rate limits and unlock more data. Hosted at `hypercore.goldrushdata.com`. ### Real-time Streaming Wallet firehose, OHLCV for every HIP-3 and HIP-4 market the moment it goes live, and pre-decoded liquidations and vault events. ### Pipeline to your warehouse Land `hl_fills`, `hl_trades`, `hl_orders`, `hl_funding`, and more directly in ClickHouse, BigQuery, Postgres, Kafka, or S3. ### HyperEVM coverage Token balances, transfers, approvals, NFTs, and gas for HyperEVM - same shape as every other EVM chain on GoldRush. ## Drop-in coverage: REST + WebSocket GoldRush replaces **both** of Hyperliquid's public surfaces with a single host - `hypercore.goldrushdata.com`. Same request bodies, same response shapes, same subscription payloads as the public API. Swap the URL, add one `Authorization` header, and your existing clients work unchanged - with no rate limits and no per-IP subscription caps. ### REST /info API Drop-in replacement for `POST https://api.hyperliquid.xyz/info`. 17 wire-compatible `type` values plus GoldRush-native batch endpoints (`batchClearinghouseState`, `batchSpotClearinghouseState`) for up to 50 wallets per call. ### WebSocket API Drop-in replacement for `wss://api.hyperliquid.xyz/ws` with no 1000-subscription-per-IP cap. Subscribe to `l2Book` (aggregated snapshots - omit `coin` to stream **every asset** on one subscription), the GoldRush-native `l2BookDiff` (snapshot plus per-block diffs of changed `{px, sz, n}` levels - accepts a single coin, a list, or wildcard), or the GoldRush-native `l4Book` (per-order snapshot plus per-block diffs with `user`, `oid`, `cloid`, and trigger metadata exposed). ## Hyperliquid API limitations addressed by GoldRush The public Hyperliquid `/info` API is generous, but it has hard limits that most production apps run into: * **1200 weight/min/IP** rate limits per address. * **1000 WebSocket subscriptions per IP** - not enough to track every active trader. * **WebSocket subscription filters are required** - every subscription must specify an asset (e.g. `coin` on `l2Book`), forcing per-asset fan-out that burns through the 1000-subscription cap. GoldRush makes these filters **optional** so a single wildcard subscription streams every asset. * **No batch address endpoints** - account-state calls are single-wallet only; GoldRush adds `batchClearinghouseState` and `batchSpotClearinghouseState` for up to 50 wallets per request. * **`userFills` capped at \~10,000 rows** - active traders blow through that in weeks. * **Liquidations buried inside fills** as a thin stub; vault, staking, and delegation data arrives untyped. * **HIP-3 and HIP-4 discovery is manual** - `candleSnapshot` is poll-based and effectively limited to mainstream markets. * **No HyperEVM concept at all** - DEXes, NFT mints, and lending live on chain `999` and the `/info` API doesn't see them. GoldRush closes every one of these gaps. See **GoldRush vs Hyperliquid public API** for the full breakdown. ## What's included ## Infrastructure * **Dedicated Hyperliquid nodes in Tokyo** - co-located with Hyperliquid's validator infrastructure for low-latency reads. * **Private backbone** for high-throughput data ingestion. * **No rate limits** - bypass the public `/info` and WebSocket constraints entirely. * **Full historical backfill** - every fill, funding payment, and ledger event back to HyperCore block `676,607,001` (`2025-07-27T01:49:59Z`). HyperEVM coverage goes back to genesis. ## Quickstart Here are three "first 5 minutes" quickstarts. Pick whichever maps to what you are building. ### Upgrade from the public Hyperliquid API Already using `api.hyperliquid.xyz/info`? Change the URL and add one header. ### Watch wallets Subscribe to thousands of HyperCore wallets in one connection. ### Pipe orderbook fills into your warehouse Stream `hl_fills` into ClickHouse, BigQuery, or Postgres. *** Pick the path that matches what you're building. All three use the same GoldRush API key. ## Prerequisites A GoldRush API key. Sign up at [goldrush.dev/platform](https://goldrush.dev/platform/auth/register/). ### Vibe Coders \$10/mo - Built for solo builders and AI-native workflows. ### Teams \$250/mo - Production-grade with priority support. *** ## 1. Drop-in Info API If your code already calls `POST https://api.hyperliquid.xyz/info`, swap the URL to `https://hypercore.goldrushdata.com/info` and add an `Authorization: Bearer` header. The request body and response shape stay byte-for-byte identical. ```bash cURL theme={null} curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"type": "metaAndAssetCtxs"}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "clearinghouseState", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import os import requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={ "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}", "Content-Type": "application/json", }, json={ "type": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` That's it. No rate limits, faster reads, and the response is byte-equal to Hyperliquid (modulo live-value drift). See the full migration guide for SDK overrides and behavioral notes: ### Info API Migration Guide Side-by-side examples in JS, Python, and cURL - including how to point existing SDKs at GoldRush. *** ## 2. Stream wallet activity Subscribe to one or many HyperCore wallets in real time over WebSocket. Pre-decoded events include fills with liquidation context, funding payments, vault actions, and 20+ ledger subtypes. ```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"] 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 HypercoreFundingEvent { coin funding_rate funding_amount } } } } `; client.StreamingService.rawQuery( SUBSCRIPTION_QUERY, {}, { next: (data) => console.log(JSON.stringify(data, null, 2)), error: (err) => console.error(err), complete: () => console.log("done"), } ); ``` ```bash Install theme={null} npm install @covalenthq/client-sdk ``` The `walletTxs` subscription has zero rate limits and scales to thousands of concurrent wallet subscriptions per connection. See **Wallet firehose** for the full pattern. *** ## 3. Pipe fills to your warehouse Stream HyperCore fills into ClickHouse, BigQuery, Postgres, Kafka, or S3 with one config - no ETL on your side. **Create a pipeline** In the [GoldRush Platform](https://goldrush.dev/platform/), navigate to **Manage Pipelines** and click **Create Pipeline**. **Pick HyperCore + Fills** Choose **Hyperliquid** as the chain and **Fills** as the data type. **Choose your destination** Connect ClickHouse, BigQuery, Postgres, Kafka, S3/GCS/R2, SQS, or a Webhook. **Deploy** Fills begin flowing within seconds. Full walkthrough with sample SQL: **Stream Hyperliquid trades to ClickHouse**. *** ## 4. Fan out across many wallets Need account state for many wallets at once? `batchClearinghouseState` and `batchSpotClearinghouseState` accept **1 to 50 wallets per call** and fan them out in parallel against our private node. There is no equivalent on the public Hyperliquid `/info` API. Each slot in the response is either the raw upstream object for that wallet (success) or a thin error envelope (`{error, user, message}`) when an individual wallet fails. The HTTP status stays `200 OK` even on partial failure - always check for the `error` key on each slot. ```typescript TypeScript theme={null} const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "batchClearinghouseState", users: [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b", ], }), }); const slots = await response.json(); for (const [i, slot] of slots.entries()) { if ("error" in slot) { console.warn(`wallet ${slot.user} failed: ${slot.message}`); continue; } console.log(`wallet ${i}: ${slot.withdrawable} USD withdrawable`); } ``` ```bash cURL theme={null} curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "batchSpotClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc" ] }' ``` Duplicates in `users` are removed (case-insensitive); input order is preserved for the survivors. For batches larger than 50, issue multiple calls. Use cases: portfolio dashboards, multi-wallet PnL aggregators, fleet-level liquidation risk monitoring, treasury balance reconciliation. Full reference: **`batchClearinghouseState`**, **`batchSpotClearinghouseState`**. *** ## What's next ### HIP-3 markets Real-time OHLCV for every builder-deployed perp market - equities, commodities, niche assets. ### Liquidations & vault events Pre-decoded `LedgerLiquidation`, `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and 17 more subtypes. ### Roadmap Time-travel queries, cross-venue unification, signed responses - what's shipping next. ### Live analytics HIP-3 Market Screener, Liquidation Cascade Map, Market Health Score.