Type definitions

Models

Complete reference for every request, response, and enum type in the Liquid API.

Overview

Every response from the Liquid API is wrapped in a standard envelope. The data field contains one of the typed models documented below. In the Python SDK these are frozen dataclasses; over the wire they are JSON objects.

Deep links

Each model heading has a Link button — use it to grab a permalink you can reference from other docs, issues, or code comments.

ApiResponse

Link

Every endpoint returns this envelope. Check success before reading data.

Field	Type	Description
success	boolean	Whether the request succeeded
data	T \| null	Response payload — type varies per endpoint
error	ApiErrorDetail \| null	Present only when success is false

Success

json

{
  "success": true,
  "data": { ... },
  "error": null
}

Error

json

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough available margin for this order"
  }
}

ApiErrorDetail

Link

Field	Type	Description
code	string	Machine-readable error code (e.g. INSUFFICIENT_BALANCE)
message	string	Human-readable explanation

OrderSide

Link

Direction of an order or position.

Value	Description
buy	Buy / long
sell	Sell / short

OrderType

Link

Execution strategy for an order.

Value	Description
market	Execute immediately at best available price
limit	Execute at the specified price or better

TimeInForce

Link

How long an order remains active.

Value	Description
gtc	Good-Till-Canceled — stays open until filled or explicitly canceled
ioc	Immediate-Or-Cancel — fills what it can, cancels the rest

Market

Link

Metadata for a tradeable perpetual contract. Returned by GET /v1/markets.

Field	Type	Description
symbol	string	Trading symbol (e.g. BTC-PERP)
ticker	string	Exchange-native ticker (e.g. BTC)
exchange	string	Exchange name — always hyperliquid
max_leverage	int \| null	Maximum allowed leverage
sz_decimals	int \| null	Decimal precision for order sizes

Example

json

{
  "symbol": "BTC-PERP",
  "ticker": "BTC",
  "exchange": "hyperliquid",
  "max_leverage": 200,
  "sz_decimals": 5
}

Ticker

Link

24-hour market snapshot. Returned by GET /v1/markets/{symbol}/ticker.

Field	Type	Description
symbol	string	Trading symbol
mark_price	string	Current mark / mid price
volume_24h	string \| null	24h trading volume in USD
change_24h	string \| null	24h price change as a decimal (e.g. 0.042 = +4.2%)
funding_rate	string \| null	Current funding rate

Example

json

{
  "symbol": "ETH-PERP",
  "mark_price": "3821.50",
  "volume_24h": "148230000",
  "change_24h": "0.042",
  "funding_rate": "0.0001"
}

SDK note

The Python SDK converts string numeric fields to float automatically. mark_price, volume_24h, change_24h, and funding_rate are all float or float | None on the Ticker dataclass.

Orderbook

Link

L2 orderbook snapshot. Returned by GET /v1/markets/{symbol}/orderbook.

Field	Type	Description
symbol	string	Trading symbol
bids	OrderbookLevel[]	Bid levels, sorted price descending
asks	OrderbookLevel[]	Ask levels, sorted price ascending
timestamp	int \| null	Snapshot timestamp in milliseconds

Example

json

{
  "symbol": "BTC-PERP",
  "bids": [
    { "price": "104200.0", "size": "1.25", "count": 1 },
    { "price": "104199.0", "size": "3.10", "count": 1 }
  ],
  "asks": [
    { "price": "104201.0", "size": "0.80", "count": 1 },
    { "price": "104202.0", "size": "2.50", "count": 1 }
  ],
  "timestamp": 1710000000000
}

OrderbookLevel

Link

A single price level in the orderbook.

Field	Type	Description
price	string	Price at this level
size	string	Total size at this level
count	int	Number of orders at this level (default 1)

Candle

Link

OHLCV candlestick bar. Returned by GET /v1/markets/{symbol}/candles.

Field	Type	Description
timestamp	int	Bar open time in milliseconds
open	string	Opening price
high	string	Highest price
low	string	Lowest price
close	string	Closing price
volume	string	Volume traded during the bar

Example

json

{
  "timestamp": 1710000000000,
  "open": "104100.0",
  "high": "104500.0",
  "low": "104050.0",
  "close": "104350.0",
  "volume": "2450000.0"
}

Account

Link

Account-level margin summary. Returned by GET /v1/account.

Field	Type	Description
equity	string	Total account equity
margin_used	string	Margin currently allocated to positions
available_balance	string	Balance available for new orders
account_value	string	Total account value including unrealized P&L

