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.

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

​
Request

​
type
string
required
Always "spotClearinghouseState".
​
user
string
required
The wallet address (lowercase 0x-prefixed hex).
​
dex
string
Reserved for future HIP-3 spot DEX support. Pass empty string.

​
Example

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

​
Response

{
  "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

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.
​
balances
array<object>
One entry per token the wallet has interacted with on Hyperliquid spot. May be empty ([]) for wallets with no spot history.
​
tokenToAvailableAfterMaintenance
array<[int, string]>
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.

​
Notes

  • 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 and read LedgerSpotTransfer events.