clearinghouseState | Hyperliquid Info API
curl --request POST \
--url https://hypercore.goldrushdata.com/info \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"user": "<string>",
"dex": "<string>"
}
'import requests
url = "https://hypercore.goldrushdata.com/info"
payload = {
"type": "<string>",
"user": "<string>",
"dex": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({type: '<string>', user: '<string>', dex: '<string>'})
};
fetch('https://hypercore.goldrushdata.com/info', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hypercore.goldrushdata.com/info",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => '<string>',
'user' => '<string>',
'dex' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hypercore.goldrushdata.com/info"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hypercore.goldrushdata.com/info")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hypercore.goldrushdata.com/info")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"marginSummary": {
"accountValue": "<string>",
"totalNtlPos": "<string>",
"totalRawUsd": "<string>",
"totalMarginUsed": "<string>"
},
"crossMarginSummary": {},
"crossMaintenanceMarginUsed": "<string>",
"withdrawable": "<string>",
"assetPositions": [
{
"type": "<string>",
"position": {
"coin": "<string>",
"szi": "<string>",
"leverage": {},
"entryPx": "<string>",
"positionValue": "<string>",
"unrealizedPnl": "<string>",
"returnOnEquity": "<string>",
"liquidationPx": {},
"marginUsed": "<string>",
"maxLeverage": 123,
"cumFunding": {}
}
}
],
"time": 123
}Info API
clearinghouseState | Hyperliquid Info API
Hyperliquid clearinghouseState: fetch a single user’s perpetuals account state by wallet address.
POST
/
info
clearinghouseState | Hyperliquid Info API
curl --request POST \
--url https://hypercore.goldrushdata.com/info \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"user": "<string>",
"dex": "<string>"
}
'import requests
url = "https://hypercore.goldrushdata.com/info"
payload = {
"type": "<string>",
"user": "<string>",
"dex": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({type: '<string>', user: '<string>', dex: '<string>'})
};
fetch('https://hypercore.goldrushdata.com/info', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hypercore.goldrushdata.com/info",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => '<string>',
'user' => '<string>',
'dex' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hypercore.goldrushdata.com/info"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hypercore.goldrushdata.com/info")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hypercore.goldrushdata.com/info")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"<string>\",\n \"user\": \"<string>\",\n \"dex\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"marginSummary": {
"accountValue": "<string>",
"totalNtlPos": "<string>",
"totalRawUsd": "<string>",
"totalMarginUsed": "<string>"
},
"crossMarginSummary": {},
"crossMaintenanceMarginUsed": "<string>",
"withdrawable": "<string>",
"assetPositions": [
{
"type": "<string>",
"position": {
"coin": "<string>",
"szi": "<string>",
"leverage": {},
"entryPx": "<string>",
"positionValue": "<string>",
"unrealizedPnl": "<string>",
"returnOnEquity": "<string>",
"liquidationPx": {},
"marginUsed": "<string>",
"maxLeverage": 123,
"cumFunding": {}
}
}
],
"time": 123
}Credit Cost
1 per call
Processing
Realtime
type: "clearinghouseState" is used to fetch a single user’s perpetuals account state by wallet address.
Estimate your monthly cost for this API using the Pricing Calculator.
- Wire-equal to
POST api.hyperliquid.xyz/infowith{"type": "clearinghouseState", "user": "..."}. - The optional
dexfield returns state on a HIP-3 deployer’s perp DEX. Pass"*"or"ALL_DEXES"to return state across the native dex and every HIP-3 dex in one call. - Wildcard (
"*"/"ALL_DEXES") requests are billed at a flat10 creditsvs.1 creditfor a single-dex call. - The
perpDexslist used for wildcard fan-out is cached ~2 minutes, so a newly-deployed dex may take up to that long to appear in wildcard results.
"*" / "ALL_DEXES") requests are billed at a flat 10 credits per call.
Endpoint
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
Request
string
default:"clearinghouseState"
required
Always
"clearinghouseState".string
required
The wallet address (lowercase 0x-prefixed hex).
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": ""
}'
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();
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
{
"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.
object
object
Cross-margin subset of the margin summary. Same fields.
string
Maintenance margin currently used for cross positions.
string
Amount currently withdrawable, in USD.
array<object>
Open positions, one entry per coin.
Show properties
Show properties
string
Position type -
"oneWay" for the standard mode.object
Show properties
Show properties
string
Asset symbol.
string
Signed position size (positive = long, negative = short).
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.string
Volume-weighted entry price.
string
Current notional value.
string
Unrealized PnL in USD.
string
Unrealized return on margin used.
string | null
Liquidation price. May be literal JSON
null when no near-term liquidation applies (e.g. cross-margin with deep cushion).string
Margin committed to this position.
int
Maximum leverage for this asset.
object
Cumulative funding paid:
allTime, sinceOpen, sinceChange.int
Snapshot timestamp in milliseconds since Unix epoch.
Related endpoints
batchClearinghouseState
fetch perpetuals account state for up to 50 wallets in a single request.
batchSpotClearinghouseState
fetch spot account balances for up to 50 wallets in a single request.
spotClearinghouseState
fetch a single user’s spot account balances by wallet address.
portfolioState
fetch a wallet’s perp state, spot balances, and account-abstraction mode in one request.