silhouette-python-sdk 0.3.0__tar.gz → 0.3.2__tar.gz

{silhouette_python_sdk-0.3.0 → silhouette_python_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: silhouette-python-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Python SDK for trading on Silhouette - the shield exchange on Hyperliquid
 License: MIT
 Keywords: silhouette,trading,privacy,exchange,hyperliquid,defi,crypto,sdk
@@ -61,9 +61,9 @@ This package provides:
 pip install silhouette-python-sdk
 ```
 
-## Quick Start
+## Quick start
 
-### Using Enhanced Hyperliquid SDK
+### Using the enhanced Hyperliquid SDK
 
 ```python
 # IMPORTANT: Always import silhouette FIRST
@@ -86,7 +86,7 @@ usdc_balance = info.get_balance("0x1615330FAee0776a643CC0075AD2008418e067Db", "U
 print(f"USDC Balance: {usdc_balance}")
 ```
 
-### Using Silhouette API
+### Using the Silhouette API
 
 ```python
 from silhouette import SilhouetteApiClient
@@ -118,9 +118,9 @@ withdrawal = client.user.initiate_withdrawal("USDC", "100.0")
 print(f"Withdrawal initiated: {withdrawal['withdrawalId']}")
 ```
 
-## Enhanced Features
+## Enhanced features
 
-### Hyperliquid SDK Enhancements
+### Hyperliquid SDK enhancements
 
 The enhanced Hyperliquid SDK includes these convenience methods:
 
@@ -133,28 +133,19 @@ The enhanced Hyperliquid SDK includes these convenience methods:
 
 All other Hyperliquid SDK methods work exactly as documented in the [official Hyperliquid SDK](https://github.com/hyperliquid-dex/hyperliquid-python-sdk).
 
-### Silhouette API Client
+### Silhouette API client
 
 The `SilhouetteApiClient` provides access to the Silhouette shielded exchange:
 
 - **Dict-based API**: All methods return plain Python dicts with camelCase keys matching the API
 - **No model imports needed**: Pydantic models are used internally for validation, but you work with simple dicts
-- **User operations**: Balances, withdrawal initiation
+- **User operations**: Balances, withdrawal initiation and status polling
 - **Order management**: Create, cancel, query orders
 - **Delegated orders**: List, get, and batch retrieve delegated orders
-- **Trade execution**: Privacy-preserving order execution
+- **Market data**: Query supported tokens and trading pairs
+- **Referral management**: Register new users, set referrers, query referral details
 - **Automatic authentication**: SIWE-based session management with automatic token refresh
 
-API response structure:
-```python
-# All responses are dicts with camelCase keys
-response = client.user.get_balances()
-# {
-#   "responseMetadata": {"timestamp": 1234567890, "requestId": "..."},
-#   "balances": [{"token": "USDC", "available": "1000.0", ...}]
-# }
-```
-
 ### Delegated orders
 
 Delegated orders are orders placed on Hyperliquid by Silhouette on behalf of a trader. Query them using the `delegated_order` operations:
@@ -178,43 +169,6 @@ batch = client.delegated_order.batch_get_delegated_orders(
 print(f"Found: {len(batch['orders'])}, Not found: {batch['notFound']}")
 ```
 
-## API Design
-
-### Why Dicts Instead of Models?
-
-The SDK uses a hybrid approach for optimal developer experience:
-
-**Internal (validation)**:
-- Pydantic models auto-generated from OpenAPI spec
-- Runtime type validation of all requests and responses
-- Models stay in sync with API via regeneration
-
-**External (your code)**:
-- Plain Python dicts with camelCase keys
-- No need to import generated models
-- Simple dict access: `response["withdrawalId"]`
-- Clean, Pythonic API
-
-### Regenerating models
-
-Models are generated from the OpenAPI specifications using `datamodel-code-generator`. When the Silhouette API changes, regenerate the models to stay in sync:
-
-```bash
-# Generate from committed specs
-make generate
-
-# Or fetch fresh specs and regenerate in one step
-make regenerate
-
-# Fetch from a specific URL
-make fetch-heimdall-v0-spec URL=https://api-staging.silhouette.exchange
-make fetch-heimdall-v1-spec URL=https://api-staging.silhouette.exchange
-make generate
-
-# Run tests to catch any breaking changes
-make test
-```
-
 ## Configuration
 
 Create `examples/config.json` from the example template:
@@ -228,133 +182,13 @@ Then configure:
 - `secret_key`: Your wallet's private key (or use `keystore_path` for a keystore file)
 - `use_testnet`: Set to `true` for testnet, `false` for mainnet
 
-### [Optional] Using an API Wallet
+### [Optional] Using an API wallet
 
 Generate and authorise a new API private key on <https://app.hyperliquid.xyz/API>, and set the API wallet's private key as the `secret_key` in `examples/config.json`. Note that you must still set the public key of the main wallet (not the API wallet) as the `account_address`.
 
-## Usage Examples
-
-See [examples/](examples/) for complete examples:
-
-- **[silhouette_full_workflow.py](examples/silhouette_full_workflow.py)** - Complete workflow: deposit, trade, withdraw
-- **[basic_order.py](examples/basic_order.py)** - Place and manage orders on Hyperliquid
-- **[basic_spot_order.py](examples/basic_spot_order.py)** - Spot trading examples
-- **[basic_adding.py](examples/basic_adding.py)** - Deposit funds to Hyperliquid
-
-Run any example after configuring your credentials:
-
-```bash
-python examples/silhouette_full_workflow.py
-```
-
-## Development
-
-### Prerequisites
-
-- Python 3.10 or higher
-- [Poetry](https://python-poetry.org/) for dependency management
-
-### Setup
+## Contributing
 
-```bash
-# Install Poetry (if not already installed)
-curl -sSL https://install.python-poetry.org | python3 -
-
-# Install dependencies
-make install
-```
-
-### Development Workflow
-
-#### Code Quality and Linting
-
-This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, with pre-commit hooks for automated checks.
-
-**Normal development workflow:**
-1. Make your changes
-2. Run `git add .` to stage changes
-3. Run `git commit` - pre-commit hooks will run automatically
-
-**If pre-commit hooks fail:**
-1. `make check` - See all linting issues
-2. `make fix` - Auto-fix safe issues
-3. `make format` - Format code
-4. `make test` - Run tests
-5. Stage changes and commit again
-
-#### Available Make Commands
-
-```bash
-make build                 # Builds as a tarball and a wheel
-make check                 # Run ruff check without fixes
-make check-safety          # Run safety checks on dependencies
-make cleanup               # Cleanup project
-make fix                   # Run ruff check with fixes
-make fix-unsafe            # Run ruff check with unsafe fixes
-make format                # Run ruff format
-make install               # Install dependencies from poetry.lock
-make install-types         # Find and install additional types for mypy
-make lockfile-update       # Update poetry.lock
-make lockfile-update-full  # Fully regenerate poetry.lock
-make poetry-download       # Download and install poetry
-make pre-commit            # Run all pre-commit hooks
-make publish               # Publish the package to PyPI
-make test                  # Run tests with pytest
-make update-dev-deps       # Update development dependencies to latest versions
-```
-
-Run `make` without arguments to see this list of commands.
-
-### Running Tests
-
-```bash
-# Run all tests
-make test
-
-# Run specific test file
-poetry run pytest tests/hyperliquid/info_test.py -v
-
-# Run with coverage report
-poetry run pytest --cov=silhouette --cov-report=html
-```
-
-## Project Structure
-
-```
-silhouette-python-sdk/
-├── silhouette/
-│   ├── api/              # Silhouette API client
-│   │   ├── client.py     # Main API client (dict-based API)
-│   │   ├── auth.py       # SIWE authentication
-│   │   └── generated/    # Generated Pydantic models from OpenAPI spec
-│   │       └── models/   # Request/response models (internal use only)
-│   ├── hyperliquid/      # Enhanced Hyperliquid SDK wrappers
-│   │   ├── info.py       # Enhanced Info class
-│   │   ├── exchange.py   # Enhanced Exchange class
-│   │   └── utils/        # Re-exported utilities
-│   └── utils/
-│       └── conversions.py # Token conversion utilities
-├── tests/                # Test suite
-│   ├── api/              # API client tests
-│   ├── hyperliquid/      # Hyperliquid wrapper tests
-│   └── utils/            # Utility tests
-└── examples/             # Usage examples
-```
-
-**Note**: The `generated/models/` directory contains Pydantic models auto-generated from the OpenAPI specification. These are used internally for validation but you don't need to import them - the API client returns plain dicts.
-
-## Releases
-
-See [GitHub Releases](https://github.com/silhouette-exchange/silhouette-python-sdk/releases) for available versions.
-
-We follow [Semantic Versioning](https://semver.org/) and use [Release Drafter](https://github.com/marketplace/actions/release-drafter) for automated release notes.
-
-### Building and Releasing
-
-1. Bump version: `poetry version <major|minor|patch>`
-2. Commit changes: `git commit -am "Bump version to X.Y.Z"`
-3. Create GitHub release
-4. Publish: `make publish`
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and project structure.
 
 ## Licence
 
@@ -371,7 +205,3 @@ This project is licensed under the terms of the MIT licence. See [LICENSE](LICEN
 }
 ```
 
-## Credits
-
-This project was generated with [`python-package-template`](https://github.com/TezRomacH/python-package-template).
-

{silhouette_python_sdk-0.3.0 → silhouette_python_sdk-0.3.2}/README.md

@@ -29,9 +29,9 @@ This package provides:
 pip install silhouette-python-sdk
 ```
 
-## Quick Start
+## Quick start
 
-### Using Enhanced Hyperliquid SDK
+### Using the enhanced Hyperliquid SDK
 
 ```python
 # IMPORTANT: Always import silhouette FIRST
@@ -54,7 +54,7 @@ usdc_balance = info.get_balance("0x1615330FAee0776a643CC0075AD2008418e067Db", "U
 print(f"USDC Balance: {usdc_balance}")
 ```
 
-### Using Silhouette API
+### Using the Silhouette API
 
 ```python
 from silhouette import SilhouetteApiClient
@@ -86,9 +86,9 @@ withdrawal = client.user.initiate_withdrawal("USDC", "100.0")
 print(f"Withdrawal initiated: {withdrawal['withdrawalId']}")
 ```
 
-## Enhanced Features
+## Enhanced features
 
-### Hyperliquid SDK Enhancements
+### Hyperliquid SDK enhancements
 
 The enhanced Hyperliquid SDK includes these convenience methods:
 
@@ -101,28 +101,19 @@ The enhanced Hyperliquid SDK includes these convenience methods:
 
 All other Hyperliquid SDK methods work exactly as documented in the [official Hyperliquid SDK](https://github.com/hyperliquid-dex/hyperliquid-python-sdk).
 
-### Silhouette API Client
+### Silhouette API client
 
 The `SilhouetteApiClient` provides access to the Silhouette shielded exchange:
 
 - **Dict-based API**: All methods return plain Python dicts with camelCase keys matching the API
 - **No model imports needed**: Pydantic models are used internally for validation, but you work with simple dicts
-- **User operations**: Balances, withdrawal initiation
+- **User operations**: Balances, withdrawal initiation and status polling
 - **Order management**: Create, cancel, query orders
 - **Delegated orders**: List, get, and batch retrieve delegated orders
-- **Trade execution**: Privacy-preserving order execution
+- **Market data**: Query supported tokens and trading pairs
+- **Referral management**: Register new users, set referrers, query referral details
 - **Automatic authentication**: SIWE-based session management with automatic token refresh
 
-API response structure:
-```python
-# All responses are dicts with camelCase keys
-response = client.user.get_balances()
-# {
-#   "responseMetadata": {"timestamp": 1234567890, "requestId": "..."},
-#   "balances": [{"token": "USDC", "available": "1000.0", ...}]
-# }
-```
-
 ### Delegated orders
 
 Delegated orders are orders placed on Hyperliquid by Silhouette on behalf of a trader. Query them using the `delegated_order` operations:
@@ -146,43 +137,6 @@ batch = client.delegated_order.batch_get_delegated_orders(
 print(f"Found: {len(batch['orders'])}, Not found: {batch['notFound']}")
 ```
 
-## API Design
-
-### Why Dicts Instead of Models?
-
-The SDK uses a hybrid approach for optimal developer experience:
-
-**Internal (validation)**:
-- Pydantic models auto-generated from OpenAPI spec
-- Runtime type validation of all requests and responses
-- Models stay in sync with API via regeneration
-
-**External (your code)**:
-- Plain Python dicts with camelCase keys
-- No need to import generated models
-- Simple dict access: `response["withdrawalId"]`
-- Clean, Pythonic API
-
-### Regenerating models
-
-Models are generated from the OpenAPI specifications using `datamodel-code-generator`. When the Silhouette API changes, regenerate the models to stay in sync:
-
-```bash
-# Generate from committed specs
-make generate
-
-# Or fetch fresh specs and regenerate in one step
-make regenerate
-
-# Fetch from a specific URL
-make fetch-heimdall-v0-spec URL=https://api-staging.silhouette.exchange
-make fetch-heimdall-v1-spec URL=https://api-staging.silhouette.exchange
-make generate
-
-# Run tests to catch any breaking changes
-make test
-```
-
 ## Configuration
 
 Create `examples/config.json` from the example template:
@@ -196,133 +150,13 @@ Then configure:
 - `secret_key`: Your wallet's private key (or use `keystore_path` for a keystore file)
 - `use_testnet`: Set to `true` for testnet, `false` for mainnet
 
-### [Optional] Using an API Wallet
+### [Optional] Using an API wallet
 
 Generate and authorise a new API private key on <https://app.hyperliquid.xyz/API>, and set the API wallet's private key as the `secret_key` in `examples/config.json`. Note that you must still set the public key of the main wallet (not the API wallet) as the `account_address`.
 
-## Usage Examples
-
-See [examples/](examples/) for complete examples:
-
-- **[silhouette_full_workflow.py](examples/silhouette_full_workflow.py)** - Complete workflow: deposit, trade, withdraw
-- **[basic_order.py](examples/basic_order.py)** - Place and manage orders on Hyperliquid
-- **[basic_spot_order.py](examples/basic_spot_order.py)** - Spot trading examples
-- **[basic_adding.py](examples/basic_adding.py)** - Deposit funds to Hyperliquid
-
-Run any example after configuring your credentials:
-
-```bash
-python examples/silhouette_full_workflow.py
-```
-
-## Development
-
-### Prerequisites
-
-- Python 3.10 or higher
-- [Poetry](https://python-poetry.org/) for dependency management
-
-### Setup
+## Contributing
 
-```bash
-# Install Poetry (if not already installed)
-curl -sSL https://install.python-poetry.org | python3 -
-
-# Install dependencies
-make install
-```
-
-### Development Workflow
-
-#### Code Quality and Linting
-
-This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, with pre-commit hooks for automated checks.
-
-**Normal development workflow:**
-1. Make your changes
-2. Run `git add .` to stage changes
-3. Run `git commit` - pre-commit hooks will run automatically
-
-**If pre-commit hooks fail:**
-1. `make check` - See all linting issues
-2. `make fix` - Auto-fix safe issues
-3. `make format` - Format code
-4. `make test` - Run tests
-5. Stage changes and commit again
-
-#### Available Make Commands
-
-```bash
-make build                 # Builds as a tarball and a wheel
-make check                 # Run ruff check without fixes
-make check-safety          # Run safety checks on dependencies
-make cleanup               # Cleanup project
-make fix                   # Run ruff check with fixes
-make fix-unsafe            # Run ruff check with unsafe fixes
-make format                # Run ruff format
-make install               # Install dependencies from poetry.lock
-make install-types         # Find and install additional types for mypy
-make lockfile-update       # Update poetry.lock
-make lockfile-update-full  # Fully regenerate poetry.lock
-make poetry-download       # Download and install poetry
-make pre-commit            # Run all pre-commit hooks
-make publish               # Publish the package to PyPI
-make test                  # Run tests with pytest
-make update-dev-deps       # Update development dependencies to latest versions
-```
-
-Run `make` without arguments to see this list of commands.
-
-### Running Tests
-
-```bash
-# Run all tests
-make test
-
-# Run specific test file
-poetry run pytest tests/hyperliquid/info_test.py -v
-
-# Run with coverage report
-poetry run pytest --cov=silhouette --cov-report=html
-```
-
-## Project Structure
-
-```
-silhouette-python-sdk/
-├── silhouette/
-│   ├── api/              # Silhouette API client
-│   │   ├── client.py     # Main API client (dict-based API)
-│   │   ├── auth.py       # SIWE authentication
-│   │   └── generated/    # Generated Pydantic models from OpenAPI spec
-│   │       └── models/   # Request/response models (internal use only)
-│   ├── hyperliquid/      # Enhanced Hyperliquid SDK wrappers
-│   │   ├── info.py       # Enhanced Info class
-│   │   ├── exchange.py   # Enhanced Exchange class
-│   │   └── utils/        # Re-exported utilities
-│   └── utils/
-│       └── conversions.py # Token conversion utilities
-├── tests/                # Test suite
-│   ├── api/              # API client tests
-│   ├── hyperliquid/      # Hyperliquid wrapper tests
-│   └── utils/            # Utility tests
-└── examples/             # Usage examples
-```
-
-**Note**: The `generated/models/` directory contains Pydantic models auto-generated from the OpenAPI specification. These are used internally for validation but you don't need to import them - the API client returns plain dicts.
-
-## Releases
-
-See [GitHub Releases](https://github.com/silhouette-exchange/silhouette-python-sdk/releases) for available versions.
-
-We follow [Semantic Versioning](https://semver.org/) and use [Release Drafter](https://github.com/marketplace/actions/release-drafter) for automated release notes.
-
-### Building and Releasing
-
-1. Bump version: `poetry version <major|minor|patch>`
-2. Commit changes: `git commit -am "Bump version to X.Y.Z"`
-3. Create GitHub release
-4. Publish: `make publish`
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and project structure.
 
 ## Licence
 
@@ -338,7 +172,3 @@ This project is licensed under the terms of the MIT licence. See [LICENSE](LICEN
   howpublished = {\url{https://github.com/silhouette-exchange/silhouette-python-sdk}}
 }
 ```
-
-## Credits
-
-This project was generated with [`python-package-template`](https://github.com/TezRomacH/python-package-template).

{silhouette_python_sdk-0.3.0 → silhouette_python_sdk-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "silhouette-python-sdk"
-version = "0.3.0"
+version = "0.3.2"
 description = "Python SDK for trading on Silhouette - the shield exchange on Hyperliquid"
 readme = "README.md"
 license = "MIT"
@@ -43,6 +43,12 @@ Repository = "https://github.com/silhouette-exchange/silhouette-python-sdk"
 packages = [
   { include = "silhouette" },
 ]
+exclude = [
+  "examples/",
+  "docs/",
+  "AGENTS.md",
+  "CONTRIBUTING.md",
+]
 include = [
   "silhouette/py.typed",
   { path = "silhouette/api/generated/__init__.py", format = ["sdist", "wheel"] },
@@ -55,12 +61,12 @@ pytest = "^8.4"
 mypy = "^1.18"
 ruff = "^0.13"
 pre-commit = "^4.3"
-safety = "^3.6"
 coverage = "^7.10"
 pytest-cov = "^7"
 pytest-socket = "^0.7.0"
 types-requests = "^2.31"
 datamodel-code-generator = {version = "^0.29", extras = ["http"]}
+pip-audit = "^2.10.0"
 
 [tool.ruff]
 target-version = "py310"

silhouette_python_sdk-0.3.0/silhouette/twap/USAGE_GUIDE.md

@@ -1,445 +0,0 @@
-# Silhouette TWAP Platform - Usage Guide
-
-## Table of Contents
-
-1. [Platform Overview](#platform-overview)
-2. [Getting Started](#getting-started)
-3. [Platform Features](#platform-features)
-4. [Common Use Cases](#common-use-cases)
-5. [How the Platform Works](#how-the-platform-works)
-6. [Key Handling and Authentication](#key-handling-and-authentication)
-
----
-
-## Platform Overview
-
-Silhouette TWAP (Time-Weighted Average Price) is an algorithmic trading platform designed to execute large trading orders on the Hyperliquid exchange over extended time periods. The platform intelligently splits large orders into smaller, randomized lots distributed across time to minimize market impact while ensuring reliable execution.
-
-### Key Benefits
-
-- **Minimized Market Impact**: Large orders are broken down into smaller pieces spread over time
-- **Anti-Detection**: Randomized timing and sizing prevent pattern recognition
-- **Automated Execution**: Hands-off execution once an order is placed
-- **Price Protection**: Configurable price bounds prevent unwanted executions
-- **Secure**: API keys encrypted at rest, only decrypted during execution
-
----
-
-## Getting Started
-
-### Prerequisites
-
-1. **Hyperliquid Account**
-   - Create an account on Hyperliquid
-   - Generate an API key
-   - Register the API key as an "agent" for your wallet
-
-2. **Python SDK**
-   - Install the Silhouette Python SDK
-
-### Installation
-
-```bash
-pip install silhouette-sdk
-```
-
-### Basic Usage
-
-The `AuthenticatedTwapClient` handles all authentication automatically - no manual setup required:
-
-```python
-from silhouette.twap.authenticated_client import AuthenticatedTwapClient
-from datetime import datetime, timedelta
-import time
-
-# Initialize the client (registration happens automatically)
-client = AuthenticatedTwapClient(
-    base_url="https://scheduler.silhouette.com",
-    private_key="0x...",  # Your Ethereum private key (for SIWE signing, never sent to server)
-)
-
-# Create a TWAP order
-start_time = datetime.now()
-end_time = start_time + timedelta(hours=2)
-
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "1.0",                  # Total amount to execute
-    "lots": 10,                       # Number of sub-orders
-    "order_side": "buy",              # "buy" or "sell"
-    "market_type": "spot",            # "spot" or "perp"
-    "start_time": int(start_time.timestamp()),
-    "end_time": int(end_time.timestamp()),
-    "price_upper_bound": "50000",     # Optional: max price
-    "price_lower_bound": "45000",     # Optional: min price
-    "slippage": "0.001"               # Optional: slippage tolerance (default 0.001)
-})
-
-print(f"Order created: {order['id']}")
-print(f"Status: {order['status']}")
-
-# Monitor order status
-order_data = order
-while order_data['status'] == "active":
-    time.sleep(60)  # Check every minute
-    order_data = client.get_order(order['id'])
-    print(f"Progress: {order_data['executedAmount']} / {order_data['totalAmount']}")
-```
-
-### Available Methods
-
-```python
-# Create a TWAP order
-order = client.create_twap_order(order_data)
-
-# Get order details
-order = client.get_order(order_id)
-
-# Cancel an order
-result = client.cancel_order(order_id)
-
-# Pause an active order
-result = client.pause_order(order_id)
-
-# Resume a paused order
-result = client.resume_order(order_id)
-
-# Get all orders for your wallet
-orders = client.get_orders_by_user()
-
-# Get your wallet address
-wallet_address = client.get_wallet_address()
-
-# Check if client is ready
-is_ready = client.is_ready()
-```
-
----
-
-## Platform Features
-
-### TWAP Order Execution
-
-Execute large orders over time with intelligent splitting and randomization.
-
-**Required Parameters:**
-- `asset_id`: Trading pair (e.g., "BTC", "ETH")
-- `amount`: Total quantity to execute (as string)
-- `lots`: Number of sub-orders to split into
-- `order_side`: "buy" or "sell"
-- `market_type`: "spot" or "perp"
-- `start_time`: Unix timestamp (seconds)
-- `end_time`: Unix timestamp (seconds)
-
-**Optional Parameters:**
-- `price_upper_bound`: Maximum price for buys (string)
-- `price_lower_bound`: Minimum price for buys (string)
-- `slippage`: Slippage tolerance (default "0.001", i.e., 0.1%)
-- `order_intent`: Required for perp orders - "open" or "close"
-
-### Price Bounds Protection
-
-Protect your orders with upper and/or lower price limits.
-
-```python
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "10.0",
-    "lots": 20,
-    "order_side": "buy",
-    "market_type": "spot",
-    "start_time": int(start_time.timestamp()),
-    "end_time": int(end_time.timestamp()),
-    "price_upper_bound": "52000",  # Don't buy above $52,000
-    "price_lower_bound": "48000"   # Don't buy below $48,000
-})
-```
-
-- Price bounds are validated before each lot execution
-- Orders automatically pause if bounds are breached
-- Orders resume when price returns to acceptable range
-
-### Randomized Execution
-
-The platform automatically randomizes:
-- **Timing**: ±20% variance in execution intervals
-- **Size**: ±15% variance in individual lot sizes
-
-This prevents market makers from detecting your order patterns.
-
-### Perpetual Futures Support
-
-For perpetual futures orders, you must specify `order_intent`:
-
-```python
-# Open a new position
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "10.0",
-    "lots": 15,
-    "order_side": "buy",
-    "market_type": "perp",
-    "order_intent": "open",  # Required for perp: "open" or "close"
-    "start_time": int(start_time.timestamp()),
-    "end_time": int(end_time.timestamp())
-})
-```
-
-### Order Management
-
-**Order States:**
-- `pending`: Order created, waiting to start
-- `active`: Order executing lots over time
-- `paused`: Price bounds breached or manually paused
-- `completed`: All lots executed successfully
-- `cancelled`: Order cancelled by user
-- `failed`: Critical error occurred
-
-**Monitoring:**
-```python
-# Get order status
-order = client.get_order(order_id)
-print(f"Status: {order['status']}")
-print(f"Executed: {order['executedAmount']} / {order['totalAmount']}")
-
-# List all your orders
-orders = client.get_orders_by_user()
-```
-
----
-
-## Common Use Cases
-
-### Use Case 1: Large Order Execution
-
-Execute a large order without moving the market.
-
-```python
-from silhouette.twap.authenticated_client import AuthenticatedTwapClient
-from datetime import datetime, timedelta
-
-client = AuthenticatedTwapClient(
-    base_url="https://scheduler.silhouette.com",
-    private_key="0x...",
-)
-
-start = datetime.now()
-end = start + timedelta(hours=6)
-
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "100.0",
-    "lots": 50,  # ~2 BTC per lot
-    "order_side": "buy",
-    "market_type": "spot",
-    "start_time": int(start.timestamp()),
-    "end_time": int(end.timestamp()),
-    "price_upper_bound": "52000"
-})
-```
-
-### Use Case 2: Dollar Cost Averaging (DCA)
-
-Accumulate an asset over time with price protection.
-
-```python
-start = datetime.now()
-end = start + timedelta(hours=24)
-
-order = client.create_twap_order({
-    "asset_id": "ETH",
-    "amount": "50.0",
-    "lots": 20,  # 20 purchases over 24 hours
-    "order_side": "buy",
-    "market_type": "spot",
-    "start_time": int(start.timestamp()),
-    "end_time": int(end.timestamp()),
-    "price_upper_bound": "3000",
-    "price_lower_bound": "2500"
-})
-```
-
-### Use Case 3: Exit Strategy
-
-Sell a large position gradually to minimize impact.
-
-```python
-start = datetime.now()
-end = start + timedelta(hours=4)
-
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "50.0",
-    "lots": 30,
-    "order_side": "sell",
-    "market_type": "spot",
-    "start_time": int(start.timestamp()),
-    "end_time": int(end.timestamp()),
-    "price_lower_bound": "48000"  # Don't sell below $48k
-})
-```
-
-### Use Case 4: Perpetual Position Entry
-
-Open a large perpetual position gradually.
-
-```python
-start = datetime.now()
-end = start + timedelta(hours=3)
-
-order = client.create_twap_order({
-    "asset_id": "BTC",
-    "amount": "25.0",
-    "lots": 15,
-    "order_side": "buy",
-    "market_type": "perp",
-    "order_intent": "open",
-    "start_time": int(start.timestamp()),
-    "end_time": int(end.timestamp()),
-    "price_upper_bound": "51000"
-})
-```
-
----
-
-## How the Platform Works
-
-### Architecture Overview
-
-The Silhouette TWAP platform uses a **split services architecture**:
-
-1. **Scheduler Service (TypeScript/NestJS)**
-   - Handles order planning and TWAP computation
-   - Manages user authentication
-   - Splits orders into randomized lots
-   - Creates execution tasks
-
-2. **Executor Service (Python/FastAPI)**
-   - Consumes tasks from the queue
-   - Validates price bounds before execution
-   - Executes trades on Hyperliquid
-   - Reports results back
-
-Both services communicate through **Upstash Redis** for task queuing and state storage.
-
-### Order Execution Flow
-
-```
-User → Scheduler → Redis → Executor → Hyperliquid
-```
-
-1. User creates a TWAP order via the SDK
-2. Scheduler validates the order and computes execution plan
-3. Scheduler creates execution tasks with randomized timing
-4. Tasks are queued in Redis
-5. Executor consumes tasks at scheduled times
-6. Executor validates price bounds and executes trades
-7. Results are reported back and stored
-
-### TWAP Algorithm
-
-When you create a TWAP order:
-
-1. **Order Splitting**: Total amount divided into multiple lots
-   - ±15% size variation per lot to avoid patterns
-   - Example: 10 BTC / 20 lots → ~0.43-0.57 BTC per lot
-
-2. **Time Distribution**: Executions spread across duration
-   - ±20% timing variance in execution intervals
-   - Example: 2-hour order → executions at 4.8min, 12.2min, 17.4min
-
-3. **Price Validation**: Price bounds checked before each execution
-   - Real-time market price validation
-   - Order pauses if bounds are breached
-
-4. **Execution Tracking**: Each lot execution is tracked individually
-   - Complete audit trail
-   - Status updates in real-time
-
----
-
-## Key Handling and Authentication
-
-### Authentication Process
-
-The `AuthenticatedTwapClient` handles all authentication automatically:
-
-```python
-client = AuthenticatedTwapClient(
-    base_url="https://scheduler.silhouette.com",
-    private_key="0x...",
-)
-```
-
-**What happens during initialization:**
-
-1. Health check - Verifies scheduler service is available
-2. Registration check - Checks if your wallet is registered
-3. Auto-registration - Registers your API key if needed
-4. JWT generation - Creates authentication token
-5. Ready to use - Client is immediately available
-
-**Automatic token refresh:**
-- If a request receives 401 (Unauthorized), the client automatically refreshes the token
-- The failed request is automatically retried
-- All happens transparently
-
-### Security Architecture
-
-**Key Components:**
-
-1. **Hyperliquid API Key**
-   - Used for authentication and trade execution
-   - Must be registered as an "agent" for your wallet
-   - Cannot withdraw funds
-   - Sent over the wire only once during registration
-   - Encrypted at rest in storage
-   - Only decrypted at lot execution time by the executor service
-
-2. **JWT Tokens**
-   - Client-signed using your Hyperliquid API key
-   - Algorithm: ES256K (ECDSA with secp256k1)
-   - Short-lived (1 hour max)
-   - Automatically refreshed
-
-### Key Rotation
-
-To rotate your API key, simply create a new client instance:
-
-```python
-client = AuthenticatedTwapClient(
-    base_url="https://scheduler.silhouette.com",
-    private_key="0x...",  # Your Ethereum private key
-)
-```
-
-The client automatically detects registration and updates your key.
-
-### Security Best Practices
-
-1. **Keep API Keys Secure**
-   - Store in environment variables or secrets manager
-   - Never commit to version control
-   - Use different keys for testnet and mainnet
-
-2. **Key Permissions**
-   - Silhouette only uses your API key for signing trades
-   - Cannot withdraw funds or access other operations
-   - Revoke immediately if compromised
-
-3. **System Protections**
-   - Anti-enumeration protection prevents key discovery
-   - Constant-time validation operations
-   - Generic error messages for security
-
----
-
-## Additional Resources
-
-You can interact with the scheduler server directly via API. The OpenAPI-compliant API documentation and architecture breakdown can be found at:
-
-**https://silhouette-scheduler.fly.dev**
-
----
-
-*Last Updated: 2025*