SDK and API reference

Getting started

Stoxa exposes everything the app does through a REST API at https://app.stoxa.io/api and a Python client, stoxa, that wraps it. Both need a personal API key from Settings → API keys; a Stoxa subscription is required.

pip install stoxa
export STOXA_API_KEY=vdk_...

from datetime import date
from stoxa import equities, macro

d = date(2026, 10, 30)
rf, src = macro.risk_free(as_of=d)                  # 10y Treasury as published on d, and where it came from
fin = equities.get_fundamentals("AAPL", as_of=d)    # only filings with filed <= d
val = equities.value_company("AAPL", as_of=d)       # the workbench's engine, sourced defaults
val.value_per_share, val.upside
g = equities.implied_growth("AAPL", as_of=d)        # reverse DCF: growth the price implies
picks = equities.screen([{"field": "pe", "op": "lt", "value": 15},
                         {"field": "roic", "op": "ge", "value": 0.15}], as_of=d)

The same calls over plain HTTP:

curl -H "Authorization: Bearer vdk_..." \
  "https://app.stoxa.io/api/companies/AAPL/fundamentals?as_of=2026-10-30"

Python ≥ 3.10. The client depends on httpx, pandas, numpy and pydantic only. Source and issues: hello@stoxa.io.

Authentication and access

Every request carries Authorization: Bearer vdk_…. A key acts as its owner: it has exactly the access your account has, so it stops working if your subscription lapses, and it is revoked the moment you revoke it in Settings. You can hold up to 10 active keys; label them per machine or agent so you can revoke one without touching the others.

Keys are shown once at creation and stored only as a hash. Treat them like passwords: environment variables or a secrets manager, never a notebook you share. GET /api/me tells you who the server thinks you are.

Point-in-time semantics

Every data call takes as_of. With it, the answer is what was public on that date: fundamentals come only from filings with filed ≤ as_of, with restatements resolved to the latest such filing; prices stop at as_of; macro series use only vintages published by then. Without it, you get today. A screen or backtest on a date is built from a snapshot of the whole universe as it stood then, so a backtest cannot peek.

get_fundamentals(..., provenance=True) appends <field>__accession and <field>__filed columns, the SEC filing each number came from, so a value can always be traced to its source.

Python SDK

Configuration

import stoxa
stoxa.configure(api_key="vdk_...")            # beats the environment; url and timeout optional
stoxa.current_config()                        # {"url": "https://app.stoxa.io", "api_key_set": True, "timeout": 60.0}

Environment: STOXA_API_KEY, and STOXA_API_URL if you are not talking to app.stoxa.io. Non-2xx answers raise stoxa.ApiError with .status and .detail.

stoxa.equities

Ratios are fractions (ROIC of 15% is 0.15); money is in dollars.

stoxa.macro

Series codes look like US.RATES.UST.10Y or US.INFL.CPI.HEADLINE.SA; 15 geographies are covered. Use list_series(q="cpi") to search.

Filters

Screens and backtests share one filter shape, in the SDK and over HTTP. A filter list is a set of entries joined with and. An entry is a condition, or an or group of conditions:

[{"field": "pe", "op": "lt", "value": 15},                       # condition
 {"any": [{"field": "pe", "op": "lt", "value": 15},               # OR group: passes when any one holds
          {"field": "ev_ebit", "op": "lt", "value": 10}]},
 {"field": "sector", "op": "not_in", "value": ["Utilities"]},
 {"field": "roic", "op": "between", "value": [0.15, 0.6]}]

Groups are one level deep: a group inside a group, or an empty group, is rejected with 422. Rows whose field is null fail the condition, as in SQL.

Numeric fields. composite_score, current_ratio, debt_to_equity, dividend_yield, dividends_ttm, ebit_ttm, ebitda_ttm, eps_growth, ev, ev_ebit, ev_ebitda, ev_sales, factor_growth, factor_momentum, factor_quality, factor_risk, factor_value, fcf_margin, fcf_ttm, gross_margin, interest_coverage, market_cap, net_debt_ebitda, net_income_ttm, net_margin, operating_margin, payout_ratio, pb, pe, pfcf, price, ps, ret_12m, ret_1m, ret_3m, ret_6m, revenue_growth, revenue_ttm, roa, roe, roic, vol_1y.

Macro fields. macro_ust10y, macro_spread_2s10s, macro_cpi_yoy, macro_unemployment, macro_hy_oas, macro_sahm (numeric) and macro_curve_state, macro_recession_signal (categorical). They hold one value per snapshot date, the regime as known then, so in a backtest a macro condition keeps or drops the whole rebalance. screener_fields() or GET /api/screener/fields is the authoritative list.

