spotClearinghouseState | 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{
"balances": [
{
"coin": "<string>",
"token": 123,
"hold": "<string>",
"total": "<string>",
"entryNtl": "<string>"
}
],
"tokenToAvailableAfterMaintenance": [
{}
]
}Info API
spotClearinghouseState | Hyperliquid Info API
Hyperliquid spotClearinghouseState: fetch a single user’s spot account balances by wallet address.
POST
/
info
spotClearinghouseState | 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{
"balances": [
{
"coin": "<string>",
"token": 123,
"hold": "<string>",
"total": "<string>",
"entryNtl": "<string>"
}
],
"tokenToAvailableAfterMaintenance": [
{}
]
}Credit Cost
1 per call
Processing
Realtime
type: "spotClearinghouseState" is used to fetch a single user’s spot account balances by wallet address.
Estimate your monthly cost for this API using the Pricing Calculator.
- Wire-equal to
POST api.hyperliquid.xyz/infowith{"type": "spotClearinghouseState", "user": "..."}. - USDC balance is returned as
token: 0.
Endpoint
POST https://hypercore.goldrushdata.com/info
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
Request
string
default:"spotClearinghouseState"
required
Always
"spotClearinghouseState".string
required
The wallet address (lowercase 0x-prefixed hex).
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": ""
}'
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: "spotClearinghouseState",
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": "spotClearinghouseState",
"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
"dex": "",
},
)
state = response.json()
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.array<object>
One entry per token the wallet has interacted with on Hyperliquid spot. May be empty (
[]) for wallets with no spot history.Show properties
Show properties
string
Token ticker symbol (e.g.
"USDC", "PURR", "HYPE").int
Numeric token index assigned by Hyperliquid. The pair
(coin, token) together identifies the asset.string
Portion of
total currently locked in open spot orders. Withdrawable balance is total - hold.string
Total balance (held + free).
string
Entry notional value at acquisition, in USD.
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.Related endpoints
batchSpotClearinghouseState
fetch spot account balances for up to 50 wallets in a single request.
spotDeployState
fetch the spot-token deployment state and gas auction for a deployer.
spotMeta
fetch the spot universe metadata and full token configuration without live market context.
spotMetaAndAssetCtxs
fetch the spot universe metadata, token configuration, and live market data in a single call.
batchClearinghouseState
fetch perpetuals account state for up to 50 wallets in a single request.
clearinghouseState
fetch a single user’s perpetuals account state by wallet address.