Hyperliquid

​

Account Model

• There are no separate “spot” and “perp” balances and no transfer between them. Deposited USDC is immediately usable as perp margin and for spot orders - just place orders.
• “Spot” vs “perp” still matters for markets (the market field on orders and the coin format: "BTC" for perps, "HYPE/USDC" for spot pairs), not for where your cash lives.
• Balance reads report the one pooled USDC collateral. Free cash for leaving the venue / funding is egress free (after margin locks), not the full pool; size sends and Max from the sendable figure (egress free after a small reserve), not from total collateral.

​

Configuration

[startingAsset]
network = "hypercore:perp"
address = "USDC"
minimumAmount = "100000000"  # 1 USDC (8 decimals)

​

Asset Allocation Notes

• You allocate a portion of the wallet’s available Hyperliquid USDC to the session (not the whole wallet). The minimumAmount still ensures anyone running the agent allocates at least that amount.
• This session’s invocation-start deployable perp collateral is the agent.allocation.balances entry carrying hyperliquidMetadata.collateral, and its open perps are in agent.allocation.positions (with hyperliquidMetadata - leverage / liquidation price / margin used). Size from this session slice - never a whole-wallet read, which on a shared wallet would overspend the other sessions sharing it.
• The collateral amount is total collateral - it includes margin already locked in open positions and excludes unrealized PnL. For session collateral (kill-switch / drawdown math), add each open position’s unrealizedPnlUsd - a losing book’s negative PnL must pull session collateral down, or the rail fires late. For free margin to size new orders, additionally subtract each position’s hyperliquidMetadata.marginUsed.

​

Units

​

Place Order

def place_order(request: HyperliquidPlaceOrderRequest | HyperliquidPlaceOrderRequestInput) -> HyperliquidPlaceOrderResponse

async placeOrder(request: HyperliquidPlaceOrderRequest): Promise<HyperliquidPlaceOrderResponse>

