A complete guide to setting up, running, and understanding the scanner.
The Dividend Capture Scanner finds and ranks stocks that are about to pay a dividend, so you can buy before the ex-dividend date, collect the dividend, and sell once the price recovers.
It scans a large list of stocks each morning, keeps only the ones worth considering, measures how quickly each one has historically rebounded after past dividends, and ranks them so the best opportunities sit at the top.
Open PowerShell or Command Prompt, go to the folder where you saved the scanner, and run it. Replace the path with your actual folder location.
It scans roughly 576 stocks in parallel and runs a rebound analysis on every stock that passes the filters, finishing in about 1 to 2 minutes. When it finishes, the ranked list prints in the window and is saved in the same folder in two formats: a plain candidates_YYYYMMDD.csv and a formatted candidates_YYYYMMDD.xlsx for Excel, with a bold locked header row and sized columns so it is easy to read.
candidates_*.csv or candidates_*.xlsx file before running, otherwise the scanner cannot save the new one.Instead of remembering to run the scanner each day, Windows can start it for you every morning. The helper script run_daily.ps1 runs the scanner and saves each day's output to a dated log file in a logs folder, alongside the usual CSV.
Save run_daily.ps1 in the same folder as the scanner, then register the daily task once (this example uses 8:00 AM):
To check that the task is set up and see when it will run next:
The kill switch: pause or resume the morning run at any time with one command. No need to delete anything.
A laptop that is asleep or shut down at 8:00 AM cannot run anything. Windows offers to catch up on a missed run as soon as the machine comes back, but that catch-up starts while you are still signing in, and a scan started that early is killed before it gets anywhere. The result is the worst kind of failure: an empty log file that looks like the scan happened.
The reliable arrangement is to leave the catch-up option off and add a second trigger that fires a few minutes after you sign in, once the computer has settled. Add it once with this command:
Two triggers do not mean two scans. The helper script checks first whether today's candidates_YYYYMMDD.csv already exists and stops immediately if it does, so whichever trigger gets there first does the work and the other simply exits. This matters: repeated full scans in a short space of time can get the data feed to start refusing requests.
Every automatic run writes a one-line file called LAST_RUN.txt in the scanner folder, recording the time it finished and whether it worked:
A failed run writes a FAIL line with the error code instead. Without this, a scan that dies leaves nothing behind but silence, and silence looks exactly like success. Glancing at this one file each morning is the quickest way to know the plan on screen is today's.
The scanner searches the S&P 500 plus a curated set of high-yield income names, combined:
Together this is about 576 stocks. Mutual funds are intentionally left out, as they rarely yield enough to be worthwhile. A couple of funds whose headline yields are mostly a return of the investor's own capital were also removed, since those numbers are misleading for capture.
Every stock must pass all four checks below. If it fails any one, it is skipped.
| Filter | Default | Why it matters |
|---|---|---|
| Ex-dividend date | Next 30 days | Only shows stocks with a dividend coming up soon. Wide enough to plan a sequence of trades. |
| Annual yield | 3% or higher | Keeps the dividend worth the risk. Higher yields rank better. |
| Avg daily volume | 100,000+ shares | Basic liquidity floor. Thinly-traded names that pass are flagged so you can judge them. |
| Stock price | $5 to $500 | Avoids penny stocks and keeps position sizes manageable, while still allowing lower-priced CEFs and preferreds. |
This is the key part of the tool. When a stock pays a dividend, its price usually drops by about that amount on the ex-dividend date. The important question is how long it takes to climb back to the price you paid.
For each stock that passes the filters, the scanner looks at the last two years of price history. For every past ex-dividend date it measures:
A faster, more reliable rebound means your capital is freed up sooner, so it pushes the stock higher in the ranking.
The same two years of history are also used to answer two practical questions for each stock:
The score is built around capital rotation: the goal is to keep the same money working continuously. You hold a stock through its dividend, sell once the price is back to even or better, then move that money straight into the next upcoming dividend, over and over. The less time your money sits idle, the more dividends it can collect in a year.
So the score rewards the combination of a high yield and a fast rebound, then adjusts for risk:
| Factor | Effect on score |
|---|---|
| Yield | Higher yield means more collected per trade. Ranked directly by percentage, no tiers. |
| Rebound speed | A faster rebound frees the money sooner, so it can be redeployed into the next dividend. This is the biggest lever. |
| Recovery rate | Past dividends that never recovered are charged at the full 60-day wait in the efficiency math, so unreliable stocks score honestly lower. |
| Price trend | A downward trend lowers the score, since the price may not recover after the dividend. The trend is measured on total-return (dividend-adjusted) prices, so big payers are not unfairly flagged as falling. |
| Liquidity | Thinly-traded names are marked down, since they are harder to exit. |
Some names are pre-approved as quality holdings: companies and funds you would be comfortable keeping for an extended period if a rebound takes far longer than expected. They show "Yes" in the Pref column, and when two candidates score within 10% of each other in the Rotation Plan, the preferred one gets the slot. The displayed Score itself is never changed, so the ranking stays honest; the preference only decides close calls when picking trades.
Each row in the results represents one candidate. Here is what every column means:
| Column | Meaning |
|---|---|
| Ticker | The stock's trading symbol. |
| Pref | "Yes" if the stock is on the preferred list: quality names judged safe to keep holding if a rebound takes far longer than expected. Preferred names also win close calls in the Rotation Plan. The list is set at the top of the script. |
| Sector | The part of the market the stock belongs to, for example Utilities or Financial Services. Whole sectors can be ruled out in the settings, and the Rotation Plan uses this to warn when several pots of capital would hold the same sector at the same time. Funds and ETFs have no sector, so they are labelled by type instead. |
| Price | Current share price. |
| Days Until | Trading days until the ex-dividend date. |
| Annual Yield | The full year's dividend as a percentage of the stock price. The list is ranked by yield and rebound together. |
| Capture Yield | The single dividend payment as a percentage of the price. This is what you actually collect per trade. |
| Div/100sh | The dividend in dollars for one 100-share round lot. |
| Capital | The cost of buying 100 shares. |
| AfterTax35/100 | The dividend per 100 shares after 35% tax (the conservative estimate). |
| AfterTax25/100 | The dividend per 100 shares after 25% tax (the optimistic estimate). |
| Avg Reb | Average trading days to recover to the pre-dividend price. Lower is better. |
| Worst Reb | Worst-case recovery time over the period. Shows ">60" if any past dividend never recovered in the window. |
| Recovered | How often the stock recovered within the test window. |
| Best Entry | The back-tested sweet spot: how many trading days before the ex-date buying has historically worked best for this stock. |
| Drop Ratio | How much of the dividend the price actually gives up on the ex-date. 1.0 means the full dividend; below 1.0 means it drops less, which is good. |
| Trend | Price trend: Up, Down, or Mixed. Downtrends are discouraged. |
| Liquidity | Thin, Moderate, or High, based on daily trading volume. |
| Beta | How much the stock moves relative to the market. Lower is steadier. |
| Ann.Eff% | Theoretical annualised after-tax return if the capital is rotated continuously, taxed at the conservative 35% rate. |
| Score | Ann.Eff% adjusted down for a downtrend and thin liquidity. The list is sorted by this. |
The dollar figures use 100-share round lots because round numbers are far easier to sell than odd amounts.
Dividend-capture trades are held only days, so both the dividend and any price gain are short-term, taxed at your ordinary income rate rather than the lower 15% to 20% long-term capital-gains rate (which requires holding for over a year). The exact rate depends on deductions and the year's tax rules, so every after-tax figure is shown at two rates side by side: 35% as the conservative estimate and 25% as the optimistic one. Both rates can be changed in the settings.
The Excel file has a second sheet called Rotation Plan. It is a trade calendar that rolls capital from one dividend into the next, so the same money is reused as often as possible. It can run several pots at once: each pot, called a slice, is the same size (default $50,000) and holds one position at a time, so a trade that gets stuck freezes its own slice while the others keep working.
| Column | Meaning |
|---|---|
| Slice | Which pot of capital pays for the trade. Each slice rotates on its own clock, and no two slices are ever put in the same stock. |
| Buy | The day to buy, based on that stock's back-tested Best Entry day. If the money is still tied up then, the plan buys as soon as the cash is free. |
| Pref | "Yes" if the trade is a preferred-list name. When two candidates score within 10% of each other, the preferred one gets the slot. |
| Sector | The trade's sector, so it is obvious at a glance when the plan is leaning on one part of the market. |
| Ex-Date | The ex-dividend date you hold through to earn the dividend. |
| Est. Sell | The expected sell day: the ex-date plus that stock's average rebound time. |
| Cash Free | When the money is ready for the next trade (one settlement day after the sale). |
| Worst Reb | The honest risk: the longest that stock has ever taken to recover. |
| Shares / Cost $ | Whole 100-share lots bought with the available capital, and what they cost. |
| Gross Div $ | The dividend collected before tax and fees. |
| Net 35% $ / Net 25% $ | What is kept after any financing fee and tax, shown at both tax rates. |
| Running 35% $ / Running 25% $ | The total profit building up across the sequence of trades, at each tax rate. |
When a slice's capital is free, the plan looks at the candidates that can be bought within the next 5 trading days and takes the one with the best score, so the money never sits idle waiting for a distant trade.
The settings include a list of the positions the account is holding right now, and the plan reads it before doing anything else. Two things follow from that. A stock already owned is never proposed again, so the plan cannot tell you to double up on a position you are already sitting in. And a slice whose money is still tied up gets no trade until the cash is expected back. If a position has no sell date because it is still below the price it was bought at, its slice is marked blocked and left out of the plan entirely, which is the honest answer: pretending that money is available is what turns a plan into one that cannot actually be funded. The run prints the status of every slice above the plan, so it is always clear how much of the capital is genuinely free.
Running several slices is meant to spread risk. It only does that if the slices are in different parts of the market, and high dividend yields are concentrated in a handful of rate-sensitive sectors, so picking the top few names off the list can quietly put every pot into the same bet. Whenever two or more slices would hold the same sector at the same time, the plan prints a warning naming the sector and the stocks involved.
Each run also saves a dated rotation_calendar_YYYYMMDD.html in the same folder, matching the CSV and Excel filenames, so each day's plan is kept as a record. Open it in any browser to see the plan as a month-grid calendar: each slice of capital has its own colour, the buy, ex-date, sell, and cash-free days are labelled, and the days in between are tinted so you can see exactly when each slice is occupied and when it is free for the next trade. Any slice that is blocked or still holding a position is noted at the top. Like the CSV and Excel files, it stays on your computer and is never uploaded.
All the filter settings live at the top of dividend_scanner_v10.py and can be changed at any time:
For example, to only see stocks paying 5% or more, change MIN_ANNUAL_YIELD to 0.05. To change the tax estimates, adjust TAX_RATE_HIGH and TAX_RATE_LOW (for example 0.24 for 24%); the column names follow automatically.
CAPITAL is the size of one slice, not the total. Four slices of $50,000 means $200,000 committed in four pots that trade independently. Raising CAPITAL on its own makes each individual position bigger, which is a real risk in thinly traded names, so it is usually better to add slices than to enlarge them.
EXCLUDED_SECTORS drops whole sectors from the results, and the run reports how many names were removed so an excluded sector is never silently missing. Worth knowing before using it: excluding a sector removes the names, not the risk behind them. Interest rates move real estate, utilities, lending companies and bond funds alike, so ruling out one of them narrows the list without removing the exposure that comes with high yields.
HOLDINGS is the list of positions the account currently owns, with the slice each one sits in and the date its cash is expected back. Leaving the date out marks the position as stuck and blocks that slice. Keeping this list current matters: an out-of-date list produces a plan that looks fine and cannot be funded.
Dividend.com does not offer a public data connection, and automatically pulling from its website is unreliable and against most sites' terms of service. Yahoo Finance provides the same dividend calendar data through a clean, free connection.
Interactive Brokers does have a data connection, but it has not been enabled on the account yet. Once it is, the scanner will be able to check live prices, confirm there are enough shares to trade, and place orders directly. That is planned for Stage 2, and it starts with paper trading: the whole strategy runs on simulated money until the real results match the predictions. The step-by-step plan is on the Paper Trading page.