TradePose Client SDK

Python SDK for TradePose quantitative trading platform. Simple, type-safe, production-ready.

What is this?

Official Python client for the TradePose trading platform API. Designed for quantitative traders, algo developers, and trading system architects who need:

• 🎯 Simple synchronous API - No async/await required, works out of the box
• 📊 Batch testing - Multi-strategy, multi-period backtesting with background polling
• 🔒 Type safety - Pydantic models, IDE autocomplete, compile-time validation
• 🎨 Direct typed authoring - Data, Base opportunity, and Advanced policy are explicit
• 🔄 Production-ready - Comprehensive error handling, automatic retries, Jupyter support
• 📋 CRUD Resources - Strategy, Portfolio, Account, Binding management via Gateway API

Installation

pip install tradepose-client

Requirements:

• Python 3.13+
• Dependencies: httpx, pydantic, polars, PyYAML, nest-asyncio

Local authoring workspace and agent skills

Initialize a local Python workspace and install the SDK-distributed Claude and Codex skills:

tradepose init . --agents claude,codex
tradepose doctor
tradepose skills check

tradepose draft new <name> creates a small human-owned package containing strategy.py and study.yaml. Choose a template, edit the strategy and structured hypothesis, then discover the published interface before planning:

tradepose draft new <name> --template rsi-reversion
# Edit playbook/drafts/<name>/strategy.py and study.yaml.
tradepose draft describe <name> --json
tradepose strategy check <name> --json
tradepose experiment check <name>:baseline --json
tradepose experiment plan <name>:baseline --json

study.yaml keeps typed Params, periods, hypothesis/rationale, and either grid or correlated case candidates. experiment plan is strict, stores the exact source and request snapshot in .tradepose/state.sqlite3, and returns a durable Run ID without contacting the Gateway. Identical plans reuse the existing Run. A human explicitly starts it later with tradepose run start <run-id> (or tradepose run start <run-id> --detach) and resumes it with tradepose run resume <run-id>.

Only strategy.py and study.yaml are authoring sources. Do not hand-edit generated experiment/policy files; none are produced by this version.

Run metadata, canonical request bytes, and source snapshots live in .tradepose/state.sqlite3. Large result files alone live under results/runs/<run-id>/<task-id>/artifacts/. Inspect local state with run list, run show, and run path; remove an unstarted Run with run remove. --force removes local evidence only and never cancels remote work.

Use tradepose skills install --agents claude,codex to add missing files. tradepose skills sync --agents claude,codex updates only unmodified generated files, and tradepose skills check reports missing, package drift, and user conflicts. Manifest integrity—including malformed or mismatched recorded checksums—or generated-file conflicts use storage exit code 7. See Security boundary and Known limitations.

Quick Start

Batch Testing (Recommended)

Test multiple strategies across multiple periods - no async/await needed:

from tradepose_client import BatchTester
from tradepose_client.batch import Period

# Create tester
tester = BatchTester(api_key="tp_live_xxx")

# Submit batch (non-blocking, returns immediately)
batch = tester.submit_backtest(
    strategies=[strategy1, strategy2, strategy3],
    periods=[
        Period.Q1(2024),  # 2024-01-01 to 2024-03-31
        Period.Q2(2024),  # 2024-04-01 to 2024-06-30
        Period.Q3(2024),  # 2024-07-01 to 2024-09-30
    ]
)

print(f"Submitted {len(batch.task_ids)} tasks")
print(f"Progress: {batch.progress:.1%}")

# Wait for completion (blocking)
batch.wait()

# Access trades (Polars DataFrame)
all_trades_df = batch.trades  # All trades with period column

# Period-specific results
q1 = batch[Period.Q1(2024).to_key()]
print(f"Q1 trades: {len(q1.trades)}")
print(f"Q1 PNL: {q1.trades['pnl'].sum()}")

Period Objects (Type-Safe Dates)

Use Period objects for type-safe date validation:

from tradepose_client.batch import Period