Rankings, simulations, strategies

A ranking system is a tree whose root is a composite. Factor nodes rank one numeric screener field within the universe, the sector or the industry; composite nodes take the weighted mean of their children and re-rank it; conditional nodes route stocks to one of two branches. Weights are relative among siblings (all zero means equal). A rank is 0 to 100, 100 best.

{"type": "composite", "name": "Cheap quality", "children": [
  {"type": "composite", "name": "Value", "weight": 1, "children": [
    {"type": "factor", "name": "P to E", "field": "pe", "direction": "lower"},
    {"type": "factor", "name": "EV to EBITDA", "field": "ev_ebitda", "direction": "lower", "scope": "industry"}]},
  {"type": "factor", "name": "ROIC", "field": "roic", "direction": "higher", "weight": 2}]}

Limits: 4 levels below the root, 60 factor nodes, sibling names unique, no / in names. na_policy decides what a missing value scores: negative (ties just below the worst valid stock; the default for new systems), neutral (the middle of the valid scores) or skip (the node drops out of its parent's mean). With a ranking attached to a screen or backtest, the fields rank, rank_pos, rank_change_4w, rank_change_13w and node:<path> are usable in filters, columns and sort; without one they are rejected (400).

A strategy is the body of every simulation endpoint and of saved strategies. Only start and end are required; unknown keys are rejected (422).

{"name": "Quality momentum", "universe": "liquid",
 "ranking": {"system": "Core: Combination", "na_policy": "negative"},
 "buy_rules": [{"field": "price", "op": "ge", "value": 5}],          // ANDed, like screen filters
 "sell_rules": [{"kind": "rank_below", "value": 80},                 // ORed, checked at rebalances
                {"kind": "pct_from_high", "op": "le", "value": -25}],
 "positions": {"target": 20, "max": null, "min_cash_pct": 0, "sector_cap_pct": 30, "industry_cap_pct": null},
 "rebalance": "M",                                                   // W | M | Q | A
 "weights": "equal",                                                 // equal | rank
 "stops": {"trailing_pct": 20, "entry_pct": null, "time_days": null},
 "buyback_cooloff_days": 30,
 "hedge": {"vehicle": "cash", "ratio_pct": 50,
           "entry": {"kind": "benchmark_below_sma", "days": 200}, "exit": null},
 "costs": {"model": "variable"}, "commission": {"per_trade": 0, "pct": 0},
 "return_type": "total", "start": "2015-01-01", "end": "2024-12-31",
 "capital": 100000, "benchmark": "SPY"}

Invalid strategies answer 422 with errors: [{"path": "sell_rules[1].op", "message": "..."}]. Simulations are long only: no shorting, margin or leverage, no formula language, fills at daily closes in whole shares. House strategies use the same schema: GET /api/strategies/house/{slug} returns the definition the simulator runs. Every statistic outside the backtest block and the backtest rows of yearly is since launch.

REST API reference

Base URL https://app.stoxa.io/api. JSON in and out; errors are {"detail": "message"}. Dates are ISO YYYY-MM-DD; timestamps are UTC. The full contract with example payloads ships with the SDK docs; this is the map.

Meta and account

Companies

Screener and backtest

Rankings

Simulations and saved strategies

House strategies, portfolios, notifications

Public (no key)

Valuation

Macro

Errors, limits, conduct

• Errors are JSON with a detail string; the SDK raises ApiError(status, detail). A 401 from a key you just created usually means the key was pasted with whitespace.
• Timeouts. Most calls answer in well under a second. A screen on a new date, a backtest, or a company Stoxa has never ingested (it fetches the filings on first request) can take minutes; the SDK's long timeouts on screen and backtest reflect that.
• Limits. Backtests run one at a time per server and queue; Monte Carlo caps at 20,000 draws; screens at 200 rows by default (limit up to the universe). There is no hard request rate today. Please keep automated clients to what a person could reasonably use; bulk re-downloading the dataset is not what the key is for.
• Use. Your key is for your own research, notebooks and agents. Redistributing the dataset or substantial extracts, or sharing keys, is outside the terms of use. Quoting figures with attribution is fine.
• Changes. Fields and endpoints are added without notice; removals or renames are announced by email to key holders at least 30 days ahead. The SDK is versioned on PyPI; pin it in production.

Nothing here is investment advice. See the terms of use and privacy policy.