# Corporate actions

> Splits, dividends, symbol changes and mergers of US equities, and split- or dividend-adjusted bars on request.

Source: https://getmarkethistory.com/docs/corporate-actions

`stocks` publishes the corporate actions of the listings it carries: forward and reverse splits,
cash dividends with their ex, record and payment dates, symbol changes, mergers, spin-offs and the
rest, from 2016 on. New actions are added with the nightly bars.

The bars themselves are **never rewritten**: they are stored as traded. An adjusted series is
computed from the actions only when a bars query asks for one with `adjust=`.

## Query

curl:

```bash
curl -sD - "https://getmarkethistory.com/query/v1/corporate-actions?symbol=AAPL&start=2020-08-01&end=2020-09-30" \
  -H "Authorization: Bearer $MARKET_HISTORY_KEY"
```

Python client:

```python
from markethistory import Client

mh = Client()  # reads MARKET_HISTORY_KEY

actions = mh.corporate_actions("AAPL", start="2020-08-01", end="2020-09-30")
[(a["type"], a["ex_date"], a["rate"]) for a in actions]
```

Plain `requests`:

```python
import json
import os

import requests

url = "https://getmarkethistory.com/query/v1/corporate-actions"
params = {"symbol": "AAPL", "start": "2020-08-01", "end": "2020-09-30"}
headers = {"Authorization": f"Bearer {os.environ['MARKET_HISTORY_KEY']}"}

rows = []
while True:
    r = requests.get(url, params=params, headers=headers, timeout=60)
    r.raise_for_status()  # see /docs/errors for what each status means
    rows += [json.loads(line) for line in r.text.splitlines() if line]
    print(r.headers["X-Row-Count"], "rows,", r.headers["X-Bars-Charged"], "bars")
    if "X-Next-Cursor" not in r.headers:
        break
    params["cursor"] = r.headers["X-Next-Cursor"]
```

Response (shape and headers as served; values illustrative):

```http
HTTP/2 200
content-type: application/x-ndjson
x-row-count: 2
x-bars-charged: 0

{"cusip":"037833100","due_bill_redemption_date":null,"ex_date":"2020-08-07","extra":null,"foreign":false,"id":"5f2c…","new_rate":null,"old_rate":null,"payable_date":"2020-08-13","process_date":"2020-08-07","rate":0.82,"record_date":"2020-08-10","special":false,"symbol":"AAPL","type":"cash_dividends"}
{"cusip":"037833100","due_bill_redemption_date":null,"ex_date":"2020-08-31","extra":null,"foreign":null,"id":"5f4d…","new_rate":4.0,"old_rate":1.0,"payable_date":"2020-08-28","process_date":"2020-08-31","rate":4.0,"record_date":"2020-08-24","special":null,"symbol":"AAPL","type":"forward_splits"}
```

| Parameter      | Meaning                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `symbol`       | One or more tickers, comma-separated (at most 50). Required.                                                |
| `source`       | Optional: `stocks`, the only source with corporate actions.                                                 |
| `start`, `end` | Date range, inclusive, on `ex_date` (or `process_date` when the action has no ex-date). Default: all of it. |
| `format`       | `jsonl` (default), `csv`, `json`, `parquet` or `arrow`. `mbt1` is bars only.                                |

Rows come by symbol in the order asked, then by date. There is no paging: a ticker has tens of
rows. A ticker with no actions returns no rows.

## Columns

| Column                     | Type   | Meaning                                                                                                     |
| -------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `type`                     | string | what happened; see below                                                                                    |
| `symbol`                   | string | the ticker whose bars the action affects                                                                    |
| `id`                       | string | a stable identifier of the action                                                                           |
| `ex_date`                  | date   | the first session that trades without the dividend, or on the new share count                               |
| `record_date`              | date   | holders of record on this date receive it                                                                   |
| `payable_date`             | date   | the payment date                                                                                            |
| `process_date`             | date   | when the action was processed; the only date of most symbol changes and mergers                             |
| `due_bill_redemption_date` | date   | when due bills on a split or large dividend settle                                                          |
| `cusip`                    | string | the security's CUSIP                                                                                        |
| `rate`                     | float  | a cash dividend's amount per share, in the price's currency; for a split, `new_rate / old_rate`             |
| `old_rate`, `new_rate`     | float  | the two legs of a split: AAPL's 4-for-1 is `old_rate` 1, `new_rate` 4; a 1-for-10 reverse split is 10 and 1 |
| `special`, `foreign`       | bool   | a special (non-recurring) dividend; a dividend from a foreign issuer                                        |
| `extra`                    | string | a JSON object with the action's other fields, such as the other ticker of a pair                            |