# Quarterly testing
periods = [
    Period.Q1(2024),  # Jan-Mar
    Period.Q2(2024),  # Apr-Jun
    Period.Q3(2024),  # Jul-Sep
    Period.Q4(2024),  # Oct-Dec
]

# Full year
full_year = Period.from_year(2024)  # 2024-01-01 to 2024-12-31

# Single month
march = Period.from_month(2024, 3)  # 2024-03-01 to 2024-03-31

# Flexible multi-month ranges
three_months = Period.from_month(2024, 3, n_months=3)  # Mar-May 2024
half_year = Period.from_month(2024, 1, n_months=6)     # Jan-Jun 2024
winter = Period.from_month(2024, 11, n_months=3)       # Nov 2024 - Jan 2025

# Custom range
custom = Period(start="2024-01-15", end="2024-02-15")

Benefits:

• ✅ Compile-time type checking
• ✅ IDE autocomplete and validation
• ✅ Automatic validation (start < end)
• ✅ Clear error messages

Strategy Authoring

Authoring separates tunable values from assembly: direct typed sources + Opportunity → recipe Draft → Definition → current-wire StrategyConfig.

@strategy(SmaParams)
def sma(draft: StrategyDraft, params: SmaParams):
    # Bind keeps Params reusable and resolves typed indicators to recipe-local handles.
    selected = draft.bind(params)
    primary = selected.primary

    # .col() selects completed-bar server columns for Polars expressions.
    fast = primary.fast_sma.col()
    slow = primary.slow_sma.col()
    atr = primary.volatility_atr.col()
    entry = fast > slow
    exit = fast < slow
    volatility_level = build_volatility_level(
        atr,
        window=primary.volatility_window,
    )

    # Register Data outputs before Base seals and assembles the Definition.
    draft.data.set_volatility_scale(primary.volatility_atr)
    draft.data.set_volatility_level(expr=volatility_level)
    draft.base(
        direction=selected.opportunity.direction,
        trend=selected.opportunity.trend,
        entry=entry,
        exit=exit,
    )

params = SmaParams.create()
definition = sma.define(params)
variants = SmaParams.sweep().expand(params)
policies = PolicySet.sweep(
    params,
    direction="long",
    entry_kind="favorable",
    entry_distances=(0.3,),
    stop_losses=(1.0, 1.5),
    take_profits=(2.0, 3.0),
)
configs = sma.build(params, policies=policies)

Call SmaParams.sweep() for the strategy author's default search ranges, or replace its typed keyword-only axes with custom tuples, lists, or ranges.

Create policies only after the Base Params seed. The SDK-owned PolicySet.sweep(params, ...) expands the entry/exit search space into Advanced Blueprints inside its Config; strategy authors only call it and do not implement it on their Params class. Conditions, sizing, lot-size behavior, volatility weights, and metadata remain fixed overrides. Distance policies reference the volatility scale declared by Base Data and cannot replace it. Direction accepts "long", "short", or TradeDirection. Use PolicySet.cases(params, Policy(...), ...) for correlated candidates. Base sweep and Advanced policies cannot be used in the same build.

Direct-source StrategyParams exposes a typed keyword-only create() with useful recipe defaults. Name each TypedDataSource by stable strategy role (primary, context), not sweepable instrument/frequency values. Sources contain flat indicators plus pure source-local Data calculations. draft.bind() registers the Data graph and returns selectable indicators. Each indicator owns its independent completed-bar shift. Use ResampledDataSource for a typed, instrument-inheriting lower-resolution role such as primary 15m → trend 1h; bind() validates and materializes that DAG. BUILDER_EXAMPLE.md for a complete executable example.

Core Concepts

Batch Testing API (Primary Interface)

BatchTester is the main way to interact with the platform:

from tradepose_client import BatchTester
from tradepose_client.batch import Period

tester = BatchTester(api_key="tp_live_xxx")

# Submit tasks
batch = tester.submit_backtest(
    strategies=[strategy1, strategy2],
    periods=[Period.Q1(2024), Period.Q2(2024)]
)

# Monitor progress
print(f"Progress: {batch.progress:.1%}")
print(f"Completed: {batch.status_counts['completed']}/{len(batch.task_ids)}")

