Liquid Trading

https://sdk.tryliquid.xyz/docs
Admin
Liquid Trading is a Python SDK and REST API for trading perpetual futures on Hyperliquid with...
Tokens:16,275
Snippets:119
Trust Score:6.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install and Connect MCP Server

Source: https://sdk.tryliquid.xyz/docs/quickstart

Installs the liquidtrading-mcp package for AI agent trading and provides examples for global installation and connecting via the 'claude' CLI, including environment variable setup for API keys.

```bash
pip install liquidtrading-mcp
```

```bash
uv tool install liquidtrading-mcp
```

```bash
claude mcp add liquid \
  -e LIQUID_API_KEY=lq_... \
  -e LIQUID_API_SECRET=sk_... \
  -- liquidtrading-mcp
```

--------------------------------

### Install Liquid Trading Python SDK

Source: https://sdk.tryliquid.xyz/docs/quickstart

Installs the liquidtrading-python package from PyPI using pip or uv. This SDK simplifies interaction with the Liquid Trading API by handling request signing and response parsing.

```bash
pip install liquidtrading-python
```

```bash
uv add liquidtrading-python
```

--------------------------------

### Initialize Liquid Client and Get Ticker

Source: https://sdk.tryliquid.xyz/docs/quickstart

Initializes the LiquidClient with API credentials and fetches the market ticker for BTC-PERP. This demonstrates basic connectivity and retrieving market data.

```python
from liquidtrading import LiquidClient

client = LiquidClient(
    api_key="lq_...",
    api_secret="sk_...",
)

# Check connectivity
ticker = client.get_ticker("BTC-PERP")
print(f"BTC mark price: {ticker.mark_price}")
```

--------------------------------

### Installation

Source: https://sdk.tryliquid.xyz/docs/sdk

Install the Liquid Trading Python SDK using pip or uv. Requires Python 3.9+.

```APIDOC
## Installation

### pip
```bash
pip install liquidtrading-python
```

### uv
```bash
uv add liquidtrading-python
```

Requires Python 3.9+.
```

--------------------------------

### Install Liquid Trading MCP Server

Source: https://sdk.tryliquid.xyz/docs/mcp

Instructions for installing the Liquid Trading MCP server package using pip or uv for global access.

```bash
pip install liquidtrading-mcp
```

```bash
uv tool install liquidtrading-mcp
```

--------------------------------

### Place a Market Order with TP/SL

Source: https://sdk.tryliquid.xyz/docs/quickstart

Places a market order for BTC-PERP with specified size, leverage, take-profit, and stop-loss triggers. The size is in USD notional, and TP/SL are optional but recommended.

```python
order = client.place_order(
    symbol="BTC-PERP",
    side="buy",
    type="market",
    size=100.0,       # $100 USD notional
    leverage=2,
    tp=72000.0,       # take-profit trigger
    sl=68000.0,       # stop-loss trigger
)

print(f"Order {order.order_id}: {order.status}")
```

--------------------------------

### GET /v1/account

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves account margin overview and balances.

```APIDOC
## GET /v1/account

### Description
Get margin overview including equity, margin used, and available balance.

### Method
GET

### Endpoint
/v1/account

### Response
#### Success Response (200)
- **equity** (string) - Total account equity
- **margin_used** (string) - Total margin currently in use
- **available_balance** (string) - Available funds for trading

### Response Example
{
  "success": true,
  "data": {
    "equity": "10523.45",
    "margin_used": "2100.00",
    "available_balance": "8423.45"
  }
}
```

--------------------------------

### Read Market Data and Order Book

Source: https://sdk.tryliquid.xyz/docs/quickstart

Fetches a list of all tradeable markets and retrieves the order book for a specific symbol (BTC-PERP) with a specified depth. This showcases how to access market information.

```python
# List all tradeable markets
markets = client.get_markets()
for m in markets:
    print(m["symbol"], m["max_leverage"])

# Get order book
book = client.get_orderbook("BTC-PERP", depth=5)
print(f"Best bid: {book.bids[0].price}")
print(f"Best ask: {book.asks[0].price}")
```

--------------------------------

### Check Account State and Positions

Source: https://sdk.tryliquid.xyz/docs/quickstart

