> ## 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 API Quickstart

> Three 5-minute paths to get Hyperliquid data with GoldRush - drop-in Info API, real-time wallet streams, and batched account state.

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/), or apply to the Early Builders Program for free credits.

> [card] [Vibe Coders](https://goldrush.dev/platform/auth/register/?plan=vibe)
>
> \$10/mo - Built for solo builders and AI-native workflows.

> [card] [Teams](https://goldrush.dev/platform/auth/register/?plan=professional)
>
> \$250/mo - Production-grade with priority support.

> [card] [Early Builders](https://goldrush.dev/docs/goldrush-hyperliquid/early-builders-program.md)
>
> Pre-revenue? Up to 1M credits over 12 months, free.

***

## 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 <GOLDRUSH_API_KEY>" \
  -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:

> [card] [Info API Migration Guide](https://goldrush.dev/docs/goldrush-hyperliquid/info-api/migration.md)
>
> 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](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/wallet-firehose.md) for the full pattern.

***

## 3. 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`](https://goldrush.dev/docs/api-reference/hyperliquid-info/batch-clearinghouse-state), [`batchSpotClearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid-info/batch-spot-clearinghouse-state).

***

## What's next

> [card] [WebSocket API](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/overview.md)
>
> Drop-in `wss://` replacement with `l2Book`, `l2BookDiff`, and the GoldRush-native `l4Book` order-level stream. No per-IP subscription cap.

> [card] [HIP-3 markets](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip3-markets.md)
>
> Real-time OHLCV for every builder-deployed perp market - equities, commodities, niche assets.

> [card] [Liquidations & vault events](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/liquidations-vaults.md)
>
> Pre-decoded `LedgerLiquidation`, `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and 17 more subtypes.

> [card] [Live analytics](https://goldrush.dev/docs/goldrush-hyperliquid/analytics-app.md)
>
> HIP-3 Market Screener, Liquidation Cascade Map, Market Health Score.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.