US ETF REST API documentation

Authenticate with an API key and call Data Captain endpoints for the ETF universe, batch prices, market status, screener, rankings, heatmap, backtesting, and portfolio tools. Official TypeScript and Python SDKs included below.

Go to Swagger

Official SDKs

Use the official client libraries instead of hand-rolling HTTP calls. Same API key, typed methods for screener, rankings, heatmap, backtest, and portfolio endpoints.

JavaScript / TypeScript

npm · datacaptain@0.1.0

npm install datacaptain

import { DataCaptain } from "datacaptain";

const dc = new DataCaptain({ apiKey: process.env.DATACAPTAIN_API_KEY });
const rankings = await dc.etf.rankings({ category: "return", period: "1y" });

Python

PyPI · datacaptain@0.1.0

pip install datacaptain

from datacaptain import DataCaptain

dc = DataCaptain(api_key="YOUR_API_KEY")
rankings = dc.etf_screener(return_min=10, period="1y")

Full SDK docs with install + examples →

Packages: npm · PyPI. Source in packages/datacaptain and packages/datacaptain-python.

Authentication

Include your API key in the x-api-key header for all requests.

x-api-key: YOUR_API_KEY

Errors & rate limits

Failed responses use a consistent JSON envelope. Include errorId when contacting support.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT",
    "message": "Daily rate limit exceeded. Upgrade your plan for more requests.",
    "errorId": "a1b2c3d4e5f6",
    "hint": "Check X-RateLimit-Remaining on responses, or GET /v1/developer/usage"
  }
}

UNAUTHORIZED · HTTP 401 — Missing/invalid JWT or API key
FORBIDDEN · HTTP 403 — Plan gate blocked this path (upgrade required)
NOT_FOUND · HTTP 404 — Unknown route or symbol
VALIDATION_ERROR · HTTP 400 — Bad query/body parameters
RATE_LIMIT · HTTP 429 — Daily API-key quota or IP limit exceeded
INTERNAL_ERROR · HTTP 500 — Unexpected server failure — include errorId in support tickets

Rate-limit headers

X-RateLimit-Limit — Your plan's daily request cap
X-RateLimit-Remaining — Requests left today for this API key

Official SDKs expose lastRateLimit / last_rate_limit from these headers after each call. Prefer GET /v1/developer/usage for dashboards.

ETF Endpoints

GET/v1/etf/list?limit=48&category=technology&sort=return&sortDir=descFreecache: 60s

Paginated US ETF universe with filters, sorting, enrichment (issuer, category, expense, AUM), and optional stats. Returns { data, total, limit, offset, stats? }.

Params: limit (number), offset (number), search (string), hasPrice (string), category (string), issuer (string), assetClass (string), leveraged (string), inverse (string), dividendMin (number), expenseMax (number), aumMin (number), volumeMin (number), sort (string), sortDir (string)

https://api.datacaptain.in/v1/etf/list?limit=48&category=technology&sort=return&sortDir=desc

GET/v1/etf/:symbolFreecache: 60s

ETF research profile — price, metrics, performance periods, OHLCV history, dividends, similar ETFs, AI summary, and risk block.

Params: symbol (string)*

https://api.datacaptain.in/v1/etf/SPY

GET/v1/etf/heatmap?basket=broad&period=1yFreecache: 60s

ETF performance heatmap cells by return % for a preset basket or custom symbols.

Params: basket (string), symbols (string), period (string)

https://api.datacaptain.in/v1/etf/heatmap?basket=broad&period=1y

GET/v1/etf/heatmap/basketsFreecache: 60s

List heatmap basket presets — { baskets: [{ id, label, symbols }] }.

https://api.datacaptain.in/v1/etf/heatmap/baskets

GET/v1/etf/screener?returnMin=10&expenseMax=0.2&period=1y&sort=returnFreecache: 60s

Screen ETFs by return, yield, volatility, expense, AUM, Sharpe, issuer/category flags. Free plan: top 10.

Params: returnMin (number), returnMax (number), dividendYieldMin (number), dividendYieldMax (number), volatilityMin (number), volatilityMax (number), volumeMin (number), volumeMax (number), priceMin (number), priceMax (number), expenseMin (number), expenseMax (number), aumMin (number), aumMax (number), sharpeMin (number), period (string), assetClass (string), category (string), issuer (string), search (string), leveraged (string), inverse (string), esg (string), sort (string), sortDir (string), limit (number), offset (number)

https://api.datacaptain.in/v1/etf/screener?returnMin=10&expenseMax=0.2&period=1y&sort=return

GET/v1/etf/rankings?metric=return&period=1y&limit=20Freecache: 60s

ETF leaderboards by return, yield, volatility, CAGR, Sharpe, expense, AUM, or drawdown. Free plan: top 10.

Params: metric (string), category (string), period (string), basket (string), assetClass (string), search (string), limit (number), offset (number)

https://api.datacaptain.in/v1/etf/rankings?metric=return&period=1y&limit=20

GET/v1/stocks/prices?symbols=SPY,QQQ,VOOFreecache: 60s

Batch ETF prices — latest close for up to 50 tickers. Cached 60s.

Params: symbols (string)*

https://api.datacaptain.in/v1/stocks/prices?symbols=SPY,QQQ,VOO

GET/v1/stocks/:symbol/history?startDate=2020-01-01&endDate=2024-12-31Freecache: 60s

Historical OHLCV bars for charts and research. Free plan.

Params: symbol (string)*, startDate (string), endDate (string), interval (string)

https://api.datacaptain.in/v1/stocks/SPY/history?startDate=2020-01-01&endDate=2024-12-31

Market

GET/v1/market/statusFreecache: 30s

US market session status from NYSE calendar (holidays + early closes). Regular 09:30–16:00 ET.

https://api.datacaptain.in/v1/market/status

Backtesting & Portfolio

POST/v1/backtest/buy-and-holdPaid

Multi-strategy ETF backtest (also accepts GET). Returns equity curve, tradeEvents, dividendEvents, OHLCV prices, drawdownCurve, Sharpe/Sortino, and more. Paid plan.

Params: symbol (string)*, investment (number), startDate (string)*, endDate (string)*, strategy (string), reinvestDividends (boolean), adjustForInflation (boolean), fastPeriod (number), slowPeriod (number), rsiPeriod (number), rsiBuyBelow (number), rsiSellAbove (number), macdFast (number), macdSlow (number), macdSignal (number)

https://api.datacaptain.in/v1/backtest/buy-and-hold

POST/v1/backtest/comparePaid

Compare multiple ETFs with the same strategy settings. Returns winner, ranked list, and per-symbol results. Paid plan.

Params: symbols (string[])*, investment (number), startDate (string)*, endDate (string)*, strategy (string), reinvestDividends (boolean), adjustForInflation (boolean)

https://api.datacaptain.in/v1/backtest/compare

POST/v1/portfolio/rebalancePaid

Compare current holdings to target weights and get buy/sell suggestions. Paid plan. Also accepts GET with JSON query strings.

Params: holdings (object[])*, target (object[])*, driftThreshold (number), mode (string)

https://api.datacaptain.in/v1/portfolio/rebalance

Developer

GET/v1/developer/usageFree

Usage stats — plan, requests today, remaining, daily limit, series, endpoint analytics.

https://api.datacaptain.in/v1/developer/usage

WebSocket (Real-Time)

Real-time ETF price streaming (when enabled). Subscribe to ETF symbols for periodic updates.

wss://api.datacaptain.in/ws

Subscribe:

{"action":"subscribe","symbols":["SPY","QQQ"]}