activeAssetData
Get active asset trading data for a specific user and coin, including leverage configuration, maximum trade sizes, available trading amounts, and current mark price.
When to Use This Endpoint#
The activeAssetData endpoint is essential for:
- Pre-Trade Validation — Check maximum trade sizes before placing orders
- Leverage Monitoring — Query current leverage settings for a user on a specific asset
- Available Capital — Determine how much a user can trade on a given asset
- Price Reference — Get the current mark price for position calculations
Request#
Endpoint#
POST https://api-hyperliquid-mainnet-info.n.dwellir.com/API_KEY/info
Headers#
| Header | Value | Required |
|---|---|---|
Content-Type | application/json | Yes |
Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be "activeAssetData" |
user | string | Yes | User's Ethereum wallet address |
coin | string | Yes | Asset symbol (e.g., "BTC", "ETH") |
Example Request#
{
"type": "activeAssetData",
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
"coin": "BTC"
}
Response#
Success Response#
{
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
"coin": "BTC",
"leverage": {
"type": "cross",
"value": 5,
"rawUsd": null
},
"maxTradeSzs": ["100000.00", "100000.00"],
"availableToTrade": ["50000.00", "50000.00"],
"markPx": "45000.00"
}
Response Fields#
| Field | Type | Description |
|---|---|---|
user | string | The queried Ethereum address |
coin | string | The queried asset symbol |
leverage | object | Current leverage configuration |
maxTradeSzs | array | Maximum trade sizes [long, short] as strings |
availableToTrade | array | Available trading amounts [long, short] as strings |
markPx | string | Current mark price for the asset |
Leverage Object#
| Field | Type | Description |
|---|---|---|
type | string | Leverage mode — "cross" or "isolated" |
value | number | Leverage multiplier (e.g., 5 for 5x) |
rawUsd | number | null | Raw USD value for isolated leverage; null for cross leverage |
Code Examples#
- cURL
- JavaScript
- Python
- Go
curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/API_KEY/info' \
-H 'Content-Type: application/json' \
-d '{
"type": "activeAssetData",
"user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f",
"coin": "BTC"
}'
const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/API_KEY/info';
async function getActiveAssetData(userAddress, coin) {
const response = await fetch(ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'activeAssetData',
user: userAddress,
coin: coin
})
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return await response.json();
}
// Usage
const data = await getActiveAssetData('0x63E8c7C149556D5f34F833419A287bb9Ef81487f', 'BTC');
console.log(`Leverage: ${data.leverage.value}x (${data.leverage.type})`);
console.log(`Mark Price: $${data.markPx}`);
console.log(`Max Long Size: $${data.maxTradeSzs[0]}`);
console.log(`Max Short Size: $${data.maxTradeSzs[1]}`);
console.log(`Available Long: $${data.availableToTrade[0]}`);
console.log(`Available Short: $${data.availableToTrade[1]}`);
import requests
from typing import Dict
ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/API_KEY/info'
def get_active_asset_data(user_address: str, coin: str) -> Dict:
"""Get active asset trading data for a user and coin"""
response = requests.post(
ENDPOINT,
json={
'type': 'activeAssetData',
'user': user_address,
'coin': coin
},
headers={
'Content-Type': 'application/json',
},
timeout=10
)
response.raise_for_status()
return response.json()
# Usage
data = get_active_asset_data('0x63E8c7C149556D5f34F833419A287bb9Ef81487f', 'BTC')
leverage = data['leverage']
print(f"Leverage: {leverage['value']}x ({leverage['type']})")
print(f"Mark Price: ${data['markPx']}")
print(f"Max Long Size: ${data['maxTradeSzs'][0]}")
print(f"Max Short Size: ${data['maxTradeSzs'][1]}")
print(f"Available Long: ${data['availableToTrade'][0]}")
print(f"Available Short: ${data['availableToTrade'][1]}")
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
const Endpoint = "https://api-hyperliquid-mainnet-info.n.dwellir.com/API_KEY/info"
type ActiveAssetDataRequest struct {
Type string `json:"type"`
User string `json:"user"`
Coin string `json:"coin"`
}
type Leverage struct {
Type string `json:"type"`
Value int `json:"value"`
RawUsd *float64 `json:"rawUsd"`
}
type ActiveAssetDataResponse struct {
User string `json:"user"`
Coin string `json:"coin"`
Leverage Leverage `json:"leverage"`
MaxTradeSzs []string `json:"maxTradeSzs"`
AvailableToTrade []string `json:"availableToTrade"`
MarkPx string `json:"markPx"`
}
func getActiveAssetData(userAddress, coin string) (*ActiveAssetDataResponse, error) {
reqBody, _ := json.Marshal(ActiveAssetDataRequest{
Type: "activeAssetData",
User: userAddress,
Coin: coin,
})
req, _ := http.NewRequest("POST", Endpoint, bytes.NewBuffer(reqBody))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result ActiveAssetDataResponse
if err := json.Unmarshal(body, &result); err != nil {
return nil, err
}
return &result, nil
}
func main() {
data, err := getActiveAssetData("0x63E8c7C149556D5f34F833419A287bb9Ef81487f", "BTC")
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Leverage: %dx (%s)\n", data.Leverage.Value, data.Leverage.Type)
fmt.Printf("Mark Price: $%s\n", data.MarkPx)
fmt.Printf("Max Long Size: $%s\n", data.MaxTradeSzs[0])
fmt.Printf("Max Short Size: $%s\n", data.MaxTradeSzs[1])
fmt.Printf("Available Long: $%s\n", data.AvailableToTrade[0])
fmt.Printf("Available Short: $%s\n", data.AvailableToTrade[1])
}
Common Use Cases#
1. Pre-Trade Size Validation#
Validate order size before submitting:
async function validateTradeSize(userAddress, coin, desiredSize, side) {
const data = await getActiveAssetData(userAddress, coin);
const sideIndex = side === 'long' ? 0 : 1;
const maxSize = parseFloat(data.maxTradeSzs[sideIndex]);
const available = parseFloat(data.availableToTrade[sideIndex]);
const isValid = desiredSize <= maxSize && desiredSize <= available;
return {
valid: isValid,
desiredSize: desiredSize,
maxTradeSize: maxSize,
availableToTrade: available,
reason: !isValid
? desiredSize > maxSize
? `Exceeds max trade size ($${maxSize})`
: `Exceeds available capital ($${available})`
: null
};
}
// Usage
const validation = await validateTradeSize(
'0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
'BTC',
25000,
'long'
);
if (!validation.valid) {
console.warn(`Trade rejected: ${validation.reason}`);
}
2. Leverage Dashboard#
Display leverage and trading capacity for multiple assets:
async function getLeverageDashboard(userAddress, coins) {
const results = await Promise.all(
coins.map(coin => getActiveAssetData(userAddress, coin))
);
console.log('=== Leverage Dashboard ===\n');
results.forEach(data => {
console.log(`${data.coin}:`);
console.log(` Leverage: ${data.leverage.value}x (${data.leverage.type})`);
console.log(` Mark Price: $${data.markPx}`);
console.log(` Max Long: $${data.maxTradeSzs[0]}`);
console.log(` Max Short: $${data.maxTradeSzs[1]}`);
console.log(` Available Long: $${data.availableToTrade[0]}`);
console.log(` Available Short: $${data.availableToTrade[1]}`);
console.log('');
});
return results;
}
// Usage
await getLeverageDashboard(
'0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
['BTC', 'ETH', 'SOL']
);
3. Trading Capacity Monitor#
Track available trading capacity over time:
class TradingCapacityMonitor {
constructor(userAddress, coin) {
this.userAddress = userAddress;
this.coin = coin;
this.history = [];
}
async snapshot() {
const data = await getActiveAssetData(this.userAddress, this.coin);
const record = {
timestamp: new Date().toISOString(),
availableLong: parseFloat(data.availableToTrade[0]),
availableShort: parseFloat(data.availableToTrade[1]),
markPx: parseFloat(data.markPx),
leverage: data.leverage.value
};
this.history.push(record);
return record;
}
getUtilization() {
if (this.history.length === 0) return null;
const latest = this.history[this.history.length - 1];
const first = this.history[0];
return {
currentAvailableLong: latest.availableLong,
currentAvailableShort: latest.availableShort,
changeLong: latest.availableLong - first.availableLong,
changeShort: latest.availableShort - first.availableShort,
snapshots: this.history.length
};
}
}
// Usage
const monitor = new TradingCapacityMonitor(
'0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
'BTC'
);
await monitor.snapshot();
4. Smart Order Sizing#
Calculate optimal order size based on available capacity:
async function getOptimalOrderSize(userAddress, coin, side, targetPercent = 0.5) {
const data = await getActiveAssetData(userAddress, coin);
const sideIndex = side === 'long' ? 0 : 1;
const available = parseFloat(data.availableToTrade[sideIndex]);
const maxSize = parseFloat(data.maxTradeSzs[sideIndex]);
const markPrice = parseFloat(data.markPx);
const targetNotional = available * targetPercent;
const clampedNotional = Math.min(targetNotional, maxSize);
const orderSizeInCoin = clampedNotional / markPrice;
return {
coin: coin,
side: side,
orderSizeUsd: clampedNotional.toFixed(2),
orderSizeCoin: orderSizeInCoin.toFixed(6),
markPrice: markPrice,
leverage: data.leverage.value,
percentUsed: ((clampedNotional / available) * 100).toFixed(1)
};
}
// Usage
const order = await getOptimalOrderSize(
'0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
'BTC',
'long',
0.25 // use 25% of available capital
);
console.log(`Order: ${order.orderSizeCoin} ${order.coin} ($${order.orderSizeUsd})`);
Error Handling#
Common Errors#
| Error | Cause | Solution |
|---|---|---|
401 Unauthorized | Invalid API key | Verify your API key is correct |
400 Bad Request | Missing or invalid parameters | Ensure valid address and coin symbol |
422 Unprocessable Entity | Invalid coin symbol | Check that the coin is listed on Hyperliquid |
429 Too Many Requests | Rate limit exceeded | Implement request throttling |
500 Internal Server Error | Server issue | Retry with exponential backoff |
Error Response Example#
{
"error": "Missing required parameter: coin",
"code": "MISSING_PARAMETER"
}
Robust Error Handling#
async function safeGetActiveAssetData(userAddress, coin, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await getActiveAssetData(userAddress, coin);
} catch (error) {
if (error.response?.status === 429) {
await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
} else if (error.response?.status === 400) {
throw new Error('Invalid user address or coin symbol');
} else if (i === maxRetries - 1) {
throw error;
}
}
}
}
Best Practices#
- Query before trading — Always check available trade sizes before placing orders
- Cache mark prices briefly — Mark prices change frequently, cache for seconds not minutes
- Validate coin symbols — Use the meta endpoint to get valid coin symbols
- Handle both sides —
maxTradeSzsandavailableToTradearrays contain [long, short] values - Monitor leverage changes — Leverage mode affects available capital calculations
Related Endpoints#
- clearinghouseState — Get full account state with all positions
- meta — Get trading pair metadata and valid coin symbols
- openOrders — Get user's open orders for the asset
- userAbstraction — Check account abstraction mode
Query real-time trading capacity with Dwellir's HyperCore Info Endpoint. Get your API key →