fd-polygon

Polygon.io US equities datasource package for fd-open-data-mcp.

Exposes US equity market data (daily OHLCV bars, single-day OHLC, company reference) from polygon.io via the official polygon-api-client Python package. It is the US-markets complement to akshare's A-share coverage.

Install

pip install fd-polygon

The package is discovered by fd-open-data-mcp through the fd_open_data_mcp.datasources entry-point — install it into the same environment as fd-open-data-mcp and it auto-registers via register_discovered().

Authentication

The API key is read from the POLYGON_API_KEY environment variable at runtime. It is never hardcoded in source. A missing/empty key makes the provider raise FetchError, which the dispatcher treats like any unavailable source (records an error outcome and fails over).

export POLYGON_API_KEY=tw_...        # free-tier key from polygon.io/dashboard/api-keys

Functions

Concepts

OHLCV columns are bound to price.close / price.open / price.high / price.low / price.vwap / trading_volume concepts for entity_type=stock with unit=currency_usd (distinct from the A-share currency_cny concepts in fd-world). Company facts (market_cap, total_employees) bind to entity_type=company.

Dispatch wiring

fd-open-data-mcp's run_upstream() is a hardcoded source→runner chain. This package adds the polygon branch:

if source == "polygon":
    from fd_polygon.provider import run_polygon
    return run_polygon(command, params)

run_polygon returns pandas DataFrames with a date column (YYYY-MM-DD) so the dispatch fallback extraction finds values without a dedicated adapter.

Smoke test

export POLYGON_API_KEY=tw_...
python -c "
from fd_polygon.provider import run_polygon
# Use recent dates — the free tier's historical entitlement only covers ~2 yrs back.
df = run_polygon('polygon_aggs', {'ticker': 'AAPL', 'start': '2026-07-01', 'end': '2026-07-10'})
print(df)
"

Free-tier limits

• 5 API calls / minute.
• Historical entitlement window ≈ 2 years. get_aggs and get_daily_open_close_agg only serve dates within roughly the last two years (observed: 2024-09 returns, 2024-01 returns NOT_AUTHORIZED as of 2026-08). Older bars require a paid plan. get_ticker_details is not subject to this window.
• Delayed intraday trades/quotes — not used by this package.