Hyperliquid

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

​

Configuration

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

​

Asset Allocation Notes

• For Hyperliquid agents, your entire wallet balance is available to the agent when you start a session.
• The minimumAmount will still ensure that anyone running the agent will at least have that amount.
• Your agent should use the below methods to pull available balances/positions directly from Hyperliquid, as opposed to the agent.currentPositions property.
  • Balances: agent.platforms.hyperliquid.balances()
  • Positions: agent.platforms.hyperliquid.positions(dex?)
  • IMPORTANT: Be careful with your usage of these methods in loops (avoid entirely if possible), Hyperliquid will rate limit if too many requests are sent.

  • Note: Hyperliquid balances are not yet included in agent.currentPositions. This will be added in a future release once Circuit’s Hyperliquid indexing is complete.

​

Units

​

Place Order

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

• symbol (string): Trading pair symbol. 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: "BTC/USDC".
• side (string): “buy” or “sell”
• size (number): Order size
• price (number): Order price. For market orders, acts as slippage limit (maximum acceptable execution price). For limit orders, the limit price.
• market (string): “perp” or “spot”
• type (string, optional): “market”, “limit”, “stop”, “take_profit”
• triggerPrice (number, optional): Trigger price for stop/take-profit orders
• reduceOnly (boolean, optional): Whether this is a reduce-only order
• postOnly (boolean, optional): Whether this is a post-only order
• 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.
• 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
  • symbol (string): Trading pair symbol
  • 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”
• error (string | null): Error message (on failure)

# Perp market order
perp_order = agent.platforms.hyperliquid.place_order({
    "symbol": "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.orderId}: {perp_order.data.status}")

# Spot market order
spot_order = agent.platforms.hyperliquid.place_order({
    "symbol": "BTC/USDC",
    "side": "buy",
    "size": 0.0001,
    "price": 110000,  # Acts as slippage limit for market orders
    "market": "spot",
    "type": "market"
})

​

Balances

def balances() -> HyperliquidBalancesResponse

• success (boolean): Whether the operation succeeded
• data.perp (object): Perp account balance
  • accountValue (string): Total account value
  • totalMarginUsed (string): Total margin used
  • withdrawable (string): Withdrawable amount
• data.spot (array): Spot token balances
  • coin (string): Token symbol
  • total (string): Total balance
  • hold (string): Amount on hold (in open orders)
• error (string | null): Error message (on failure)

balances = agent.platforms.hyperliquid.balances()
if balances.success and balances.data:
    agent.log(f"Account value: {balances.data.perp.accountValue}")
    agent.log(f"Withdrawable: {balances.data.perp.withdrawable}")

    for token in balances.data.spot:
        agent.log(f"{token.coin}: {token.total} (hold: {token.hold})")

​

Positions

def positions(dex: str | None = None) -> HyperliquidPositionsResponse

• dex (string, optional): Builder DEX name to filter positions for a specific venue, such as "xyz", "cash", or "vntl". If omitted, positions are returned across the default venue and supported builder DEXes. Currently that supported builder DEX set is "xyz", "cash", and "vntl", and unsupported builder DEX names are rejected.

• success (boolean): Whether the operation succeeded
• data (array): Array of open positions
  • symbol (string): Trading pair symbol
  • side (string): “long” or “short”
  • size (string): Position size
  • entryPrice (string): Average entry price
  • markPrice (string): Current mark price
  • liquidationPrice (string | null): Liquidation price
  • unrealizedPnl (string): Unrealized profit/loss
  • leverage (string): Current leverage
  • marginUsed (string): Margin allocated to position
• error (string | null): Error message (on failure)

positions = agent.platforms.hyperliquid.positions()
xyz_positions = agent.platforms.hyperliquid.positions(dex="xyz")

if positions.success and positions.data:
    for pos in positions.data:
        agent.log(f"{pos.symbol} {pos.side}: {pos.size} @ {pos.entryPrice}")
        agent.log(f"  PnL: {pos.unrealizedPnl}, Leverage: {pos.leverage}x")
        if pos.liquidationPrice:
            agent.log(f"  Liq price: {pos.liquidationPrice}")

​

Order

def order(order_id: str) -> HyperliquidOrderResponse

• success (boolean): Whether the operation succeeded
• data (object): Order information (same shape as placeOrder response)
  • orderId (string): Order ID
  • symbol (string): Trading pair symbol
  • 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”
• error (string | null): Error message (on failure)

​

Delete Order

def delete_order(order_id: str, symbol: str) -> HyperliquidDeleteOrderResponse

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)

​

Open Orders

def open_orders() -> HyperliquidOpenOrdersResponse

• success (boolean): Whether the operation succeeded
• data (array): Array of open orders (same shape as placeOrder response — orderId, symbol, side, price, size, filled, status, market)
• error (string | null): Error message (on failure)

​

Orders

def orders() -> HyperliquidHistoricalOrdersResponse

• status: “open”, “filled”, “canceled”, “triggered”, “rejected”, “marginCanceled”, “liquidatedCanceled”
• orderType: “Market”, “Limit”, “Stop Market”, “Stop Limit”, “Take Profit Market”, “Take Profit Limit”
• timestamp: Order creation timestamp
• statusTimestamp: Status update timestamp

​

Order Fills

def order_fills() -> HyperliquidOrderFillsResponse

• price (string): Fill price
• size (string): Fill size
• fee (string): Trading fee paid

​

Transfer

def transfer(request: HyperliquidTransferRequest | dict) -> HyperliquidTransferResponse

• amount (number): Amount to transfer
• toPerp (boolean): true to transfer to perp account, false to transfer to spot
• expiresAt (string | null, optional): ISO 8601 timestamp for suggestion expiry in manual mode.

# Transfer USDC from spot to perp account
transfer = agent.platforms.hyperliquid.transfer({
    "amount": 1000.0,
    "toPerp": True
})

if transfer.success:
    agent.log("Transfer completed")

​

Liquidations

def liquidations(start_time: int | None = None) -> HyperliquidLiquidationsResponse

• startTime (number, optional): Unix timestamp in milliseconds to filter liquidations from

• timestamp (number): Liquidation timestamp
• liquidatedPositions (array): Liquidated positions
• totalNotional (string): Total notional value liquidated
• accountValue (string): Account value at liquidation
• leverageType (string): “Cross” or “Isolated”
• txHash (string): Transaction hash

​

Midpoint Price

def midpoint_price(coin: str | list[str], dex: str | None = None) -> 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 most recent midpoint tick.
• isStale (boolean): true when the latest tick is older than ~90 seconds.

# 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}")

​

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).
• Transfer operations return void responses (no data on success).
• Spot symbols use the format "BTC/USDC", while perp symbols use just the base asset like "BTC".
• Hyperliquid rate-limits aggressively. Avoid calling balances() or positions() in loops.

​

See Also

• Hyperliquid Agent Example — Full working trading agent
• Wallets & Asset Allocation — Why Hyperliquid agents get the full wallet balance
• Suggestions — Control suggestion expiry with expiresAt in manual mode