# Moving Average Convergence/Divergence (MACD)

The **MACD** is a momentum indicator derived from two exponential moving averages. It highlights trend strength, direction, and potential crossover signals. Each result row contains three values: the MACD line, the signal line, and the histogram (the difference between the two).

Use MACD with [Aggregates](/docs/aggregates), [Options Chain API](/options-chain-api), [Historical Options Data API](/historical-options-data-api), [Backtesting Data Quality Checklist](/docs/backtesting-data-quality-checklist), and [Stock Aggregates and Indicators](/docs/stock-aggregates-indicators).

Use cases: momentum analysis, crossover signals, spotting overbought/oversold conditions, and confirming trend direction.

<div data-try-url="/v1/options/indicators/macd/O:NFLX260402C00075000/?timespan=day&limit=10"></div>

## Endpoint

```
GET /v1/options/indicators/macd/{ticker}
```

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `ticker` | string | Yes | Full options ticker (for example `O:NFLX260402C00075000`). |

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `timestamp` | string | No | Anchor time: `YYYY-MM-DD` or **millisecond** Unix timestamp. |
| `timestamp.gte` | string | No | Range lower bound (date or ms timestamp). |
| `timestamp.gt` | string | No | Strictly greater. |
| `timestamp.lte` | string | No | Range upper bound. |
| `timestamp.lt` | string | No | Strictly less. |
| `timespan` | string | No | Aggregate bar width: `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`. |
| `adjusted` | boolean | No | Use split-adjusted aggregates when `true` (default). `false` uses non-adjusted bars. |
| `short_window` | integer | No | Short EMA length used for the MACD line (commonly `12`). |
| `long_window` | integer | No | Long EMA length used for the MACD line (commonly `26`). |
| `signal_window` | integer | No | Smoothing window for the signal line (commonly `9`). |
| `series_type` | string | No | Which aggregate field drives the calculation (commonly `close`). |
| `expand_underlying` | boolean | No | When `true`, `results.underlying` includes an `aggregates` array and a `url` for the matching [aggregates](/docs/aggregates) range. When `false` or omitted, `underlying` is omitted. |
| `order` | string | No | Sort order of points by timestamp (`asc` / `desc`). |
| `limit` | integer | No | Max points returned. Default **10**, maximum **1000**. |
| `page` | string | No | Pagination continuation: use the URL in `next_url`, or pass the `page` query value from that URL here. |

### Response

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Outcome (for example `OK`). |
| `request_id` | string | Unique identifier for this request, assigned by CuteMarkets. |
| `results` | object | Indicator payload. |
| `next_url` | string | When more values exist, full URL for the next page. |

Use `limit` and timestamp filters per page; follow `next_url` when present.

`results` contains:

| Field | Type | Description |
| --- | --- | --- |
| `values` | array | MACD data points: see fields below. |
| `underlying` | object | **Only when** you pass `expand_underlying=true`. Contains `aggregates` and `url`: an absolute URL to the same contract's aggregates over the inferred date range (for example `https://api.cutemarkets.com/v1/options/aggs/{ticker}/1/day/{from}/{to}/`). |

Each object in `values` contains:

| Field | Type | Description |
| --- | --- | --- |
| `timestamp` | integer | Millisecond Unix timestamp of the bar. |
| `value` | number | MACD line (short EMA minus long EMA). |
| `signal` | number | Signal line (EMA of the MACD line). |
| `histogram` | number | `value` minus `signal`. |

### Example request

```bash
curl \
  "https://api.cutemarkets.com/v1/options/indicators/macd/O:NFLX260402C00075000/?timespan=day&short_window=12&long_window=26&signal_window=9&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Sample response

```json
{
  "results": {
    "values": [
      { "timestamp": 1775102400000, "value": 1.5792238252289934, "signal": 1.743386105515799, "histogram": -0.16416228028680568 },
      { "timestamp": 1775016000000, "value": 1.358035555688602,  "signal": 1.7844266755875005, "histogram": -0.42639111989889855 },
      { "timestamp": 1774929600000, "value": 1.2596020108470398, "signal": 1.8910244555622249, "histogram": -0.631422444715185 }
    ]
  },
  "status": "OK",
  "request_id": "cm_6b4abb381e65434da465c527122093d9"
}
```

## MACD-specific behavior

MACD is a two-speed momentum measure. The short EMA reacts first, the long EMA reacts more slowly, and the signal line smooths the difference. On option contracts, that structure can be useful when the contract has enough regular activity to support indicator math, but it can be misleading on contracts that trade only occasionally.

For options, interpret MACD beside the underlying, implied volatility, and liquidity. A bullish-looking MACD histogram on a call can come from underlying movement, IV expansion, or one sparse premium print. A bearish histogram on a put can reflect the opposite mechanics. The indicator is easier to trust when quotes are recent, spreads are controlled, and the contract has enough volume in the lookback period.

| Check | MACD guidance | Why it matters |
| --- | --- | --- |
| Window fit | Keep `short_window` lower than `long_window` and store both values. | Reproducibility depends on the exact smoothing inputs. |
| Contract liquidity | Require recent quotes or trades before ranking contracts. | Sparse prints can distort the two EMA lines. |
| Signal confirmation | Compare histogram changes with IV, delta, and underlying movement. | Option premiums move for several reasons at once. |

## Implementation note

When MACD drives a scanner or alert, persist the full parameter set: `ticker`, `timespan`, `short_window`, `long_window`, `signal_window`, `series_type`, and `adjusted`. Pair the MACD value with the latest quote timestamp and spread so a later review can distinguish a real momentum change from an illiquid-contract artifact.

MACD is only as reliable as the aggregates behind it, so connect this endpoint to [Aggregates](/docs/aggregates), [Stock Aggregates and Indicators](/docs/stock-aggregates-indicators), and [Backtesting Data Quality Checklist](/docs/backtesting-data-quality-checklist). Track fast EMA, slow EMA, signal line, histogram, warm-up, split adjustment, and session timestamp rules before using it as a trading signal.

## MACD implementation notes

MACD needs more metadata than a value column. Store fast length, slow length, signal length, source timespan, adjusted flag, warm-up length, and the bar timestamp used for each calculation. If a UI shows MACD beside current stock snapshots, label whether the indicator came from completed historical bars or a live refresh path.

MACD signals often feed momentum screens. When a momentum screen hands a ticker into options research, carry the stock signal timestamp into [Expirations](/docs/expirations), [Option Chain](/docs/option-chain), and [Quotes](/docs/quotes). That timestamp prevents the option selector from using a later chain snapshot or Greek value. The [Stock and Options Data Join Workflow](/docs/stock-options-data-join-workflow) is the safer model than a date-only join.

The histogram is not an execution signal by itself. A production screen still needs market session labels, halted-symbol handling, stale snapshot labels, and corporate-action awareness from [Stock Reference](/docs/stock-reference). For research, log rejected bars when the warm-up is incomplete or the requested window crosses a split without the expected adjustment policy.

Use MACD sparingly in options scanners. Short-dated option fills are usually more sensitive to spread, quote age, and IV than to small indicator changes. If a MACD filter selects a contract, the artifact should still include OCC symbol, DTE bucket, bid, ask, quote timestamp, open interest, and reject reasons.