# QuantGist API Reference Summary

> REST and WebSocket API for real-time and historical economic data.

- Base URL: `https://api.quantgist.com/v1`
- Authentication: `X-API-Key` header
- API key format: `qg_live_<32chars>` (production) or `qg_test_<32chars>` (sandbox)
- All responses are JSON. All timestamps are UTC ISO 8601.
- Full interactive docs: https://quantgist.com/docs
- OpenAPI spec: https://api.quantgist.com/openapi.json

## Quickstart

```bash
# 1. Get a free API key at https://quantgist.com/signup
# 2. Fetch today's high-impact events
curl "https://api.quantgist.com/v1/events?impact=high&limit=5" \
  -H "X-API-Key: qg_live_your_key_here"
```

## Endpoints

### Events — GET /v1/events
Paginated list of macro and financial events.

Query parameters:
- `from_date` — ISO 8601 start of range (default: 7 days ago)
- `to_date` — ISO 8601 end of range
- `impact` — low | medium | high
- `currency` — ISO 4217 currency code (e.g. USD)
- `symbol` — ticker symbol filter (comma-separated)
- `event_type` — earnings | fomc | cpi | nfp | gdp | pmi | other
- `q` — full-text search
- `page` — page number (default 1)
- `per_page` — results per page (max 100, default 20)

Example response:
```json
{
  "data": [{
    "id": "evt_01HX9M3K4R2BGCZ8JQNVP7YW5E",
    "event_type": "nfp",
    "title": "US Non-Farm Payrolls (Mar 2024)",
    "currency": "USD",
    "impact": "high",
    "release_time": "2024-04-05T12:30:00Z",
    "actual": 303000,
    "forecast": 214000,
    "previous": 270000,
    "surprise_pct": 41.6,
    "sentiment_score": 0.82
  }],
  "meta": { "page": 1, "page_size": 20, "total": 1842, "has_more": true }
}
```

### Single Event — GET /v1/events/{event_id}
Full event object. Key response fields: `id`, `event_type`, `title`, `currency`, `symbol`, `impact`, `release_time`, `actual`, `forecast`, `previous`, `surprise_pct`, `sentiment_score`, `impact_score`, `summary`, `tags`.

### Historical Data — GET /v1/events/historical
Raw bulk download. Requires `from_date` and `to_date`. Supports `format=ndjson` for streaming. NDJSON bulk download requires Enterprise plan. Use `/v2/backtest` for strategy-ready macro backtests.

### Calendar — GET /v1/calendar
Today's economic calendar. Optional `date` (YYYY-MM-DD), `currency`, `impact`, `include_actual`.

### Calendar Range — GET /v1/calendar/range
Multi-day calendar. Requires `date_from` and `date_to` (max +30 days). Optional `currency`, `impact`.

### Macro Shortcuts — GET /v1/macro/*
Trader-friendly convenience wrappers for well-known macro releases.

- `GET /v1/macro/events` — list all supported aliases
- `GET /v1/macro/latest?event=NFP` — most recent released value
- `GET /v1/macro/upcoming?event=CPI` — next scheduled release
- `GET /v1/macro/calendar?events=CPI,NFP,FOMC&days=14` — grouped upcoming

Supported aliases: `NFP`, `CPI`, `PCE`, `FOMC`, `GDP`, `UNEMPLOYMENT`, `RETAIL_SALES`, `PPI`, `ISM`, `ECB`, `HICP`.

### News — GET /v1/news
Financial news headlines from Bloomberg, WSJ, CNBC, NYT, Yahoo Finance. Ingested every 20 minutes. Parameters: `source`, `currency`, `symbol`, `impact`, `q`, `page`.

### News Radar — GET /v1/news/radar
Scored, asset-linked market-risk clusters grouped by topic pack. Each cluster has `impact_score` [0,1], `affected_assets` ticker list, lifecycle `status`, and AI-generated `why_it_matters` summary.

Parameters: `topic`, `symbols`, `min_impact`, `event_type`, `status`, `lookback_hours`, `limit`.

Topic packs: `iran-war`, `middle-east-risk`, `oil-supply`, `sanctions`, `trump-posts`, `central-bank-unscheduled`, `cyberattack`, `ceasefire`, `opec`.

### News Topics — GET /v1/news/topics
Catalogue of all News Radar topic packs with affected tickers and asset-class breakdown.

### News Watchlists — GET/POST/DELETE /v1/news/watchlists
Subscribe to topic packs for automatic alert creation. Requires Starter+.

### News Alerts — GET /v1/news/alerts
Alerts created when a cluster crosses your watchlist threshold. Acknowledge with `POST /v1/news/alerts/{id}/ack` or clear all with `POST /v1/news/alerts/ack-all`.

### Earnings — GET /v1/earnings
Earnings data sourced from Alpha Vantage + SEC EDGAR 8-K filings.

Key endpoints:
- `GET /v1/earnings` — paginated list (filter by ticker, date_from, date_to, beat_miss)
- `GET /v1/earnings/upcoming` — next 30 days
- `GET /v1/earnings/{ticker}` — most recent for a ticker
- `GET /v1/earnings/{ticker}/summary` — beat/miss statistics
- `GET /v1/earnings/{ticker}/history` — full history (Pro+)
- `GET /v1/earnings/surprises` — top EPS surprises
- `GET /v1/earnings/movers` — stocks with largest post-earnings moves
- `GET /v1/earnings/season/summary` — aggregate beat rate for current season

### Market Overview — GET /v1/markets/*
Cached daily quote snapshots for indexes (SPY, QQQ, DIA), equities (AAPL, MSFT, GOOGL, NVDA, AMZN), and commodities (GLD, USO). Sourced from Alpha Vantage. The `recency` field reports `delayed_15m` during US market hours or `previous_close` for end-of-day snapshots.

Endpoints: `/v1/markets/overview`, `/v1/markets/indexes`, `/v1/markets/equities`, `/v1/markets/sectors`, `/v1/markets/currencies`, `/v1/markets/commodities`, `/v1/markets/{symbol}`.

### Intelligence — GET /v1/intelligence/*
- `GET /v1/intelligence/surprises` — events ranked by surprise magnitude (Starter+)
- `GET /v1/intelligence/movers` — events ranked by market-impact potential (Starter+)

### Sentiment — GET /v1/sentiment/*
- `GET /v1/sentiment/summary` — aggregate sentiment grouped by currency/country/event_type/sector (Starter+)
- `GET /v1/sentiment/events` — paginated events filtered by sentiment score (Starter+)

### Data Export — GET /v1/data/export
Bulk streaming export (NDJSON or CSV). Requires `from_date`, `to_date`. Pro+ plan required.

### WebSocket — wss://api.quantgist.com/v1/stream
Real-time event stream. Authenticate via `?api_key=qg_live_...` query param. Subscribe with `{"type":"subscribe","currencies":["USD"],"impact":["high"]}`. Server sends snapshot on connect, then pushes new events.

### Changelog — GET /v1/changelog
Public API changelog. No authentication required.

## v2 API (Beta — Pro+)

Base URL: `https://api.quantgist.com/v2`

- `GET /v2/events` — point-in-time queries with `?as_of=2024-06-15`, official-source filtering
- `GET /v2/backtest` — backtest-safe historical series with first-print vintages, official release timing, and `canonical_id`
- `GET /v2/backtest/coverage` — coverage matrix per canonical_id with `backtest_grade` flag

## SDKs

```bash
pip install quantgist        # Python SDK
npm install quantgist        # JavaScript SDK
pip install quantgist-mcp    # MCP Server for Claude Desktop / Claude Code
uv tool install qgist        # CLI tool
```

- Python SDK: https://github.com/QuantGist-Technologies/quantgist-SDK-python
- JavaScript SDK: https://github.com/QuantGist-Technologies/QuantGist_SDK_js
- MCP Server: exposes `get_upcoming_events`, `get_events_range`, `check_safe_to_trade`, `get_economic_calendar`, `get_event_detail`

## Error Codes

| Status | Meaning |
|--------|---------|
| 401 | No API key or invalid format |
| 402 | Plan upgrade required for this endpoint |
| 403 | Valid key but plan doesn't include this feature |
| 404 | Resource not found |
| 429 | Rate limit exceeded — check `Retry-After` header |

## Links

- Interactive API docs: https://quantgist.com/docs
- OpenAPI spec: https://api.quantgist.com/openapi.json
- Sign up: https://quantgist.com/signup
- Pricing: https://quantgist.com/pricing