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

​
Request

​
type
string
required
Always "clearinghouseState".
​
user
string
required
The wallet address (lowercase 0x-prefixed hex).
​
dex
string
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

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

​
Response

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

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.
​
marginSummary
object
Top-level account margin and value summary.
​
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<object>
Open positions, one entry per coin.
​
time
int
Snapshot timestamp in milliseconds since Unix epoch.

​
Notes

  • Wire-equal to POST api.hyperliquid.xyz/info with {"type": "clearinghouseState", "user": "..."}.
  • For real-time push instead of polling, subscribe to walletTxs with the same wallet address.
  • The optional dex field returns state on a HIP-3 deployer’s perp DEX.