Skip to main content

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#

HeaderValueRequired
Content-Typeapplication/jsonYes

Parameters#

ParameterTypeRequiredDescription
typestringYesMust be "activeAssetData"
userstringYesUser's Ethereum wallet address
coinstringYesAsset 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#

FieldTypeDescription
userstringThe queried Ethereum address
coinstringThe queried asset symbol
leverageobjectCurrent leverage configuration
maxTradeSzsarrayMaximum trade sizes [long, short] as strings
availableToTradearrayAvailable trading amounts [long, short] as strings
markPxstringCurrent mark price for the asset

Leverage Object#

FieldTypeDescription
typestringLeverage mode — "cross" or "isolated"
valuenumberLeverage multiplier (e.g., 5 for 5x)
rawUsdnumber | nullRaw USD value for isolated leverage; null for cross leverage

Code Examples#

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"
}'

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#

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify your API key is correct
400 Bad RequestMissing or invalid parametersEnsure valid address and coin symbol
422 Unprocessable EntityInvalid coin symbolCheck that the coin is listed on Hyperliquid
429 Too Many RequestsRate limit exceededImplement request throttling
500 Internal Server ErrorServer issueRetry 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#

  1. Query before trading — Always check available trade sizes before placing orders
  2. Cache mark prices briefly — Mark prices change frequently, cache for seconds not minutes
  3. Validate coin symbols — Use the meta endpoint to get valid coin symbols
  4. Handle both sidesmaxTradeSzs and availableToTrade arrays contain [long, short] values
  5. Monitor leverage changes — Leverage mode affects available capital calculations

Query real-time trading capacity with Dwellir's HyperCore Info Endpoint. Get your API key →