Backtest Ex-Dividend Recovery With an API

Backtest ex-dividend recovery by separating the ex-day price give-back, net capture, and time to breakeven, then subtract costs and taxes appropriate to the research account.

An ex-dividend recovery backtest needs more than a calendar of payment dates. Alphanume's Dividend Capture dataset provides one row per ex-dividend event with the dividend schedule, cum-date price, ex-day open and close, price-drop ratios, net capture percentage, breakeven level, recovery status, and recovery horizons. That structure separates what happens on the ex-day from what happens afterward.

The Dividend Capture documentation defines each field and the upcoming-event query. Alphanume also publishes its methodology and proof material for broader research context. Historical gross behavior is not guaranteed income and does not include a user's commissions, spreads, slippage, financing, withholding, or tax treatment.

Decompose the trade into three outcomes

First measure the price give-back from the cum-date close to the ex-day open or close. Second calculate the gross net capture after adding the cash dividend. Third track whether and when price reaches the served breakeven threshold. These are different outcomes and should not be merged into a single success flag.

Keep ex-open and ex-close variants separate. A strategy entered before the ex-date and sold at the open has different exposure from one held through the close or until recovery. Define entry, dividend eligibility, exit, and treatment of overnight gaps before computing returns.

Query history and the forward calendar separately

Use ticker for one issuer's history or date bounds for a completed event panel. Set upcoming=true for future ex-dates, with a forward horizon up to 120 calendar days. Upcoming rows contain schedule data but their ex-day and recovery fields remain empty until price observations exist.

GET /v1/dividend-capture
ticker=<selected ticker>
date_gte=2021-01-01
date_lte=2025-12-31

For research today:
GET /v1/dividend-capture?upcoming=true&future_days=30

gross_capture = served net_capture_pct
research_net = gross_capture - commissions - spread_cost
retain recovery_status, bars_observed, recovery_window_days

The first call supports historical distribution analysis. The second identifies candidates, but it should not borrow future recovery outcomes. Keep calendar and realized fields distinct in storage so a backtest cannot accidentally populate an upcoming event with information learned afterward.

Estimate recovery distributions with censoring

Group historical events by ticker, dividend type, yield band, or other prespecified characteristics. Report the proportion recovered within one, three, five, ten, and twenty trading days among events with enough bars to answer each horizon. Pending events and events with short histories should remain censored rather than coded as permanent failures.

• Report ex-open and ex-close price-drop distributions separately.
• Condition horizon statistics on sufficient bars observed.
• Keep regular and special dividends distinct.
• Subtract explicit trading costs before comparing strategies.

A recovery distribution can be heavily influenced by the underlying market regime and issuer trend. Consider point-in-time sector, market cap, volatility, and broad-market controls if the study seeks explanatory evidence. Do not choose only historically fast-recovering tickers using their full future record and then call the result out of sample.

Corporate actions need explicit review as well. Splits, special distributions, mergers, and unusually large one-time dividends can make ordinary recovery assumptions misleading. Preserve dividend_type and separate special dividends before estimating a regular-income strategy. If adjusted prices are used downstream, confirm that the adjustment method does not add the cash dividend a second time.

For time-to-recovery summaries, show the number still at risk at each horizon. A simple average among recovered events ignores the slowest and unresolved cases. Horizon flags with sufficient bar counts provide a clearer empirical distribution, while pending rows remain visible rather than disappearing from the calculation.

Avoid the income illusion

The primary failure mode is counting the dividend as income while ignoring the ex-day price adjustment. A second is calling eventual recovery profit even when capital was tied up for weeks and exposed to further drawdown. Compare returns over equal horizons, track maximum adverse movement where price data permit, and include the opportunity cost of waiting.

Taxes and withholding can vary by account, jurisdiction, holding period, and dividend qualification. The dataset cannot determine those user-specific amounts. Present gross research results, then add clearly labeled cost and tax scenarios rather than embedding an unexplained universal rate.

Run one cost-aware historical test

As a concrete next action, pull completed events for one liquid ticker, exclude rows without enough bars for the chosen horizon, and export the dividend amount, ex-day give-back, gross net capture, recovery state, days to recover, and bars observed. Apply two explicit cost scenarios and compare exits at the ex-open, ex-close, and fixed recovery horizon. Then query upcoming events separately. This yields a reproducible recovery distribution without presenting gross historical outcomes as a guaranteed income strategy.