analogtrader-sdk 0.1.0

AnalogTrader Risk API — Python SDK (typed, sync + async, retry-aware)

AnalogTrader Python SDK

Typed, production-grade client for the AnalogTrader Risk API (v1).

pip install analogtrader-sdk

Quick start

from analogtrader_sdk import AnalogTraderClient

client = AnalogTraderClient(
    base_url="https://api.analogtrader.com",
    api_key="at_live_xxx",
)

# Health check (no auth)
health = client.health()
print(health.ok, health.checks)

# Risk validation (requires API key with risk.validate scope)
result = client.risk_validate(
    venue="MT5",
    symbol="XAUUSD",
    side="BUY",
    size_usd=100.0,
    conviction=0.72,         # optional
    regime="calm",           # optional
)
print(result.approved, result.risk_grade)
for name, gate in result.gates.items():
    print(f"  {name}: pass={gate.pass_} value={gate.value} limit={gate.limit}")

Async usage

import asyncio
from analogtrader_sdk import AsyncAnalogTraderClient

async def main():
    async with AsyncAnalogTraderClient(
        base_url="https://api.analogtrader.com",
        api_key="at_live_xxx",
    ) as client:
        result = await client.risk_validate(
            venue="MT5", symbol="XAUUSD", side="BUY", size_usd=100.0,
        )
        print(result.approved, result.risk_grade)

asyncio.run(main())

Configuration

Parameter	Default	Notes
base_url	required	https://api.analogtrader.com
api_key	optional	Required for /v1/risk/* endpoints
timeout	10.0s	Per-request timeout (httpx)
max_retries	3	0 disables retry
backoff_base	0.2s	First-retry delay before jitter
backoff_max	5.0s	Cap on exponential backoff

Retries fire on 429, 502, 503, 504, network errors, and timeouts. Backoff is jittered exponential (base × 2^attempt, capped, randomized 50%-100% to avoid thundering-herd).

Error handling

from analogtrader_sdk import (
    ATApiError,           # API returned non-2xx
    ATConnectionError,    # network failure
    ATTimeoutError,       # request timed out (subclass of ATConnectionError)
)

try:
    result = client.risk_validate(...)
except ATApiError as e:
    print(e.status, e.code, e.type, e.request_id, e.details)
except ATTimeoutError as e:
    print("timeout", e)
except ATConnectionError as e:
    print("network", e)

ATApiError carries the structured error body the API returns (error.type, error.code, error.message, error.details, request_id).

Tracing

Every request emits X-Request-ID: <uuid>. The meta.request_id field on every response (mirrored back from the server) lets you correlate client-side logs with server-side audit chain.

Versioning

This SDK follows semver. The Risk API contract is frozen at v1; new endpoints land additively, breaking changes require a major bump.

See CHANGELOG.md.

License

MIT.