corp_actions.py — NSE Corporate Actions
backend/nseeod/corp_actions.py builds scr_corp_action: every split, bonus, rights issue,
dividend, symbol change and delisting for NSE equities, mainboard and SME, since 1995. It checks
each price-moving action against our own prices and finds the ones NSE's list misses. It is the
input for adjusted EOD prices, applied on read from the Parquet history store.
Why a list is needed: NSE's bhav PREVCLOSE is not adjusted on ex-dates. On
07-Sep-2017, RELIANCE's file shows prevclose 1645.4 and close 818.1 (1:1 bonus). Our own prices
can only show where a jump happened, not what caused it.
Phases
| Phase | What | State |
|---|---|---|
| 1 | Download + backup + parse + table + CLI | done 2026-09-27 |
| 2 | reconcile: price check of every split/bonus/rights, rights and dividend factors, gap detector, inferred delistings; SME board | done 2026-09-27 |
| 3 | eq_store.get_eod(adjust='none'|'price'|'total', follow_renames=...) + chart toggle | done 2026-09-27 |
| 4 | Daily sync in the Bhav Downloader + Corporate Actions review page | done 2026-09-27 |
Sources
| Source | Content | Coverage |
|---|---|---|
www.nseindia.com/api/corporates-corporateActions?index=equities&from_date=&to_date= | Mainboard JSON: symbol, series, isin, faceVal, exDate, subject (free text) | 1995 →. Sparse before 2005 (70–250 a year until 2004) and no splits before 2006 |
same API, index=sme | NSE Emerge (series SM); the two feeds don't overlap. Its isin field holds other codes (411559) | 2013 →, 1,537 records |
nsearchives.nseindia.com/content/equities/symbolchange.csv | company, old symbol, new symbol, date (no header) | 1,064 rows |
.../namechange.csv | company name changes | backup only |
.../delisted.csv | symbol, company, date, type | 329 rows, incomplete |
The API needs a page warm-up and browser headers. It is called month by month, so no silent row cap is hit.
Backup
D:\kss\stock\EODData\NSE_CA\ holds:
{year}.jsonfor 1995–2026 (mainboard);sme_{year}.jsonfor 2012–2026;- the three CSVs, plus a
manifest.csv(file, records, SHA-1).
download skips past years that already exist, but always refetches the current and previous year to pick up late filings.
Usage
Run from backend/:
python -m nseeod.corp_actions download --dir D:/kss/stock/EODData/NSE_CA [--from 1995 --to 2026 --refresh]
python -m nseeod.corp_actions parse --dir D:/kss/stock/EODData/NSE_CA # dry run: counts + not-understood list
python -m nseeod.corp_actions parse --dir D:/kss/stock/EODData/NSE_CA --apply # write, then runs reconcile --apply
python -m nseeod.corp_actions reconcile [--apply] # price checks + gap detector + review CSV
python -m nseeod.corp_actions accept-high [--apply] # mark high-confidence detected jumps VERIFIED
python -m nseeod.corp_actions ignore-gaps [--min-days 365] [--apply] # mark jumps across a long trading gap IGNORED
python -m nseeod.corp_actions stats
Always reconcile after parse. Parse resets NSE rows to their parsed status, so parse --apply runs reconcile --apply itself.
Table scr_corp_action
DDL is owned by corp_actions.ensure_table(). Alembic 6637f64fd4c1 is the paper trail, same
pattern as scr_mcxsp_eod.
| Column | Meaning |
|---|---|
masid, symbol, isin, series, ex_date | The symbol that traded on the ex-date (see "Renamed symbols") |
action | SPLIT BONUS RIGHTS DIVIDEND SYMBOL_CHANGE DELIST OTHER (demerger / scheme / capital reduction), ADJUST (detected price jump of unknown kind) |
ratio_a, ratio_b | Bonus or rights a new for every b held |
old_fv, new_fv | Split face values |
amount | Dividend, Rs per share |
issue_price | Rights price (face value + premium) |
factor | Price multiplier for bars before ex_date (see "Factors") |
new_symbol, new_masid | Symbol change target |
subject_raw, part | NSE's subject text, and which piece of it this row is |
source | NSE_API, NSE_CSV, DETECTED (reconcile), MANUAL |
status | AUTO (used), REVIEW (needs a human, not used), VERIFIED / IGNORED (set by a human), SKIP (dropped by the parser) |
note | Why: parse notes, price-check result, detected-jump details |
Rows a human set to VERIFIED or IGNORED, and MANUAL rows, are never touched by parse or reconcile.
Parsing the subject
One subject can hold several actions, like Div 25%/Bonus 1:2/Rights 1:2. One action can also be
spread over slashes, like Rights/2:5/Prem Of Rs 30. The parser:
- Splits the subject on
/ ; and & plus +. It won't split insideRs 5/ To 2/, and it splits beforeSpl-Rs…(except afterFv). - Classifies each piece by keyword, including abbreviations:
Fv Spl,Bon,Rght/Rhts,Div30%,Prm/Prfor premium. - Reads
Spl-Rs10 To Rs2as a split, butDiv-Fin Rs.3 + Spl Rs.5as a special dividend (no from-to pair). - Glues a piece with no keyword onto the previous action. A ratio is never glued onto a dividend:
Rght1:5@Rs.500would otherwise become a Rs 500 dividend. - Non-equity issues become
SKIP, because they don't dilute the equity:- bonuses in debentures, preference shares, NCRPS or DVR (NTPC, BRITANNIA, DRREDDY, TVSMOTOR);
- rights issued only in NCD, CCD, CCPS, bonds or warrants.
- Drops AGM, book closure, interest, redemption, buyback and similar pieces. It counts pieces it doesn't understand, but doesn't store them.
faceVal is today's face value on every record. LITL shows 1 in 2007, before its 2010
10 → 1 split. Div 30% and Prem Rs 30 therefore use the face value on the ex-date: today's
value divided by the factor of every later split. Check: KOTAKBANK 2008 Dividend - 7.50% gives
Rs 0.75.
Renamed symbols
NSE files old events under today's symbol. INFY's 2006 bonus is listed as INFY, but it traded
as INFOSYSTCH until 2011-06-29, and our prices are stored under INFOSYSTCH. The parser walks
symbolchange.csv backwards (following chains) to the symbol that traded on the ex-date, and notes
NSE lists it as INFY. This moved 4,050 events. Actions with no prices around them dropped from
2,825 to 231.
Factors
| Action | factor (applied to bars before the ex-date) | Set by |
|---|---|---|
| Split old → new face value | new/old | parse |
| Bonus a:b | b/(a+b) | parse |
| Rights a:b at issue price I | TERP/P, where TERP = (b·P + a·I)/(a+b) and P = cum-date close; 1 if I ≥ P | reconcile |
| Dividend D | (P − D)/P, total-return series only | reconcile |
| ADJUST (detected) | snapped common factor (or the raw ratio) | reconcile |
Special dividends (fixed 2026-09-27): a big special dividend also shows up as a detected price jump. In
total-return mode, factors() / all_factors() drop an ADJUST row when a dividend on the same day already
explains it (within 15%). Otherwise it was counted twice: STAR 2013-12-19 (₹500 special dividend, factor 0.433,
plus a detected "bonus" of 0.417) showed +135% on the ex-day instead of −2%.
Before 2006, NSE's records have almost no splits or bonuses (1–2 a year, against 30–80 a year from 2006).
The real events exist only as detected jumps, most of them still REVIEW (e.g. ITC 2005-09-21, WIPRO
2004-06-25, TVSMOTOR 2003-12-18). Until they are reviewed, adjusted prices before 2006 show those days as crashes.
Reconcile
-
Price check of every NSE split, bonus and rights date:
- cum close = the last row before the ex-date;
- expected factor = the product of that day's non-ignored split, bonus and rights factors;
- the ex-date open or close over the cum close must be within ±20% of the expected factor (in log terms).
Result Status Gap is there AUTO(gap ok)Factor within 12% of 1, which a normal day can't be told apart from AUTO(weak)No gap, but a matching jump within ±15 days REVIEW, with that date in the noteNo gap REVIEWNo factor yet (e.g. rights with no issue price) REVIEW -
Gap detector looks at every day where the close fell below 0.75× (or rose above 1.6×) the previous close, the open agreed, and the median of the next 5 closes stayed there. That last condition filters out one-day bad prints.
- Jumps within 10 days of a listed split, bonus, rights, scheme or symbol change are "explained" and skipped.
- The rest become
ADJUST/DETECTED/REVIEWrows, with the factor snapped to a common one. The label lists every action that gives it, likeFV 10->5 or FV 2->1 or bonus 1:1. [high]means the open, the close and the next closes all sit within 6% of the snapped factor, with no trading gap over 7 days and a previous close of at least Rs 2. Penny stocks flipping between Rs 0.05 and 0.10 otherwise look like perfect 2× consolidations.- Everything else is
[low]: mostly illiquid stocks with erratic prices.
-
Inferred delistings: stocks with no row in the last 45 days, and no NSE delisting or symbol change, get
DELIST/DETECTED/AUTO(information only; nothing is adjusted). -
Review list: every
REVIEWrow goes toLOG_PATH/corp_actions_review.csv.
Reconcile gives the same result every time it runs. The expected factor uses all non-ignored claims, so a row marked REVIEW last run doesn't flip back to AUTO.
Results (local, 2026-09-27)
| Action | AUTO | REVIEW | SKIP |
|---|---|---|---|
| DIVIDEND | 26,556 | 163 (no amount) | 103 (nil) |
| BONUS | 875 | 9 | 18 (debenture / preference / DVR) |
| SPLIT | 769 | 3 | |
| RIGHTS | 401 | 32 (no price, or mixed instruments) | 5 |
| SYMBOL_CHANGE | 805 | 11 | |
| DELIST | 328 NSE + 1,662 inferred | ||
| OTHER (demerger / scheme) | 239 | ||
| ADJUST (detected) | 3,604 (590 high, 3,014 low) |
NSE's list is confirmed by our prices: 1,719 of 1,731 checkable split, bonus and rights dates show the expected gap (99.3%). Another 333 are "weak" (factor too close to 1), and 231 have no prices around the ex-date.
High-confidence detections are real actions NSE's list leaves out. Examples:
- ETF unit splits (NIFTYBEES 1:10 on 2019-12-19, IGOLD, HDFCNIFETF);
- 1997–2004 bonuses and splits (INFOSYSTCH 1999 and 2004, RELIANCE 1997, HCLTECH 2000).
accept-high --apply verifies all of them at once, after a spot check.
accept-high --apply was run on 2026-09-27: all 590 are VERIFIED, so they are applied.
Long-gap detections are not corporate actions. Every detected note ends with
prev row YYYY-MM-DD (Nd): the previous NSE price row and how many days back it is. When the gap is
long, the "jump" compares a price from years ago with today's price. The stock was suspended, or
traded only on BSE in between (on 2026-04-20 many stocks came back to NSE trading after a gap
since about 2000–2002: HAWKINCOOK, NIRLON, WIMPLAST, TRANSPEK...). The factor is meaningless, and the
review chart has no bars before the ex-date, so Raw and With-this-factor look the same.
ignore-gaps marks these IGNORED (default gap of 365 days or more, --min-days to change it) and
appends | auto-ignored: long gap to the note. IGNORED survives every reconcile. On 2026-09-28
there were 139 such rows with a gap of 365 days or more, and 238 with a gap of 90 days or more. The review page shows a gap Nd badge
on any detected row with a gap over 90 days.
Adjusted prices (phase 3)
Adjustment is computed on read. There is no second copy of the history, and a newly verified action takes effect on the next read.
from nseeod import eq_store
eq_store.get_eod("RELIANCE") # raw (default, unchanged for every existing caller)
eq_store.get_eod("RELIANCE", adjust="price") # split / bonus / rights / verified jumps
eq_store.get_eod("RELIANCE", adjust="total") # + dividends (total-return series)
eq_store.get_eod("INFY", adjust="price", follow_renames=True) # + INFOSYSTCH's rows before 2011-06-29
- Today's terms: every bar before an ex-date is multiplied by that event's factor (the product over all later events).
- Columns:
- OHLC,
slast,avgpriceand the 5/15-minute prices are multiplied by the factor; svolumeanddelqtyare divided by the share-count part only (split / bonus / detected jump);svalueis unchanged;prevcloseuses the previous row's multiplier, because it's the prior day's price;- an
adj_factorcolumn is added (1.0 = unchanged).
- OHLC,
- Which events:
AUTO/VERIFIEDrows with a factor.REVIEWrows are never applied.- Events come from the whole rename family (
corp_actions.family()), so an old symbol's rows are also in today's terms. OTHERrows (demergers) apply only once a factor has been entered and the row verified.
follow_renameswalksSYMBOL_CHANGErows backwards (corp_actions.predecessors()). It takes each earlier symbol's rows before its change date. INFY becomes one series from 1994.- Chart:
GET /api/chart-data?...&adjust=none|price|total(defaultprice) always joins renamed histories;/chart-data/exporttakes the same parameter.- The Dashboard has Raw / Adj / TR buttons for SPOT daily-and-above charts; the choice is remembered.
- Intraday charts and IEOD / audit readers stay raw.
Checks (local):
- RELIANCE: 4 raw one-day moves of more than 30% become 0 adjusted. Across the 2017 bonus date the adjusted closes are 407.49 and 405.21.
- LITL: bars before the 2010 split are scaled by 0.1;
prevcloseon the ex-date is consistent. adjust='none'returns exactly the old reader's frame.- INFY with renames: 7,869 rows, 1994-11-03 → today. Two gaps remain, 1997-08-20 and 2000-01-27; these are
[low]detected jumps (a 1:1 bonus and a 10 → 5 split) waiting for review.
Daily sync (phase 4)
After every Bhav Downloader run (full sync and single date), BhavProcessor._sync_corp_actions() calls
corp_actions.daily_sync():
- Re-fetches ex-dates from 30 days back to 60 days ahead, for both boards, and merges new records into the year files in
Config.CORPACT_PATH. - Refreshes the three CSVs and the manifest.
- Runs
parse --applyandreconcile --apply.
It takes about 75 seconds. It is best-effort: it runs after the status is final and AMI is
written, and a failure only adds a CorpActions log line. The job log gets one line, for example
Corporate actions: 3 new record(s) (...); 3139 row(s) to review.
| Setting | Local | VPS |
|---|---|---|
Config.CORPACT_PATH | LOCAL_CORPACT_PATH=D:/kss/stock/EODData/NSE_CA | VPS_CORPACT_PATH=/home/kss/EODData/NSE_CA (add it to the VPS backend/.env) |
If the folder has no year files, the sync logs a message and does nothing. Run download once first,
or copy the local backup up.
CLI equivalent: python -m nseeod.corp_actions daily.
Review page (phase 4)
Sidebar → Corporate Actions (/corporate-actions, DEVELOPER). API: backend/app/api/corp_actions.py.
| Endpoint | Use |
|---|---|
GET /api/corp-actions/summary?universe=&as_of= | Counts by action and status; detected [high] / [low] still to review; sync state |
GET /api/corp-actions?status=&action=&source=&tier=&symbol=&from_date=&to_date=&universe=&as_of=&limit=&offset= | Filtered list, newest ex-date first |
GET /api/corp-actions/universes | Choices for the universe filter: SME + every index with membership history (TE-FO INDEX, NIFTY 50, NIFTY 500 ...) |
GET /api/corp-actions/{id}/preview?days=30 | Raw closes around the ex-date, and the same closes as if this factor applied |
PATCH /api/corp-actions/{id} | {status, factor, note}: a human decision |
POST /api/corp-actions/bulk | {ids, status} |
POST /api/corp-actions | Hand-entered action: source MANUAL, status VERIFIED |
POST /api/corp-actions/sync | Run daily_sync now (background) |
Page layout:
- Review chips per action, which also work as filters.
- Universe (any of) + As on (added 2026-10-03): pick one or more of SME, TE-FO Index and the tracked NSE indices.
- The list and the chip counts keep rows of stocks in any chosen set on the as-on date (default today).
- Index membership is survivorship-free (
idx_members_on). A row matches onmasidor on the symbol, since index lists use the symbol that traded then. - SME =
scr_master.typ = 10stocks trading on the date: first EOD row on or before it, last row within 45 days. - Nothing chosen = all stocks.
- Example: TE-FO + NIFTY 500 on 2005-01-01 leaves 314 of 3,384 REVIEW rows, and SME today leaves 6.
- The logic is shared with the Stock Universe page:
nseeod/universe.py(index-members.md).
- A table with Verify / Ignore / Back-to-review on each row, plus bulk actions.
- A side panel with the preview chart: grey is raw; blue is with this factor, and should be continuous across the dashed ex-date line.
- Factor and note editing, and a manual-add form (e.g. demerger factors).
- Dates show as dd-mm-yyyy.
Guards:
- Price-changing actions can't be verified without a factor; bulk-verify skips those rows.
- A factor must be between 0 and 100.
- Decisions take effect on the next chart read, with nothing to rebuild.
Rights-entitlement symbols (-RE, -RE1 …) are excluded from the gap detector. They trade for a
few days and collapse to zero by design (84 jumps).
OTHER rows, like the RELIANCE / Jio Financial demerger on 2023-07-20, are never applied
automatically. Enter the factor (MANUAL or VERIFIED with a factor) during review.