Hyperliquid

Trade perpetual futures and spot markets on Hyperliquid DEX.

Configuration

To define USDC Perps as your agent's required asset, use the following network and address in the .circuit.toml file.

[[requiredAssets]]
network = "hypercore:perp" 
address = ""
minimumAmount = "1000000" // 6 decimals
devRunAmount = "1000000" // See note below regarding allocation 

Asset Allocation Notes

Circuit restricts users from deploying multiple Hyperliquid agents per wallet. This enables your agent to safely manage margin requirements on open perpetual positions without potential interference from other agents. This also introduces a few quirks to be aware of.

• The devRunAmount in the .circuit.toml file is not relevant for Hyperliquid agents, as your entire balance will be available to the agent when you start a session

• The minimumAmount will still ensure that anyone deploying the agent will at least have that amount.

• Your agent should use the below methods to pull available balances/positions directly from Hyperliquid, 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: This is temporary while Circuit enhances the indexing of Hyperliquid activity, which will allow us to include the balances natively in the agent's currentPositions property.

Units

When querying via Hyperliquid's api (via agent.platforms.hyperliquid), all values will be returned in their formatted value, opposed to the rest of Circuit which returns values in their raw units (wei/lamports)

Place Order

If you are un-familar with placing orders via Hyperliquid's API, please see these docs for information regarding tick/lot sizes, as well as decimals.

TypeScript

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

Python

Request Parameters:

• 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

Response:

• 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)

Example:

TypeScript

// Perp market order
const perpOrder = await agent.platforms.hyperliquid.placeOrder({
  symbol: "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({
  symbol: "BTC-USDC",
  side: "buy",
  size: 0.0001,
  price: 110000, // Acts as slippage limit for market orders
  market: "spot",
  type: "market"
});

Python

Balances

Get account balances.

TypeScript

async balances(): Promise<HyperliquidBalancesResponse>

Python

Response:

• 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

• error (string | null): Error message (on failure)

Positions

Get open positions.

TypeScript

async positions(): Promise<HyperliquidPositionsResponse>

Python

Response:

• 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)

Order

Get order information by order ID.

TypeScript

async order(orderId: string): Promise<HyperliquidOrderResponse>

Python

Delete Order

Cancel an order.

TypeScript

async deleteOrder(orderId: string, symbol: string): Promise<HyperliquidDeleteOrderResponse>

Python

Open Orders

Get all open orders.

TypeScript

async openOrders(): Promise<HyperliquidOpenOrdersResponse>

Python

Orders

Get historical orders.

TypeScript

async orders(): Promise<HyperliquidHistoricalOrdersResponse>

Python

Response includes:

• 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

Get order fill history.

TypeScript

async orderFills(): Promise<HyperliquidOrderFillsResponse>

Python

Response includes:

• price (string): Fill price

• size (string): Fill size

• fee (string): Trading fee paid

• isMaker (boolean): True if maker, false if taker

Transfer

Transfer between spot and perp accounts.

TypeScript

async transfer(request: HyperliquidTransferRequest): Promise<HyperliquidTransferResponse>

Python

Request Parameters:

• amount (number): Amount to transfer

• toPerp (boolean): true to transfer to perp account, false to transfer to spot

Example:

TypeScript

// Transfer USDC from spot to perp account
const transfer = await agent.platforms.hyperliquid.transfer({
  amount: 1000.0,
  toPerp: true
});

if (transfer.success) {
  await agent.log("Transfer completed");
}

Python

Liquidations

Get liquidation events.

TypeScript

async liquidations(startTime?: number): Promise<HyperliquidLiquidationsResponse>

Python

Parameters:

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

Response includes:

• 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

Errors are returned in the error field of the response. Common errors include:

Error	Cause	Solution
"Unknown perp asset: {asset}. Available assets: ..."	Invalid perp symbol (e.g., "BTC" for perps)	Use valid perp asset symbol like "BTC", "ETH"
"Unknown spot pair: {pair}. Available pairs: ..."	Invalid spot symbol (e.g., "BTC-USDC" for spot)	Use valid spot pair format like "BTC-USDC", "ETH-USDC"
"Invalid coin format: {coin}"	Invalid symbol format	Ensure symbol matches expected format (perps: "BTC", spot: "BTC-USDC")
"{order.type} order requires triggerPrice"	Stop or take_profit order missing triggerPrice	Provide triggerPrice parameter for stop/take_profit orders
"Order not found"	Order ID doesn't exist	Verify order ID is correct
"Failed to place order"	Order submission failed	Check order parameters and account balance

Note: Additional error messages may be returned by Hyperliquid's API. Check the error field in the response for specific details.

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=True).