Molecule.dev

@molecule/api-equity-prices-polygon

Provider bond · equity-prices · API (Node) · v1.0.2 · Apache-2.0

Polygon.io equity-prices provider — quotes, historical bars, symbol search, and fundamentals from polygon.io.

npm install @molecule/api-equity-prices-polygon

npm · Source on GitHub · Implements @molecule/api-equity-prices

How it works

@molecule/api-equity-prices-polygon is a provider bond on the API (Node) side: it implements the equity-prices core interface (@molecule/api-equity-prices) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setProvider } from '@molecule/api-equity-prices'
import { provider } from '@molecule/api-equity-prices-polygon'

setProvider(provider)

Works with: @molecule/api-equity-prices, @molecule/api-secrets

Secrets: POLYGON_API_KEY

Reference

Polygon.io equity-prices provider for molecule.dev.

Implements the EquityPricesProvider interface against the public Polygon.io REST endpoints. Provides quotes (/v2/last/trade), historical aggregate bars (/v2/aggs), symbol search (/v3/reference/tickers), fundamentals (/v3/reference/tickers/:symbol combined with /vX/reference/financials), and a list of supported stock exchanges (/v3/reference/exchanges).

Requires POLYGON_API_KEY. The provider detects HTTP 429 rate-limit responses, parses any Retry-After header, and surfaces them via Error.cause.code === 'RATE_LIMITED' with an optional Error.cause.retryAfterSeconds. The API key is sanitized out of all error messages.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-equity-prices'
import { provider } from '@molecule/api-equity-prices-polygon'

setProvider(provider)

Type

provider

Installation

npm install @molecule/api-equity-prices-polygon @molecule/api-equity-prices @molecule/api-secrets

API

Interfaces

PolygonEquityPricesConfig

Configuration options for the Polygon.io equity-prices provider.

Polygon requires an API key (POLYGON_API_KEY) sent as the apiKey query parameter on every request. The free tier supports all five endpoints used by this provider but caps requests at 5/minute and delivers end-of-day data only for non-paid plans.

interface PolygonEquityPricesConfig {
  /**
   * API key, sent as the `apiKey` query parameter on every request.
   *
   * If omitted, the provider falls back to the `POLYGON_API_KEY`
   * environment variable. Requests will fail with a descriptive (and
   * sanitized) error if neither is set.
   */
  apiKey?: string

  /**
   * Base URL override. Defaults to `'https://api.polygon.io'`. Useful for
   * self-hosted / proxy deployments and for testing.
   */
  baseUrl?: string

  /**
   * Request timeout in milliseconds. Defaults to `10000`.
   */
  timeout?: number
}

Functions

sanitizeUrl(url)

Returns a copy of url with the apiKey query parameter redacted, so it can safely appear in error messages and logs. Polygon uses camelCase apiKey (compare Alpha Vantage's lowercase apikey).

function sanitizeUrl(url: string): string
  • url — URL string that may contain an apiKey=... query parameter.

Returns: The same URL with apiKey=REDACTED.

createProvider(config)

Creates a Polygon.io equity-prices provider.

function createProvider(config?: PolygonEquityPricesConfig): EquityPricesProvider
  • config — Provider configuration. The API key may be supplied here directly or via the POLYGON_API_KEY environment variable.

Returns: An EquityPricesProvider backed by Polygon.io.

Constants

provider

The default provider implementation, lazily initialized on first use.

Reads POLYGON_API_KEY and (optional) POLYGON_BASE_URL from environment variables. Use createProvider directly if you need to supply configuration programmatically.

const provider: EquityPricesProvider

equityPricesPolygonSecretDefinitions

Secret definitions required by the Polygon.io equity-prices bond.

const equityPricesPolygonSecretDefinitions: SecretDefinition[]

RATE_LIMITED

Error code raised when Polygon.io's rate limit is exceeded (HTTP 429). Surfaced via Error.cause on rate-limit failures so callers can handle them distinctly from generic upstream errors. When Polygon includes a Retry-After response header, its parsed value (in seconds) is attached to Error.cause.retryAfterSeconds.

const RATE_LIMITED: 'RATE_LIMITED'

MISSING_API_KEY

Error code raised when the Polygon.io API key is missing (neither the config object nor the POLYGON_API_KEY environment variable provided one).

const MISSING_API_KEY: 'MISSING_API_KEY'

UPSTREAM_ERROR

Error code raised when Polygon.io returns an unexpected payload (no results block, missing required fields, or a non-OK HTTP status that isn't a rate-limit response).

const UPSTREAM_ERROR: 'UPSTREAM_ERROR'

Core Interface

Implements @molecule/api-equity-prices interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-equity-prices'
import { provider } from '@molecule/api-equity-prices-polygon'

export function setupEquityPricesPolygon(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-equity-prices ^1.0.1
  • @molecule/api-secrets ^1.0.1

Environment Variables

Runtime Dependencies

  • @molecule/api-equity-prices
  • @molecule/api-secrets

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • A known ticker (e.g. getQuote('AAPL')) renders a PLAUSIBLE quote in the UI — a real price in a sane range, formatted with the quote's own currency (never a hardcoded $), never 0 / null / NaN or a spinner that never resolves.
  • Several distinct tickers (e.g. AAPL and MSFT) each render their OWN price — not one shared placeholder or the same number repeated (a stale-cache or wrong-symbol wiring bug).
  • If the app charts history, getHistorical(symbol, range) returns an ascending series of { ts, close } that actually draws a line that moves — not an empty array, a flat line, or points in reversed order.
  • An invalid / unknown ticker resolves to a clear "not found" in the UI (empty searchSymbol() results, or a caught getQuote error) — never a crash, a blank card, or a NaN price.
  • Staleness is honest: the quote's ts is surfaced (a timestamp or a "delayed / last close" label) so an out-of-hours last-close price is NOT presented as a live trade — the UI never dresses stale data up as real-time.
  • A provider rate-limit / outage (free tiers cap at a few calls) degrades gracefully to last-known-cached data or an empty state with a message — never a crashed page or a NaN; quotes are cached server-side, not refetched per render.
  • The provider API key stays server-side: quotes are served only through the app's own authenticated endpoint, scoped to specific symbols — not an open, unbounded proxy any caller can pass arbitrary tickers/params to.