On some older split rows `rate` is empty: use `new_rate / old_rate`, as `adjust=` does. A dividend
amount is the one declared for its ex-date, in the shares of that date: it is not restated for
later splits.

`type` is one of `forward_splits`, `reverse_splits`, `cash_dividends`, `stock_dividends`,
`unit_splits`, `spin_offs`, `name_changes`, `cash_mergers`, `stock_mergers`,
`stock_and_cash_mergers`, `rights_distributions`, `capital_gains_distributions`,
`reorganizations`, `partial_calls`, `redemptions` or `worthless_removals`; new types may appear.
A symbol change, merger, spin-off or unit split names two tickers. Its row is filed under the one
that already has bars (the old ticker, the company acquired, the parent) and the other one is in
`extra` (`new_symbol`, `acquirer_symbol`, …).

## Adjusted bars

Add `adjust=` to a bars query on `stocks`:

```bash
curl -s "https://getmarkethistory.com/query/v1/bars/stocks/AAPL/1d?start=2020-08-24&end=2020-09-04&adjust=splits" \
  -H "Authorization: Bearer $MH_KEY"
```

| `adjust` | Prices                                                      |
| -------- | ----------------------------------------------------------- |
| `raw`    | as traded. The default.                                     |
| `splits` | adjusted for forward and reverse splits.                    |
| `all`    | adjusted for splits and cash dividends (total-return view). |

Other sources answer 400 to `adjust=splits` or `all`, and so does the free sample. The rules are
exact:

- **Which actions.** `splits` applies `forward_splits` and `reverse_splits`; `all` also applies
  `cash_dividends`. Spin-offs, stock dividends and mergers are never applied. An action whose
  `ex_date` is after today (New York) is announced, not effective, and is ignored.
- **Which bars.** An action applies to every bar that opens before its ex-date begins: 00:00
  America/New_York on the ex-date for minute and hour bars, so the previous session's after-hours
  is before it and the ex-date's pre-market is not. Coarser bars built from minutes, such as `1d`,
  are adjusted minute by minute and then aggregated.
- **Split factor.** `S` is the product of `new_rate / old_rate` over the splits that apply to the
  bar: 4 before AAPL's 4-for-1, 0.1 before a 1-for-10 reverse split, 1 when none apply.
- **Dividend factor** (`all` only). `D` is the product of `1 − d / C` over the cash dividends that
  apply to the bar, where `d` is the dividend per share and `C` is the raw close of the last bar
  before the ex-date begins (for minute data, the last minute traded, after-hours included). This
  is the standard multiplicative back-adjustment: a return computed from adjusted closes includes
  the dividend. A dividend with no bar in the 30 days before its ex-date, or one at least as large
  as `C`, is skipped. `D` is 1 under `splits`.
- **Prices.** `open`, `high`, `low`, `close` and `vwap` become `price / S × D`.
- **Volume.** `volume` becomes `volume × S`: the same turnover in today's shares. Dividends never
  change it. After a reverse split it can be fractional.
- **Everything else**, `trade_count` included, is unchanged. Bars after the newest applied action
  equal the raw ones. Adjusted prices are not rounded.

Examples: AAPL closed at 499.23 on 2020-08-28, the session before its 4-for-1; with `adjust=splits`
that close is 124.8075 and its volume is four times the raw one. NVDA's 10-for-1 took effect on
2024-06-10: a 1,200.00 trade on 2024-06-07 reads 120.00. A stock that closed at 80.00 before a 0.50
dividend gets `D = 1 − 0.50 / 80.00 = 0.99375`, so every earlier price is 0.625% lower.

An adjusted history changes whenever a new split or dividend lands, and raw never does: to
reproduce a backtest exactly, keep the raw bars and the actions you used.

## Price

Free with any API key, whatever the balance: no bars are charged (`X-Bars-Charged: 0`). `adjust=`
does not change what a bars page costs. Requests still count toward the account's
[limits](https://getmarkethistory.com/docs/limits): 2 in flight and 300 a minute.