liquidtrading-python 0.1.1

Python SDK for the Liquid trading API

liquidtrading-python

Official Python SDK for the Liquid trading API.

Installation

pip install liquidtrading-python

uv add liquidtrading-python

Quick Start

from liquidtrading import LiquidClient

client = LiquidClient(api_key="lq_...", api_secret="sk_...")
ticker = client.get_ticker("BTC-PERP")
print(f"BTC: {ticker.mark_price}")

Legacy compatibility import:

from liquid import Client

Authentication

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

Hosted Liquid API requests currently require credentials:

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

Quick connectivity check after install:

liquidtrading-demo --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...

If you also want to query open orders:

liquidtrading-demo --base-url http://localhost:8001 --api-key lq_... --api-secret sk_... --include-open-orders

Easiest local repo smoke test:

bash scripts/run_smoke_demo.sh --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...

Alternative local repo smoke test:

uv run python examples/smoke_demo.py --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...

Publishing guide:

See PUBLISHING.md

Methods

Market Data (read scope)

client.get_markets()                                    # list[dict]
client.get_ticker("BTC-PERP")                           # Ticker
client.get_orderbook("BTC-PERP", depth=20)              # Orderbook
client.get_candles("BTC-PERP", interval="1h", limit=100) # list[Candle]

Account (read scope)

client.get_account()      # Account
client.get_balances()     # Balance
client.get_positions()    # list[Position]

Orders (trade scope)

client.place_order("BTC-PERP", "buy", size=100, leverage=10)                    # Order
client.place_order("ETH-PERP", "sell", type="limit", size=500, leverage=5,
                   price=4000, tp=3800, sl=4200, time_in_force="gtc")           # Order
client.get_open_orders()                                                         # list[OpenOrder]
client.get_order("order-id")                                                     # Order
client.cancel_order("order-id")                                                  # bool
client.cancel_all_orders()                                                       # int

Positions (trade scope)

client.close_position("BTC-PERP")                       # CloseResult
client.set_tp_sl("BTC-PERP", tp=70000, sl=60000)        # TpSlResult
client.update_leverage("BTC-PERP", leverage=20)         # LeverageResult
client.update_margin("BTC-PERP", amount=50)             # MarginResult

Error Handling

from liquidtrading import (
    LiquidClient,
    AuthenticationError,
    InvalidSignatureError,
    InvalidApiKeyError,
    RateLimitError,
    InsufficientBalanceError,
    InsufficientScopeError,
)

try:
    order = client.place_order("BTC-PERP", "buy", size=100, leverage=10)
except InvalidApiKeyError:
    print("API key is invalid or revoked")
except InvalidSignatureError:
    print("Check your API secret")
except InsufficientScopeError:
    print("API key needs trade permissions")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except InsufficientBalanceError:
    print("Not enough balance")
except AuthenticationError:
    print("Other auth error")

All errors inherit from LiquidError. Auth errors: AuthenticationError, InvalidApiKeyError, InvalidSignatureError, ExpiredTimestampError, ReplayedNonceError. Permission errors: ForbiddenError, IpForbiddenError, InsufficientScopeError. Others: RateLimitError, ValidationError, InsufficientBalanceError, OrderRejectedError, SymbolNotFoundError, TimeoutError, ConnectionError, ServiceUnavailableError.

Client-side validation raises ValueError before the request is sent.

Rate Limits

Tier	Requests/sec	Orders/sec
free	10	2
trader	30	10
pro	100	50

Enable retries for transient 429s (GET only, exponential backoff):

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

MCP Server

The MCP server lives in the sibling ../liquidtrading-mcp/ repo and depends on this SDK as a published package.

Requirements

Python 3.9+ · httpx >= 0.25.0