Skip to main content

Documentation Index

Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 <GOLDRUSH_API_KEY>
Content-Type: application/json

​
Request

​
type
string
required
Always "batchClearinghouseState".
​
users
array<string>
required
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
Optional perpetuals DEX name. Forwarded unchanged to each per-wallet upstream call. Omit for the primary DEX.

​
Example

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"
    ]
  }'

​
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. 
[
  {
    "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
  },
  {
    "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
  },
  {
    "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. 
[
  { "withdrawable": "13104.514502", "...": "..." },
  {
    "error": "upstream_error",
    "user": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
    "message": "overall batch timeout exceeded"
  },
  { "withdrawable": "0.0", "...": "..." }
]

​
Per-wallet error slot

​
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: <node message>, upstream returned HTTP <status>, 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.

​
Notes

  • 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.