@furlpay/market-data

@furlpay/market-data

Real-time stock/ETF market data for FurlPay — a thin, zero-dependency aggregator over Alpha Vantage and Nasdaq Data Link with a deterministic demo fallback. It powers live prices in the FurlPay dashboard and is drop-in usable in any Node service.

• Clone-and-run — no API key needed. Every quote/bar is deterministic demo data until you add a key, so charts render immediately.
• Fails soft — a live call that errors or hits a rate limit degrades to demo data instead of throwing, so a quote is never empty.
• Zero runtime dependencies — uses the global fetch (Node 18+).

Maintained by FurlPay · MIT licensed.

Install

npm i @furlpay/market-data

Usage

import { MarketData } from "@furlpay/market-data";

const md = new MarketData({
  alphaVantageKey: process.env.ALPHA_VANTAGE_KEY,   // optional
  nasdaqKey: process.env.NASDAQ_DATA_LINK_KEY,      // optional (daily bars)
});

md.live;                                    // false until a key is set

await md.quote("AAPL");
// { symbol: "AAPL", price: 241.75, change: 1.9, changePercent: 0.79,
//   open, high, low, previousClose, volume, currency: "USD", asOf, source }

await md.quotes(["AAPL", "VOO", "NVDA"]);   // batch, never rejects

await md.bars("VOO", { interval: "daily", limit: 100 });
// { symbol, interval, bars: [{ t, o, h, l, c, v }, ...], source }

await md.search("vanguard");
// [{ symbol: "VOO", name: "Vanguard S&P 500 ETF", type: "ETF", ... }]

Keys are read from the constructor first, then from ALPHA_VANTAGE_KEY / NASDAQ_DATA_LINK_KEY in the environment.

API

Method	Returns	Notes
new MarketData(opts?)	—	alphaVantageKey?, nasdaqKey?, fetchImpl?, timeoutMs?
md.live	boolean	true when any provider key is configured
md.quote(symbol)	Promise<Quote>	latest quote; demo fallback on error
md.quotes(symbols)	Promise<Quote[]>	batch; resolves all, never rejects
md.bars(symbol, { interval?, limit? })	Promise<BarsResult>	interval: 1min|5min|15min|30min|60min|daily (default daily); daily prefers Nasdaq
md.search(query)	Promise<AssetMatch[]>	symbol/name lookup

All shapes are exported types (Quote, Bar, BarsResult, AssetMatch).

Providers

Provider	Used for	Key
Alpha Vantage	quotes, intraday & daily bars, search	alphaVantageKey
Nasdaq Data Link	historical daily bars (preferred when set)	nasdaqKey

Example

npm run example            # demo data
npm run example -- TSLA    # different symbol
ALPHA_VANTAGE_KEY=xxx npm run example

Test

npm test        # tsc build + node --test (runs in demo mode, no network)

The suite asserts the contract: demo quotes are deterministic per symbol, batch quotes resolve, bars are chronological with valid OHLC, search matches by symbol and name, and a failing live provider falls back to demo instead of throwing.

License

MIT