Retrieves the user's account equity and available balance, and lists current open positions with their details. This is useful for monitoring trading account status.

```python
account = client.get_account()
print(f"Equity: {account.equity}")
print(f"Available: {account.available_balance}")

positions = client.get_positions()
for pos in positions:
    print(f"{pos.symbol} {pos.side} {pos.size} @ {pos.entry_price}")
```

--------------------------------

### GET /v1/account

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves account-level margin and balance summary.

```APIDOC
## GET /v1/account

### Description
Returns the current account margin summary including equity, margin used, and available balance.

### Method
GET

### Endpoint
/v1/account

### Response
#### Success Response (200)
- **data** (Account) - Object containing equity, margin_used, available_balance, and account_value.

#### Response Example
{
  "success": true,
  "data": {
    "equity": "50000.00",
    "margin_used": "12500.00",
    "available_balance": "37500.00",
    "account_value": "50250.00"
  },
  "error": null
}
```

--------------------------------

### GET /v1/orders

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves a list of all open orders.

```APIDOC
## GET /v1/orders

### Description
Retrieves a list of all open orders.

### Method
GET

### Endpoint
/v1/orders

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **orders** (array) - An array of OpenOrder objects.

#### Response Example
```json
[
  {
    "order_id": "0x1a2b3c...",
    "symbol": "BTC-PERP",
    "side": "buy",
    "size": "0.48",
    "price": "104000.0",
    "timestamp": 1710000000000
  }
]
```
```

--------------------------------

### Retrieve Market Data

Source: https://sdk.tryliquid.xyz/docs/sdk

Examples of fetching market information, ticker prices, order books, and historical candle data using the LiquidClient.

```python
markets = client.get_markets()
ticker = client.get_ticker("ETH-PERP")
book = client.get_orderbook("BTC-PERP", depth=10)
candles = client.get_candles("BTC-PERP", interval="1h", limit=24)
```

--------------------------------

### Configure Claude Code and Desktop

Source: https://sdk.tryliquid.xyz/docs/mcp

Configuration examples for integrating the Liquid MCP server with Claude Code via terminal commands and Claude Desktop via JSON configuration.

```bash
claude mcp add liquid \
  -e LIQUID_API_KEY=lq_... \
  -e LIQUID_API_SECRET=sk_... \
  -- liquidtrading-mcp
```

```json
{
  "mcpServers": {
    "liquid": {
      "command": "liquidtrading-mcp",
      "env": {
        "LIQUID_API_KEY": "lq_...",
        "LIQUID_API_SECRET": "sk_...",
        "MAX_ORDER_USD": "1000",
        "DAILY_LOSS_LIMIT": "5000"
      }
    }
  }
}
```

--------------------------------

### GET /v1/markets

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves metadata for all tradeable perpetual contracts.

```APIDOC
## GET /v1/markets

### Description
Returns a list of metadata for all tradeable perpetual contracts on the exchange.

### Method
GET

### Endpoint
/v1/markets

### Response
#### Success Response (200)
- **data** (Market[]) - List of market objects containing symbol, ticker, exchange, max_leverage, and sz_decimals.

#### Response Example
{
  "success": true,
  "data": [
    {
      "symbol": "BTC-PERP",
      "ticker": "BTC",
      "exchange": "hyperliquid",
      "max_leverage": 200,
      "sz_decimals": 5
    }
  ],
  "error": null
}
```

--------------------------------

### GET /v1/markets

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves a list of all tradeable symbols available on the platform.

```APIDOC
## GET /v1/markets

### Description
List all tradeable symbols. Scope: READ.

### Method
GET

### Endpoint
/v1/markets

### Response
#### Success Response (200)
- **data** (array) - List of market objects
  - **symbol** (string) - Liquid symbol identifier
  - **ticker** (string) - Base asset ticker
  - **exchange** (string) - Underlying exchange
  - **max_leverage** (integer) - Maximum allowed leverage
  - **sz_decimals** (integer) - Size decimal precision

#### Response Example
{
  "success": true,
  "data": [
    {
      "symbol": "BTC-PERP",
      "ticker": "BTC",
      "exchange": "hyperliquid",
      "max_leverage": 40,
      "sz_decimals": 5
    }
  ]
}
```

