liquidtrading-python 0.1.0__tar.gz

liquidtrading_python-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env

liquidtrading_python-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

liquidtrading_python-0.1.0/.uv-cache/.gitignore

@@ -0,0 +1 @@
+*

liquidtrading_python-0.1.0/.uv-cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

liquidtrading_python-0.1.0/PKG-INFO

@@ -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/PUBLISHING.md

@@ -0,0 +1,104 @@
+# Publishing `liquidtrading-python`
+
+This package is set up to publish as:
+
+- package name: `liquidtrading-python`
+- canonical import path: `from liquidtrading import LiquidClient`
+- legacy compatibility import: `from liquid import Client`
+- console scripts: `liquidtrading-demo` (primary) and `liquid-demo` (compatibility)
+
+## One-time setup
+
+1. Create accounts on both [PyPI](https://pypi.org/) and [TestPyPI](https://test.pypi.org/).
+2. Verify the email address on both sites.
+3. Confirm that the name `liquidtrading-python` is still available on both indexes before you publish. If it is already taken, pick a different package name before going further.
+4. In GitHub, create two repository environments:
+   - `testpypi`
+   - `pypi`
+5. In TestPyPI, create a pending GitHub trusted publisher for project `liquidtrading-python` with:
+   - owner: your GitHub org or username
+   - repository: this repository
+   - workflow filename: `.github/workflows/publish-liquidtrading-python.yml`
+   - environment: `testpypi`
+6. In PyPI, create the same pending trusted publisher, but set the environment to `pypi`.
+
+Pending publishers let the first successful upload create the project. They do not reserve the name until that first publish succeeds.
+
+## Release flow
+
+### 1. Update the version
+
+Edit [pyproject.toml](/Users/raymondcosgrove/Liquid/Public%20Apis/liquidtrading-python/pyproject.toml) and bump:
+
+```toml
+version = "0.1.0"
+```
+
+### 2. Run the SDK tests
+
+From the repo root:
+
+```bash
+PYTHONPATH=. .venv/bin/python -m pytest \
+  tests/test_auth.py \
+  tests/test_client.py \
+  tests/test_demo.py \
+  tests/test_errors.py \
+  tests/test_models.py \
+  tests/test_package_exports.py -q
+```
+
+### 3. Publish to TestPyPI
+
+In GitHub Actions, run the `Publish liquidtrading-python` workflow manually. That will:
+
+- build the package from this repository
+- run import smoke tests against both the wheel and source distribution
+- publish to TestPyPI using GitHub Trusted Publishing
+
+### 4. Verify the TestPyPI package
+
+After the workflow succeeds:
+
+```bash
+python3 -m venv /tmp/liquidtrading-python-test
+source /tmp/liquidtrading-python-test/bin/activate
+python -m pip install --upgrade pip
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ liquidtrading-python
+python -c "from liquidtrading import LiquidClient; print(LiquidClient)"
+```
+
+### 5. Publish to real PyPI
+
+Create and push a tag that starts with `liquidtrading-python-v`:
+
+```bash
+git tag -a liquidtrading-python-v0.1.0 -m "liquidtrading-python v0.1.0"
+git push origin liquidtrading-python-v0.1.0
+```
+
+That tag triggers the same workflow, but publishes to PyPI instead of TestPyPI.
+
+### 6. Verify the real package
+
+```bash
+python3 -m venv /tmp/liquidtrading-python-prod
+source /tmp/liquidtrading-python-prod/bin/activate
+python -m pip install --upgrade pip
+python -m pip install liquidtrading-python
+python -c "from liquidtrading import LiquidClient; print(LiquidClient)"
+```
+
+## Fallback manual publish
+
+If you do not want to use Trusted Publishing, you can publish with an API token instead:
+
+```bash
+cd /path/to/liquidtrading-python
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine upload --repository testpypi dist/*
+python3 -m twine upload dist/*
+```
+
+Use a project-scoped API token when prompted.

liquidtrading_python-0.1.0/README.md

@@ -0,0 +1,167 @@
+# 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