# Stock analytics API

7 endpoints under `https://apexvol.com/api/mcp/data`. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access. Web version: https://apexvol.com/developers/stock-analytics-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /borrow-rate/{ticker}` | Premium | Is NVDA hard to borrow, and is the borrow rate spiking? |
| `GET /cores/{ticker}` | Pro | What is in the raw analytics row the platform screens NVDA on? |
| `GET /correlation/{ticker}` | Premium | How tightly does NVDA track SPY and its sector ETF? |
| `GET /correlation/{ticker}/compare/{ticker2}` | Premium | How correlated are NVDA and AMD, and has it changed? |
| `GET /dividend/{ticker}` | Premium | What does AAPL pay, when is the next ex-date, and does the options market agree? |
| `GET /price-context/{ticker}` | Basic | Where is NVDA in its range, how is momentum, and how does IV compare with the move? |
| `GET /relative-value/{ticker}` | Pro | Is NVDA's IV rich or cheap relative to SPY and its sector? |

## GET /borrow-rate/{ticker}

Returns the current 30-day and 2-year borrow rates, the class and percentile, a squeeze score, spike detection with severity, sector comparison and the daily series.

- **Units:** Borrow rates in percent per year; percentiles 0 to 100.
- **Basis:** Options-implied borrow from the data feed; spikes are z-scores against the trailing series.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/borrow-rate.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `days` | query | 252 | 20 to 1000 | History length. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/borrow-rate/NVDA"
```

- `current.borrow30, borrow2yr, borrow_class, borrow_pctile`: The rate now.
- `spike_detected, spike_severity, squeeze_score`: The alert.
- `sector_comparison`: Versus the sector.
- `timeseries[].date, borrow30, is_spike`: The history.

## GET /cores/{ticker}

Returns the data feed's analytics row: IV summaries, IV and HV statistics, slope and contango, earnings-move components, borrow rates, betas and percentiles. Defaults to the curated 45-field subset the platform screens on; ask for specific fields or all.

- **Units:** Vendor units: IVs and HVs in percentage points, price changes in percentage points, borrow in percent, market cap in dollars. The row contains a numeric field named error, a model-fit statistic, not a failure.
- **Basis:** Vendor field names are returned as-is (iv30d, clsHv20d, ivPctile1y, slope, contango and so on).
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/cores.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `fields` | query | curated subset | CSV of field names, or all | Which fields to return. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/cores/NVDA"
```

- `iv30d, iv60d, ivPctile1y, exErnIv30d`: IV summaries.
- `clsHv20d, orHv20d, ivHvXernRatio`: Realized vol and the ratio.
- `slope, contango, dlt25Iv30d, dlt75Iv30d`: Skew and term.
- `impErnMv, absAvgErnMv, nextErn, daysToNextErn`: Earnings.
- `borrow30, beta1y, correlSpy1y, mktCap`: The rest.

## GET /correlation/{ticker}

Returns one-month and one-year correlation and beta to SPY and to the best sector ETF, with the IV-to-SPY ratio.

- **Units:** Correlations -1 to 1; beta unitless.
- **Basis:** Daily returns; best_etf is chosen by fit.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/correlation.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/correlation/NVDA"
```

- `correlations.spy_1m, spy_1y, etf_1m, etf_1y`: The correlations.
- `beta.beta_1m, beta_1y`: The betas.
- `best_etf, sector, iv_spy_ratio`: Context.

## GET /correlation/{ticker}/compare/{ticker2}

Returns a daily series of one-month and one-year correlation and one-month beta between the two tickers.

- **Units:** Correlations -1 to 1; beta unitless.
- **Basis:** Daily returns over days of history.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/correlation-compare.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `ticker2` (required) | path |  | symbol | The second ticker. |
| `days` | query | 400 | 20 to 1000 | History length. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/correlation/NVDA/compare/AMD"
```

- `timeseries[].date, correl1m, correl1y, beta1m`: The pair through time.
- `ticker1, ticker2`: Echo.

## GET /dividend/{ticker}

Returns the current dividend amount, frequency, yield and growth, the implied dividend from options versus the declared one, the next ex-date and the payment history.

- **Units:** Amounts in dollars per share; yields and growth in percent.
- **Basis:** Implied dividend from put-call parity on the chain; history from the data feed.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/dividend.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/dividend/AAPL"
```

- `current.div_amount, div_freq, div_yield, next_div_date`: The dividend now.
- `current.annual_implied, annual_actual, implied_vs_actual`: What options imply versus what is paid.
- `history[].ex_date, pay_date, amount`: Past payments.
- `cagr, pays_dividends`: Growth and flag.

## GET /price-context/{ticker}

A single flat payload with price and returns over 1 week to 1 year, the 52-week range position, momentum and vol regime labels, IV, realized vol, VRP, earnings timing and option activity, plus a plain-language quick take.

- **Units:** Returns and changes in percent; IV and HV in percentage points; vrp in points; volumes in shares or contracts.
- **Basis:** Daily bulk data from the feed; iv_30d is the 30-day constant-maturity IV.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/price-context.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/price-context/NVDA"
```

- `price, return_1w, return_1m, return_6m, return_1y`: Performance.
- `range_position, pct_from_high, pct_from_low`: Where in the 52-week range.
- `momentum_regime, vol_regime, flow_sentiment`: Labels with colors.
- `iv_30d, hv_20d, vrp, iv_pctile_1y`: Vol context.
- `quick_take, essentials_summary`: The sentence version.

## GET /relative-value/{ticker}

Returns the IV ratios to SPY and the sector ETF with their one-month and one-year averages, percentiles, z-scores, sigma bands, a signal and the ratio time series.

- **Units:** IVs in percentage points; ratios unitless; percentiles 0 to 100; vrp in points.
- **Basis:** Ratios use 30-day IV. The signal compares the current ratio to its one-year distribution.
- **Markdown:** https://apexvol.com/developers/stock-analytics-api/relative-value.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `days` | query | 252 | 20 to 1000 | History length for the series. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/relative-value/NVDA"
```

- `signal`: RICH, CHEAP or NEUTRAL versus the market.
- `ratios.iv_spy_ratio, iv_spy_ratio_avg_1y, iv_etf_ratio`: The ratios.
- `z_scores.spy_ratio_z, etf_ratio_z, percentiles`: How stretched.
- `timeseries[]`: The ratios through time.

Conventions: https://apexvol.com/developers/conventions. Errors: https://apexvol.com/developers/errors. Whole API in one file: https://apexvol.com/docs/api/apexvol-api.md