The Problem

Developers building applications on financial market data face a recurring integration problem: every REST endpoint and WebSocket channel has its own response shape, pagination rules, and rate limits. Maintaining hand-rolled HTTP clients for each endpoint is error-prone and burns engineering time. This repository is the official Python SDK for the Massive.com (formerly Polygon.io) market data API, and it exists to replace that per-endpoint boilerplate with a single, typed client.

What This Does

The repo is a portfolio of five self-contained projects, not a single codebase. The core library lives in massive/ and provides two clients: RESTClient (defined in massive/rest/__init__.py) for HTTP requests and WebSocketClient (defined in massive/websocket/__init__.py) for real-time streaming. Both are built on a small set of shared primitives in massive/rest/base.py and massive/modelclass.py.

The examples/ directory (158 files) is the largest project. It is a collection of standalone scripts, one per API endpoint, plus a few larger tools like examples/launchpad/launchpad.py and examples/tools/docker/app.py. The test_rest/ directory (59 files) holds the test suite, with 43 JSON fixture files alongside 16 test modules.

How It Is Wired

Execution starts at main in examples/launchpad/launchpad.py:26, which reaches 29 functions. The shortest traced path to an external effect is main -> fetch_stock_data -> get_aggs -> _get, where _get in massive/rest/base.py makes the network call via self.client.request. That is four hops from entry point to the wire.

Everything routes through a small set of hot functions. _get_params is called from 87 places, _paginate from 63, and _get from 30. These live in massive/rest/base.py, which is the most-connected module in the repo: 15 files import it, and it makes the outbound HTTP call. massive/__init__.py is the hub with 138 modules depending on it; a change there ripples through nearly the entire codebase.

The file-by-file map is straightforward: massive/rest/base.py owns HTTP transport and pagination, massive/rest/reference.py owns reference-data endpoints (28 functions), and the massive/rest/models/ subpackage is a set of from_dict factory classes, one per response type. The WebSocket client in massive/websocket/__init__.py handles connection lifecycle and subscription, with its own model classes in massive/websocket/models/models.py.

How To Use It

Setup: Install with pip per the README: pip install -U massive. The repo uses Poetry (pyproject.toml, poetry.lock), so poetry install also works. Python 3.9+ is required.

Configuration: Set your API key when constructing the client. The README shows client = RESTClient(api_key="<API_KEY>"). The API now defaults to api.massive.com; api.polygon.io remains supported.

Running it: There is no single application to run. The examples/ scripts are self-contained, each taking an API key and returning data. The only executable entry point is examples/launchpad/launchpad.py, which is a CLI tool. The Dockerfile in examples/tools/docker/ builds a container for one of the example tools.

Real-World Use

A quantitative research team needs daily OHLCV bars for a watchlist of 500 tickers. They use client.list_aggs with pagination enabled, which the client handles automatically:

client = RESTClient(api_key="<API_KEY>")
bars = [bar for bar in client.list_aggs(
    ticker="AAPL", multiplier=1, timespan="day",
    from_="2024-01-01", to="2024-12-31", limit=50000
)]

The same client pattern extends to trades, quotes, and WebSocket streams for real-time signals.

Code Health & Issues

Static analysis found 23 issues (7 high, 16 medium). The high-severity findings are:

  • High - Hub module - massive/__init__.py has 138 dependents; changes here have maximum blast radius. Keep it stable and small.
  • High - Deep nesting - 12 files exceed indentation depth 7, including massive/rest/base.py and massive/websocket/__init__.py. Control flow is hard to follow; extract inner blocks.
  • High - Oversized files - massive/rest/models/financials.py (1227 lines) and massive/rest/reference.py are too large to hold in one head. Split by responsibility.
  • High - Duplicated code - 109 repeated 6-line blocks across 53 files in examples/rest/. Extract shared helpers.

The SDLC audit adds two high-severity security issues: GitHub Actions are pinned to mutable tags (e.g., abatilo/actions-poetry@v2) rather than commit SHAs, and the Dockerfile bakes MASSIVE_API_KEY into image layers via ENV, readable with docker history. Both warrant immediate fixes.

The Bottom Line

This is a functional, well-tested SDK for a real financial data API, with solid pagination and a clean client surface. The main risks are structural: the massive/__init__.py hub makes core changes expensive, and the example scripts are copy-paste heavy rather than shared. Teams needing Polygon/Massive market data should use this library, but should fix the CI pinning and Docker secret handling before production use.