Metadata-Version: 2.3
Name: silhouette-python-sdk
Version: 0.3.3
Summary: Python SDK for trading on Silhouette - the shield exchange on Hyperliquid
License: MIT
Keywords: silhouette,trading,privacy,exchange,hyperliquid,defi,crypto,sdk
Author: Silhouette
Author-email: aidan@silhouette.exchange
Requires-Python: >=3.10,<4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: cryptography (>=46,<47)
Requires-Dist: httpx (>=0.23,<0.29)
Requires-Dist: hyperliquid-python-sdk (>=0.21,<1)
Requires-Dist: pydantic (>=2.0,<3)
Requires-Dist: pyjwt (>=2.10,<3)
Requires-Dist: requests (>=2.32,<3)
Requires-Dist: siwe (>=4.4,<5)
Requires-Dist: typing_extensions (>=4.9) ; python_version < "3.11"
Requires-Dist: websockets (>=15,<16)
Project-URL: Homepage, https://github.com/silhouette-exchange/silhouette-python-sdk
Project-URL: Repository, https://github.com/silhouette-exchange/silhouette-python-sdk
Description-Content-Type: text/markdown

# silhouette-python-sdk

<div align="center">

[![Dependencies Status](https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen.svg)](https://github.com/silhouette-exchange/silhouette-python-sdk/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/silhouette-exchange/silhouette-python-sdk/blob/main/.pre-commit-config.yaml)
[![Semantic Versions](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versions-e10079.svg)](https://github.com/silhouette-exchange/silhouette-python-sdk/releases)
[![License](https://img.shields.io/pypi/l/silhouette-python-sdk)](https://github.com/silhouette-exchange/silhouette-python-sdk/blob/main/LICENSE.md)

Python SDK for trading on Silhouette - the shielded exchange on Hyperliquid.

</div>

## Overview

This package provides:
- **Drop-in replacement** for the official Hyperliquid Python SDK with enhanced convenience methods
- **Silhouette API integration** for trading on the shielded exchange
- **Type-safe** interfaces with Pydantic models generated from OpenAPI specifications
- **Clean dict-based API** for easy usage without model imports
- **Enhanced functionality** including balance checking, deposit automation, and withdrawal polling

**IMPORTANT**: This package replaces `hyperliquid-python-sdk`. Do not install both packages together. The official Hyperliquid SDK is included as a dependency.

## Installation

```bash
pip install silhouette-python-sdk
```

## Quick start

### Using the enhanced Hyperliquid SDK

```python
# IMPORTANT: Always import silhouette FIRST
import silhouette

# Then use standard hyperliquid imports to get enhanced versions
from hyperliquid.info import Info
from hyperliquid.exchange import Exchange
from hyperliquid.utils.constants import TESTNET_API_URL

# Enhanced Info client with get_balance() and await_withdrawal_completion()
info = Info(base_url=TESTNET_API_URL, skip_ws=True)

# Check spot balances
spot_state = info.spot_user_state("0x1615330FAee0776a643CC0075AD2008418e067Db")
print(spot_state)

# Get specific token balance (convenience method)
usdc_balance = info.get_balance("0x1615330FAee0776a643CC0075AD2008418e067Db", "USDC")
print(f"USDC Balance: {usdc_balance}")
```

### Using the Silhouette API

```python
from silhouette import SilhouetteApiClient

# Initialize client with auto-authentication
client = SilhouetteApiClient(
    base_url="https://api.silhouette.exchange",
    private_key="your_private_key_here",
    auto_auth=True,
)

# Check balances (returns plain dict with camelCase keys)
balances_response = client.user.get_balances()
print(f"Balances: {balances_response['balances']}")

# Place an order (returns dict, no need to import models)
order = client.order.create_order(
    side="buy",
    order_type="limit",
    base_token="HYPE",
    quote_token="USDC",
    amount="1.0",
    price="0.001",
)
print(f"Order placed: {order['orderId']}")

# Initiate a withdrawal
withdrawal = client.user.initiate_withdrawal("USDC", "100.0")
print(f"Withdrawal initiated: {withdrawal['withdrawalId']}")
```

## Enhanced features

### Hyperliquid SDK enhancements

The enhanced Hyperliquid SDK includes these convenience methods:

**Info class:**
- `get_balance(wallet_address: str, token_symbol: str) -> float` - Get user's balance for a specific token
- `await_withdrawal_completion(wallet_address: str, pre_withdrawal_balance: float, token_symbol: str, timeout: int) -> bool` - Poll balance until withdrawal completes

**Exchange class:**
- `deposit_to_silhouette(silhouette_address: str, token_symbol: str, amount: str, converter: TokenConverter) -> dict` - Deposit tokens from Hyperliquid to Silhouette contract

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

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 and status polling
- **Order management**: Create, cancel, query orders
- **Delegated orders**: List, get, and batch retrieve delegated orders
- **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

### Delegated orders

Delegated orders are orders placed on Hyperliquid by Silhouette on behalf of a trader. Query them using the `delegated_order` operations:

```python
# List delegated orders with optional filters
orders = client.delegated_order.list_delegated_orders(
    status="open",
    limit=50,
)
print(f"Found {len(orders['orders'])} orders")

# Get a single order by ID
order = client.delegated_order.get_delegated_order("order-id-here")
print(f"Order status: {order['order']['status']}")

# Batch retrieve multiple orders
batch = client.delegated_order.batch_get_delegated_orders(
    ["order-1", "order-2", "order-3"]
)
print(f"Found: {len(batch['orders'])}, Not found: {batch['notFound']}")
```

## Configuration

Create `examples/config.json` from the example template:

```bash
cp examples/config.json.example examples/config.json
```

Then configure:
- `account_address`: Your wallet's public address
- `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

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and project structure.

## Licence

This project is licensed under the terms of the MIT licence. See [LICENSE](LICENSE.md) for more details.

```bibtex
@misc{silhouette-python-sdk,
  author = {Silhouette},
  title = {Python SDK for trading on Silhouette - the shielded exchange on Hyperliquid},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/silhouette-exchange/silhouette-python-sdk}}
}
```

