/massive-api-patterns

name: massive-api-patterns
description: Foundation skill for any REST workflow hitting api.massive.com. Use when calling any /v1, /v2, /v3 endpoint. Covers auth header, rate limit handling, pagination, and the best-price fallback chain. Every other REST-using skill depends on this.

massive-api-patterns

The REST foundation. Every skill that calls `api.massive.com` reads these rules first.

Auth

API key goes in the `Authorization` header as a bearer token:

Authorization: Bearer ${MASSIVE_API_KEY}

Query-string auth (`?apiKey=...`) also works but logs the key in URLs. Use the header.

Rate limits

• **Free Basic:** 5 requests per minute. Hard cap. 429 if you exceed it.
• **Any paid tier:** unlimited requests per minute. Soft cap at 100

requests per second to avoid throttling.

The skills in this repo declare their rate assumptions in `requires.yml`. A skill that fans out parallel calls will warn the user if it detects a free key.

Always handle 429 explicitly: back off with exponential delay, retry once, then surface the error.

Pagination

List endpoints return a `next_url` field when more results exist:

{
  "results": [...],
  "next_url": "https://api.massive.com/v3/reference/tickers?cursor=..."
}

Follow `next_url` directly, don't reconstruct it. The cursor is opaque and includes auth context.

The best-price fallback chain

Never quote a price from a single field. The v2 snapshot response nests everything under `ticker`, so all reads start there. Walk this 4-step chain and stop at the first non-null value:

1. `snapshot.ticker.lastTrade.p` (most recent trade across exchanges) 2. `snapshot.ticker.min.c` (current minute bar close, intraday only) 3. `snapshot.ticker.day.c` (today's session close) 4. `snapshot.ticker.prevDay.c` (previous session close, off-hours or quiet names)

Always emit the timestamp of whichever field won so the caller knows how stale the price is. `lastTrade.t` and `min.t` are nanosecond epochs; the daily fields don't always carry a timestamp.

`lib/quant_garage/snapshot.py::resolve_price` is the canonical implementation. Every skill in this repo that needs a current price imports it rather than rewriting the walk.

This is the generic REST pattern. Massive's proprietary **FMV** metric is a different thing (Business plan, stream-only on the WebSocket FMV channel) and not what these skills mean by "fair value." It is not a field on the v2 snapshot response.

Error codes

| Code | Meaning | What to do | |---|---|---| | 401 | Bad or missing API key | Surface immediately, don't retry | | 403 | Endpoint not available on user's plan | Surface with plan upgrade hint | | 404 | Ticker or contract not found | Skip, don't retry | | 429 | Rate limited | Back off, retry once | | 5xx | Server error | Retry with exponential backoff, max 3 attempts |

Real-time vs delayed

Stocks REST is 15-minute delayed on Basic, Starter, and Developer tiers. Real-time stocks need Advanced. Options REST is real-time on Developer and above. Crypto REST is real-time on Developer.

If a skill needs real-time, declare `realtime: yes` in `requires.yml` and fail fast if the user's tier doesn't support it.

Example: snapshot a ticker

curl -sS --max-time 15 \
  -H "Authorization: Bearer ${MASSIVE_API_KEY}" \
  "https://api.massive.com/v2/snapshot/locale/us/markets/stocks/tickers/AAPL"

The response includes the full snapshot. Walk the fallback chain to pick the price field, then emit `{ticker, price, source_field, timestamp}`.

What does NOT live here

WebSocket streaming patterns (see [`massive-websockets`](../massive-websockets)) and bulk flat-file downloads (see [`massive-flat-files`](../massive-flat-files)).