Metadata-Version: 2.4
Name: liquidtrading-python
Version: 0.1.1
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 (read scope)

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