--------------------------------

### Place Order Request Schemas

Source: https://sdk.tryliquid.xyz/docs/models

Examples of request bodies for the POST /v1/orders endpoint, supporting both market and limit order types with optional take-profit and stop-loss parameters.

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

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

--------------------------------

### Get OHLCV Candle Data

Source: https://sdk.tryliquid.xyz/docs/api-reference

Fetches historical OHLCV (Open, High, Low, Close, Volume) candle data for a specified market symbol. You can filter by interval, limit the number of candles, and specify a start and end timestamp. The timestamp in the data is in milliseconds.

```json
{
  "success": true,
  "data": [
    {
      "timestamp": 1700000000000,
      "open": "68000.0",
      "high": "68200.0",
      "low": "67850.0",
      "close": "68120.0",
      "volume": "1234.56"
    }
  ]
}
```

--------------------------------

### GET /v1/account/positions

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves a list of all open perpetual positions for the account.

```APIDOC
## GET /v1/account/positions

### Description
Retrieves a list of all open perpetual positions for the account.

### Method
GET

### Endpoint
/v1/account/positions

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **positions** (array) - An array of Position objects.

#### Response 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"
  }
]
```
```

--------------------------------

### GET /v1/markets/{symbol}/ticker

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves a 24-hour market snapshot for a specific symbol.

```APIDOC
## GET /v1/markets/{symbol}/ticker

### Description
Provides a 24-hour snapshot of market performance including mark price, volume, and funding rate.

### Method
GET

### Endpoint
/v1/markets/{symbol}/ticker

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The trading symbol (e.g., BTC-PERP)

### Response
#### Success Response (200)
- **data** (Ticker) - Object containing mark_price, volume_24h, change_24h, and funding_rate.

#### Response Example
{
  "success": true,
  "data": {
    "symbol": "ETH-PERP",
    "mark_price": "3821.50",
    "volume_24h": "148230000",
    "change_24h": "0.042",
    "funding_rate": "0.0001"
  },
  "error": null
}
```

--------------------------------

### Get Account Overview

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves a summary of the account's margin status, including equity, margin used, available balance, and overall account value. This endpoint requires READ scope.

```json
{
  "success": true,
  "data": {
    "equity": "10523.45",
    "margin_used": "2100.00",
    "available_balance": "8423.45",
    "account_value": "10523.45"
  }
}
```

--------------------------------

### GET /v1/account/balances

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves a detailed breakdown of the account's balance, including equity, available balance, and margin used.

```APIDOC
## GET /v1/account/balances

### Description
Retrieves a detailed breakdown of the account's balance, including equity, available balance, and margin used.

### Method
GET

### Endpoint
/v1/account/balances

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **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) - Cross-margin details if applicable

#### Response 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"
  }
}
```
```

--------------------------------

### GET /v1/markets/{symbol}/orderbook

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves the L2 orderbook snapshot for a specific symbol.

```APIDOC
## GET /v1/markets/{symbol}/orderbook

### Description
Returns the current L2 orderbook snapshot, including bids and asks.

### Method
GET

### Endpoint
/v1/markets/{symbol}/orderbook

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The trading symbol

### Response
#### Success Response (200)
- **data** (Orderbook) - Object containing bids, asks, and timestamp.

#### Response Example
{
  "success": true,
  "data": {
    "symbol": "BTC-PERP",
    "bids": [{"price": "104200.0", "size": "1.25", "count": 1}],
    "asks": [{"price": "104201.0", "size": "0.80", "count": 1}],
    "timestamp": 1710000000000
  },
  "error": null
}
```

--------------------------------

### GET /v1/positions/{symbol}

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves details for a specific open perpetual position by its symbol.

```APIDOC
## GET /v1/positions/{symbol}

### Description
Retrieves details for a specific open perpetual position by its symbol.

### Method
GET

### Endpoint
/v1/positions/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - Trading symbol (e.g. BTC-PERP)

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **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

#### Response 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"
}
```
```

--------------------------------

### GET /v1/markets/{symbol}/ticker

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves current mark price and 24-hour market metadata for a specific symbol.

```APIDOC
## GET /v1/markets/{symbol}/ticker

