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

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

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

builder_info()

@type builder_info() :: %{builder: String.t(), fee: non_neg_integer()}

grouping()

@type grouping() :: :na | :normal_tpsl | :position_tpsl

limit_order()

@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
}

order()

@type order() :: limit_order() | trigger_order()

order_opts()

@type order_opts() :: [vault_address: String.t(), builder: builder_info()]

order_response()

@type order_response() :: %{
  status: String.t(),
  response: %{type: String.t(), data: %{statuses: list()}}
}

trigger_order()

@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

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

@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: "Gtc", "Ioc", "Alo" (default: "Gtc")
: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")

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

@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")

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

@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")

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

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

place(order, opts \\ [])

@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).

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

@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

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

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

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

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

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

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

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

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

@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")

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

@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")