Example

json

{
  "equity": "50000.00",
  "margin_used": "12500.00",
  "available_balance": "37500.00",
  "account_value": "50250.00"
}

Balance

Link

Detailed balance breakdown. Returned by GET /v1/account/balances.

Field	Type	Description
exchange	string	Exchange name (hyperliquid)
equity	string	Total equity
available_balance	string	Available for trading
margin_used	string	Margin allocated to positions
cross_margin	CrossMargin \| null	Cross-margin details if applicable

Example

json

{
  "exchange": "hyperliquid",
  "equity": "50000.00",
  "available_balance": "37500.00",
  "margin_used": "12500.00",
  "cross_margin": {
    "account_value": "50250.00",
    "total_margin_used": "12500.00",
    "total_ntl_pos": "125000.00"
  }
}

CrossMargin

Link

Cross-margin account details, nested inside Balance.

Field	Type	Description
account_value	string	Total cross-margin account value
total_margin_used	string	Total margin used across all cross positions
total_ntl_pos	string	Total notional position size

Position

Link

An open perpetual position. Returned by GET /v1/account/positions and GET /v1/positions/{symbol}.

Field	Type	Description
symbol	string	Trading symbol (e.g. BTC-PERP)
side	string	Position direction — long or short
size	string	Position size in asset units
entry_price	string	Average entry price
mark_price	string \| null	Current mark price
leverage	string	Position leverage
unrealized_pnl	string	Unrealized profit and loss
liquidation_price	string \| null	Estimated liquidation price
margin_used	string \| null	Margin allocated to this position

Example

json

{
  "symbol": "ETH-PERP",
  "side": "long",
  "size": "5.0",
  "entry_price": "3800.00",
  "mark_price": "3821.50",
  "leverage": "10",
  "unrealized_pnl": "107.50",
  "liquidation_price": "3420.00",
  "margin_used": "1900.00"
}

Order

Link

Full order details returned after placing or querying a single order. Returned by POST /v1/orders and GET /v1/orders/{order_id}.

Field	Type	Description
order_id	string \| null	Exchange order ID
symbol	string	Trading symbol
side	string	buy or sell
type	string	market or limit
size	float	Order size in USD notional
price	float \| null	Limit price or execution price
leverage	int	Leverage multiplier (default 1)
status	string	filled, open, accepted, or cancelled
exchange	string	Exchange name (hyperliquid)
tp	float \| null	Take-profit trigger price
sl	float \| null	Stop-loss trigger price
reduce_only	boolean	Whether this order only reduces an existing position
created_at	string \| null	ISO 8601 timestamp

Example

json

{
  "order_id": "0x1a2b3c...",
  "symbol": "BTC-PERP",
  "side": "buy",
  "type": "limit",
  "size": 50000.0,
  "price": 104000.0,
  "leverage": 10,
  "status": "open",
  "exchange": "hyperliquid",
  "tp": 110000.0,
  "sl": 100000.0,
  "reduce_only": false,
  "created_at": "2025-03-10T14:30:00Z"
}

OpenOrder

Link

Lightweight representation of an open order. Returned by GET /v1/orders.

Field	Type	Description
order_id	string	Exchange order ID
symbol	string	Trading symbol
side	string	buy or sell
size	string	Order size in asset units
price	string	Limit price
timestamp	int	Placement time in milliseconds

Example

json

{
  "order_id": "0x1a2b3c...",
  "symbol": "BTC-PERP",
  "side": "buy",
  "size": "0.48",
  "price": "104000.0",
  "timestamp": 1710000000000
}

PlaceOrderRequest

Link

Request body for POST /v1/orders.

Field	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. BTC-PERP)
side	OrderSide	Yes	buy or sell
type	OrderType	Yes	market or limit
size	float	Yes	Order size in USD notional (must be > 0)
price	float	Limit only	Limit price (required when type is limit)
leverage	int	No	Leverage 1–200 (default 1)
time_in_force	TimeInForce	No	gtc (default) or ioc
tp	float	No	Take-profit trigger price
sl	float	No	Stop-loss trigger price
reduce_only	boolean	No	Only reduce an existing position (default false)

Market order

json

{
  "symbol": "BTC-PERP",
  "side": "buy",
  "type": "market",
  "size": 50000,
  "leverage": 10
}

Limit order with TP/SL

json