### Description
Get current mark price and 24h metadata for a symbol. Scope: READ.

### Method
GET

### Endpoint
/v1/markets/{symbol}/ticker

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The symbol identifier (e.g., BTC-PERP)

### Response
#### Success Response (200)
- **mark_price** (string) - Current mark price
- **volume_24h** (string) - 24-hour trading volume in USD
- **change_24h** (string) - 24-hour price change percentage
- **funding_rate** (string) - Current funding rate

#### Response Example
{
  "success": true,
  "data": {
    "symbol": "BTC-PERP",
    "mark_price": "69420.50",
    "volume_24h": "1234567.89",
    "change_24h": "2.34",
    "funding_rate": "0.0001"
  }
}
```

--------------------------------

### GET /v1/orders/{order_id}

Source: https://sdk.tryliquid.xyz/docs/models

Retrieves details for a specific order by its order ID.

```APIDOC
## GET /v1/orders/{order_id}

### Description
Retrieves details for a specific order by its order ID.

### Method
GET

### Endpoint
/v1/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The ID of the order to retrieve.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **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

#### Response 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"
}
```
```

--------------------------------

### Get Account Positions

Source: https://sdk.tryliquid.xyz/docs/api-reference

Fetches details of all open positions for the account. Each position includes symbol, side, size, entry price, mark price, leverage, unrealized PNL, liquidation price, and margin used. This endpoint requires READ scope.

```json
{
  "success": true,
  "data": [
    {
      "symbol": "BTC-PERP",
      "side": "long",
      "size": "0.05",
      "entry_price": "69000.00",
      "mark_price": "69420.50",
      "leverage": 5,
      "unrealized_pnl": "21.00",
      "liquidation_price": "55200.00",
      "margin_used": "690.00"
    }
  ]
}
```

--------------------------------

### GET /v1/markets/{symbol}/orderbook

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves an L2 order book snapshot for a specific market symbol.

```APIDOC
## GET /v1/markets/{symbol}/orderbook

### Description
Get an L2 order book snapshot for the specified market symbol.

### Method
GET

### Endpoint
/v1/markets/{symbol}/orderbook

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The market symbol (e.g., BTC-PERP)

#### Query Parameters
- **depth** (integer) - Optional - Number of levels per side (1-500). Default: 20

### Response
#### Success Response (200)
- **success** (boolean) - Indicates request success
- **data** (object) - Contains symbol, bids, asks, and timestamp

### Response Example
{
  "success": true,
  "data": {
    "symbol": "BTC-PERP",
    "bids": [{ "price": "69400.00", "size": "1.25", "count": 3 }],
    "asks": [{ "price": "69420.00", "size": "0.80", "count": 2 }],
    "timestamp": null
  }
}
```

--------------------------------

### GET /v1/health

Source: https://sdk.tryliquid.xyz/docs/api-reference

Unauthenticated health check endpoint to verify connectivity to the Liquid Trading API.

```APIDOC
## GET /v1/health

### Description
Unauthenticated health check. Use this to verify connectivity.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **status** (string) - Current system status
- **version** (string) - API version

#### Response Example
{
  "status": "ok",
  "version": "1.0.0"
}
```

--------------------------------

### Retrieve Open Order Summary Data Model

Source: https://sdk.tryliquid.xyz/docs/models

A lightweight representation of an active order, returned when listing all open orders via GET /v1/orders.

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

--------------------------------

### Get L2 Order Book Snapshot

Source: https://sdk.tryliquid.xyz/docs/api-reference

Retrieves a Level 2 order book snapshot for a given market symbol. The 'depth' parameter controls the number of bid and ask levels returned. The timestamp in the response is currently null and should not be relied upon for freshness.

```json
{
  "success": true,
  "data": {
    "symbol": "BTC-PERP",
    "bids": [
      { "price": "69400.00", "size": "1.25", "count": 3 }
    ],
    "asks": [
      { "price": "69420.00", "size": "0.80", "count": 2 }
    ],
    "timestamp": null
  }
}
```

--------------------------------

### Retrieve Account Balance Data Model

Source: https://sdk.tryliquid.xyz/docs/models

