tradeodds — Python SDK

Official Python client for the TradeOdds REST API. Run quantitative pattern analysis on ~3,200 symbols (US equities, ETFs, major crypto) with one function call.

pip install tradeodds

Quickstart

from tradeodds import TradeOddsClient

client = TradeOddsClient()  # reads TRADEODDS_API_KEY from env

result = client.analyze(
    symbol="SPY",
    forward_period="5d",
    conditions={"daily_change": True, "vix_level": True, "regime": True},
    lookback_years="20y",
)

stats = result["forward_stats"]
print(f"{result['match_count']} matches | win rate {stats['win_rate']:.0%} | median {stats['median_return']:+.2%}")

Get an API key at https://tradeodds.io/account. Free tier ships with the platform — pay-as-you-go pricing kicks in at $0.05/analyze and $0.15/factor-match.

What's in the box

Installation

pip install tradeodds

Requires Python 3.9+. The only runtime dependency is requests.

Configuration

from tradeodds import TradeOddsClient

client = TradeOddsClient(api_key="sk-to-abc123...", timeout=60.0)

API reference

client.symbols(active_only=True)

List every symbol available for analysis.

universe = client.symbols()
print(f"{universe['count']} symbols")
spy = next(s for s in universe["symbols"] if s["symbol"] == "SPY")

client.analyze(symbol, **kwargs)

Returns probability-weighted historical analogs for the symbol's current DNA fingerprint. Auth required. $0.05/call.

client.factor_match(**kwargs)

Scans all symbols for whose current state matches the supplied conditions. Returns a ranked list with historical forward-return stats. Auth required. $0.15/call.

result = client.factor_match(
    conditions={"vix_level": True, "regime": True, "rsi_zone": True},
    filters={"is_etf": False, "price_min": 10},
    perf_filter={"metric": "win_5d", "operator": "gt", "threshold": 0.6},
    min_instances=20,
)

Error handling

Errors are typed exceptions that preserve the structured envelope (code, hint, request_id):

from tradeodds import ApiError, AuthError, NotFoundError, RateLimitError

try:
    result = client.analyze(symbol="SPY")
except RateLimitError as exc:
    print(exc.code, exc.message, exc.hint, exc.request_id)
except AuthError:
    print("Set TRADEODDS_API_KEY")
except NotFoundError:
    print("Unknown symbol")
except ApiError as exc:
    print(f"[{exc.status_code}] {exc.code}: {exc.message}")

Every exception exposes:

• exc.code — machine-readable code (e.g. rate_limit_exceeded)
• exc.message — human-readable summary
• exc.hint — suggested remediation, when the API provides one
• exc.request_id — server request id for support contact
• exc.status_code — HTTP status

License

MIT. See LICENSE.