Get perp account state

Get perp account state

get

Fetch a wallet's Hyperliquid perpetuals account state: withdrawable balance, account value, margin usage and open positions, as the exchange reports them.

The response also carries spotUsdc, the wallet's spot USDC balance. Only the perpetuals balance can be used as margin, so a wallet that looks funded but cannot open a position usually has its USDC sitting in spot — move it with /api/v1/perp/transfer. spotUsdc is null when the spot balance could not be read; the perpetuals figures are unaffected.

Authorizations

ApiKeyAuth

apikeystringRequired

API key for authentication

Query parameters

wallet_addressstringRequired

Wallet address on Hyperliquid

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

get/api/v1/perp/account

HTTPcURLJavaScriptPython

GET /api/v1/perp/account?wallet_address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}