Represents the structure of account balance information, including equity, available margin, and cross-margin details. This object is returned by the GET /v1/account/balances endpoint.

```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"
  }
}
```

--------------------------------

### Initialize and Configure LiquidClient

Source: https://sdk.tryliquid.xyz/docs/sdk

Demonstrates how to instantiate the LiquidClient with authentication credentials and optional configuration parameters like base URL, timeout, and retry logic.

```python
from liquidtrading import LiquidClient

client = LiquidClient(
    api_key="lq_...",
    api_secret="sk_...",
    base_url="https://api-public.liquidmax.xyz",
    timeout=30.0,
    max_retries=0
)
```

--------------------------------

### Execute and Manage Orders

Source: https://sdk.tryliquid.xyz/docs/sdk

Demonstrates placing market and limit orders with optional take-profit and stop-loss parameters, as well as order cancellation.

```python
order = client.place_order(symbol="BTC-PERP", side="buy", type="market", size=100.0, tp=72000.0, sl=68000.0)
limit = client.place_order(symbol="ETH-PERP", side="sell", type="limit", size=50.0, price=4200.0)
client.cancel_order(limit.order_id)
```

--------------------------------

### Client Configuration

Source: https://sdk.tryliquid.xyz/docs/sdk

Configure the LiquidClient with your API key, secret, and optional parameters like base_url, timeout, and max_retries.

```APIDOC
## Client Configuration

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| api_key | str | — | Your Liquid API key |
| api_secret | str | — | Your Liquid API secret |
| base_url | str | https://api-public.liquidmax.xyz | REST API base URL |
| timeout | float | 30.0 | Request timeout in seconds |
| max_retries | int | 0 | Retry count for GET requests on 429/5xx |

Retries use exponential backoff with jitter and respect Retry-After headers. Only GET requests are retried — mutations are never automatically retried.

### Example
```python
from liquidtrading import LiquidClient

client = LiquidClient(
    api_key="lq_...",
    api_secret="sk_...",
    base_url="https://api-public.liquidmax.xyz",  # default
    timeout=30.0,                          # seconds
    max_retries=0,                         # retries for GET on 429/5xx
)
```
```

--------------------------------

### Handle API Exceptions and Order Placement

Source: https://sdk.tryliquid.xyz/docs/sdk

Demonstrates how to place an order and implement robust error handling using specific Liquid SDK exception classes. It catches common issues like authentication failures, insufficient funds, and validation errors.

```python
from liquidtrading import LiquidClient
from liquidtrading.errors import (
	InvalidApiKeyError,
	InvalidSignatureError,
	InsufficientScopeError,
	InsufficientBalanceError,
	OrderRejectedError,
	SymbolNotFoundError,
	RateLimitError,
	ValidationError,
)

client = LiquidClient(api_key="lq_...", api_secret="sk_...")

try:
	client.place_order("BTC-PERP", "buy", size=100, leverage=2)
except InvalidApiKeyError:
	print("Check your API key")
except InvalidSignatureError:
	print("Check your API secret")
except InsufficientScopeError:
	print("Key needs TRADE scope")
except InsufficientBalanceError:
	print("Not enough balance")
except OrderRejectedError as exc:
	print(f"Exchange rejected: {exc.message}")
except SymbolNotFoundError:
	print("Invalid symbol — call get_markets() to list valid symbols")
except RateLimitError as exc:
	print(f"Retry after {exc.retry_after}s")
except ValidationError as exc:
	print(f"Bad request: {exc.message}")
```

--------------------------------

### Manage Account and Positions

Source: https://sdk.tryliquid.xyz/docs/sdk

Retrieves account equity, balances, and open positions to monitor portfolio performance.

```python
account = client.get_account()
for pos in client.get_positions():
    print(f"{pos.symbol} {pos.side} | PnL: {pos.unrealized_pnl}")
```

--------------------------------

### Positions API

Source: https://sdk.tryliquid.xyz/docs/sdk

Manage open positions, including closing, setting take-profit/stop-loss, updating leverage, and adjusting margin.

