# GET /api/mcp/data/price-context/{ticker}

> Where is NVDA in its range, how is momentum, and how does IV compare with the move?

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.

- **Family:** Stock analytics (https://apexvol.com/developers/stock-analytics-api)
- **Plan:** Basic and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **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.
- **MCP tools:** `get_ticker_analytics`
- **Background:** https://apexvol.com/learn/volatility-trading

## Parameters

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

## Request

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

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "avg_opt_volume_20d": 3290792,
    "avg_opt_volume_baseline": 3290792,
    "best_etf": "XLK",
    "beta_1m": 3.08,
    "beta_1y": 1.93,
    "borrow_30d": 3.42,
    "call_oi": 8454385,
    "call_volume": 3549509,
    "contango": 1.26,
    "correl_etf_1y": 0.27,
    "correl_spy_1y": 0.41,
    "daily_change": -0.06,
    "daily_change_pct": -0.03,
    "days_since_hi_52w": 117,
    "days_since_lo_52w": 368,
    "days_to_earnings": 71,
    "div_yield": 0.4,
    "earnings_flag": false,
    "essentials_summary": "92% up the 52-week range, option flow 1.7× the 20-day average",
    "flow_sentiment": {
      "color": "emerald",
      "label": "Bullish"
    },
    "forecast_20d": 32.03,
    "forecast_inf": 41.38,
    "hi_52w": 236.26,
    "hv_20d": 37.86,
    "hv_bars": [
      {
        "close": 44.28,
        "label": "5D",
        "open_range": 43.95
      },
      {
        "close": 56.93,
        "label": "10D",
        "open_range": 46.68
      },
      {
        "close": 44.92,
        "label": "20D",
        "open_range": 37.86
      }
    ],
    "implied_earnings_move": 4.8,
    "implied_earnings_move_sigma": 6.0,
    "implied_move": 4.8,
    "is_partial_session": false,
    "iv_30d": 33.05,
    "iv_etf_ratio": 2.8,
    "iv_pctile_1y": 11.9,
    "iv_spy_ratio": 2.8,
    "lo_52w": 163.85,
    "market_cap": 5561054100,
    "market_cap_fmt": "$5.56T",
    "momentum_regime": {
      "color": "green",
      "label": "Bullish"
    },
    "next_earnings": "2026-11-18",
    "pct_from_high": -2.52,
    "pct_from_low": 40.56,
    "price": 230.3,
    "price_1m": 219.22,
    "price_1w": 217.55,
    "price_1y": 171.43,
    "price_6m": 177.6,
    "prior_close": 230.36,
    "put_call_ratio_volume": 0.54,
    "put_oi": 7571013,
    "put_volume": 1906366,
    "quick_take": "NVDA is 3% off its 52-week high, in an extreme low vol regime.",
    "range_position": 91.8,
    "return_1m": 5.05,
    "return_1w": 5.86,
    "return_1y": 34.34,
    "return_6m": 29.67,
    "sector": "Technology",
    "session_progress": null,
    "stock_volume": 6443150,
    "ticker": "NVDA",
    "trade_date": "2026-09-04",
    "vol_regime": {
      "color": "cyan",
      "label": "Extreme Low"
    },
    "volume_as_of": "2026-09-04 20:55:19",
    "vrp": -4.8
  }
}
```

## Fields

- `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.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `424`: data feed unavailable, retry
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- Give me price context on NVDA: range, momentum and vol.
- Where is AAPL in its 52-week range?
- Summarise TSLA in one paragraph with the numbers.

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions