> ## 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. # Info api # Hyperliquid Info API ## Available Types (today) | Type | Body | Returns | | ----------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `metaAndAssetCtxs` | `{type:"metaAndAssetCtxs",dex:""}` | Tuple \[meta, assetCtxs\[]] - perp universe + per-asset mark, funding, OI, day volume | | `spotMetaAndAssetCtxs` | `{type:"spotMetaAndAssetCtxs"}` | Tuple \[spotMeta, assetCtxs\[]] - spot universe + per-pair mark, mid, day volume | | `outcomeMeta` | `{type:"outcomeMeta"}` | Active HIP-4 outcome universe with outcome IDs, descriptions, and Yes/No side specs | | `clearinghouseState` | `{type:"clearinghouseState",user:"0x...",dex:""}` | Perp account state | | `spotClearinghouseState` | `{type:"spotClearinghouseState",user:"0x...",dex:""}` | Spot balances | | `frontendOpenOrders` | `{type:"frontendOpenOrders",user:"0x...",dex:""}` | Open orders w/ TP/SL metadata | | `subAccounts` | `{type:"subAccounts",user:"0x..."}` | Sub-accounts owned by a master, each with inlined perp and spot state | | `userFills` | `{type:"userFills",user:"0x..."}` | Most recent fills for a user | | `userFillsByTime` | `{type:"userFillsByTime",user:"0x...",startTime:...}` | Fills bounded by a time window | | `userTwapSliceFills` | `{type:"userTwapSliceFills",user:"0x..."}` | Most recent TWAP slice fills tagged with parent `twapId` | | `userFunding` | `{type:"userFunding",user:"0x...",startTime:...}` | Funding payment history with rate, applied size, USDC delta | | `userNonFundingLedgerUpdates` | `{type:"userNonFundingLedgerUpdates",user:"0x...",startTime:...}` | Ledger events except funding - deposits, withdrawals, transfers, vault flows, liquidations | | `userVaultEquities` | `{type:"userVaultEquities",user:"0x..."}` | Per-vault locked equity with unlock timestamps | | `delegatorSummary` | `{type:"delegatorSummary",user:"0x..."}` | Current delegated, undelegated, pending-withdrawal HYPE totals | | `delegatorHistory` | `{type:"delegatorHistory",user:"0x..."}` | Delegate, undelegate, deposit, and withdrawal staking events | | `delegatorRewards` | `{type:"delegatorRewards",user:"0x..."}` | Accrued staking rewards (delegation and validator commission) | | `batchClearinghouseState` | `{type:"batchClearinghouseState",users:["0x...",...],dex:""}` | Array of clearinghouseState slots, 1-50 wallets. **GoldRush-native** (no upstream equivalent) | | `batchSpotClearinghouseState` | `{type:"batchSpotClearinghouseState",users:["0x...",...]}` | Array of spotClearinghouseState slots, 1-50 wallets. **GoldRush-native** (no upstream equivalent) | Any other `type` value returns `{"error":"unsupported_type","type":""}` with HTTP 400. Requests are not forwarded to upstream Hyperliquid. ## Migration Pattern ```typescript theme={null} // Before fetch("https://api.hyperliquid.xyz/info", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); // After -same body, no rate limits fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(body), }); ``` *** The GoldRush Hyperliquid Info API is a **drop-in replacement** for `POST https://api.hyperliquid.xyz/info`. The request body, the response shape, and the JSON keys are byte-for-byte identical to the public Hyperliquid API. The only differences are the URL and the authentication header. Eighteen `type` values are supported today across market metadata, user state, user history, vaults, and staking - plus two GoldRush-native batch endpoints with no upstream equivalent. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Comparison with the public Hyperliquid API | | Public API | GoldRush | | ------------------------ | ---------------------------------- | ----------------------------------------- | | URL | `https://api.hyperliquid.xyz/info` | `https://hypercore.goldrushdata.com/info` | | Auth | None | `Authorization: Bearer ` | | Rate limit | 1200 weight/min/IP | None | | Orderbook latency target | `p50`: `~280 ms` | `p50`: `"}` instead of being forwarded | ## Available types The Info API supports the wire-compatible drop-in types below, organized by what they return. Two GoldRush-native batch endpoints (`batchClearinghouseState`, `batchSpotClearinghouseState`) have no upstream Hyperliquid equivalent. ### Market metadata | Type | Body | Returns | | -------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **`metaAndAssetCtxs`** | `{"type": "metaAndAssetCtxs", "dex": ""}` | Tuple `[meta, assetCtxs[]]` - perp universe + per-asset live mark price, funding, OI, day volume. | | **`spotMetaAndAssetCtxs`** | `{"type": "spotMetaAndAssetCtxs"}` | Tuple `[spotMeta, assetCtxs[]]` - spot universe + per-pair live mark price, mid, day volume. | | **`outcomeMeta`** | `{"type": "outcomeMeta"}` | Active HIP-4 outcome universe - integer outcome IDs, names, structured descriptions, and `sideSpecs` (`Yes` / `No`). | ### User account state | Type | Body | Returns | | ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **`clearinghouseState`** | `{"type": "clearinghouseState", "user": "0x…", "dex": ""}` | Perp account: positions, margin summary, account value, withdrawable. | | **`spotClearinghouseState`** | `{"type": "spotClearinghouseState", "user": "0x…", "dex": ""}` | Spot balances per token, total USD value. | | **`frontendOpenOrders`** | `{"type": "frontendOpenOrders", "user": "0x…", "dex": ""}` | Open orders + trigger metadata (TP/SL, `isPositionTpsl`, `reduceOnly`, `orderType`). | | **`subAccounts`** | `{"type": "subAccounts", "user": "0x…"}` | List of sub-accounts owned by a master, each with its inlined perp and spot state. | ### User history | Type | Body | Returns | | --------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | **`userFills`** | `{"type": "userFills", "user": "0x…"}` | Most recent fills for a wallet (up to 2,000). | | **`userFillsByTime`** | `{"type": "userFillsByTime", "user": "0x…", "startTime": …}` | Fills bounded by a time window. | | **`userTwapSliceFills`** | `{"type": "userTwapSliceFills", "user": "0x…"}` | Most recent TWAP slice fills, each tagged with the parent `twapId`. | | **`userFunding`** | `{"type": "userFunding", "user": "0x…", "startTime": …}` | Funding payment history with rate, applied size, and USDC delta per event. | | **`userNonFundingLedgerUpdates`** | `{"type": "userNonFundingLedgerUpdates", "user": "0x…", "startTime": …}` | Ledger events except funding - deposits, withdrawals, transfers, vault flows, liquidations. | ### Vaults & staking | Type | Body | Returns | | ----------------------- | ---------------------------------------------- | ------------------------------------------------------------------- | | **`userVaultEquities`** | `{"type": "userVaultEquities", "user": "0x…"}` | Per-vault locked equity with unlock timestamps. | | **`delegatorSummary`** | `{"type": "delegatorSummary", "user": "0x…"}` | Current delegated, undelegated, and pending-withdrawal HYPE totals. | | **`delegatorHistory`** | `{"type": "delegatorHistory", "user": "0x…"}` | Delegate, undelegate, deposit, and withdrawal staking events. | | **`delegatorRewards`** | `{"type": "delegatorRewards", "user": "0x…"}` | Accrued staking rewards (delegation and validator commission). | ### GoldRush-native batch | Type | Body | Returns | | --------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **`batchClearinghouseState`** | `{"type": "batchClearinghouseState", "users": ["0x…", …], "dex": ""}` | Array of `clearinghouseState` slots. **GoldRush-native**, 1 to 50 wallets per call. | | **`batchSpotClearinghouseState`** | `{"type": "batchSpotClearinghouseState", "users": ["0x…", …]}` | Array of `spotClearinghouseState` slots. **GoldRush-native**, 1 to 50 wallets per call. | If you send a `type` that isn't in the table above, the response body is `{"error":"unsupported_type","type":""}`. Requests are not forwarded to upstream Hyperliquid. Type expansion is tracked on the **Roadmap**. See the **Roadmap** for what's shipping next. ## How clients see it Existing Hyperliquid SDKs work unchanged after a `baseUrl` override. See **SDK compatibility** for `nomeida/hyperliquid` (JS) and `hyperliquid-dex/hyperliquid-python-sdk` setup snippets. ## Errors | Status | Body | Cause | | ------ | ---------------------------------------- | ----------------------------------------------------------- | | `400` | `{"error":"invalid request"}` | Malformed body. | | `400` | `{"error":"unsupported_type","type":""}` | The `type` field isn't one of the natively-supported types. | | `401` | `{"error":"unauthorized"}` | Missing or invalid `Authorization` header. | | `5xx` | Server error | Internal server error. | ## Networks Mainnet only. Testnet support is deferred. ## Next ### Migration guide Side-by-side examples - change one URL and one header. ### SDK compatibility Drop-in setup for `nomeida/hyperliquid` and `hyperliquid-python-sdk`. ### Limits and caching No rate limits - what to know about caching and recommended polling cadences. ### API reference Per-endpoint request and response schemas. *** Moving from the public Hyperliquid `/info` API to GoldRush is two changes: 1. **URL** - replace `api.hyperliquid.xyz/info` with `hypercore.goldrushdata.com/info`. 2. **Header** - add `Authorization: Bearer `. That's it. The request body and response shape are byte-for-byte identical. ## Side-by-side ### cURL ```bash Public Hyperliquid theme={null} curl -X POST https://api.hyperliquid.xyz/info \ -H "Content-Type: application/json" \ -d '{ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```bash GoldRush theme={null} curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ### JavaScript / TypeScript ```typescript Public Hyperliquid theme={null} const response = await fetch("https://api.hyperliquid.xyz/info", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "metaAndAssetCtxs", dex: "", }), }); const data = await response.json(); ``` ```typescript GoldRush 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: "metaAndAssetCtxs", dex: "", }), }); const data = await response.json(); ``` ### Python ```python Public Hyperliquid theme={null} import requests response = requests.post( "https://api.hyperliquid.xyz/info", json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` ```python GoldRush theme={null} import os import requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) print(response.json()) ``` ## Behavioral notes Things to be aware of when you cut over. ### Response is byte-equal, modulo live drift For implemented types, the response body matches Hyperliquid byte-for-byte - same keys, same nesting, same value types. Numeric fields update independently on each side, so a market-price field will diverge by tens of milliseconds, but the schema is identical. ### Unsupported types return a JSON error Types that GoldRush doesn't natively serve return `{"error":"unsupported_type","type":""}` with HTTP 400. They are not forwarded to upstream Hyperliquid. See the **Info API overview** for the current list of supported types and the **Roadmap** for what's shipping next. ### Auth errors return JSON A missing or invalid key returns `401` with body `{"error":"unauthorized"}`. Public Hyperliquid has no auth and never returns 401. ### Existing SDKs work after a `baseUrl` override The two most-used SDKs work unchanged: * `nomeida/hyperliquid` (JavaScript) * `hyperliquid-dex/hyperliquid-python-sdk` (Python) See **SDK compatibility** for the override snippets. ## Authentication The Info API uses your standard GoldRush API key. The same key works against the **Foundational API**, the **Streaming API**, and the **Pipeline API**. If you don't have one yet, [sign up here](https://goldrush.dev/platform/auth/register/). Never hardcode keys in source. Use environment variables or a secrets manager. ## What you gain * **No rate limits.** No 1200 weight/min cap, no per-address throttling, no IP buckets. * **Faster reads.** Sub-150 ms p50 target for warm responses; orderbook reads driven from a live WebSocket-fed cache. * **More types.** Batched user state, builder-attribution data, liquidation feed, and composites are on the **Roadmap**. * **HIP-3 and HIP-4 first-class.** Deployer-prefix syntax (`xyz:GOLD-USDC`) is supported across `meta` and `metaAndAssetCtxs` when a `dex` is provided. * **One key for everything Hyperliquid.** The same API key unlocks Streaming, Pipeline, and HyperEVM via the Foundational API. *** The most popular Hyperliquid SDKs work against GoldRush after a one-line `baseUrl` override and adding an `Authorization` header. ## JavaScript / TypeScript: `nomeida/hyperliquid` ### Install ```bash npm theme={null} npm install hyperliquid ``` ```bash yarn theme={null} yarn add hyperliquid ``` ### Configure ```typescript theme={null} import { Hyperliquid } from "hyperliquid"; const sdk = new Hyperliquid({ // Point at GoldRush baseUrl: "https://hypercore.goldrushdata.com", // Inject the Authorization header on every request headers: { Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`, }, }); // Existing methods work unchanged const ctxs = await sdk.info.metaAndAssetCtxs(); const account = await sdk.info.clearinghouseState({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); const spot = await sdk.info.spotClearinghouseState({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); const orders = await sdk.info.frontendOpenOrders({ user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", }); ``` > **Note:** If your SDK version doesn't expose a `headers` option, wrap `fetch` to inject the header globally before instantiating the SDK. See the patch pattern below. ### Header injection fallback ```typescript theme={null} const originalFetch = globalThis.fetch; globalThis.fetch = (input, init = {}) => { const headers = new Headers(init.headers); if (typeof input === "string" && input.startsWith("https://hypercore.goldrushdata.com")) { headers.set("Authorization", `Bearer ${process.env.GOLDRUSH_API_KEY}`); } return originalFetch(input, { ...init, headers }); }; ``` ## Python: `hyperliquid-dex/hyperliquid-python-sdk` ### Install ```bash theme={null} pip install hyperliquid-python-sdk ``` ### Configure ```python theme={null} import os from hyperliquid.info import Info # Point Info at GoldRush info = Info(base_url="https://hypercore.goldrushdata.com", skip_ws=True) # Inject the Authorization header on the underlying session info.session.headers.update({ "Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}" }) # Existing methods work unchanged ctxs = info.meta_and_asset_ctxs() account = info.user_state("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") spot = info.spot_user_state("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") orders = info.frontend_open_orders("0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00") ``` > **Tip:** `skip_ws=True` is recommended when using the Info API only - it skips the WebSocket connection that the SDK opens by default to upstream Hyperliquid. For real-time event streams, use the **GoldRush Streaming API** instead. ## Verification After cutover, confirm everything is wired correctly: 1. **Diff a known wallet** - call `clearinghouseState` for the same wallet against both endpoints; the JSON shape (keys, nesting, types) should match exactly. 2. **Confirm auth** - remove the API key and confirm you get a `401` with body `{"error":"unauthorized"}`. If you get any other response, your request isn't reaching GoldRush. ## Other SDKs The pattern is the same for any HTTP client: override the base URL to `https://hypercore.goldrushdata.com` and attach `Authorization: Bearer `. If you run into a specific SDK that doesn't expose either knob, **email us** - we'll publish a recipe. *** ## No rate limits The GoldRush Hyperliquid Info API has **no per-IP, per-key, or per-address rate limits**. The 1200 weight/min cap on the public Hyperliquid `/info` API does not apply. You can: * Poll any user-state endpoint as fast as your code wants. * Open as many concurrent connections as your client supports. * Pull state for thousands of wallets in tight loops. For wallet-level real-time updates without polling at all, use the **Streaming API `walletTxs` subscription** instead - push-based, also no rate limits. ## How caching works Responses are served from a real-time cache that's kept fresh by direct ingestion from Hyperliquid. The cache is transparent to your client code - same JSON in, same JSON out. | Cache layer | Typical freshness | | --------------------------------------------------------------------------------------- | ------------------------------------ | | User-state types (`clearinghouseState`, `spotClearinghouseState`, `frontendOpenOrders`) | Sub-second after each user event. | | Market types (`metaAndAssetCtxs`) | Sub-second on every mark-price tick. | ## Recommended polling cadences You're not rate-limited, but polling smartly saves your own bandwidth. | Endpoint | Recommended interval | Notes | | ------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------ | | `metaAndAssetCtxs` | 1 second | Mark prices update on every tick - for sub-second freshness, use the Streaming API. | | `clearinghouseState` | 1 second per user, OR push via **`walletTxs`** | Account state only changes on a user event; push is far more efficient than polling. | | `spotClearinghouseState` | 5 seconds | Spot balances change less frequently than perp positions. | | `frontendOpenOrders` | 1 second per user, OR push via `walletTxs` | Same as `clearinghouseState`. | ## Watch out for client-side limits GoldRush has no rate limits, but the rest of your stack might: * **Browser fetch concurrency** - most browsers cap at \~6 concurrent requests per host. Use connection pooling on the server side or batch requests. * **HTTP/2 stream limits** - most clients allow 100+ concurrent streams per connection by default. Bump if you're saturating. * **OS file descriptor limits** - if you're opening thousands of connections, raise `ulimit -n`. For multi-wallet fan-out, use the **`batchClearinghouseState`** and **`batchSpotClearinghouseState`** endpoints, which accept up to 50 wallets per call. For more than 50 wallets, issue multiple calls. ## Network and TLS * **HTTP/2** keep-alive is supported and recommended. * **TLS 1.2+** required. * **`Accept-Encoding: gzip`** is honored. `zstd` support is on the roadmap. ## Need higher guarantees? Enterprise SLA, dedicated capacity, regional pinning, and on-prem options are all available. **Email sales**. *** # Hyperliquid Info API Reference ## batchClearinghouseState **Credit Cost:** 25 per call **Processing:** Realtime > **Note:** - No upstream equivalent. This endpoint exists only on `hypercore.goldrushdata.com`. It is not a passthrough. * Deduplication is case-insensitive. Two addresses that differ only in case (`0xAbC...` vs `0xabc...`) collapse to a single slot in the output, at the position of the first occurrence in the input. * Order preservation. The order of slots in the response matches the order of unique wallets in the input. * Partial failure is normal. HTTP `200 OK` is returned even when individual slots are error envelopes. Always check for the `error` key on each slot before using its fields. * No cursor or pagination. All requested wallets are fanned out in parallel. For batches larger than 50, issue multiple calls. * Use cases: portfolio dashboards, multi-wallet PnL aggregators, fleet-level liquidation risk monitoring, copy-trade source-wallet inventory. Fetches perpetuals account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet, so polling N wallets means N round trips; this endpoint fans them out in parallel against our private node and returns a single combined response. This is a **GoldRush-native extension**. There is no equivalent on `api.hyperliquid.xyz/info`. The wrapped slots return exactly the same shape as Hyperliquid’s native single-wallet `clearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `string` | Yes | Always `"batchClearinghouseState"`. | | `users` | `array` | Yes | List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries. | | `dex` | `string` | No | Optional perpetuals DEX name. Forwarded unchanged to each per-wallet upstream call. Omit for the primary DEX. | ### Example ```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": "batchClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b" ] }' ``` ```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`); } ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "batchClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "0x31ca8395cf837de08b24da3f660e77761dfb974b", ], }, ) slots = response.json() for i, slot in enumerate(slots): if "error" in slot: print(f"wallet {slot['user']} failed: {slot['message']}") continue print(f"wallet {i}: {slot['withdrawable']} USD withdrawable") ``` ## Response ``` HTTP/2 200 OK Content-Type: application/json ``` The body is a JSON array. **Element `i` corresponds to the i-th unique wallet in the deduplicated input order.** Each element is either: * The raw upstream Hyperliquid response object for that wallet (success), or * A slot-level error object (failure for that wallet only, see below). ### All success Example success body for `batchClearinghouseState` with 3 wallets: one empty account, one with a single cross-margin position, one with a single isolated-margin position. ```json theme={null} [ { "user": "0x.....", "marginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "0.0", "assetPositions": [], "time": 1777671895013 }, { "user": "0x.....", "marginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"}, "crossMarginSummary": {"accountValue":"28.848558","totalNtlPos":"134.30367","totalRawUsd":"163.152228","totalMarginUsed":"22.383945"}, "crossMaintenanceMarginUsed": "6.715183", "withdrawable": "6.464613", "assetPositions": [ { "type": "oneWay", "position": { "coin": "SUI", "szi": "-145.8", "leverage": { "type": "cross", "value": 6 }, "entryPx": "0.91652", "positionValue": "134.30367", "unrealizedPnl": "-0.674997", "returnOnEquity": "-0.0303077319", "liquidationPx": "1.0657275328", "marginUsed": "22.383945", "maxLeverage": 10, "cumFunding": { "allTime": "0.348217", "sinceOpen": "0.234102", "sinceChange": "0.206894" } } } ], "time": 1777671895076 }, { "user": "0x.....", "marginSummary": {"accountValue":"681.226963","totalNtlPos":"1353.54306","totalRawUsd":"-672.316097","totalMarginUsed":"681.226963"}, "crossMarginSummary": {"accountValue":"0.0","totalNtlPos":"0.0","totalRawUsd":"0.0","totalMarginUsed":"0.0"}, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "0.0", "assetPositions": [ { "type": "oneWay", "position": { "coin": "BTC", "szi": "0.01734", "leverage": { "type": "isolated", "value": 2, "rawUsd": "-672.316097" }, "entryPx": "77441.3", "positionValue": "1353.54306", "unrealizedPnl": "10.710288", "returnOnEquity": "0.0159517823", "liquidationPx": "39263.3464441622", "marginUsed": "681.226963", "maxLeverage": 40, "cumFunding": { "allTime": "0.326319", "sinceOpen": "0.271556", "sinceChange": "-0.026742" } } } ], "time": 1777671895076 } ] ``` ### Mixed result (one wallet failed) When a single wallet fails (upstream timeout, transport failure, parse failure, etc.), only its slot is replaced with an error object. The rest of the batch is unaffected. The HTTP status is still `200 OK`. ```json theme={null} [ { "withdrawable": "13104.514502", "...": "..." }, { "error": "upstream_error", "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "message": "overall batch timeout exceeded" }, { "withdrawable": "0.0", "...": "..." } ] ``` ### Per-wallet error slot | Field | Type | Description | | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `error` | `string` | Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field. | | `user` | `string` | The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order. | | `message` | `string` | Human-readable description: `upstream_error: `, `upstream returned HTTP `, `overall batch timeout exceeded`, or similar. | ## clearinghouseState slot field reference Each success slot mirrors Hyperliquid's native `clearinghouseState` response: `assetPositions[]`, `crossMarginSummary`, `marginSummary`, `crossMaintenanceMarginUsed`, `time`, `withdrawable`. There is no schema imposition - it's the raw upstream object. For full per-field types and notes (including the two `leverage` shapes and the nullable `liquidationPx`), see the single-wallet endpoint: ### clearinghouseState field reference Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot. For the canonical upstream documentation, see Hyperliquid's [Perpetuals info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals). *** ## batchSpotClearinghouseState **Credit Cost:** 25 per call **Processing:** Realtime > **Note:** - No upstream equivalent. This endpoint exists only on `hypercore.goldrushdata.com`. It is not a passthrough. * Deduplication is case-insensitive. Two addresses that differ only in case collapse to a single slot at the position of the first occurrence in the input. * Order preservation. Slots in the response are in the order of unique wallets in the input. * Partial failure is normal. HTTP `200 OK` is returned even when individual slots are error envelopes. Always check for the `error` key on each slot before using its fields. * No cursor or pagination. All requested wallets are fanned out in parallel. For batches larger than 50, issue multiple calls. * Use cases: token treasury monitoring, holder analytics, balance reconciliation, multi-wallet airdrop eligibility checks. Fetches spot account state for **1 to 50 wallets** in a single request. The standard Hyperliquid `/info` API is single-wallet; this endpoint fans the requests out in parallel against our private node and returns a combined response. This is a **GoldRush-native extension**. There is no equivalent on `api.hyperliquid.xyz/info`. The wrapped slots return exactly the same shape as Hyperliquid’s native single-wallet `spotClearinghouseState`, with a thin per-wallet error envelope when an individual wallet fails. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `string` | Yes | Always `"batchSpotClearinghouseState"`. | | `users` | `array` | Yes | List of wallet addresses to query. **1 to 50 entries.** Duplicates are removed (case-insensitive); input order is preserved for the surviving entries. | | `dex` | `string` | No | Reserved for future HIP-3 spot DEX support. Pass empty string or omit. | ### Example ```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" ] }' ``` ```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: "batchSpotClearinghouseState", users: [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", ], }), }); 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.balances.length} tokens`); } ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "batchSpotClearinghouseState", "users": [ "0xb0a55f13d22f66e6d495ac98113841b2326e9540", "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", ], }, ) slots = response.json() for i, slot in enumerate(slots): if "error" in slot: print(f"wallet {slot['user']} failed: {slot['message']}") continue print(f"wallet {i}: {len(slot['balances'])} tokens") ``` ## Response ``` HTTP/2 200 OK Content-Type: application/json ``` The body is a JSON array. **Element `i` corresponds to the i-th unique wallet in the deduplicated input order.** Each element is either: * The raw upstream Hyperliquid response object for that wallet (success), or * A slot-level error object (failure for that wallet only, see below). ### All success Example success body for `batchSpotClearinghouseState` with 3 wallets: one empty wallet, one with a single USDC balance, one with multiple tokens including held amounts. ```json theme={null} [ { "user": "0x.....", "balances": [] }, { "user": "0x.....", "balances": [ { "coin": "USDC", "token": 0, "total": "0.001124", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDE", "token": 235, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDT0", "token": 268, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" }, { "coin": "USDH", "token": 360, "total": "0.0", "hold": "0.0", "entryNtl": "0.0" } ], "tokenToAvailableAfterMaintenance": [[0, "0.001124"]] }, { "user": "0x.....", "balances": [ { "coin": "USDC", "token": 0, "total": "129411.68874505", "hold": "73888.84763", "entryNtl": "0.0" }, { "coin": "HYPE", "token": 150, "total": "959.37146013", "hold": "0.0", "entryNtl": "33092.4684" }, { "coin": "UBTC", "token": 197, "total": "0.2104009544", "hold": "0.0", "entryNtl": "16128.2486005" }, { "coin": "UETH", "token": 221, "total": "20.87812637", "hold": "7.0018", "entryNtl": "49605.34810641" } ] } ] ``` ### Mixed result (one wallet failed) When a single wallet fails (upstream timeout, transport failure, parse failure, etc.), only its slot is replaced with an error object. The rest of the batch is unaffected. The HTTP status is still `200 OK`. ```json theme={null} [ { "balances": [...] }, { "error": "upstream_error", "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc", "message": "overall batch timeout exceeded" } ] ``` ### Per-wallet error slot | Field | Type | Description | | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `error` | `string` | Always `"upstream_error"` for slot-level failures. Distinguishes error slots from success slots, which never have a top-level `error` field. | | `user` | `string` | The exact wallet address (lowercased) whose slot this is. Lets you correlate even if you didn't track input order. | | `message` | `string` | Human-readable description: `upstream_error: `, `upstream returned HTTP `, `overall batch timeout exceeded`, or similar. | ## spotClearinghouseState slot field reference Each success slot mirrors Hyperliquid's native `spotClearinghouseState` response: `balances[]` plus the optional `tokenToAvailableAfterMaintenance` field. There is no schema imposition - it's the raw upstream object. The `tokenToAvailableAfterMaintenance` field is **optional** and only present when at least one token has a non-zero margin-deduction-aware balance. Wallets without this field can simply ignore it; absence is normal for empty or inactive wallets. For full per-field types and notes, see the single-wallet endpoint: ### spotClearinghouseState field reference Full request and response schema for the single-wallet variant. The batch endpoint returns the same object per slot. For the canonical upstream documentation, see Hyperliquid's [Spot info docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot). *** ## clearinghouseState **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "clearinghouseState", "user": "..."}`. * For real-time push instead of polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) with the same wallet address. * The optional `dex` field returns state on a HIP-3 deployer’s perp DEX. Returns a single user’s perpetuals account state: every open position, margin summary, account value, and withdrawable balance. User-keyed: pass a wallet address. Cached and kept fresh by a per-user WebSocket subscription to upstream Hyperliquid, so updates are sub-second after any user event. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Always `"clearinghouseState"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) returns canonical Hyperliquid perp state. Pass a builder code to query a HIP-3 deployer's perp DEX. | ### Example ```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": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```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 state = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "clearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) state = response.json() ``` ## Response ```json theme={null} { "marginSummary": { "accountValue": "12450.83", "totalNtlPos": "8500.00", "totalRawUsd": "5200.50", "totalMarginUsed": "1700.00" }, "crossMarginSummary": { "accountValue": "12450.83", "totalNtlPos": "8500.00", "totalRawUsd": "5200.50", "totalMarginUsed": "1700.00" }, "crossMaintenanceMarginUsed": "850.00", "withdrawable": "10750.83", "assetPositions": [ { "type": "oneWay", "position": { "coin": "ETH", "szi": "2.5", "leverage": { "type": "cross", "value": 5 }, "entryPx": "3400.0", "positionValue": "8500.00", "unrealizedPnl": "120.50", "returnOnEquity": "0.07", "liquidationPx": "2800.5", "marginUsed": "1700.00", "maxLeverage": 50, "cumFunding": { "allTime": "12.30", "sinceOpen": "1.50", "sinceChange": "0.50" } } } ], "time": 1735689600000 } ``` ### Field descriptions > **Note:** All numeric fields below (account value, position size, prices, funding amounts, etc.) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `marginSummary` | `object` | Top-level account margin and value summary. | | `marginSummary.accountValue` | `string` | Total account value in USD. | | `marginSummary.totalNtlPos` | `string` | Total notional position size. | | `marginSummary.totalRawUsd` | `string` | Raw USDC balance excluding unrealized PnL. | | `marginSummary.totalMarginUsed` | `string` | Margin currently committed to open positions. | | `crossMarginSummary` | `object` | Cross-margin subset of the margin summary. Same fields. | | `crossMaintenanceMarginUsed` | `string` | Maintenance margin currently used for cross positions. | | `withdrawable` | `string` | Amount currently withdrawable, in USD. | | `assetPositions` | `array` | Open positions, one entry per coin. | | `assetPositions.type` | `string` | Position type - `"oneWay"` for the standard mode. | | `assetPositions.position` | `object` | \_\_RESPONSE\_ROW\_\_coin string Asset symbol. \_\_RESPONSE\_ROW\_\_assetPositions.szi string Signed position size (positive = long, negative = short). \_\_RESPONSE\_ROW\_\_assetPositions.leverage object Two shapes: - Cross: `{ "type": "cross", "value": int }` - Isolated: `{ "type": "isolated", "value": int, "rawUsd": string }` `rawUsd` is **only present** for isolated leverage and may be negative. \_\_RESPONSE\_ROW\_\_assetPositions.entryPx string Volume-weighted entry price. \_\_RESPONSE\_ROW\_\_assetPositions.positionValue string Current notional value. \_\_RESPONSE\_ROW\_\_assetPositions.unrealizedPnl string Unrealized PnL in USD. \_\_RESPONSE\_ROW\_\_assetPositions.returnOnEquity string Unrealized return on margin used. \_\_RESPONSE\_ROW\_\_assetPositions.liquidationPx string \| null Liquidation price. **May be literal JSON `null`** when no near-term liquidation applies (e.g. cross-margin with deep cushion). \_\_RESPONSE\_ROW\_\_assetPositions.marginUsed string Margin committed to this position. \_\_RESPONSE\_ROW\_\_assetPositions.maxLeverage int Maximum leverage for this asset. \_\_RESPONSE\_ROW\_\_assetPositions.cumFunding object Cumulative funding paid: `allTime`, `sinceOpen`, `sinceChange`. | | `time` | `int` | Snapshot timestamp in milliseconds since Unix epoch. | *** ## delegatorHistory **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorHistory", "user": "..."}`. * For totals (delegated, undelegated, pending withdrawal sums), use [`delegatorSummary`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-summary). * For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards). * For real-time push of staking events, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreDelegationEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-delegation-event) entries. Returns a user’s HYPE staking event history: every delegate, undelegate, staking-account deposit, and unstake withdrawal, ordered by `time`. Use this to reconstruct the sequence behind the totals shown in [delegatorSummary](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-summary). User-keyed. Each entry carries a `delta` whose discriminator describes the event variant. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `type` | `string` | Yes | Always `"delegatorHistory"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "delegatorHistory", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```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: "delegatorHistory", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const events = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorHistory", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) events = response.json() ``` ## Response An array of staking event objects. ```json theme={null} [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "delegate": { "validator": "0x5ac99df645f3414876c816caa18b2d234024b487", "amount": "1000.5", "isUndelegate": false } } } ] ``` ### Field descriptions > **Note:** `delta.delegate.amount` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float. | Field | Type | Description | | ----------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `time` | `int` | Unix timestamp in milliseconds when the event was applied. | | `hash` | `string` | L1 transaction hash that produced the event. | | `delta` | `object` | Event-specific payload. The example above shows a `delegate` variant; other variants observed in the wild include `cDeposit` (staking-account deposit) and `withdrawal` (unstake withdrawal). The shape changes per variant. | | `delta.delegate.validator` | `string` | Validator address the delegation targets. | | `delta.delegate.amount` | `string` | HYPE amount delegated or undelegated. | | `delta.delegate.isUndelegate` | `boolean` | `true` for an undelegate, `false` for a delegate. | *** ## delegatorRewards **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorSummary", "user": "..."}`. * For the sequence of delegation events behind these totals, use [`delegatorHistory`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history). * For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards). Returns a single user’s accrued HYPE staking rewards: one entry per accrual, with the timestamp, the source (delegation reward versus validator commission), and the amount. User-keyed. Use this for tax reports, reward attribution dashboards, and validator P\&L; use [delegatorHistory](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history) for the underlying delegate / undelegate events and [delegatorSummary](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-summary) for current totals. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `type` | `string` | Yes | Always `"delegatorRewards"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "delegatorRewards", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```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: "delegatorRewards", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const rewards = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorRewards", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) rewards = response.json() ``` ## Response An array of reward entries. ```json theme={null} [ { "time": 1735689600000, "source": "delegation", "totalAmount": "1.5234" }, { "time": 1735776000000, "source": "commission", "totalAmount": "0.8791" } ] ``` ### Field descriptions > **Note:** `totalAmount` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float. | Field | Type | Description | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `time` | `int` | Unix timestamp in milliseconds when the reward accrued. | | `source` | `string` | Reward source. `"delegation"` for rewards earned by delegating to a validator; `"commission"` for commission earned as a validator on others' delegations. | | `totalAmount` | `string` | Reward amount in HYPE. | *** ## delegatorSummary **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "delegatorSummary", "user": "..."}`. * For the sequence of delegation events behind these totals, use [`delegatorHistory`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history). * For accrued staking and commission rewards, use [`delegatorRewards`](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-rewards). Returns a single user’s HYPE staking summary: the amount currently delegated, the amount sitting undelegated in the staking account, the total of any pending withdrawals, and how many such withdrawals are pending. User-keyed. Use this for a one-shot snapshot; for the underlying sequence of delegate / undelegate / deposit / withdrawal events, use [delegatorHistory](https://goldrush.dev/docs/api-reference/hyperliquid/delegator-history). ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `type` | `string` | Yes | Always `"delegatorSummary"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "delegatorSummary", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036" }' ``` ```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: "delegatorSummary", user: "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }), }); const summary = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "delegatorSummary", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }, ) summary = response.json() ``` ## Response ```json theme={null} { "delegated": "1500.50", "undelegated": "250.00", "totalPendingWithdrawal": "100.00", "nPendingWithdrawals": 2 } ``` ### Field descriptions > **Note:** `delegated`, `undelegated`, and `totalPendingWithdrawal` are returned as **decimal strings**. Do not parse them as floats. | Field | Type | Description | | ------------------------ | -------- | ------------------------------------------------- | | `delegated` | `string` | HYPE currently delegated to validators. | | `undelegated` | `string` | HYPE in the staking account but not delegated. | | `totalPendingWithdrawal` | `string` | Sum of HYPE in any in-flight unstake withdrawals. | | `nPendingWithdrawals` | `int` | Count of in-flight unstake withdrawals. | *** ## frontendOpenOrders **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "frontendOpenOrders", "user": "..."}`. * Use `frontendOpenOrders` instead of `openOrders` when you need the trigger metadata and human-readable order type - exactly what the Hyperliquid web UI displays. * For a real-time stream of order placement and cancellation events, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream). Returns a single user’s currently open orders, enriched with the **frontend-only metadata** the Hyperliquid web UI uses: TP/SL trigger info, whether the order is a position-level TP/SL, reduce-only flag, and the human-readable order type. User-keyed. Updated on every order placement, cancellation, or fill. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------ | | `type` | `string` | Yes | Always `"frontendOpenOrders"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string returns orders on the canonical Hyperliquid perp DEX. | ### Example ```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": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```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: "frontendOpenOrders", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const orders = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "frontendOpenOrders", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) orders = response.json() ``` ## Response An array of open orders. Each order object includes the standard `openOrders` fields plus the `frontend*` enrichment fields. ```json theme={null} [ { "coin": "ETH", "side": "B", "limitPx": "3300.0", "sz": "0.5", "oid": 95012345, "timestamp": 1735689600000, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "children": [], "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "origSz": "0.5", "tif": "Gtc", "cloid": null }, { "coin": "ETH", "side": "A", "limitPx": "3800.0", "sz": "2.5", "oid": 95012346, "timestamp": 1735689700000, "triggerCondition": "Mark price >= 3800.0", "isTrigger": true, "triggerPx": "3800.0", "children": [], "isPositionTpsl": true, "reduceOnly": true, "orderType": "Take Profit Market", "origSz": "2.5", "tif": null, "cloid": null } ] ``` ### Field descriptions | Field | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------- | | `coin` | `string` | Asset symbol. | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `limitPx` | `string` | Limit price. | | `sz` | `string` | Remaining order size. | | `oid` | `int` | Numeric order ID. | | `timestamp` | `int` | Order placement time in milliseconds since Unix epoch. | | `triggerCondition` | `string` | Human-readable trigger condition. `"N/A"` for non-trigger orders. | | `isTrigger` | `boolean` | `true` for stop-loss, take-profit, and other conditional orders. | | `triggerPx` | `string` | Trigger price for conditional orders. `"0.0"` for limits. | | `children` | `array` | Child orders attached to this parent (e.g. bracket orders). | | `isPositionTpsl` | `boolean` | `true` if this is a position-level TP/SL (closes the entire position when triggered). | | `reduceOnly` | `boolean` | `true` if this order can only reduce, not increase, position size. | | `orderType` | `string` | Human-readable order type - `"Limit"`, `"Take Profit Market"`, `"Stop Limit"`, etc. | | `origSz` | `string` | Original order size before any partial fills. | | `tif` | `string` | Time-in-force - `"Gtc"`, `"Ioc"`, `"Alo"`, or `null` for trigger orders. | | `cloid` | `string` | Client order ID (null if not provided at placement). | *** ## metaAndAssetCtxs **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "metaAndAssetCtxs"}`. * For real-time mark-price updates, use the [Streaming API OHLCV streams](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) instead of polling. Returns a tuple `[meta, assetCtxs[]]` covering the entire Hyperliquid perpetuals universe - every coin’s metadata plus a live snapshot of mark price, funding rate, open interest, and 24-hour volume. This is a global, non-user-keyed type. A single cache entry is shared across all callers and is refreshed continuously from upstream Hyperliquid. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `string` | Yes | Always `"metaAndAssetCtxs"`. | | `dex` | `string` | No | HIP-3 builder DEX identifier. Empty string (default) returns the canonical Hyperliquid perp universe. Pass a builder code (e.g. `"xyz"`) to query a HIP-3 deployer's universe. | ### Example ```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", "dex": "" }' ``` ```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: "metaAndAssetCtxs", dex: "", }), }); const [meta, assetCtxs] = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "metaAndAssetCtxs", "dex": ""}, ) meta, asset_ctxs = response.json() ``` ## Response A two-element JSON array. Element 0 is the universe metadata; element 1 is an array of per-asset contexts indexed identically to the `universe` array. ```json theme={null} [ { "universe": [ { "name": "BTC", "szDecimals": 5, "maxLeverage": 50 }, { "name": "ETH", "szDecimals": 4, "maxLeverage": 50 }, { "name": "SOL", "szDecimals": 2, "maxLeverage": 20 } ] }, [ { "funding": "0.0000125", "openInterest": "12345.67", "prevDayPx": "67500.0", "dayNtlVlm": "894500000.0", "premium": "0.00001", "oraclePx": "68210.5", "markPx": "68215.0", "midPx": "68214.0", "impactPxs": ["68210.0", "68220.0"], "dayBaseVlm": "13130.45" }, { "funding": "0.0000050", "openInterest": "9876.54", "...": "..." }, { "funding": "0.0000200", "openInterest": "543210.98", "...": "..." } ] ] ``` ### Element 0: `meta` | Field | Type | Description | | ----------------------- | --------- | -------------------------------------------------------------------------------------- | | `universe` | `array` | Array of perp asset metadata, indexed identically to element 1's `assetCtxs`. | | `universe.name` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"`. For HIP-3 markets, includes the deployer prefix. | | `universe.szDecimals` | `int` | Number of decimals for size precision. | | `universe.maxLeverage` | `int` | Maximum leverage for this asset. | | `universe.onlyIsolated` | `boolean` | If true, the asset only supports isolated margin. | ### Element 1: `assetCtxs[]` Array of per-asset live context, indexed identically to `universe`. | Field | Type | Description | | -------------- | -------- | ----------------------------------------------- | | `funding` | `string` | Current funding rate (decimal string). | | `openInterest` | `string` | Open interest in base units. | | `prevDayPx` | `string` | Mark price 24 hours ago. | | `dayNtlVlm` | `string` | 24-hour notional volume in USD. | | `premium` | `string` | Mark vs oracle premium. | | `oraclePx` | `string` | Current oracle price. | | `markPx` | `string` | Current mark price. | | `midPx` | `string` | Current orderbook mid price. | | `impactPxs` | `array` | Bid/ask impact prices `[bidImpact, askImpact]`. | | `dayBaseVlm` | `string` | 24-hour volume in base units. | *** ## outcomeMeta **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "outcomeMeta"}`. * For real-time price updates on a discovered outcome, subscribe to [`ohlcvCandlesForPair`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) using the per-side encoding. See the [HIP-4 markets recipe](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip4-markets) for end-to-end discovery and streaming patterns. * HIP-4 launched on Hyperliquid mainnet on May 2, 2026. Read the canonical spec: [HIP-4: Outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets). Returns the live HIP-4 outcome universe: every active binary outcome market on HyperCore with its integer `outcome` ID, human-readable `name`, structured `description`, and `sideSpecs` (Yes / No). This is a global, non-user-keyed type. A single cache entry is shared across all callers and is refreshed continuously from upstream Hyperliquid. `outcomeMeta` is HIP-4’s dedicated metadata type - separate from `metaAndAssetCtxs`, which covers perps and spot. Use it to discover live outcome IDs and compute per-side market encodings (`encoding = 10 * outcome + side`) before subscribing to OHLCV or fills. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------- | | `type` | `string` | Yes | Always `"outcomeMeta"`. | ### Example ```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": "outcomeMeta" }' ``` ```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: "outcomeMeta", }), }); const { outcomes } = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "outcomeMeta"}, ) outcomes = response.json()["outcomes"] ``` ## Response ```json theme={null} { "outcomes": [ { "outcome": 123, "name": "Recurring", "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m", "sideSpecs": [ { "name": "Yes" }, { "name": "No" } ] } ] } ``` ### Field descriptions | Field | Type | Description | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outcomes` | `array` | Array of active outcome markets. | | `outcomes.outcome` | `int` | Integer outcome ID. Combine with a side index to compute the tradeable market encoding: `encoding = 10 * outcome + side`. An outcome with `Yes` (side 0) and `No` (side 1) yields two encodings (e.g. `1230` and `1231`). | | `outcomes.name` | `string` | Human-readable label for the market - for example, `"Recurring"` for repeating daily/weekly markets. | | `outcomes.description` | `string` | Pipe-delimited spec describing the market. Parse it once to extract the full definition: \| Field \| Example \| Meaning \| \|---\|---\|---\| \| `class` \| `priceBinary` \| Market class (binary outcome on a price threshold). \| \| `underlying` \| `HYPE` \| Asset the outcome resolves against. \| \| `expiry` \| `20260310-1100` \| Resolution timestamp, `YYYYMMDD-HHMM` UTC. \| \| `targetPrice` \| `34.5` \| Threshold the underlying is compared against at expiry. \| \| `period` \| `3m` \| Recurrence cadence for repeating markets. \| | | `outcomes.sideSpecs` | `array` | Tradeable sides of the outcome, ordered by side index. For binary outcomes, index 0 is `Yes` and index 1 is `No`. \_\_RESPONSE\_ROW\_\_name string Side label - typically `"Yes"` or `"No"` for binary outcomes. | *** ## spotClearinghouseState **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotClearinghouseState", "user": "..."}`. * USDC balance is returned as `token: 0`. * For real-time push of spot transfers, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerSpotTransfer` events. Returns a single user’s spot account state - token-by-token balances and the total USD value. User-keyed. Cached and kept fresh by a per-user WebSocket subscription, so updates are sub-second after any user event. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------------------------- | | `type` | `string` | Yes | Always `"spotClearinghouseState"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `dex` | `string` | No | Reserved for future HIP-3 spot DEX support. Pass empty string. | ### Example ```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": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "" }' ``` ```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: "spotClearinghouseState", user: "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", dex: "", }), }); const state = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "spotClearinghouseState", "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", "dex": "", }, ) state = response.json() ``` ## Response ```json theme={null} { "balances": [ { "coin": "USDC", "token": 0, "hold": "0.0", "total": "5000.00", "entryNtl": "5000.00" }, { "coin": "HYPE", "token": 150, "hold": "0.0", "total": "320.45", "entryNtl": "1530.00" }, { "coin": "PURR", "token": 1, "hold": "0.0", "total": "12500.0", "entryNtl": "375.00" } ], "tokenToAvailableAfterMaintenance": [[0, "5000.00"]] } ``` ### Field descriptions > **Note:** All numeric balance fields (`total`, `hold`, `entryNtl`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `balances` | `array` | One entry per token the wallet has interacted with on Hyperliquid spot. May be empty (`[]`) for wallets with no spot history. | | `balances.coin` | `string` | Token ticker symbol (e.g. `"USDC"`, `"PURR"`, `"HYPE"`). | | `balances.token` | `int` | Numeric token index assigned by Hyperliquid. The pair `(coin, token)` together identifies the asset. | | `balances.hold` | `string` | Portion of `total` currently locked in open spot orders. Withdrawable balance is `total - hold`. | | `balances.total` | `string` | Total balance (held + free). | | `balances.entryNtl` | `string` | Entry notional value at acquisition, in USD. | | `tokenToAvailableAfterMaintenance` | `array` | **Optional.** Present only when at least one token has a non-zero margin-deduction-aware balance. Each tuple is `[tokenId, availableAmountString]` where `tokenId` references `balances[].token`. Wallets without this field can ignore it; absence is normal for empty or inactive wallets. | *** ## spotMetaAndAssetCtxs **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "spotMetaAndAssetCtxs"}`. * For perp universe + live contexts, use [`metaAndAssetCtxs`](https://goldrush.dev/docs/api-reference/hyperliquid/meta-and-asset-ctxs) instead. * For real-time mark-price updates on a discovered spot pair, use the [Streaming API OHLCV pair stream](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream). Returns a tuple `[spotMeta, assetCtxs[]]` covering the entire Hyperliquid spot universe - every pair’s universe entry, every token’s metadata, and a live snapshot of mark price, mid price, prior-day price, and 24-hour notional volume per pair. This is the spot counterpart of `metaAndAssetCtxs`. Global, non-user-keyed; a single cache entry is shared across all callers and refreshed continuously from upstream Hyperliquid. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | -------------------------------- | | `type` | `string` | Yes | Always `"spotMetaAndAssetCtxs"`. | ### Example ```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": "spotMetaAndAssetCtxs" }' ``` ```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: "spotMetaAndAssetCtxs", }), }); const [spotMeta, assetCtxs] = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={"type": "spotMetaAndAssetCtxs"}, ) spot_meta, asset_ctxs = response.json() ``` ## Response A two-element JSON array. Element 0 is the spot universe and token metadata; element 1 is an array of per-pair live contexts indexed identically to element 0's `universe`. ```json theme={null} [ { "universe": [ { "name": "PURR/USDC", "tokens": [1, 0], "index": 0, "isCanonical": true } ], "tokens": [ { "name": "USDC", "szDecimals": 8, "weiDecimals": 8, "index": 0, "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054", "isCanonical": true, "evmContract": null, "fullName": null }, { "name": "PURR", "szDecimals": 0, "weiDecimals": 5, "index": 1, "tokenId": "0xc1fb593aeffbeb02f85e0308e9956a90", "isCanonical": true, "evmContract": null, "fullName": null } ] }, [ { "coin": "PURR/USDC", "markPx": "0.5250", "midPx": "0.5245", "prevDayPx": "0.4800", "dayNtlVlm": "1250000.0", "dayBaseVlm": "2380952.38", "circulatingSupply": "1000000000.0" } ] ] ``` ### Element 0: `spotMeta` | Field | Type | Description | | | ---------------------- | --------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `universe` | `array` | Array of spot pairs, indexed identically to element 1's `assetCtxs`. | | | `universe.name` | `string` | Pair label - e.g. `"PURR/USDC"`. | | | `universe.tokens` | `array` | Two-element array of token indices `[base, quote]` referencing entries in `tokens[].index`. | | | `universe.index` | `int` | Numeric pair index. The spot encoding for trading subscriptions is `10000 + index`. | | | `universe.isCanonical` | `boolean` | `true` for pairs in the canonical Hyperliquid spot universe. | | | `tokens` | `array` | Token configuration referenced by `universe[].tokens`. | | | `tokens.name` | `string` | Token symbol - e.g. `"USDC"`, `"PURR"`. | | | `tokens.szDecimals` | `int` | Number of decimals used for size precision. | | | `tokens.weiDecimals` | `int` | Number of decimals used for the on-chain wei representation. | | | `tokens.index` | `int` | Token index. `(coin, index)` together identifies the asset. | | | `tokens.tokenId` | `string` | Hyperliquid token identifier (hex). | | | `tokens.isCanonical` | `boolean` | `true` for tokens deployed in the canonical Hyperliquid spot universe. | | | `tokens.evmContract` | \`object | null\` | EVM contract address if the token has an HyperEVM mapping; `null` otherwise. | | `tokens.fullName` | \`string | null\` | Optional full token name. | ### Element 1: `assetCtxs[]` Array of per-pair live context, indexed identically to `universe`. > **Note:** All numeric fields below are returned as **decimal strings**. Do not parse them as floats. | Field | Type | Description | | ------------------- | -------- | ---------------------------------------- | | `coin` | `string` | Pair symbol - matches `universe[].name`. | | `markPx` | `string` | Current mark price. | | `midPx` | `string` | Current orderbook mid price. | | `prevDayPx` | `string` | Mark price 24 hours ago. | | `dayNtlVlm` | `string` | 24-hour notional volume in USDC. | | `dayBaseVlm` | `string` | 24-hour volume in base units. | | `circulatingSupply` | `string` | Circulating supply of the base token. | *** ## subAccounts **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "subAccounts", "user": "..."}`. * For per-sub-account real-time updates, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) on each `subAccountUser` returned here. * For multi-wallet polling without traversing master/sub-account hierarchy, see [`batchClearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid/batch-clearinghouse-state) and [`batchSpotClearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid/batch-spot-clearinghouse-state). Returns the sub-accounts owned by a master wallet, with each sub-account’s perp [clearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid/clearinghouse-state) and spot [spotClearinghouseState](https://goldrush.dev/docs/api-reference/hyperliquid/spot-clearinghouse-state) inlined per slot - so a single call returns the full balance picture across the master plus its sub-accounts. User-keyed. The result is `null` for wallets that aren’t master accounts. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------ | | `type` | `string` | Yes | Always `"subAccounts"`. | | `user` | `string` | Yes | The master wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "subAccounts", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036" }' ``` ```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: "subAccounts", user: "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }), }); const subAccounts = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "subAccounts", "user": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", }, ) sub_accounts = response.json() ``` ## Response An array of sub-account objects, or `null` if the queried wallet is not a master account. ```json theme={null} [ { "name": "trading-bot-1", "subAccountUser": "0x2b804617c6f63c040377e95bb276811747006f4b", "master": "0x2ba553d9f990a3b66b03b2dc0d030dfc1c061036", "clearinghouseState": { "marginSummary": { "accountValue": "5000.00", "totalNtlPos": "0.0", "totalRawUsd": "5000.00", "totalMarginUsed": "0.0" }, "crossMarginSummary": { "accountValue": "5000.00", "totalNtlPos": "0.0", "totalRawUsd": "5000.00", "totalMarginUsed": "0.0" }, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "5000.00", "assetPositions": [], "time": 1735689600000 }, "spotState": { "balances": [ { "coin": "USDC", "token": 0, "hold": "0.0", "total": "1000.00", "entryNtl": "1000.00" } ] } } ] ``` ### Field descriptions | Field | Type | Description | | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Optional human-readable label assigned to the sub-account. | | `subAccountUser` | `string` | The sub-account's wallet address (0x-prefixed hex). | | `master` | `string` | The master wallet address that owns this sub-account. | | `clearinghouseState` | `object` | Perp account state for this sub-account. Identical shape to the single-wallet **`clearinghouseState`** response - margin summaries, asset positions, withdrawable balance, snapshot timestamp. | | `spotState` | `object` | Spot account state for this sub-account. Identical shape to the single-wallet **`spotClearinghouseState`** response - per-token balances and the optional `tokenToAvailableAfterMaintenance` array. | *** ## userFillsByTime **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFillsByTime", "user": "...", "startTime": ...}`. * Each response contains at most 2,000 fills; widen the window in chunks if you need more. Hyperliquid retains only the 10,000 most recent fills per wallet. * For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events. * Use [`userFills`](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals) (no `Time` suffix) when you only need the most recent N fills without specifying a window. Returns a single user’s fills bounded by a `[startTime, endTime)` window in milliseconds. Use this when you want fills since a specific moment - daily P\&L recaps, post-deploy backfills, or rebuilding a tax ledger - rather than the most recent N fills. User-keyed. The upstream Hyperliquid API caps each response at **2,000 fills** and only retains the **10,000 most recent** fills per wallet; window queries that span more than that are truncated. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Always `"userFillsByTime"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | Yes | Unix timestamp in milliseconds. Inclusive lower bound. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | | `aggregateByTime` | `boolean` | No | When `true`, partial fills sharing the same timestamp are consolidated into one row. Default `false`. | ### Example ```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": "userFillsByTime", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000 }' ``` ```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: "userFillsByTime", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, }), }); const fills = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFillsByTime", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, }, ) fills = response.json() ``` ## Response An array of fill objects ordered by `time`. ```json theme={null} [ { "coin": "BTC", "px": "43250.5", "sz": "0.1", "side": "B", "time": 1735689600000, "startPosition": "0", "dir": "Open Long", "closedPnl": "0", "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "oid": 95012345, "tid": 678900012345, "crossed": true, "fee": "2.16", "feeToken": "USDC" } ] ``` ### Field descriptions > **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | | --------------- | --------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | | `px` | `string` | Fill execution price. | | | `sz` | `string` | Fill size. | | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | | `time` | `int` | Unix timestamp in milliseconds when the fill executed. | | | `startPosition` | `string` | Signed position size on the same coin immediately before this fill. | | | `dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | | `closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). | | | `hash` | `string` | L1 transaction hash that included this fill. | | | `oid` | `int` | Parent order ID. | | | `tid` | `int` | Unique trade ID. | | | `crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. | | | `fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. | | | `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | | `builderFee` | `string` | Optional. Builder fee paid for this fill if the order routed through a builder code. | | | `twapId` | \`int | null\` | Optional TWAP order ID if this fill is a slice of a TWAP order. | | `cloid` | \`string | null\` | Optional client order ID if one was set at order placement. | *** ## userFills **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFills", "user": "..."}`. * Each response contains at most 2,000 fills. * For real-time push instead of windowed polling, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `HypercoreFillTransaction` events. Returns the most recent fills for a user, up to 2,000. Use this when you need the latest trade activity without specifying a time window. User-keyed. The upstream Hyperliquid API caps each response at **2,000 fills** per wallet. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Always `"userFills"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `aggregateByTime` | `boolean` | No | When `true`, partial fills sharing the same timestamp are consolidated into one row. Default `false`. | ### Example ```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": "userFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```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: "userFills", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const fills = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) fills = response.json() ``` ## Response An array of fill objects ordered most-recent-first. ```json theme={null} [ { "coin": "BTC", "px": "43250.5", "sz": "0.1", "side": "B", "time": 1735689600000, "startPosition": "0", "dir": "Open Long", "closedPnl": "0", "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "oid": 95012345, "tid": 678900012345, "crossed": true, "fee": "2.16", "feeToken": "USDC" } ] ``` ### Field descriptions > **Note:** All numeric fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`, `builderFee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | | --------------- | --------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | `coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | | `px` | `string` | Fill execution price. | | | `sz` | `string` | Fill size. | | | `side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | | `time` | `int` | Unix timestamp in milliseconds when the fill executed. | | | `startPosition` | `string` | Signed position size on the same coin immediately before this fill. | | | `dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | | `closedPnl` | `string` | Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position). | | | `hash` | `string` | L1 transaction hash that included this fill. | | | `oid` | `int` | Parent order ID. | | | `tid` | `int` | Unique trade ID. | | | `crossed` | `boolean` | `true` when the fill came from the taker side of the order, `false` when it was the maker side. | | | `fee` | `string` | Trading fee paid for this fill, denominated in `feeToken`. | | | `feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | | `builderFee` | `string` | Optional. Builder fee paid for this fill if the order routed through a builder code. | | | `twapId` | \`int | null\` | Optional TWAP order ID if this fill is a slice of a TWAP order. | | `cloid` | \`string | null\` | Optional client order ID if one was set at order placement. | *** ## userFunding **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userFunding", "user": "..."}`. * For real-time push, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read [`HypercoreFundingEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-funding-event) entries. * Use [`userNonFundingLedgerUpdates`](https://goldrush.dev/docs/api-reference/hyperliquid/user-non-funding-ledger-updates) for deposits, withdrawals, transfers, vault flows, liquidations, and other balance-moving events. Returns a single user’s funding payment history within a `[startTime, endTime)` window. Each entry is one funding application: a coin, the rate that was applied, the position size at the time, and the resulting USDC delta (negative = paid, positive = received). User-keyed. Use this for funding-only P\&L attribution; use [userNonFundingLedgerUpdates](https://goldrush.dev/docs/api-reference/hyperliquid/user-non-funding-ledger-updates) for everything else. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Always `"userFunding"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | No | Unix timestamp in milliseconds. Inclusive lower bound for the window. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | ### Example ```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": "userFunding", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, "endTime": 1735776000000 }' ``` ```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: "userFunding", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, endTime: 1735776000000, }), }); const events = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userFunding", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, "endTime": 1735776000000, }, ) events = response.json() ``` ## Response An array of funding event objects, one per applied funding interval and coin. ```json theme={null} [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "type": "funding", "coin": "BTC", "usdc": "-50.25", "szi": "1.5", "fundingRate": "0.0001", "nSamples": null } } ] ``` ### Field descriptions > **Note:** All numeric `delta` fields are returned as **decimal strings**. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `time` | `int` | Unix timestamp in milliseconds when the funding payment was applied. | | | `hash` | `string` | L1 transaction hash that included the funding application. | | | `delta` | `object` | Funding-event payload. | | | `delta.type` | `string` | Always `"funding"` for entries returned by this endpoint. | | | `delta.coin` | `string` | Asset symbol the funding rate applied to. | | | `delta.usdc` | `string` | USDC delta credited to or debited from the account. Negative values are paid, positive values are received. | | | `delta.szi` | `string` | Signed position size at the time of application (positive = long, negative = short). | | | `delta.fundingRate` | `string` | The funding rate applied (decimal string, e.g. `"0.0001"` for 1 bp). | | | `delta.nSamples` | \`int | null\` | Optional - number of samples used by the upstream funding calculation. May be `null`. | *** ## userNonFundingLedgerUpdates **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userNonFundingLedgerUpdates", "user": "..."}`. * Funding payments are not included here - use [`userFunding`](https://goldrush.dev/docs/api-reference/hyperliquid/user-funding). * For real-time push of the same events, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream); the `delta.type` discriminator on the polled response maps 1:1 to the streamed `LedgerDelta` interface in the Streaming API. Returns a single user’s USDC and account ledger history within a \[startTime, endTime) window, excluding funding payments. Funding events are intentionally separated into their own type, userFunding, so applications can render fee accruals separately from balance-moving events. User-keyed. Each entry carries a `delta` whose `type` discriminates the event variant - deposits, withdrawals, internal transfers, sub-account transfers, vault flows, liquidations, rewards claims, and similar. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Always `"userNonFundingLedgerUpdates"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | | `startTime` | `int` | No | Unix timestamp in milliseconds. Inclusive lower bound for the window. | | `endTime` | `int` | No | Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. | ### Example ```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": "userNonFundingLedgerUpdates", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000 }' ``` ```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: "userNonFundingLedgerUpdates", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", startTime: 1735689600000, }), }); const events = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userNonFundingLedgerUpdates", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "startTime": 1735689600000, }, ) events = response.json() ``` ## Response An array of ledger event objects. Each entry has `time`, `hash`, and a `delta` discriminated by `delta.type`. ```json theme={null} [ { "time": 1735689600000, "hash": "0x6b9c0a4a3d54b0d4d6b1a0c4d8c9e7f2b6e5d3c2a1f0e9d8c7b6a5f4e3d2c1b0a", "delta": { "type": "vaultWithdraw", "vault": "0x1962905b0a2d0ce8907a92ed5f7a17fef3e1b53e", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", "requestedUsd": "1000.50", "commission": "10.00", "closingCost": "5.25", "basis": "950.00", "netWithdrawnUsd": "985.25" } } ] ``` ### Field descriptions > **Note:** All numeric `delta` fields are returned as **decimal strings**. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `time` | `int` | Unix timestamp in milliseconds when the event was applied. | | `hash` | `string` | L1 transaction hash that produced the event. | | `delta` | `object` | Event-specific payload. The shape depends on `delta.type`. The example above shows a `vaultWithdraw`; common discriminators include `deposit`, `withdraw`, `accountClassTransfer`, `internalTransfer`, `subAccountTransfer`, `spotTransfer`, `vaultDeposit`, `vaultWithdraw`, `vaultDistribution`, `vaultLeaderCommission`, `liquidation`, `rewardsClaim`, and others. See the [Hyperliquid `nonFundingLedgerUpdates` reference](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint) for the full discriminator table. | | `delta.type` | `string` | Discriminator. Always present on every variant. | *** ## userTwapSliceFills **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userTwapSliceFills", "user": "..."}`. * Each response contains at most 2,000 most recent TWAP slice fills. Older slices beyond that window are not retrievable from this endpoint. * TWAP slice fills have a `hash` of all zeros - use that, or the presence of `twapId`, to distinguish them from regular fills. * Use [`userFillsByTime`](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-fills-by-time) when you want all fills (regular + TWAP slices) for a wallet within a time window; each TWAP slice there carries the same `twapId` field. Returns a single user’s most recent TWAP slice fills - each individual slice executed as part of a larger TWAP (Time-Weighted Average Price) order. Every entry is a `{fill, twapId}` pair, where `twapId` ties the slice back to its parent TWAP order. Multiple slices from the same TWAP share the same `twapId`. User-keyed. Use this when you want execution-quality data for TWAP orders specifically - slippage per slice, fills-per-TWAP, realized average price - rather than the unified fills feed from [userFillsByTime](https://goldrush.dev/docs/api-reference/hyperliquid-info/user-fills-by-time). ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `type` | `string` | Yes | Always `"userTwapSliceFills"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "userTwapSliceFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b" }' ``` ```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: "userTwapSliceFills", user: "0x31ca8395cf837de08b24da3f660e77761dfb974b", }), }); const slices = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userTwapSliceFills", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b", }, ) slices = response.json() ``` ## Response An array of TWAP slice fill objects, most recent first. ```json theme={null} [ { "fill": { "closedPnl": "0.0", "coin": "AVAX", "crossed": true, "dir": "Open Long", "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "oid": 90542681, "px": "18.435", "side": "B", "startPosition": "26.86", "sz": "93.53", "time": 1681222254710, "fee": "0.01", "feeToken": "USDC", "tid": 118906512037719 }, "twapId": 3156 } ] ``` ### Field descriptions > **Note:** All numeric `fill` fields (`px`, `sz`, `startPosition`, `closedPnl`, `fee`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats - keep them as strings or use a fixed-precision decimal type. | Field | Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `fill` | `object` | The slice's fill payload - the same shape as one entry from **`userFillsByTime`**. | | `fill.coin` | `string` | Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`). | | `fill.px` | `string` | Fill execution price for this slice. | | `fill.sz` | `string` | Slice fill size. | | `fill.side` | `string` | `"B"` for buy/long, `"A"` for ask/short. | | `fill.time` | `int` | Unix timestamp in milliseconds when the slice executed. | | `fill.startPosition` | `string` | Signed position size on the same coin immediately before this slice. | | `fill.dir` | `string` | Human-readable direction label - e.g. `"Open Long"`, `"Close Short"`, `"Buy"`, `"Sell"`. | | `fill.closedPnl` | `string` | Realized PnL in USDC attributable to this slice (zero when the slice opens or extends a position). | | `fill.hash` | `string` | All-zero (`0x000…000`) for TWAP slice fills - the distinguishing marker versus regular fills, which carry an L1 transaction hash. | | `fill.oid` | `int` | Order ID for the slice. | | `fill.tid` | `int` | Unique trade ID for the slice. | | `fill.crossed` | `boolean` | `true` when the slice came from the taker side, `false` when it was the maker side. | | `fill.fee` | `string` | Trading fee paid for this slice, denominated in `feeToken`. | | `fill.feeToken` | `string` | Symbol the fee was paid in - typically `"USDC"`. | | `twapId` | `int` | Identifier of the parent TWAP order. Multiple slice fills from the same TWAP share this value - group by `twapId` to reconstruct per-TWAP execution. | *** ## userVaultEquities **Credit Cost:** 1 per call **Processing:** Realtime > **Note:** - Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "userVaultEquities", "user": "..."}`. * For real-time push of vault deposit, withdrawal, and distribution events, subscribe to [`walletTxs`](https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/wallet-activity-stream) and read `LedgerVaultDeposit`, `LedgerVaultWithdraw`, and `LedgerVaultDistribution` entries. Returns the wallet’s per-vault equity: one entry per vault the user has deposited into, with the locked amount and the timestamp at which that equity becomes unlockable. User-keyed. The result is `[]` for wallets that haven’t deposited into any vault. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request | Parameter | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `type` | `string` | Yes | Always `"userVaultEquities"`. | | `user` | `string` | Yes | The wallet address (lowercase 0x-prefixed hex). | ### Example ```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": "userVaultEquities", "user": "0x2b804617c6f63c040377e95bb276811747006f4b" }' ``` ```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: "userVaultEquities", user: "0x2b804617c6f63c040377e95bb276811747006f4b", }), }); const equities = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "userVaultEquities", "user": "0x2b804617c6f63c040377e95bb276811747006f4b", }, ) equities = response.json() ``` ## Response An array of vault equity entries. ```json theme={null} [ { "vaultAddress": "0x1962905b0a2d0ce8907a92ed5f7a17fef3e1b53e", "equity": "5000.50", "lockedUntilTimestamp": 1741132800000 } ] ``` ### Field descriptions > **Note:** `equity` is returned as a **decimal string**, preserving upstream precision. Do not parse it as a float - keep it as a string or use a fixed-precision decimal type. | Field | Type | Description | | ---------------------- | -------- | ----------------------------------------------------------------------- | | `vaultAddress` | `string` | Vault contract address (0x-prefixed hex). | | `equity` | `string` | User's equity in this vault, in USD. | | `lockedUntilTimestamp` | `int` | Unix timestamp in milliseconds at which this equity becomes unlockable. | ***