```APIDOC
## Positions

### Methods

| Method | Returns | Description |
|---|---|---|
| close_position(symbol, size=None) | CloseResult | Full close if size omitted, partial close in coin units |
| set_tp_sl(symbol, tp=None, sl=None) | TpSlResult | Set or update take-profit and/or stop-loss |
| update_leverage(symbol, leverage, is_cross=False) | LeverageResult | Update leverage (1-200) and margin mode |
| update_margin(symbol, amount) | MarginResult | Adjust isolated margin (positive adds, negative removes) |

### Examples

```python
# Close entire position
client.close_position("BTC-PERP")

# Partial close (0.025 BTC, not USD)
client.close_position("BTC-PERP", size=0.025)

# Update TP/SL
client.set_tp_sl("BTC-PERP", tp=75000.0, sl=65000.0)
```
```

--------------------------------

### Account API

Source: https://sdk.tryliquid.xyz/docs/sdk

Access account information, balances, and open positions.

```APIDOC
## Account

### Methods

| Method | Returns | Description |
|---|---|---|
| get_account() | Account | Equity, margin_used, available_balance, account_value |
| get_balances() | Balance | Detailed balance breakdown with optional cross_margin |
| get_positions() | list[Position] | Open positions with full detail |

### Examples

```python
account = client.get_account()
print(f"Equity: {account.equity}")
print(f"Available: {account.available_balance}")

for pos in client.get_positions():
    print(f"{pos.symbol} {pos.side} | PnL: {pos.unrealized_pnl}")
```
```

--------------------------------

### Orders API

Source: https://sdk.tryliquid.xyz/docs/sdk

Place, retrieve, and cancel orders. Supports market and limit orders with optional take-profit and stop-loss.

```APIDOC
## Orders

### Methods

| Method | Returns | Description |
|---|---|---|
| place_order(...) | Order | Place market or limit order |
| get_open_orders() | list[OpenOrder] | All currently open orders |
| get_order(order_id) | Order | Fetch specific order by ID |
| cancel_order(order_id) | bool | Cancel single order |
| cancel_all_orders() | int | Cancel all open orders, returns count |

### Parameters for `place_order`

| Parameter | Type | Required | Description |
|---|---|---|---|
| symbol | str | Yes | Market symbol |
| side | str | Yes | buy or sell |
| type | str | No | market (default) or limit |
| size | float | Yes | USD notional (must be > 0) |
| price | float | Limit only | Required for limit orders |
| leverage | int | No | 1-200 (default 1) |
| time_in_force | str | No | gtc (default) or ioc |
| tp | float | No | Take-profit trigger |
| sl | float | No | Stop-loss trigger |
| reduce_only | bool | No | Only reduce existing position |

### Examples

```python
# Market buy with TP/SL
order = client.place_order(
    symbol="BTC-PERP",
    side="buy",
    type="market",
    size=100.0,       # USD notional
    leverage=2,
    tp=72000.0,
    sl=68000.0,
)
print(f"Filled: {order.order_id}")

# Limit sell
limit = client.place_order(
    symbol="ETH-PERP",
    side="sell",
    type="limit",
    size=50.0,
    price=4200.0,
    leverage=3,
)

# Cancel
client.cancel_order(limit.order_id)
```
```

--------------------------------

### POST /v1/orders

Source: https://sdk.tryliquid.xyz/docs/api-reference

Places a new market or limit order on the exchange.

```APIDOC
## POST /v1/orders

### Description
Place a market or limit order. Requires TRADE scope.

### Method
POST

### Endpoint
/v1/orders

### Parameters
#### Request Body
- **symbol** (string) - Required - Market symbol (e.g. BTC-PERP)
- **side** (string) - Required - buy or sell
- **type** (string) - Optional - market (default) or limit
- **size** (number) - Required - Order size in USD notional
- **price** (number) - Conditional - Limit price (required for limit orders)
- **leverage** (integer) - Optional - 1-200 (default 1)

### Request Example
{
  "symbol": "BTC-PERP",
  "side": "buy",
  "type": "market",
  "size": 100.0,
  "leverage": 5
}

### Response
#### Success Response (200)
- **order_id** (string) - Unique identifier for the order
- **status** (string) - Current status of the order

### Response Example
{
  "success": true,
  "data": {
    "order_id": "ord_abc123",
    "status": "filled"
  }
}
```

--------------------------------

