View Source Hyperliquid.Api.Exchange.Order (hyperliquid v0.3.1)

Place orders on Hyperliquid.

Supports limit orders, trigger orders (stop-loss/take-profit), and batch ordering.

See: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint

Summary

Types

builder_info()
grouping()

Order grouping strategy.

limit_order()
order()
order_opts()
order_response()
trigger_order()

Functions

limit(asset, is_buy, limit_px, sz, opts \\ [])

Build a limit order.

limit_order(coin, is_buy, limit_px, sz, opts \\ [])

Build a limit order using coin symbol.

market(asset, is_buy, sz, opts \\ [])

Build a market order (IOC limit order at far price).

market_order(coin, is_buy, sz, opts \\ [])

Build a market order using coin symbol.

place(order, opts \\ [])

Place a single order.

place_batch(orders, grouping \\ :na, opts \\ [])

Place multiple orders in a batch.

place_limit(coin, is_buy, limit_px, sz, opts \\ [])

Build and place a limit order in one call.

place_market(coin, is_buy, sz, opts \\ [])

Build and place a market order in one call.

place_trigger(coin, is_buy, limit_px, sz, trigger_px, opts \\ [])

Build and place a trigger order in one call.

trigger(asset, is_buy, limit_px, sz, trigger_px, opts \\ [])

Build a trigger order (stop-loss or take-profit).

trigger_order(coin, is_buy, limit_px, sz, trigger_px, opts \\ [])

Build a trigger order using coin symbol.

Types

Link to this type

builder_info()

View Source 
@type builder_info() :: %{builder: String.t(), fee: non_neg_integer()}
Link to this type

grouping()

View Source 
@type grouping() ::
  :na | :normal_tpsl | :position_tpsl | {:priority, non_neg_integer()}

Order grouping strategy.

{:priority, rate} is an order priority fee: the rate is charged as the fraction rate / 100_000_000 of filled notional for IOC orders, or of resting notional for ALO orders, taken from undelegated staking balance.

Priority grouping is only valid when every order in the batch is on a non-outcome asset and either all of them are IOC or all of them are non-reduce-only ALO.

See: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/priority-fees

Link to this type

limit_order()

View Source 
@type limit_order() :: %{
  asset: non_neg_integer(),
  is_buy: boolean(),
  limit_px: String.t(),
  sz: String.t(),
  reduce_only: boolean(),
  order_type: :limit,
  tif: String.t(),
  cloid: String.t() | nil
}
Link to this type

order()

View Source 
@type order() :: limit_order() | trigger_order()
Link to this type

order_opts()

View Source 
@type order_opts() :: [vault_address: String.t(), builder: builder_info()]
Link to this type

order_response()

View Source 
@type order_response() :: %{
  status: String.t(),
  response: %{type: String.t(), data: %{statuses: list()}}
}
Link to this type

trigger_order()

View Source 
@type trigger_order() :: %{
  asset: non_neg_integer(),
  is_buy: boolean(),
  limit_px: String.t(),
  sz: String.t(),
  reduce_only: boolean(),
  order_type: :trigger,
  trigger_px: String.t(),
  is_market: boolean(),
  tpsl: String.t(),
  cloid: String.t() | nil
}

Functions

Link to this function

limit(asset, is_buy, limit_px, sz, opts \\ [])

View Source 
@spec limit(non_neg_integer(), boolean(), String.t(), String.t(), keyword()) ::
  limit_order()

Build a limit order.

Parameters

  • asset: Asset index
  • is_buy: true for buy, false for sell
  • limit_px: Limit price as string
  • sz: Size as string
  • opts: Optional parameters

Options

  • :reduce_only - Only reduce position (default: false)
  • :tif - Time in force (default: "Gtc"):
    • "Gtc" - Remains active until filled or cancelled
    • "Ioc" - Fills immediately, cancels any unfilled portion
    • "Alo" - Add liquidity only; rejected if it would cross
    • "FrontendMarket" - Behaves like "Ioc", but tags the order as a market order. Not currently listed in the public API docs; accepted by the exchange and used by the frontend.
  • :cloid - Client order ID

Examples 

Order.limit(0, true, "50000.0", "0.1")
Order.limit(0, true, "50000.0", "0.1", tif: "Ioc", cloid: "my-order-1")
Link to this function