# Wait for completion
batch.wait()  # Blocks until all tasks complete

# Access trades
all_trades = batch.trades  # All trades across periods

# Period-specific results
q1_result = batch[Period.Q1(2024).to_key()]
print(f"Q1 trades: {len(q1_result.trades)}")

Features:

• Synchronous interface - No async/await required
• Background polling - Tasks execute in background, results auto-download
• Type-safe dates - Period objects with validation
• Polars DataFrames - High-performance data analysis
• Jupyter-friendly - Automatic event loop setup

Instrument Discovery

Query available trading instruments:

from tradepose_client import BatchTester

tester = BatchTester(api_key="tp_live_xxx")

# List all available instruments
instruments = tester.list_instruments()
print(f"Available instruments: {len(instruments)}")

for inst in instruments[:5]:
    print(f"  {inst.symbol} - {inst.exchange} ({inst.freq})")

# Filter by exchange
binance = [i for i in instruments if i.exchange == "BINANCE"]

CRUD Resources (v0.3.0)

Manage trading entities via Gateway API:

from tradepose_client import TradePoseClient

client = TradePoseClient(api_key="tp_live_xxx")

# Strategy management
strategies = client.strategies.list()
strategy = client.strategies.create(name="MyStrategy", config={...})

# Portfolio management
portfolios = client.portfolios.list()
portfolio = client.portfolios.create(
    name="MyPortfolio",
    capital=100000,
    currency="USD"
)

# Account management (MT5, Binance, etc.)
accounts = client.accounts.list()

# Binding (connect Portfolio to Account)
binding = client.bindings.create(
    account_id=account.id,
    portfolio_id=portfolio.id
)

Low-Level API (Advanced Users)

For fine-grained control over HTTP connections, custom retry logic, or manual event loop management, see Low-Level API Documentation.

Most users should use BatchTester - it's simpler and handles async complexity automatically.

Task Polling Pattern

Long-running operations return immediately with a task ID. Results are downloaded automatically in the background:

# Submit returns immediately
batch = tester.submit_backtest(strategies=[strategy], periods=[Period.Q1(2024)])
print(f"Task ID: {batch.task_ids[0]}")  # Submitted

# Background polling starts automatically
# Do other work while tasks run...

# Wait when you need results
batch.wait()  # Blocks until completion

# Results ready
trades = batch.trades

Documentation

• 💡 Examples - Real-world usage patterns (start here!)
• 📚 API Reference - Complete API documentation
• 🔧 Low-Level API - Advanced async API (for experts)
• ⚠️ Error Handling - Exception types and handling strategies
• ⚙️ Configuration - Environment variables, timeout settings
• 📐 Architecture - Design decisions and data flow

Features

Current (Alpha)

Batch Testing API

• ✅ Multi-strategy, multi-period testing
• ✅ Background polling (daemon thread)
• ✅ Auto-download on completion
• ✅ Type-safe Period objects with validation
• ✅ Convenient constructors (Q1, Q2, from_year, from_month)
• ✅ Reactive results (lazy loading)
• ✅ Memory caching
• ✅ Jupyter support (nest_asyncio auto-applied)

Builder API

• ✅ Fluent strategy construction
• ✅ Type-safe indicator references
• ✅ 60% less boilerplate
• ✅ TradingContext convenience accessors
• ✅ Automatic field inheritance

Low-Level Client API

• ✅ Authentication (API key + JWT)
• ✅ Resource-based organization (6 resources, 21 methods)
• ✅ Async-first with HTTP/2
• ✅ Automatic retry with exponential backoff
• ✅ Comprehensive error handling (18 exception types)
• ✅ Type-safe with Pydantic models

CRUD Resources (v0.3.0)

• ✅ Strategy management (create, list, get, update, delete)
• ✅ Portfolio management with capital allocation
• ✅ Account management (MT5, Binance, etc.)
• ✅ Binding management (Account ↔ Portfolio)
• ✅ Instrument discovery (list_instruments())
• ✅ TradingContext convenience accessors

