liquidtrading-python 0.1.0__py3-none-any.whl

liquidtrading/models.py

@@ -0,0 +1,296 @@
+"""Frozen dataclasses matching server response shapes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _to_float(value: object) -> float:
+    return float(value)
+
+
+def _to_float_or_none(value: object) -> float | None:
+    return float(value) if value is not None else None
+
+
+@dataclass(frozen=True)
+class Market:
+    symbol: str
+    ticker: str
+    exchange: str
+    max_leverage: int | None
+    sz_decimals: int | None
+
+
+@dataclass(frozen=True)
+class Ticker:
+    symbol: str
+    mark_price: float
+    volume_24h: float | None
+    change_24h: float | None
+    funding_rate: float | None
+
+
+@dataclass(frozen=True)
+class OrderbookLevel:
+    price: float
+    size: float
+    count: int
+
+
+@dataclass(frozen=True)
+class Orderbook:
+    symbol: str
+    bids: tuple[OrderbookLevel, ...]
+    asks: tuple[OrderbookLevel, ...]
+    timestamp: int | None
+
+
+@dataclass(frozen=True)
+class Candle:
+    timestamp: int
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+
+
+@dataclass(frozen=True)
+class Account:
+    equity: float
+    margin_used: float
+    available_balance: float
+    account_value: float
+
+
+@dataclass(frozen=True)
+class Position:
+    symbol: str
+    side: str
+    size: float
+    entry_price: float
+    leverage: float
+    unrealized_pnl: float
+    mark_price: float | None
+    liquidation_price: float | None
+    margin_used: float | None
+
+
+@dataclass(frozen=True)
+class Order:
+    order_id: str | None
+    symbol: str
+    side: str
+    type: str
+    size: float
+    price: float | None
+    leverage: int
+    status: str
+    exchange: str
+    tp: float | None
+    sl: float | None
+    reduce_only: bool
+    created_at: str | None
+
+
+@dataclass(frozen=True)
+class OpenOrder:
+    order_id: str
+    symbol: str
+    side: str
+    size: float
+    price: float
+    timestamp: int
+
+
+@dataclass(frozen=True)
+class CloseResult:
+    symbol: str
+    status: str
+    message: str
+
+
+@dataclass(frozen=True)
+class TpSlResult:
+    tp: dict[str, Any] | None
+    sl: dict[str, Any] | None
+
+
+@dataclass(frozen=True)
+class MarginResult:
+    symbol: str
+    margin_adjusted: float
+
+
+@dataclass(frozen=True)
+class LeverageResult:
+    symbol: str
+    leverage: int
+    is_cross: bool
+
+
+@dataclass(frozen=True)
+class CrossMargin:
+    account_value: float
+    total_margin_used: float
+    total_ntl_pos: float
+
+
+@dataclass(frozen=True)
+class Balance:
+    exchange: str
+    equity: float
+    available_balance: float
+    margin_used: float
+    cross_margin: CrossMargin | None
+
+
+# --- Factory functions ---
+
+
+def _market_from_dict(d: dict[str, Any]) -> Market:
+    return Market(
+        symbol=d["symbol"],
+        ticker=d["ticker"],
+        exchange=d["exchange"],
+        max_leverage=d.get("max_leverage"),
+        sz_decimals=d.get("sz_decimals"),
+    )
+
+
+def _ticker_from_dict(d: dict[str, Any]) -> Ticker:
+    return Ticker(
+        symbol=d["symbol"],
+        mark_price=_to_float(d["mark_price"]),
+        volume_24h=_to_float_or_none(d.get("volume_24h")),
+        change_24h=_to_float_or_none(d.get("change_24h")),
+        funding_rate=_to_float_or_none(d.get("funding_rate")),
+    )
+
+
+def _orderbook_level_from_dict(d: dict[str, Any]) -> OrderbookLevel:
+    return OrderbookLevel(
+        price=_to_float(d["price"]),
+        size=_to_float(d["size"]),
+        count=d.get("count", 1),
+    )
+
+
+def _orderbook_from_dict(d: dict[str, Any]) -> Orderbook:
+    return Orderbook(
+        symbol=d["symbol"],
+        bids=tuple(_orderbook_level_from_dict(b) for b in d["bids"]),
+        asks=tuple(_orderbook_level_from_dict(a) for a in d["asks"]),
+        timestamp=d.get("timestamp"),
+    )
+
+
+def _candle_from_dict(d: dict[str, Any]) -> Candle:
+    return Candle(
+        timestamp=d["timestamp"],
+        open=_to_float(d["open"]),
+        high=_to_float(d["high"]),
+        low=_to_float(d["low"]),
+        close=_to_float(d["close"]),
+        volume=_to_float(d["volume"]),
+    )
+
+
+def _account_from_dict(d: dict[str, Any]) -> Account:
+    return Account(
+        equity=_to_float(d["equity"]),
+        margin_used=_to_float(d["margin_used"]),
+        available_balance=_to_float(d["available_balance"]),
+        account_value=_to_float(d["account_value"]),
+    )
+
+
+def _position_from_dict(d: dict[str, Any]) -> Position:
+    return Position(
+        symbol=d["symbol"],
+        side=d["side"],
+        size=_to_float(d["size"]),
+        entry_price=_to_float(d["entry_price"]),
+        leverage=_to_float(d["leverage"]),
+        unrealized_pnl=_to_float(d["unrealized_pnl"]),
+        mark_price=_to_float_or_none(d.get("mark_price")),
+        liquidation_price=_to_float_or_none(d.get("liquidation_price")),
+        margin_used=_to_float_or_none(d.get("margin_used")),
+    )
+
+
+def _order_from_dict(d: dict[str, Any]) -> Order:
+    return Order(
+        order_id=d.get("order_id"),
+        symbol=d["symbol"],
+        side=d["side"],
+        type=d.get("type", "unknown"),
+        size=d.get("size", 0.0),
+        price=d.get("price"),
+        leverage=d.get("leverage", 1),
+        status=d.get("status", "unknown"),
+        exchange=d.get("exchange", "hyperliquid"),
+        tp=d.get("tp"),
+        sl=d.get("sl"),
+        reduce_only=d.get("reduce_only", False),
+        created_at=d.get("created_at"),
+    )
+
+
+def _open_order_from_dict(d: dict[str, Any]) -> OpenOrder:
+    return OpenOrder(
+        order_id=d["order_id"],
+        symbol=d["symbol"],
+        side=d["side"],
+        size=_to_float(d["size"]),
+        price=_to_float(d["price"]),
+        timestamp=d["timestamp"],
+    )
+
+
+def _close_result_from_dict(d: dict[str, Any]) -> CloseResult:
+    return CloseResult(
+        symbol=d["symbol"],
+        status=d["status"],
+        message=d["message"],
+    )
+
+
+def _tp_sl_result_from_dict(d: dict[str, Any]) -> TpSlResult:
+    return TpSlResult(tp=d.get("tp"), sl=d.get("sl"))
+
+
+def _margin_result_from_dict(d: dict[str, Any]) -> MarginResult:
+    return MarginResult(
+        symbol=d["symbol"],
+        margin_adjusted=d["margin_adjusted"],
+    )
+
+
+def _leverage_result_from_dict(d: dict[str, Any]) -> LeverageResult:
+    return LeverageResult(
+        symbol=d["symbol"],
+        leverage=d["leverage"],
+        is_cross=d["is_cross"],
+    )
+
+
+def _cross_margin_from_dict(d: dict[str, Any]) -> CrossMargin:
+    return CrossMargin(
+        account_value=_to_float(d["account_value"]),
+        total_margin_used=_to_float(d["total_margin_used"]),
+        total_ntl_pos=_to_float(d["total_ntl_pos"]),
+    )
+
+
+def _balance_from_dict(d: dict[str, Any]) -> Balance:
+    cm = d.get("cross_margin")
+    return Balance(
+        exchange=d["exchange"],
+        equity=_to_float(d["equity"]),
+        available_balance=_to_float(d["available_balance"]),
+        margin_used=_to_float(d["margin_used"]),
+        cross_margin=_cross_margin_from_dict(cm) if isinstance(cm, dict) else None,
+    )

liquidtrading_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: liquidtrading-python
+Version: 0.1.0
+Summary: Python SDK for the Liquid trading API
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# liquidtrading-python
+
+Official Python SDK for the Liquid trading API.
+
+## Installation
+
+```bash
+pip install liquidtrading-python
+```
+
+```bash
+uv add liquidtrading-python
+```
+
+## Quick Start
+
+```python
+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:
+
+```python
+from liquid import Client
+```
+
+## Authentication
+
+```python
+client = LiquidClient(api_key="lq_...", api_secret="sk_...")
+```
+
+Hosted Liquid API requests currently require credentials:
+
+```python
+client = LiquidClient(api_key="lq_...", api_secret="sk_...")
+markets = client.get_markets()
+```
+
+Quick connectivity check after install:
+
+```bash
+liquidtrading-demo --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...
+```
+
+If you also want to query open orders:
+
+```bash
+liquidtrading-demo --base-url http://localhost:8001 --api-key lq_... --api-secret sk_... --include-open-orders
+```
+
+Easiest local repo smoke test:
+
+```bash
+bash scripts/run_smoke_demo.sh --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...
+```
+
+Alternative local repo smoke test:
+
+```bash
+uv run python examples/smoke_demo.py --base-url http://localhost:8001 --api-key lq_... --api-secret sk_...
+```
+
+Publishing guide:
+
+```text
+See PUBLISHING.md
+```
+
+## Methods
+
+### Market Data (public)
+
+```python
+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)
+
+```python
+client.get_account()      # Account
+client.get_balances()     # Balance
+client.get_positions()    # list[Position]
+```
+
+### Orders (trade scope)
+
+```python
+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)
+
+```python
+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
+
+```python
+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):
+
+```python
+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

liquidtrading_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+liquid/__init__.py,sha256=VrOpzbJXU4xLhMFb5oZEOhWf_3mimkNl0pgVlOXvPxU,759
+liquidtrading/__init__.py,sha256=eshLeLSS6b_8uDR25zGm5FzAydzX5ickmyMR1AG7E_I,1879
+liquidtrading/auth.py,sha256=c8gAJzk7_XtcJu4-KbKh9J8MG9slfKcbB74PGpwE1sc,5230
+liquidtrading/client.py,sha256=Lz4R4IWKolKC3eX0JpbqgeVS-xxymXQMIT8XpJZ0aAM,15422
+liquidtrading/constants.py,sha256=7se1j7GeR9x-okSbOaX3a3TOEWTZQ9C9-GH1TjuGs2o,437
+liquidtrading/demo.py,sha256=9aCyF6JiW00GrutKMdSfKwFwCfjq52wbSX-qpWkGA1Y,2617
+liquidtrading/errors.py,sha256=AxzklcSbtW1vftI-cOWs-iCd3PKZ7tnD4rzAtfM6mAk,5867
+liquidtrading/http.py,sha256=Dl7UrdQuUI1hF2XDxKi-hSre8rLWLf7VpYySEe0ehwQ,7732
+liquidtrading/models.py,sha256=HRLllqMDxRtOrKQzfPtq7Oj4AcqlfgcDWbhYcMjZV7s,6869
+liquidtrading_python-0.1.0.dist-info/METADATA,sha256=TVo4hsZncLFLcg-IBVwoX1GUmEss5DKV03nKHy7y9X0,4997
+liquidtrading_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+liquidtrading_python-0.1.0.dist-info/entry_points.txt,sha256=QUYkeYHRfA5rnyEwIXWA1wkd_abBBNyFTfP3gDlb7sQ,101
+liquidtrading_python-0.1.0.dist-info/RECORD,,

liquidtrading_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

liquidtrading_python-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+liquid-demo = liquidtrading.demo:main
+liquidtrading-demo = liquidtrading.demo:main