limit_order(coin, is_buy, limit_px, sz, opts \\ [])

View Source 
@spec limit_order(
  String.t(),
  boolean(),
  number() | String.t(),
  number() | String.t(),
  keyword()
) :: limit_order() | {:error, term()}

Build a limit order using coin symbol.

Automatically looks up asset index and formats price/size.

Parameters

  • coin: Coin symbol (e.g., "BTC", "ETH", "HYPE/USDC")
  • is_buy: true for buy, false for sell
  • limit_px: Limit price
  • sz: Size
  • opts: Optional parameters (see limit/5)

Examples 

Order.limit_order("BTC", true, 50000.0, 0.1)
Order.limit_order("ETH", false, "3500.5", "1.5", tif: "Ioc")
Link to this function

market(asset, is_buy, sz, opts \\ [])

View Source 
@spec market(non_neg_integer(), boolean(), String.t(), keyword()) :: limit_order()

Build a market order (IOC limit order at far price).

Parameters

  • asset: Asset index
  • is_buy: true for buy, false for sell
  • sz: Size as string
  • opts: Optional parameters

Options

  • :slippage_price - Far limit price for slippage protection (auto-calculated if not provided)
  • :slippage - Slippage percentage (default: 0.05 = 5%)
  • :reduce_only - Only reduce position (default: false)
  • :cloid - Client order ID

When :slippage_price is not provided, the coin is resolved from the asset index via cache reverse lookup and the mid price is used to calculate slippage.

Examples 

# Automatic price lookup (resolves coin from asset index)
Order.market(0, true, "0.1")

# With explicit slippage price
Order.market(0, true, "0.1", slippage_price: "100000.0")
Link to this function

market_order(coin, is_buy, sz, opts \\ [])

View Source 
@spec market_order(String.t(), boolean(), number() | String.t(), keyword()) ::
  limit_order() | {:error, term()}

Build a market order using coin symbol.

Automatically looks up asset index, mid price, and formats size.

Parameters

  • coin: Coin symbol
  • is_buy: true for buy, false for sell
  • sz: Size
  • opts: Optional parameters
    • :slippage - Slippage percentage (default: 0.05 = 5%)
    • :slippage_price - Explicit far price (overrides automatic calculation)
    • :reduce_only - Only reduce position
    • :cloid - Client order ID

Examples 

Order.market_order("BTC", true, 0.1)
Order.market_order("ETH", false, 1.5, slippage: 0.03)
Link to this function

place(order, opts \\ [])

View Source 
@spec place(order(), order_opts()) :: {:ok, order_response()} | {:error, term()}

Place a single order.

Parameters

  • order: Order built with limit/5, trigger/6, or market/5
  • opts: Optional parameters

Options

  • :private_key - Private key for signing (falls back to config)
  • :vault_address - Trade on behalf of a vault
  • :builder - Builder info for builder fee

Returns

  • {:ok, response} - Order placement result
  • {:error, term()} - Error details

Examples 

order = Order.limit(0, true, "50000.0", "0.1")
{:ok, result} = Order.place(order)

Breaking Change (v0.2.0)

private_key was previously the first positional argument. It is now an option in the opts keyword list (:private_key).

Link to this function

place_batch(orders, grouping \\ :na, opts \\ [])

View Source 
@spec place_batch([order()], grouping(), order_opts()) ::
  {:ok, order_response()} | {:error, term()}

Place multiple orders in a batch.

Parameters

  • orders: List of orders
  • grouping: Order grouping strategy
  • opts: Optional parameters

Grouping Options

  • :na - No grouping (default)
  • :normal_tpsl - Group TP/SL with entry order
  • :position_tpsl - Attach TP/SL to existing position
  • {:priority, rate} - Order priority fee, charged as rate / 1e8 of filled notional (IOC) or resting notional (ALO), from undelegated staking balance. Only valid when every order is on a non-outcome asset and either all are IOC or all are non-reduce-only ALO. Max rate is 100_000_000.

Options

  • :private_key - Private key for signing (falls back to config)
  • :vault_address - Trade on behalf of a vault
  • :builder - Builder info for builder fee

Returns

  • {:ok, response} - Batch order result
  • {:error, term()} - Error details

