Historical Stock-Universe API for Systematic Research

A historical stock-universe API should reconstruct which securities met a strategy's eligibility rules on each rebalance date. For an options strategy, that means starting with the optionable tickers recorded at the time, joining market capitalization from the same information period, and applying any classification rule with its timing limitation disclosed.

Alphanume's Historical Optionable Tickers dataset supplies monthly point-in-time snapshots of US equities with listed option chains. It records a weekly-style expiration-density flag and the mean of the four gaps after the first observed expiration gap. It is a universe dataset, not historical option prices, spreads, volume, open interest, or execution-quality data.

Combine three contracts without blurring them

The monthly optionability date is not an arbitrary daily flag. For a rebalance later in the month, select the latest optionability snapshot available on or before the decision date and record that snapshot date separately. For market cap, select the decision date or a clearly defined prior trading observation. Do not relabel both source dates as the rebalance date.

Ticker Classification adds alphanume_sector and alphanume_industry, but it is current-state. It can segment a current reconstruction of a historical universe, not prove what classification was available then. If the study requires historical industry membership, use a versioned classification source instead of silently treating the current mapping as point-in-time.

Pull the optionable snapshot and dated size data

The two historical endpoints support date filters and cursor pagination. Retrieve the complete optionable snapshot first, then the market-cap rows required for the same decision period. The example uses environment-backed authentication and saves the raw response envelopes before joining.

import os
import requests

headers = {"X-API-Key": os.environ["ALPHANUME_API_KEY"]}

optionable = requests.get(
    "https://api.alphanume.com/v1/optionable-tickers",
    headers=headers,
    params={"date_gte": "2026-02-02", "date_lte": "2026-02-02"},
    timeout=30,
)
optionable.raise_for_status()

market_cap = requests.get(
    "https://api.alphanume.com/v1/historical-market-cap",
    headers=headers,
    params={"date": "2026-02-02"},
    timeout=30,
)
market_cap.raise_for_status()

optionable_payload = optionable.json()
market_cap_payload = market_cap.json()

Both wide responses can return has_more and next_cursor. Continue until has_more is false, passing both cursor date and ticker on every continuation. A universe built from the first page only is truncated even if the downstream code runs without error. The Historical Optionable Tickers guide and endpoint reference document the snapshot and pagination rules.

Apply eligibility rules after the joins

Suppose the research rule requires listed options, a weekly-style expiration-density flag, market cap of at least $500 million, and a technology classification. Join optionability and market cap on date and ticker, then left join classification on ticker. Keep unmatched classifications in an audit table before filtering.

universe = (
    optionable_rows
      .merge(market_cap_rows, on=["date", "ticker"], how="inner")
      .merge(classification_rows, on="ticker", how="left")
)

eligible = universe.loc[
    (universe["has_weeklies"] == 1)
    & (universe["market_cap"] >= 500_000_000)
    & (universe["alphanume_sector"] == "technology")
].copy()

assert eligible["date"].nunique() == 1

has_weeklies=1 means the four-gap average is under nine days, a weekly-style density rule rather than proof of particular consecutive contracts. avg_days_between reports that average, with values near seven indicating denser spacing. Neither field says the contracts had acceptable bid-ask spreads, sufficient volume, usable strikes, or executable prices. Those are separate screens that require options quote and liquidity data.

Prevent survivorship and timing leaks

• Do not begin with today's optionable list and ask which names have old prices.
• Do not substitute current market cap for the value recorded at the historical decision date.
• Do not forward-fill optionability beyond the next published monthly snapshot without documenting that policy.
• Do not convert missing joins to false eligibility without reporting why the row was absent.
• Do not describe current ticker classification as a historical taxonomy.

The optionable universe itself does not solve delistings, ticker changes, corporate-action adjustments, or forward-return measurement. It only answers which covered equities had listed option chains at the snapshot and what expiration density was observed. The Historical Market Cap documentation covers the dated size fields used in the join.

Respect access and snapshot coverage

Free access covers the trailing 20 trading sessions after a one-trading-session delay. Because optionability snapshots are monthly, that coverage can contain only one snapshot. It can test the pipeline but cannot support a multi-year universe claim. Confirm that every intended rebalance month has a completed snapshot before running returns.

Coverage changes over time as tickers gain or lose listed options. That evolution is the reason to use a historical universe. Report the number of optionable names, weekly names, market-cap matches, classification matches, and final eligible names for every rebalance. Abrupt count changes should trigger a data audit before they are treated as market structure.

Freeze one universe before attaching outcomes

Choose one documented monthly snapshot and save the complete raw optionability pages, complete market-cap pages, current classification extract, unmatched-row report, and final eligible list. Hash the final ticker list and rerun the pipeline. Only after the hash reproduces should the study attach next-period returns or options outcomes. The existing universe-construction bias guide explains the broader leakage problem; this workflow supplies the concrete API joins.