{
  "symbol": "ETH-PERP",
  "side": "sell",
  "type": "limit",
  "size": 10000,
  "price": 3900.0,
  "leverage": 5,
  "time_in_force": "gtc",
  "tp": 3700.0,
  "sl": 4000.0
}

ClosePositionRequest

Link

Request body for POST /v1/positions/{symbol}/close. Send an empty body to close the full position.

Field	Type	Required	Description
size	float	No	Partial close size in coin units. Omit to close the entire position.

Partial close

json

{ "size": 0.5 }

SetTpSlRequest

Link

Request body for PATCH /v1/positions/{symbol}/tp-sl. At least one of tp or sl must be provided.

Field	Type	Required	Description
tp	float \| null	Conditional	Take-profit trigger price (> 0)
sl	float \| null	Conditional	Stop-loss trigger price (> 0)

Example

json

{ "tp": 110000.0, "sl": 100000.0 }

AdjustMarginRequest

Link

Request body for PATCH /v1/positions/{symbol}/margin.

Field	Type	Required	Description
amount	float	Yes	Positive to add margin, negative to remove

Add margin

json

{ "amount": 500.0 }

UpdateLeverageRequest

Link

Request body for PATCH /v1/positions/{symbol}/leverage.

Field	Type	Required	Description
leverage	int	Yes	New leverage value (1–200)
is_cross	boolean	No	Use cross margin mode (default false)

Example

json

{ "leverage": 20, "is_cross": false }

CloseResult

Link

Returned in the data field after closing a position via POST /v1/positions/{symbol}/close.

Field	Type	Description
symbol	string	Trading symbol that was closed
status	string	Result status (e.g. closed, failed)
message	string	Human-readable result description

Example

json

{
  "symbol": "BTC-PERP",
  "status": "closed",
  "message": "Position fully closed"
}

TpSlResult

Link

Returned after setting take-profit / stop-loss via PATCH /v1/positions/{symbol}/tp-sl.

Field	Type	Description
tp	object \| null	Take-profit order details, or null if not set
sl	object \| null	Stop-loss order details, or null if not set

Example

json

{
  "tp": { "status": "ok", "price": 110000.0 },
  "sl": { "status": "ok", "price": 100000.0 }
}

MarginResult

Link

Returned after adjusting margin via PATCH /v1/positions/{symbol}/margin.

Field	Type	Description
symbol	string	Trading symbol
margin_adjusted	float	Amount of margin added (positive) or removed (negative)

Example

json

{
  "symbol": "BTC-PERP",
  "margin_adjusted": 500.0
}

LeverageResult

Link

Returned after updating leverage via PATCH /v1/positions/{symbol}/leverage.

Field	Type	Description
symbol	string	Trading symbol
leverage	int	New leverage value
is_cross	boolean	Whether cross margin mode is active

Example

json

{
  "symbol": "ETH-PERP",
  "leverage": 20,
  "is_cross": false
}

ApiKeyResponse

Link

API key metadata returned when listing keys. The secret is never included.

Field	Type	Description
id	string	API key identifier
label	string	User-assigned label
key_prefix	string	First 8 characters of the key for identification
permissions	int	Permission bitmask (1 = READ, 2 = TRADE, 3 = both)
ip_whitelist	string[]	Allowed IP addresses or CIDR ranges
is_revoked	boolean	Whether the key has been revoked
created_at	string	ISO 8601 creation timestamp
expires_at	string \| null	ISO 8601 expiration timestamp
last_used_at	string \| null	ISO 8601 last usage timestamp

Example

json

{
  "id": "key_abc123",
  "label": "production-bot",
  "key_prefix": "lq_a1b2c3",
  "permissions": 3,
  "ip_whitelist": ["203.0.113.0/24"],
  "is_revoked": false,
  "created_at": "2025-03-01T00:00:00Z",
  "expires_at": null,
  "last_used_at": "2025-03-10T14:30:00Z"
}

ApiKeyCreatedResponse

Link

Returned once when a new API key is created. This is the only time the secret is visible — store it securely.

Field	Type	Description
id	string	API key identifier
key	string	The API key (lq_... prefix)
secret	string	The API secret (sk_... prefix) — shown only once
label	string	User-assigned label
permissions	int	Permission bitmask
ip_whitelist	string[]	Allowed IP addresses or CIDR ranges

Store your secret

The secret field is only returned at creation time. It cannot be retrieved later. If you lose it, revoke the key and create a new one.