Tutorial: Polygon (Market Data)

Finance

Data source: Polygon.io

Overview

Polygon (Market Data) wraps Polygon.io, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-polygon": {
      "url": "https://context.gnist.ai/mcp/polygon/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`get_quote`

Get the latest quote snapshot for a US equity ticker. Returns real-time (or 15-minute delayed on free tier) bid/ask, last trade, intraday OHLCV, and day-over-day change for a single ticker. Args: ticker: Ticker symbol (e.g. "AAPL", "MSFT", "TSLA"). Case-insensitive. Returns: ticker, name, last_price, bid, ask, open, high, low, close, volume, vwap, prev_close, change, change_pct, updated (Unix nanoseconds).

Parameter	Type	Required	Description
`ticker`	string	required	Ticker symbol (e.g. "AAPL", "MSFT", "TSLA"). Case-insensitive.

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_quote", "arguments": {"ticker": "AAPL"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'ticker': 'AAPL'}, 'name': 'get_quote'}},
)
print(resp.json())

`get_trades`

Get recent trade ticks for a US equity ticker on a specific date. Returns individual trade executions with price, size, exchange, and trade conditions. Useful for microstructure analysis, VWAP calculations, and understanding intraday price action. Args: ticker: Ticker symbol (e.g. "AAPL"). Case-insensitive. date: Trade date in YYYY-MM-DD format (e.g. "2024-01-15"). limit: Maximum trades to return (default 50, max 50000). Returns: ticker, date, count, and trades list of {timestamp (Unix ns), price, size, exchange (int code), conditions (list of condition codes)}.

Parameter	Type	Required	Description
`ticker`	string	required	Ticker symbol (e.g. "AAPL"). Case-insensitive.
`date`	string	required	Trade date in YYYY-MM-DD format (e.g. "2024-01-15").
`limit`	integer	optional	Maximum trades to return (default 50, max 50000). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_trades", "arguments": {"ticker": "AAPL", "date": "2024-01-15"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'date': '2024-01-15', 'ticker': 'AAPL'},
            'name': 'get_trades'}},
)
print(resp.json())

`get_aggs`

Get OHLCV aggregate bars for a ticker over a date range. Retrieves candlestick/bar data at any granularity from 1-minute to annual. Use for charting, technical analysis, trend identification, and backtesting. Timespans: "minute", "hour", "day", "week", "month", "quarter", "year" Examples: - get_aggs("AAPL", 1, "day", "2024-01-01", "2024-03-31") — daily bars for Q1 2024 - get_aggs("MSFT", 5, "minute", "2024-01-15", "2024-01-15") — 5-min bars for one day - get_aggs("SPY", 1, "week", "2023-01-01", "2024-01-01") — weekly bars for 2023 Args: ticker: Ticker symbol (e.g. "AAPL", "SPY", "BTC-USD"). Case-insensitive. multiplier: Size of the aggregate window (e.g. 1, 5, 15). timespan: Time unit — "minute", "hour", "day", "week", "month", "quarter", "year". from_date: Start date (YYYY-MM-DD). to_date: End date (YYYY-MM-DD). adjusted: Whether to adjust for splits and dividends (default True). limit: Maximum bars to return (default 120, max 50000). Returns: ticker, multiplier, timespan, adjusted, count, and bars list of {timestamp (Unix ms), open, high, low, close, volume, vwap, transactions}.

Parameter	Type	Required	Description
`ticker`	string	required	Ticker symbol (e.g. "AAPL", "SPY", "BTC-USD"). Case-insensitive.
`multiplier`	integer	required	Size of the aggregate window (e.g. 1, 5, 15).
`timespan`	string	required	Time unit — "minute", "hour", "day", "week", "month", "quarter", "year".
`from_date`	string	required	Start date (YYYY-MM-DD).
`to_date`	string	required	End date (YYYY-MM-DD).
`adjusted`	boolean	optional	Whether to adjust for splits and dividends (default True). (default: `True`)
`limit`	integer	optional	Maximum bars to return (default 120, max 50000). (default: `120`)

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_aggs", "arguments": {"ticker": "AAPL", "multiplier": 1, "timespan": "example", "from_date": "2025-01-15", "to_date": "2025-01-15"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'from_date': '2025-01-15',
                          'multiplier': 1,
                          'ticker': 'AAPL',
                          'timespan': 'example',
                          'to_date': '2025-01-15'},
            'name': 'get_aggs'}},
)
print(resp.json())

`get_options_chain`

Get the options chain snapshot for an underlying equity ticker. Returns options contracts with strike, expiration, implied volatility, open interest, and Greeks (delta, gamma, theta, vega). Use for options analysis, hedging decisions, and volatility surface exploration. Note: Options data requires a paid Polygon.io subscription (Starter or above). Args: underlying: Underlying ticker symbol (e.g. "AAPL", "SPY"). Case-insensitive. expiration_date: Filter to a specific expiration (YYYY-MM-DD). If omitted, returns all expirations. contract_type: Filter by "call" or "put". If omitted, returns both. strike_price_gte: Minimum strike price filter. strike_price_lte: Maximum strike price filter. limit: Maximum contracts to return (default 50). Returns: underlying, count, and contracts list of {ticker, contract_type, strike_price, expiration_date, exercise_style, implied_volatility, open_interest, delta, gamma, theta, vega, last_price, volume}.

Parameter	Type	Required	Description
`underlying`	string	required	Underlying ticker symbol (e.g. "AAPL", "SPY"). Case-insensitive.
`expiration_date`	any	optional	Filter to a specific expiration (YYYY-MM-DD). If omitted, returns all expirations.
`contract_type`	any	optional	Filter by "call" or "put". If omitted, returns both.
`strike_price_gte`	any	optional	Minimum strike price filter.
`strike_price_lte`	any	optional	Maximum strike price filter.
`limit`	integer	optional	Maximum contracts to return (default 50). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_options_chain", "arguments": {"underlying": "AAPL"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'underlying': 'AAPL'}, 'name': 'get_options_chain'}},
)
print(resp.json())

`search_tickers`

Search for ticker symbols and company names on Polygon.io. Use this to find the correct ticker symbol when you know a company name but not its symbol, or to explore what's available in a given market. Markets: "stocks" (US equities), "crypto" (cryptocurrency), "fx" (forex), "otc" (OTC/pink sheets), "indices" (market indices) Examples: - search_tickers("Apple") — find AAPL and related tickers - search_tickers("bitcoin", market="crypto") — find BTC crypto pairs - search_tickers("EUR", market="fx") — find EUR currency pairs - search_tickers("S&P 500", market="indices") — find S&P 500 index Args: query: Search string — company name, partial ticker, or keyword. market: Market type (default "stocks"). active: If True, only return currently active/listed tickers (default True). limit: Maximum results to return (default 20). Returns: count and tickers list of {ticker, name, market, locale, type, currency, primary_exchange, active}.

Parameter	Type	Required	Description
`query`	string	required	Search string — company name, partial ticker, or keyword.
`market`	string	optional	Market type (default "stocks"). (default: `stocks`)
`active`	boolean	optional	If True, only return currently active/listed tickers (default True). (default: `True`)
`limit`	integer	optional	Maximum results to return (default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_tickers", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_tickers'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/polygon/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/polygon/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_tickers to find items, then get_quote to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does Polygon (Market Data) provide?

Market data — stock prices, options, forex, and crypto from Polygon.io. It exposes 6 tools: get_quote, get_trades, get_aggs, get_options_chain, search_tickers, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Polygon (Market Data) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.