Info - Allium Documentation Hub

This endpoint provides access to Hyperliquid’s trading data and functionality. This endpoint mirrors the official Hyperliquid API while adding improved error handling.

For the most up-to-date parameter details, refer to the official Hyperliquid API Documentation.

Making Requests

Endpoint

Send all requests to the info endpoint

Request Format

Use the following JSON structure:

{
  "type": "[Type]"
}

Error Handling DifferenceWhile the official Hyperliquid APIs return a 500 HTTP Status Code for invalid payloads, the Allium Hyperliquid APIs return a 533 HTTP Status Code in these cases for better error differentiation.

Types

activeAssetData

User details regarding an asset:

leverage
leverage type
available to trade
mark price

Show Example

Request:

{
	"type": "activeAssetData",
	"user": "0x102a618b36c32b338c03526255dcf2a39eb1897f",
	"asset": 1
}

Response:

{
	"user": "0x102a618b36c32b338c03526255dcf2a39eb1897f",
	"coin": "ETH",
	"leverage": {
		"type": "cross",
		"value": 20
	},
	"maxTradeSzs": [
		"0.0",
		"0.0"
	],
	"availableToTrade": [
		"0.0",
		"0.0"
	],
	"markPx": "2419.8"
}

clearinghouseState

Includes user margin account summaries:

positions
leverage
margin
funding paid
etc

Show Example

Request:

{
	"type": "clearinghouseState",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671",
    "dex": ""
}

Response:

{
"marginSummary": {
  "accountValue": "211927.614841",
  "totalNtlPos": "1923479.383901",
  "totalRawUsd": "1992450.186428",
  "totalMarginUsed": "67359.529636"
},
"crossMarginSummary": {
  "accountValue": "211927.614841",
  "totalNtlPos": "1923479.383901",
  "totalRawUsd": "1992450.186428",
  "totalMarginUsed": "67359.529636"
},
"crossMaintenanceMarginUsed": "33679.764815",
"withdrawable": "0.0",
"assetPositions": [
  {
    "type": "oneWay",
    "position": {
      "coin": "BTC",
      "szi": "-10.81525",
      "leverage": {
        "type": "cross",
        "value": 40
      },
      "entryPx": "104838.1",
      "positionValue": "1135157.8247499999",
      "unrealizedPnl": "-1306.65792",
      "returnOnEquity": "-0.0460962764",
      "liquidationPx": "121236.6874584099",
      "marginUsed": "28378.945618",
      "maxLeverage": 40,
      "cumFunding": {
        "allTime": "-14077.424452",
        "sinceOpen": "0.0",
        "sinceChange": "0.0"
      }
    }
  }
],
"time": 1750753764566
}

delegations

Show Example

Request:

{
	"type": "delegations",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

[
{
  "validator": "0x5ac99df645f3414876c816caa18b2d234024b487",
  "amount": "12060.16529862",
  "lockedUntilTimestamp": 1735466781353
}
]

delegatorSummary

Show Example

Request:

{
	"type": "delegatorSummary",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

{
"delegated": "0.0",
"undelegated": "0.0",
"totalPendingWithdrawal": "0.0",
"nPendingWithdrawals": 0
}

exchangeStatus

Show Example

Request:

{
	"type": "exchangeStatus"
}

Response:

{
"specialStatuses": null,
"time": 1750754795672
}

extraAgents

Show Example

Request:

{
	"type": "extraAgents",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

frontendOpenOrders

Includes a user’s open orders details. This is the same call that powers the Hyperliquid Frontend.

Show Example

Request:

{
	"type": "frontendOpenOrders",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

[
  {
  	"coin": "XRP",
  	"side": "A",
  	"limitPx": "2.1761",
  	"sz": "44703.0",
  	"oid": 105773236743,
  	"timestamp": 1750754980508,
  	"triggerCondition": "N/A",
  	"isTrigger": false,
  	"triggerPx": "0.0",
  	"children": [],
  	"isPositionTpsl": false,
  	"reduceOnly": false,
  	"orderType": "Limit",
  	"origSz": "44703.0",
  	"tif": "Alo",
  	"cloid": "0x17507549803518906739128985115394"
  },
  {
  	"coin": "XRP",
  	"side": "A",
  	"limitPx": "2.1757",
  	"sz": "44703.0",
  	"oid": 105773236742,
  	"timestamp": 1750754980508,
  	"triggerCondition": "N/A",
  	"isTrigger": false,
  	"triggerPx": "0.0",
  	"children": [],
  	"isPositionTpsl": false,
  	"reduceOnly": false,
  	"orderType": "Limit",
  	"origSz": "44703.0",
  	"tif": "Alo",
  	"cloid": "0x17507549803518706739128985115394"
  }
  // ... (truncated for brevity - see official Hyperliquid docs for full response)
]

leadingVaults

Show Example

Request:

{
	"type": "leadingVaults",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

liquidatable

Show Example

Request:

{
	"type": "liquidatable"
}

Response:

marginTable

Maximum leverage for an asset. Any position below $150,000,000 can use leverage of 40x Any position of $150,000,000 or greater can only use a leverage of 20x.

Show Example

Request:

{
	"type": "marginTable",
	"id": 56
}

Response:

{
"description": "tiered 40x",
"marginTiers": [
  {
    "lowerBound": "0.0",
    "maxLeverage": 40
  }
]
}

maxBuilderFee

Show Example

Request:

{
	"type": "maxBuilderFee",
	"user": "0x47fc45cebfc47cef07a09a98405b6ebaef00ef75",
	"builder": "0x1922810825c90f4270048b96da7b1803cd8609ef"
}

Response:

maxMarketOrderNtls

Maximum notional value allowed for a market order

Show Example

Request:

{
	"type": "maxMarketOrderNtls"
}

Response:

[
  [
  	25,
  	"15000000.0"
  ],
  [
  	20,
  	"5000000.0"
  ]
  // ... (truncated for brevity - see official Hyperliquid docs for full response)
]

openOrders

User’s open orders. Lighter version than frontendOpenOrders

Show Example

Request:

{
	"type": "openOrders",
	"user": "0x48cd535b80439fefd6d00f74e5cf9b152adf2671"
}

Response:

[
  {
  	"coin": "SPX",
  	"side": "A",
  	"limitPx": "1.2257",
  	"sz": "962.3",
  	"oid": 105776978379,
  	"timestamp": 1750755964151,
  	"origSz": "962.3",
  	"cloid": "0x17507559639529516246375212044205"
  },
  {
  	"coin": "SPX",
  	"side": "A",
  	"limitPx": "1.2253",
  	"sz": "962.9",
  	"oid": 105776978378,
  	"timestamp": 1750755964151,
  	"origSz": "962.9",
  	"cloid": "0x17507559639529316246375212044205"
  }
  // ... (truncated for brevity - see official Hyperliquid docs for full response)
]

perpDexs

Show Example

Request:

{
	"type": "perpDexs"
}

Response:

[
  null,
  {
    "name": "test",
    "full_name": "test dex",
    "deployer": "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152",
    "oracle_updater": null
  }
]

perpDeployAuctionStatus

Show Example

Request:

{
	"type": "perpDeployAuctionStatus"
}

Response:

{
"startTimeSeconds": 1747656000,
"durationSeconds": 111600,
"startGas": "500.0",
"currentGas": "500.0",
"endGas": null
}

perpsAtOpenInterestCap

Show Example

Request:

{
	"type": "perpsAtOpenInterestCap"
}

Response:

[
	"CANTO",
	"FTM",
	"JELLY",
	"LOOM",
	"RLB",
	"VVV"
]

referral

Freshness is ~5s.The following fields are not present in our API response when compared with the Hyperliquid Response.

unclaimedRewards
claimedRewards
builderRewards

For cumVlm you can sum up cumFeesRewardedToReferrer from referralStatesIn addition if the user has not referrer anyone, they will also not show up. If you need to check the referredBy to see if you referred the user, you can check the array of referralStates for your account, and check if the user is in the array.

Show Example

Request:

{
	"type": "referral"
  "user": "0xb0d1d954d7c328ea8b8dc7b8feac0f2440de3d5e"
}

Response:

{
"referredBy": {
  "referrer": "0x5e9ee1089755c3435139848e47e6635505d5a13a",
  "code": "ALPHA"
},
"referrerState": {
  "stage": "ready",
  "data": {
    "code": "YYDS",
    "nReferrals": 12,
    "referralStates": [
      {
        "cumVlm": "2942321.945388",
        "cumRewardedFeesSinceReferred": "675.27837862",
        "cumFeesRewardedToReferrer": "67.52746463",
        "timeJoined": 1710311341203,
        "user": "0x8ff3059f1bf4b0c5f53508f3d0b6f50d992e4263"
      }
    ]
  }
}
}

spotClearinghouseState

Users positions held for spot tokens.

Show Example

Request:

{
	"type": "spotClearinghouseState",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"balances": [
  {
    "coin": "USDC",
    "token": 0,
    "total": "1895577.62119652",
    "hold": "1870590.29932",
    "entryNtl": "0.0"
  }
]
}

spotDeployState

Show Example

Request:

{
	"type": "spotDeployState",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"states": [],
"gasAuction": {
  "startTimeSeconds": 1750669200,
  "durationSeconds": 111600,
  "startGas": "1354.95227154",
  "currentGas": null,
  "endGas": "722.9084269"
}
}

spotMeta

Show Example

Request:

{
	"type": "spotMeta"
}

Response:

{
"universe": [
  {
    "tokens": [
      1
    ],
    "name": "PURR/USDC",
    "index": 0,
    "isCanonical": true
  }
],
"tokens": [
  {
    "name": "USDC",
    "szDecimals": 8,
    "weiDecimals": 8,
    "index": 0,
    "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054",
    "isCanonical": true,
    "evmContract": null,
    "fullName": null,
    "deployerTradingFeeShare": "0.0"
  }
]
}

subAccounts

List a user’s subaccount along with their clearing house state.

Show Example

Request:

{
	"type": "subAccounts",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

[
  {
  	"name": "test",
  	"subAccountUser": "0x82578861165b62466f8e11e51efe74455ed0e1a6",
  	"master": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
  	"clearinghouseState": {
  		"marginSummary": {
  			"accountValue": "0.0",
  			"totalNtlPos": "0.0",
  			"totalRawUsd": "0.0",
  			"totalMarginUsed": "0.0"
  		},
  		"crossMarginSummary": {
  			"accountValue": "0.0",
  			"totalNtlPos": "0.0",
  			"totalRawUsd": "0.0",
  			"totalMarginUsed": "0.0"
  		},
  		"crossMaintenanceMarginUsed": "0.0",
  		"withdrawable": "0.0",
  		"assetPositions": [],
  		"time": 1750757719621
  	},
  	"spotState": {
  		"balances": []
  	}
  },
  {
  	"name": "sub1",
  	"subAccountUser": "0x8185204d31602595fadbb9305155e8981762e60c",
  	"master": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
  	"clearinghouseState": {
  		"marginSummary": {
  			"accountValue": "0.0",
  			"totalNtlPos": "0.0",
  			"totalRawUsd": "0.0",
  			"totalMarginUsed": "0.0"
  		},
  		"crossMarginSummary": {
  			"accountValue": "0.0",
  			"totalNtlPos": "0.0",
  			"totalRawUsd": "0.0",
  			"totalMarginUsed": "0.0"
  		},
  		"crossMaintenanceMarginUsed": "0.0",
  		"withdrawable": "0.0",
  		"assetPositions": [],
  		"time": 1750757719621
  	},
  	"spotState": {
  		"balances": []
  	}
  }
  // ... (truncated for brevity - see official Hyperliquid docs for full response)
]

userFees

Show Example

Request:

{
	"type": "userFees",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"dailyUserVlm": [
  {
    "date": "2025-06-10",
    "userCross": "76535297.222202003",
    "userAdd": "305016714.9012349844",
    "exchange": "9886955586.1455211639"
  }
],
"feeSchedule": {
  "cross": "0.00045",
  "add": "0.00015",
  "spotCross": "0.0007",
  "spotAdd": "0.0004",
  "tiers": {
    "vip": [
      {
        "ntlCutoff": "5000000.0",
        "cross": "0.0004",
        "add": "0.00012",
        "spotCross": "0.0006",
        "spotAdd": "0.0003"
      }
    ],
    "mm": [
      {
        "makerFractionCutoff": "0.005",
        "add": "-0.00001"
      }
    ]
  },
  "referralDiscount": "0.04",
  "stakingDiscountTiers": [
    {
      "bpsOfMaxSupply": "0.0",
      "discount": "0.0"
    }
  ]
},
"userCrossRate": "0.000182",
"userAddRate": "-0.00003",
"userSpotCrossRate": "0.00021",
"userSpotAddRate": "-0.00003",
"activeReferralDiscount": "0.0",
"trial": null,
"feeTrialReward": "0.0",
"nextTrialAvailableTimestamp": null,
"stakingLink": null,
"activeStakingDiscount": {
  "bpsOfMaxSupply": "2.5231419664",
  "discount": "0.3"
}
}

userRateLimit

This rate limit applies only to API endpoints in the api.hyperliquid.xyz

Show Example

Request:

{
	"type": "userRateLimit",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"cumVlm": "122320141158.6737365723",
"nRequestsUsed": 6079898862,
"nRequestsCap": 122320151158
}

userRole

Show Example

Request:

{
	"type": "userRole",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"role": "user"
}

userToMultiSigSigners

Show Example

Request:

{
	"type": "userToMultiSigSigners",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

userVaultEquities

Show Example

Request:

{
	"type": "userVaultEquities",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

[
{
  "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
  "equity": "129.003413",
  "lockedUntilTimestamp": 1713602521372
}
]

webData2

Show Example

Request:

{
  "type": "webData2",
  "user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

{
"clearinghouseState": {
  "marginSummary": {
    "accountValue": "56832965.0819410011",
    "totalNtlPos": "110204251.0530920029",
    "totalRawUsd": "165328023.9461790025",
    "totalMarginUsed": "13352493.8974220008"
  },
  "crossMarginSummary": {
    "accountValue": "56832965.0819410011",
    "totalNtlPos": "110204251.0530920029",
    "totalRawUsd": "165328023.9461790025",
    "totalMarginUsed": "13352493.8974220008"
  },
  "crossMaintenanceMarginUsed": "4281427.6640910003",
  "withdrawable": "34644519.5326099992",
  "assetPositions": [
    {
      "type": "oneWay",
      "position": {
        "coin": "BTC",
        "szi": "-167.44292",
        "leverage": {
          "type": "cross",
          "value": 20
        },
        "entryPx": "108426.2",
        "positionValue": "18134570.5647599995",
        "unrealizedPnl": "20641.250393",
        "returnOnEquity": "0.02273865",
        "liquidationPx": "418275.8134535844",
        "marginUsed": "906728.528238",
        "maxLeverage": 40,
        "cumFunding": {
          "allTime": "-2974814.8313640002",
          "sinceOpen": "-15484.362694",
          "sinceChange": "-226.675852"
        }
      }
    }
  ],
  "time": 1751958339384
},
"leadingVaults": [],
"totalVaultEquity": "129.281566",
"openOrders": [
  {
    "coin": "SEI",
    "side": "A",
    "limitPx": "0.24919",
    "sz": "1003.0",
    "oid": 110574134974,
    "timestamp": 1751958339384,
    "triggerCondition": "N/A",
    "isTrigger": false,
    "triggerPx": "0.0",
    "children": [],
    "isPositionTpsl": false,
    "reduceOnly": false,
    "orderType": "Limit",
    "origSz": "1003.0",
    "tif": "Alo",
    "cloid": "0x676094ff3fdbdb0481d7af0659eac7e9"
  }
],
"agentAddress": null,
"agentValidUntil": null,
"cumLedger": "-17565216.6999999993",
"meta": {
  "universe": [
    {
      "szDecimals": 5,
      "name": "BTC",
      "maxLeverage": 40,
      "marginTableId": 56
    }
  ],
  "marginTables": [
    [
      50
    ]
  ]
},
"assetCtxs": [],
"serverTime": 1751958339384,
"isVault": false,
"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00",
"twapStates": [],
"spotState": {
  "balances": [
    {
      "coin": "USDC",
      "token": 0,
      "total": "1454430.75374566",
      "hold": "1443468.5969700001",
      "entryNtl": "0.0"
    }
  ]
},
"perpsAtOpenInterestCap": [
  "CANTO"
]
}

validatorL1Votes

Show Example

Request:

{
	"type": "validatorL1Votes",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

vaultSummaries

Show Example

Request:

{
	"type": "vaultSummaries",
	"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"
}

Response:

[
  {
  	"name": "Mad Scientists",
  	"vaultAddress": "0x565b1c32936bdaa526947178acc95c5b08cfacc4",
  	"leader": "0x77eea13a1146a77e637a0a5ec181d0bff8629ab4",
  	"tvl": "499.80942",
  	"isClosed": false,
  	"relationship": {
  		"type": "normal"
  	},
  	"createTimeMillis": 1750754796477
  },
  {
  	"name": "[Neutral Trade] BTC Dominance",
  	"vaultAddress": "0x799e0112977c37f8d93a768cf5a2305bdd3ae6f9",
  	"leader": "0xecb7323035ff99dc0e4ab0d23d96b13be0d00343",
  	"tvl": "5000.0",
  	"isClosed": false,
  	"relationship": {
  		"type": "normal"
  	},
  	"createTimeMillis": 1750751126111
  }
  // ... (truncated for brevity - see official Hyperliquid docs for full response)
]

votes

Show Example

Request:Response:

Authorizations

X-API-KEY

string

header

required

Body

application/json

type

string

Request type parameter

user

string

User parameter

dex

string

DEX parameter

Response

Successful response

Realtime API

Stream Transformation API

Beam API

Explorer API

Account API

Deep Dives

Documentation Index

​Making Requests

​Types

​activeAssetData

​clearinghouseState

​delegations

​delegatorSummary

​exchangeStatus

​extraAgents

​frontendOpenOrders

​leadingVaults

​liquidatable

​marginTable

​maxBuilderFee

​maxMarketOrderNtls

​meta

​openOrders

​perpDexs

​perpDeployAuctionStatus

​perpsAtOpenInterestCap

​referral

​spotClearinghouseState

​spotDeployState

​spotMeta

​subAccounts

​userFees

​userRateLimit

​userRole

​userToMultiSigSigners

​userVaultEquities

​webData2

​validatorL1Votes

​vaultSummaries

​votes

Authorizations

Body

Response

Making Requests

Types

activeAssetData

clearinghouseState

delegations

delegatorSummary

exchangeStatus

extraAgents

frontendOpenOrders

leadingVaults

liquidatable

marginTable

maxBuilderFee

maxMarketOrderNtls

meta

openOrders

perpDexs

perpDeployAuctionStatus

perpsAtOpenInterestCap

referral

spotClearinghouseState

spotDeployState

spotMeta

subAccounts

userFees

userRateLimit

userRole

userToMultiSigSigners

userVaultEquities

webData2

validatorL1Votes

vaultSummaries

votes