Roadmap

• ⏳ Webhook support (replace polling)
• ⏳ GraphQL endpoint (reduce requests)
• ⏳ Result streaming (large datasets)

Configuration

Environment Variables

# Authentication (required, at least one)
export TRADEPOSE_API_KEY="tp_live_xxx"
export TRADEPOSE_JWT_TOKEN="eyJ..."

# Server (optional)
export TRADEPOSE_SERVER_URL="https://api.tradepose.com"

# HTTP (optional)
export TRADEPOSE_TIMEOUT="30.0"        # Request timeout (1.0 - 600.0s)
export TRADEPOSE_MAX_RETRIES="3"        # Max retry attempts (0 - 10)

# Task polling (optional)
export TRADEPOSE_POLL_INTERVAL="2.0"    # Poll interval (0.5 - 60.0s)
export TRADEPOSE_POLL_TIMEOUT="300.0"   # Max poll duration (10.0 - 3600.0s)

# Logging (optional)
export TRADEPOSE_DEBUG="false"
export TRADEPOSE_LOG_LEVEL="INFO"       # DEBUG/INFO/WARNING/ERROR/CRITICAL

Configuration Methods

# Method 1: Environment variables (recommended)
tester = BatchTester()  # Auto-loads from TRADEPOSE_API_KEY

# Method 2: Direct parameters
tester = BatchTester(
    api_key="tp_live_xxx",
    poll_interval=2.0,
)

# Method 3: Configuration file (see Configuration Guide)

See Configuration Guide for details.

Error Handling

All exceptions inherit from TradePoseError:

from tradepose_client import (
    BatchTester,
    AuthenticationError,
    RateLimitError,
    TaskTimeoutError,
    ValidationError
)
from tradepose_client.batch import Period

tester = BatchTester(api_key="tp_xxx")

try:
    batch = tester.submit_backtest(
        strategies=[strategy],
        periods=[Period.Q1(2024)]
    )
    batch.wait(timeout=600.0)

except AuthenticationError:
    # Invalid API key
    print("Authentication failed")

except ValidationError as e:
    # Invalid Period or strategy configuration
    print(f"Validation error: {e.errors}")

except RateLimitError as e:
    # Rate limit exceeded
    print(f"Rate limited. Wait {e.retry_after}s")

except TaskTimeoutError as e:
    # Task didn't complete in time
    print(f"Timeout. Task ID: {e.task_id}")

See Error Handling Guide for complete reference.

Period Validation

Period objects automatically validate date ranges:

from tradepose_client.batch import Period

# Valid period
period = Period(start="2024-01-01", end="2024-12-31")  # ✅ OK

# Invalid period (start >= end)
try:
    period = Period(start="2024-12-31", end="2024-01-01")  # ❌ Error
except ValueError as e:
    print(e)  # "Period start (2024-12-31) must be before end (2024-01-01)"

# Invalid date format
try:
    period = Period(start="invalid", end="2024-12-31")  # ❌ Error
except ValueError as e:
    print(e)  # "Cannot parse datetime from type..."

Migration from Tuple-Based Periods

Before (deprecated):

# ❌ No longer supported
batch = tester.submit_backtest(
    strategies=[strategy],
    periods=[("2024-01-01", "2024-12-31")]  # Tuple not accepted
)

After (type-safe):

# ✅ Required: Use Period objects
from tradepose_client.batch import Period

batch = tester.submit_backtest(
    strategies=[strategy],
    periods=[Period(start="2024-01-01", end="2024-12-31")]
)

# ✅ Even better: Use convenience constructors
batch = tester.submit_backtest(
    strategies=[strategy],
    periods=[Period.from_year(2024)]  # Clearer and type-safe
)

This is a Breaking Change in version 0.2.0+. Update your code to use Period objects.

Development Status

Alpha - API is stable but subject to minor changes. Production use at your own risk.

Python Version Support

Requires Python 3.13+ to leverage:

• Type parameter syntax ([T])
• Self type hint
• Performance improvements

License

MIT License - see LICENSE file for details.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Email: support@tradepose.com