# Events and calendars API

3 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/events-calendar-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /earnings-calendar` | Basic | Who reports this week, and which names have the biggest move priced in? |
| `GET /economic-calendar` | Basic | When are CPI, FOMC and the jobs report over the next two weeks? |
| `GET /seasonality/{ticker}` | Pro | Which months have historically been strongest and weakest for NVDA? |

## GET /earnings-calendar

Lists reports over the next days_ahead with timing, estimates, the implied earnings move, the average move over the last twelve reports and the ratio of the two, plus a day grid for display.

- **Units:** implied_move and hist_avg_move in percent (expected absolute move); market_cap in dollars.
- **Basis:** implied_move is the feed's one-sigma figure times 0.8 so it shares hist_avg_move's basis; implied_move_basis says so and implied_move_sigma keeps the raw figure.
- **Markdown:** https://apexvol.com/developers/events-calendar-api/earnings-calendar.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `days_ahead` | query | 7 | 1 to 90 | How far ahead to look. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-calendar?days_ahead=7"
```

- `earnings[].symbol, company_name, date, timing`: Who and when.
- `earnings[].implied_move, hist_avg_move, move_ratio`: Priced versus typical.
- `earnings[].eps_estimate, revenue_estimate, market_cap, sector`: Context.
- `total_count, from_date, to_date`: The window.

## GET /economic-calendar

Returns scheduled macro events with date, time, impact level, estimate, previous and actual once released, grouped by date and as a flat list.

- **Units:** Values in the event's own unit (unit field); times are US Eastern.
- **Basis:** Economic calendar feed; country defaults to US.
- **Markdown:** https://apexvol.com/developers/events-calendar-api/economic-calendar.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `from_date` | query | today | YYYY-MM-DD | Start. |
| `to_date` | query | +14 days | YYYY-MM-DD | End. |
| `country` | query | US | ISO country | Which calendar. |

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

- `events[].event, date, time, impact`: What and when.
- `events[].estimate, previous, actual, unit`: The numbers.
- `high_count, medium_count`: How busy the window is.
- `by_date`: Events grouped per day.

## GET /seasonality/{ticker}

Returns per-month and per-quarter average and median returns with the sample size and volatility over the requested years, plus the best and worst months.

- **Units:** Returns and volatility in percent.
- **Basis:** Monthly close-to-close returns over analysis_years.
- **Markdown:** https://apexvol.com/developers/events-calendar-api/seasonality.md

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

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

- `monthly_seasonality.<month>.avg_return_pct, median_return_pct, volatility_pct, sample_size`: Per month.
- `quarterly_seasonality.<quarter>`: Per quarter.
- `best_month, worst_month`: The extremes.

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