Examples 

orders = [
  Order.limit(0, true, "50000.0", "0.1"),
  Order.limit(0, true, "49000.0", "0.1")
]
{:ok, result} = Order.place_batch(orders, :na)

Breaking Change (v0.2.0)

private_key was previously the first positional argument. It is now an option in the opts keyword list (:private_key).

Link to this function

place_limit(coin, is_buy, limit_px, sz, opts \\ [])

View Source

Build and place a limit order in one call.

Parameters

  • coin: Coin symbol
  • is_buy: true for buy, false for sell
  • limit_px: Limit price
  • sz: Size
  • opts: Optional parameters (see limit_order/5 and place/3)

Options

  • :private_key - Private key for signing (falls back to config)

Examples 

{:ok, result} = Order.place_limit("BTC", true, 50000, 0.1)
{:ok, result} = Order.place_limit("ETH", false, 3500, 1.5, tif: "Ioc", private_key: "abc...")

Breaking Change (v0.2.0)

private_key was previously the first positional argument. It is now an option in the opts keyword list (:private_key).

Link to this function

place_market(coin, is_buy, sz, opts \\ [])

View Source

Build and place a market order in one call.

Parameters

  • coin: Coin symbol
  • is_buy: true for buy, false for sell
  • sz: Size
  • opts: Optional parameters (see market_order/4 and place/3)

Options

  • :private_key - Private key for signing (falls back to config)

Examples 

{:ok, result} = Order.place_market("BTC", true, 0.1)
{:ok, result} = Order.place_market("ETH", false, 1.5, slippage: 0.03)

Breaking Change (v0.2.0)

private_key was previously the first positional argument. It is now an option in the opts keyword list (:private_key).

Link to this function

place_trigger(coin, is_buy, limit_px, sz, trigger_px, opts \\ [])

View Source

Build and place a trigger order in one call.

Parameters

  • coin: Coin symbol
  • is_buy: true for buy, false for sell
  • limit_px: Limit price
  • sz: Size
  • trigger_px: Trigger price
  • opts: Optional parameters (see trigger_order/6 and place/3)

Options

  • :private_key - Private key for signing (falls back to config)

Examples 

{:ok, result} = Order.place_trigger("BTC", false, 48000, 0.1, 49000, tpsl: "sl")

Breaking Change (v0.2.0)

private_key was previously the first positional argument. It is now an option in the opts keyword list (:private_key).

Link to this function

trigger(asset, is_buy, limit_px, sz, trigger_px, opts \\ [])

View Source 
@spec trigger(
  non_neg_integer(),
  boolean(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  trigger_order()

Build a trigger order (stop-loss or take-profit).

Parameters

  • asset: Asset index
  • is_buy: true for buy, false for sell
  • limit_px: Limit price as string (use far price for market trigger)
  • sz: Size as string
  • trigger_px: Trigger price as string
  • opts: Optional parameters

Options

  • :reduce_only - Only reduce position (default: false)
  • :is_market - Execute as market order when triggered (default: true)
  • :tpsl - "sl" for stop-loss, "tp" for take-profit (default: "sl")
  • :cloid - Client order ID

Examples 

# Stop-loss at 49000
Order.trigger(0, false, "48000.0", "0.1", "49000.0", tpsl: "sl")

# Take-profit at 55000
Order.trigger(0, false, "56000.0", "0.1", "55000.0", tpsl: "tp")
Link to this function

trigger_order(coin, is_buy, limit_px, sz, trigger_px, opts \\ [])

View Source 
@spec trigger_order(
  String.t(),
  boolean(),
  number() | String.t(),
  number() | String.t(),
  number() | String.t(),
  keyword()
) :: trigger_order() | {:error, term()}

Build a trigger order using coin symbol.

Automatically looks up asset index and formats price/size.

Parameters

  • coin: Coin symbol
  • is_buy: true for buy, false for sell
  • limit_px: Limit price
  • sz: Size
  • trigger_px: Trigger price
  • opts: Optional parameters (see trigger/6)

Examples 

# Stop-loss
Order.trigger_order("BTC", false, 48000, 0.1, 49000, tpsl: "sl")

# Take-profit
Order.trigger_order("BTC", false, 56000, 0.1, 55000, tpsl: "tp")