### Authenticate API Requests with HMAC-SHA256

Source: https://sdk.tryliquid.xyz/docs/api-reference

Demonstrates how to construct an authenticated request using HMAC-SHA256 headers. The payload includes a timestamp, nonce, method, path, query, and body hash.

```bash
curl https://api-public.liquidmax.xyz/v1/account \
  -H "X-Liquid-Key: lq_..." \
  -H "X-Liquid-Timestamp: 1700000000000" \
  -H "X-Liquid-Nonce: abc123xyz789" \
  -H "X-Liquid-Signature: <hex-hmac>"
```

--------------------------------

### Update Leverage Configuration

Source: https://sdk.tryliquid.xyz/docs/sdk

Updates the leverage settings for a specific trading pair. It requires the symbol, the desired leverage multiplier, and a boolean flag for cross-margin status.

```python
client.update_leverage("ETH-PERP", leverage=10, is_cross=False)
```

--------------------------------

### POST /v1/orders

Source: https://sdk.tryliquid.xyz/docs/models

Places a new order. Returns full order details upon successful placement.

```APIDOC
## POST /v1/orders

### Description
Places a new order. Returns full order details upon successful placement.

### Method
POST

### Endpoint
/v1/orders

### Parameters
#### Path Parameters
None

#### Query Parameters
None

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

### Request Example
**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
}
```

### Response
#### Success Response (200)
- **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

#### Response 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"
}
```
```

--------------------------------

### Market Data API

Source: https://sdk.tryliquid.xyz/docs/sdk

Retrieve market data including tickers, order books, and historical candles.

```APIDOC
## Market Data

### Methods

| Method | Returns | Description |
|---|---|---|
| get_markets() | list[dict] | All tradeable markets with symbol, ticker, exchange, max_leverage |
| get_ticker(symbol) | Ticker | Mark price, 24h volume, 24h change, funding rate |
| get_orderbook(symbol, depth=20) | Orderbook | L2 snapshot with bids and asks (price, size, count per level) |
| get_candles(symbol, interval, limit, start, end) | list[Candle] | OHLCV candles (intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d) |

### Examples

```python
# Get all markets
markets = client.get_markets()

# Get ticker
ticker = client.get_ticker("ETH-PERP")
print(f"ETH: {ticker.mark_price} | Funding: {ticker.funding_rate}")

# Get order book
book = client.get_orderbook("BTC-PERP", depth=10)
print(f"Spread: {book.asks[0].price - book.bids[0].price}")

# Get 1h candles
candles = client.get_candles("BTC-PERP", interval="1h", limit=24)
```
```

--------------------------------

### Retrieve Market Data

Source: https://sdk.tryliquid.xyz/docs/api-reference

Endpoints for listing tradeable symbols and fetching ticker information for specific markets. These require authentication with READ scope.

```bash
curl https://api-public.liquidmax.xyz/v1/markets \
  -H "X-Liquid-Key: lq_..." \
  -H "X-Liquid-Timestamp: ..." \
  -H "X-Liquid-Nonce: ..." \
  -H "X-Liquid-Signature: ..."
```

```bash
curl https://api-public.liquidmax.xyz/v1/markets/BTC-PERP/ticker \
  -H "X-Liquid-Key: lq_..." \
  -H "X-Liquid-Timestamp: ..." \
  -H "X-Liquid-Nonce: ..." \
  -H "X-Liquid-Signature: ..."
```

--------------------------------

### Run Liquid MCP Server over HTTP

Source: https://sdk.tryliquid.xyz/docs/mcp

Command to run the Liquid MCP server over a streamable HTTP transport on port 4243 for remote or multi-client environments.

```bash
LIQUID_API_KEY=lq_... \
LIQUID_API_SECRET=sk_... \
liquidtrading-mcp --http
```

--------------------------------

### Order Placement Response

Source: https://sdk.tryliquid.xyz/docs/api-reference

The response after placing an order, indicating success or failure. If successful, it includes details like order ID, symbol, side, type, size, price, leverage, status, and associated take-profit and stop-loss triggers. The size is always in USD notional.

