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

​
Request

​
type
string
required
Always "batchSpotClearinghouseState".
​
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
Reserved for future HIP-3 spot DEX support. Pass empty string or omit.

​
Example

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

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

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

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

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