tradeodds 0.1.0

Official Python SDK for the TradeOdds REST API — quantitative pattern analysis on ~3,200 symbols.

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

Method	Endpoint	Auth	Cost
client.symbols()	GET /api/v1/symbols	none	free
client.analyze(symbol, ...)	POST /api/v1/analyze	API key	$0.05
client.factor_match(...)	POST /api/v1/factor-match	API key	$0.15

Installation

pip install tradeodds

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

Configuration

Source	Variable	Notes
Env	TRADEODDS_API_KEY	sk-to-... token. Default auth source.
Env	TRADEODDS_BASE_URL	Override for staging / self-host. Defaults to production.
Constructor	TradeOddsClient(api_key=..., base_url=..., timeout=200.0)	Explicit overrides win over env.

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.

Arg	Type	Default	Notes
symbol	str	—	Ticker (case-insensitive).
reference_period	1d 5d 1m …	1d	How recent the observed window is.
forward_period	1d 5d 20d …	5d	Trading days forward to compute outcomes.
conditions	DNAConditions	{daily_change: True}	Toggle factors: vix_level, regime, rsi_zone, streak, macro_risk, etc.
lookback_years	1y 5y 20y max	max	History window for matches.
price_tolerance	int 0-3	0	Bucket-step tolerance for price.
vix_tolerance	int 0-3	0	Bucket-step tolerance for VIX.

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}")

Exception	When
AuthError	401 — missing or invalid key
NotFoundError	404 — unknown symbol
ValidationError	400 / 422 — bad request body
RateLimitError	429 — daily or per-minute cap
ServerError	5xx and client-side timeouts (504 from server-side timeout)
ApiError	base class for all of the above

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.