```json
{
  "success": true,
  "data": {
    "order_id": "ord_abc123",
    "symbol": "BTC-PERP",
    "side": "buy",
    "type": "market",
    "size": "100.0",
    "price": "69420.50",
    "leverage": 5,
    "status": "filled",
    "exchange": "hyperliquid",
    "tp": "72000.0",
    "sl": "68000.0",
    "reduce_only": false,
    "created_at": "2025-01-15T12:00:00Z"
  }
}
```

--------------------------------

### Place Market Order

Source: https://sdk.tryliquid.xyz/docs/api-reference

Places a new order, which can be a market or limit order. Required fields include symbol, side, and size (in USD notional). Optional fields include type, price (for limit orders), leverage, time in force, take-profit, stop-loss, and reduce_only flag. This endpoint requires TRADE scope.

```json
{
  "symbol": "BTC-PERP",
  "side": "buy",
  "type": "market",
  "size": 100.0,
  "leverage": 5,
  "tp": 72000.0,
  "sl": 68000.0
}
```

--------------------------------

### Modify Positions

Source: https://sdk.tryliquid.xyz/docs/sdk

Provides methods to close positions, update take-profit/stop-loss levels, and adjust leverage or isolated margin.

```python
client.close_position("BTC-PERP", size=0.025)
client.set_tp_sl("BTC-PERP", tp=75000.0, sl=65000.0)
```

--------------------------------

### Market Ticker Snapshot

Source: https://sdk.tryliquid.xyz/docs/models

Provides a 24-hour market snapshot containing pricing, volume, and funding rate information.

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

--------------------------------

### Set Take-Profit and Stop-Loss Request

Source: https://sdk.tryliquid.xyz/docs/models

Request body for updating take-profit and stop-loss levels on a position. At least one of the fields must be provided.

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

--------------------------------

### Take-Profit and Stop-Loss Result

Source: https://sdk.tryliquid.xyz/docs/models

Response object confirming the status and price settings for take-profit and stop-loss orders.

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

--------------------------------

### Update Leverage via PATCH

Source: https://sdk.tryliquid.xyz/docs/api-reference

Updates the leverage multiplier and toggles the margin mode (cross vs isolated) for a position.

```json
{
  "leverage": 10,
  "is_cross": false
}
```

--------------------------------

### Account Margin Summary

Source: https://sdk.tryliquid.xyz/docs/models

Provides a summary of account-level margin, including total equity, used margin, and available balance.

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

--------------------------------

### Update TP/SL via PATCH

Source: https://sdk.tryliquid.xyz/docs/api-reference

Sets or updates the take-profit (tp) and stop-loss (sl) price levels for an existing position.

```json
{
  "tp": 72000.0,
  "sl": 68000.0
}
```

--------------------------------

### Retrieve Order Details Data Model

Source: https://sdk.tryliquid.xyz/docs/models

Represents the full state of an order, including status, pricing, and trigger conditions. This is returned when querying specific orders or after placement.

```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"
}
```

--------------------------------

### PATCH /v1/positions/{symbol}/tp-sl

Source: https://sdk.tryliquid.xyz/docs/models

Updates the take-profit and stop-loss trigger prices for an existing position.

```APIDOC
## PATCH /v1/positions/{symbol}/tp-sl

### Description
Updates the take-profit and stop-loss trigger prices for an existing position. At least one of tp or sl must be provided.

### Method
PATCH

### Endpoint
/v1/positions/{symbol}/tp-sl

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The trading symbol of the position

#### Request Body
- **tp** (float) - Conditional - Take-profit trigger price (> 0)
- **sl** (float) - Conditional - Stop-loss trigger price (> 0)

### Request Example
{
  "tp": 110000.0,
  "sl": 100000.0
}

### Response
#### Success Response (200)
- **tp** (object) - Take-profit order details, or null if not set
- **sl** (object) - Stop-loss order details, or null if not set

#### Response Example
{
  "tp": { "status": "ok", "price": 110000.0 },
  "sl": { "status": "ok", "price": 100000.0 }
}
```

--------------------------------

### Leverage Update Result

Source: https://sdk.tryliquid.xyz/docs/models

Response object confirming the new leverage settings for a specific trading symbol.

```json
{
  "symbol": "ETH-PERP",
  "leverage": 20,
  "is_cross": false
}
```
Tokens:
Raw