Hyperliquid

​

Configuration

[startingAsset]
network = "hypercore:perp"
address = "USDC"
minimumAmount = "1000000"  # 1 USDC (6 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()
  • 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 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
• 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() -> HyperliquidPositionsResponse

• 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()
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
• isMaker (boolean): True if maker, false if taker

​

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

​

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