datacaptain

Official TypeScript client for the DataCaptain US ETF API.

Requires Node.js 18+ (uses native fetch).

Install

npm install datacaptain

From this monorepo before publish:

npm install ../packages/datacaptain

Quick start

import { DataCaptain, DataCaptainError } from "datacaptain";

const dc = new DataCaptain({
  apiKey: process.env.DATACAPTAIN_API_KEY!,
  // Optional — defaults to https://datacaptain.up.railway.app
  // When api.datacaptain.in is live: baseUrl: "https://api.datacaptain.in",
});

try {
  const usage = await dc.developer.usage();
  const etfs = await dc.etf.list({ search: "SPY", limit: 10 });
  const rankings = await dc.etf.rankings({ category: "return", period: "1y", limit: 20 });

  const backtest = await dc.backtest.buyAndHold({
    symbol: "SPY",
    investment: 10_000,
    startDate: "2020-01-01",
    endDate: "2024-12-31",
  });

  const rebalance = await dc.portfolio.rebalance({
    holdings: [{ symbol: "SPY", value: 6000 }, { symbol: "BND", value: 4000 }],
    target: [{ symbol: "SPY", weight: 0.6 }, { symbol: "BND", weight: 0.4 }],
  });
} catch (err) {
  if (err instanceof DataCaptainError) {
    console.error(err.message, err.statusCode, err.code);
  }
  throw err;
}

Get an API key from datacaptain.in → Dashboard → API Keys.

API surface

| Namespace | Methods | |-----------|---------| | developer | usage() | | market | status() | | prices | batch(symbols) | | etf | list, get, screener, rankings, heatmap, heatmapBaskets | | backtest | buyAndHold, compare | | portfolio | rebalance |

baseUrl

Pass the API origin only (no /api suffix). The client appends /api/... paths automatically.

Default: https://datacaptain.up.railway.app. When you add a custom API domain (e.g. api.datacaptain.in), pass baseUrl or we will update the package default.

Build (maintainers)

npm run build

prepublishOnly runs the build automatically before npm publish.

Publish (maintainers)

cd packages/datacaptain
npm login
npm publish --access public

If the datacaptain name is taken on npm, publish under a scope instead (@yourorg/datacaptain) and update name in package.json.