Hyperliquid

​

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.
• Your agent should use the below methods to pull live balances/positions directly from Hyperliquid for time-sensitive logic. agent.portfolio captures perp exposures in agent.portfolio.positions at execution start, but these methods read live from the clearinghouse and reflect the latest state.
  • 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.

​

Units

​

Place Order

def place_order(request: HyperliquidPlaceOrderRequest | HyperliquidPlaceOrderRequestInput) -> 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: "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.
• 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": "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
  • fullName (string | null): Full token name
  • tokenId (string): Hyperliquid token identifier
  • total (string): Total balance
  • hold (string): Amount on hold (in open orders)
  • priceUsd (string): Current price per token in USD
  • valueUsd (string): Total USD value of the balance
  • decimals (number): Token decimals
• 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.account_value}")
    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
  • coin (string): Asset identifier
  • 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)

# All venues: native + supported builder DEXes.
positions = agent.platforms.hyperliquid.positions()

# One builder DEX.
xyz_positions = agent.platforms.hyperliquid.positions(dex="xyz")

if positions.success and positions.data:
    for pos in positions.data:
        agent.log(f"{pos.coin} {pos.side}: {pos.size} @ {pos.entry_price}")
        agent.log(f"  PnL: {pos.unrealized_pnl}, Leverage: {pos.leverage}x")
        if pos.liquidation_price:
            agent.log(f"  Liq price: {pos.liquidation_price}")

​

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
  • 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”
• error (string | null): Error message (on failure)

​

Delete Order

def delete_order(order_id: str, coin: str, idempotency_key: str | None = None) -> 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)

​

Open Orders

def open_orders() -> HyperliquidOpenOrdersResponse

• success (boolean): Whether the operation succeeded
• data (array): Array of open orders (same shape as placeOrder response — orderId, coin, 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

• orderId (string): Order ID
• coin (string): Asset identifier
• side (string): “buy” or “sell”
• direction (string): Whether the fill opened or closed a position
• price (string): Fill price
• size (string): Fill size
• fee (string): Trading fee paid
• timestamp (number): Fill timestamp in milliseconds
• isCrossed (boolean): true for cross margin, false for isolated

​

Transfer

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

• amount (number): Amount to transfer
• toPerp (boolean): true to transfer to perp account, false to transfer to spot
• idempotencyKey (string, optional): Durable retry key for auto-mode transfers. SDKs generate one automatically; provide a stable key only when retrying the same logical transfer 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).

# 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 coins use the format "BTC/USDC", while perp coins 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 — How Hyperliquid collateral is allocated per session
• Suggestions — Control suggestion expiry for manual-mode order suggestions