• coin (string): Asset identifier. For perps: "BTC". For builder DEX perps: "xyz:GOLD", "cash:GOLD", or "vntl:MAG7" (currently xyz, cash, and vntl are supported; unsupported builder DEX prefixes are rejected). For spot: the live spot listing name, e.g. "UBTC/USDC" - bridged majors are Unit assets with a U prefix (UBTC, UETH, USOL), while Hyperliquid-native tokens use their plain ticker ("HYPE/USDC", "PURR/USDC"). "BTC/USDC" does not exist and is rejected with Unknown spot pair.
• side (string): “buy” or “sell”
• size (number): Order size
• price (number): Slippage limit for the immediate market order
• market (string): “perp” or “spot”
• type (string): Must be "market". Omitting type or using a resting/triggered type is rejected.
• reduceOnly (boolean, optional): Whether this is a reduce-only order
• leverage (integer, optional, perp only, fresh positions only): Set the account’s cross leverage for this coin (1 up to the asset’s max) before the order places. The dial is per coin per wallet, so leverage can only be set when OPENING a fresh position — the order is refused when the wallet already has an open position on the coin (omit leverage to trade at the position’s current leverage, or use a wallet without one). Also refused above the asset’s max and with reduceOnly (a close opens nothing to lever). Omit to trade at the account’s current per-asset setting.
• postOnly (boolean, optional): Must be omitted or false
• message (string, optional): Short human-readable message for this order, max 250 characters. Stored verbatim and rendered as the Activity-feed caption for this trade. When omitted, the caption is synthesized from recent agent logs.
• idempotencyKey (string, optional): Durable retry key for auto-mode orders. SDKs generate one automatically; provide a stable key only when retrying the same logical order after a process restart.
• expiresAt (string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion expires at this time. If omitted, no time-based expiry is set (suggestions are auto-cleared at each run start).

• success (boolean): Whether the operation succeeded
• data (object): Order information (on success)
  • orderId (string): Order ID
  • coin (string): Asset identifier
  • side (string): “buy” or “sell”
  • price (number): Order price
  • size (number): Order size
  • filled (number): Filled amount
  • status (string): Order status
  • market (string): “perp” or “spot”
  • clientOrderId (string, optional): Client order ID (hex), when present
• error (string | null): Error message (on failure)

# Perp market order
perp_order = agent.platforms.hyperliquid.place_order({
    "coin": "BTC",
    "side": "buy",
    "size": 0.0001,
    "price": 110000,  # Acts as slippage limit for market orders
    "market": "perp",
    "type": "market"
})

if perp_order.success and perp_order.data:
    agent.log(f"Perp Order {perp_order.data.order_id}: {perp_order.data.status}")

# Spot market order
spot_order = agent.platforms.hyperliquid.place_order({
    "coin": "UBTC/USDC",  # Live spot listing name - bridged BTC is the Unit asset UBTC
    "side": "buy",
    "size": 0.0001,
    "price": 110000,  # Acts as slippage limit for market orders
    "market": "spot",
    "type": "market"
})

// Perp market order
const perpOrder = await agent.platforms.hyperliquid.placeOrder({
  coin: "BTC",
  side: "buy",
  size: 0.0001,
  price: 110000, // Acts as slippage limit for market orders
  market: "perp",
  type: "market"
});

if (perpOrder.success && perpOrder.data) {
  await agent.log(`Perp Order ${perpOrder.data.orderId}: ${perpOrder.data.status}`);
}

// Spot market order
const spotOrder = await agent.platforms.hyperliquid.placeOrder({
  coin: "UBTC/USDC", // Live spot listing name - bridged BTC is the Unit asset UBTC
  side: "buy",
  size: 0.0001,
  price: 110000, // Acts as slippage limit for market orders
  market: "spot",
  type: "market"
});

​

Reading balances

allocation = agent.allocation
cash = next(
    (b for b in allocation.balances if b.hyperliquid_metadata and b.hyperliquid_metadata.collateral),
    None,
)
if cash:
    # Exact raw-to-decimal render - never float-divide an amount_raw.
    agent.log(f"Allocated collateral: ${base_units_to_decimal(cash.amount_raw, cash.decimals)}")

const allocation = agent.allocation;
const cash = allocation.balances.find((b) => b.hyperliquidMetadata?.collateral);
if (cash) {
  // Exact raw-to-decimal render - never float-divide an amountRaw.
  await agent.log(`Allocated collateral: $${baseUnitsToDecimal(cash.amountRaw, cash.decimals)}`);
}

​

Reading positions

• coin (string), size (string, signed - long > 0, short < 0), averageEntryPrice (string | null), markPriceUsd (string | null), unrealizedPnlUsd (string | null)
• hyperliquidMetadata (object | undefined) - HL perp detail: leverage (string), liquidationPrice (string | null), marginUsed (string). Wallet-level (shared across sessions on the same wallet). Best-effort: absent if the live enrichment read failed.

allocation = agent.allocation
for pos in allocation.positions:
    if pos.network != "hypercore:perp":
        continue
    agent.log(f"{pos.coin}: {pos.size} @ {pos.average_entry_price} (PnL: {pos.unrealized_pnl_usd})")
    if pos.hyperliquid_metadata:
        m = pos.hyperliquid_metadata
        agent.log(f"  leverage: {m.leverage}x, liq: {m.liquidation_price}, margin: {m.margin_used}")

const allocation = agent.allocation;
for (const pos of allocation.positions) {
  if (pos.network !== "hypercore:perp") continue;
  await agent.log(`${pos.coin}: ${pos.size} @ ${pos.averageEntryPrice} (PnL: ${pos.unrealizedPnlUsd})`);
  const m = pos.hyperliquidMetadata;
  if (m) await agent.log(`  leverage: ${m.leverage}x, liq: ${m.liquidationPrice}, margin: ${m.marginUsed}`);
}

​

Delete Order

def delete_order(order_id: str, coin: str, idempotency_key: str | None = None) -> HyperliquidDeleteOrderResponse

async deleteOrder(orderId: string, coin: string, idempotencyKey?: string): Promise<HyperliquidDeleteOrderResponse>

• idempotencyKey (string, optional): Durable retry key for auto-mode cancels. SDKs generate one automatically; provide a stable key only when retrying the same logical cancel after a process restart.

result = agent.platforms.hyperliquid.delete_order("1234567890", "BTC")
if result.success:
    agent.log("Order cancelled")
else:
    agent.log(result.error or "Failed to cancel order", error=True)

const result = await agent.platforms.hyperliquid.deleteOrder("1234567890", "BTC");
if (result.success) {
  await agent.log("Order cancelled");
} else {
  await agent.log(result.error || "Failed to cancel order", { error: true });
}

​

Midpoint Price

def midpoint_price(coin: str | list[str], dex: str | None = None) -> HyperliquidMidpointPriceResponse

async midpointPrice(coin: string | string[], dex?: string): Promise<HyperliquidMidpointPriceResponse>

• coin (string | string[]): Coin ticker(s), e.g. "BTC" or ["BTC", "ETH"]. For spot pairs use the "BASE/QUOTE" format (e.g. "HYPE/USDC"). For builder-DEX coins, pass just the base ticker (e.g. "GOLD").
• dex (string, optional): Hyperliquid market suffix. Defaults to "perp" (main perp DEX). Use "spot" for spot or a builder-DEX name like "xyz", "cash", or "vntl". Internally translated to hypercore:<dex>.

• coin (string): The coin ticker that was matched.
• network (string): Full market identifier - always hypercore:<dex> (e.g. "hypercore:perp").
• priceUsd (string): Midpoint price in USD as a decimal string (preserve precision).
• timestamp (string): ISO 8601 timestamp of the live read.

# Defaults to perps
btc = agent.platforms.hyperliquid.midpoint_price("BTC")
if btc.success and btc.data and not isinstance(btc.data, list):
    agent.log(f"BTC perp mid: {btc.data.price_usd} @ {btc.data.timestamp}")

# Spot pair
agent.platforms.hyperliquid.midpoint_price("HYPE/USDC", "spot")

# Multiple coins on a builder DEX
many = agent.platforms.hyperliquid.midpoint_price(["GOLD", "MAG7"], "xyz")
if many.success and isinstance(many.data, list):
    for row in many.data:
        agent.log(f"{row.coin}: {row.price_usd}")

// Defaults to perps
const btc = await agent.platforms.hyperliquid.midpointPrice("BTC");
if (btc.success && btc.data && !Array.isArray(btc.data)) {
  await agent.log(`BTC perp mid: ${btc.data.priceUsd} @ ${btc.data.timestamp}`);
}

// Spot pair
await agent.platforms.hyperliquid.midpointPrice("HYPE/USDC", "spot");

// Multiple coins on a builder DEX
const many = await agent.platforms.hyperliquid.midpointPrice(["GOLD", "MAG7"], "xyz");
if (many.success && Array.isArray(many.data)) {
  for (const row of many.data) {
    await agent.log(`${row.coin}: ${row.priceUsd}`);
  }
}

​

Common Errors

​

Notes

• All balance and position amounts are strings to preserve precision.
• Market orders use price as a slippage limit (maximum acceptable execution price).
• Spot coins use the live spot listing pair name - bridged majors are Unit assets with a U prefix ("UBTC/USDC", "UETH/USDC", "USOL/USDC"), Hyperliquid-native tokens their plain ticker ("HYPE/USDC", "PURR/USDC") - while perp coins use just the base asset like "BTC".
• Hyperliquid rate-limits aggressively. Avoid calling midpointPrice in tight loops - fetch a coin’s mid once per cycle and reuse it.

​

See Also

• Hyperliquid Agent Example - Full working trading agent
• Wallets & Asset Allocation - How Hyperliquid collateral is allocated per session
• Suggestions - Control suggestion expiry for manual-mode order suggestions