silhouette-python-sdk

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

pip install silhouette-python-sdk

Quick start

Using the enhanced Hyperliquid SDK

# 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

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.

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:

# 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:

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 for development setup, testing, and project structure.

Licence

This project is licensed under the terms of the MIT licence. See LICENSE for more details.

@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}}
}