Node.js/TypeScript SDK for EODHD Financial APIs

Summarize article with AI:

The official EODHD Node.js/TypeScript library gives you a single, typed client for every EODHD API — historical prices, fundamentals, real-time WebSocket streaming, options, news, screener, macro indicators, and more. It covers 150,000+ tickers across 70+ exchanges, ships with built-in retry logic, rate-limit handling, and works in Node.js, Deno, Bun, and modern browsers.

Note that different datasets are available depending on your subscription plan. Core APIs such as end-of-day prices, fundamentals, and news are included in standard plans, while advanced features like real-time WebSocket streaming, US options, S&P Global indices, PRAAMS analytics, and ESG data are provided by third-party vendors through the EODHD Marketplace and require a separate purchase. Check the pricing page and individual Marketplace product pages to see what is included in your plan.

Installation

npm install eodhd

The package has zero runtime dependencies. For WebSocket streaming in Node.js, install the optional ws peer dependency:

npm install ws

Quick Start

import { EODHDClient } from 'eodhd';

const client = new EODHDClient({ apiToken: 'YOUR_API_TOKEN' });

// Get historical end-of-day prices
const prices = await client.eod('AAPL.US', { from: '2024-01-01', to: '2024-12-31' });
console.log(prices[0]);
// { date: '2024-01-02', open: 187.15, high: 188.44, low: 183.89, close: 185.64, adjusted_close: 184.53, volume: 82488700 }

// Get live (delayed) stock price
const quote = await client.realTime('AAPL.US');
console.log(`${quote.code}: $${quote.close} (${quote.change_p}%)`);

// Search for stocks
const results = await client.search('Tesla', { limit: 5 });

You can also set the EODHD_API_TOKEN environment variable instead of passing it directly:

export EODHD_API_TOKEN=your_token_here
// Token is read from EODHD_API_TOKEN automatically
const client = new EODHDClient({});

Configuration

OptionTypeDefaultDescription
apiTokenstringEODHD_API_TOKEN env varYour EODHD API token
baseUrlstringhttps://eodhd.com/apiAPI base URL
timeoutnumber30000Request timeout in milliseconds
maxRetriesnumber2Retry attempts on 429/5xx errors (0 to disable)
loggerLoggerundefinedCustom logger; or set EODHD_LOG=debug for console output
const client = new EODHDClient({
  apiToken: 'YOUR_API_TOKEN',
  timeout: 60000,       // 60 seconds
  maxRetries: 3,        // retry up to 3 times on transient errors
});

Historical & Price Data

End-of-Day Prices

Fetch daily, weekly, or monthly OHLCV data for any ticker. The ticker format is SYMBOL.EXCHANGE (e.g. AAPL.US, VOD.LSE, BTC-USD.CC).

const eod = await client.eod('AAPL.US', {
  from: '2024-01-01',
  to: '2024-12-31',
  period: 'd', // 'd' (daily), 'w' (weekly), 'm' (monthly)
  order: 'a',  // 'a' (ascending), 'd' (descending)
});

Intraday Data

const intraday = await client.intraday('AAPL.US', {
  interval: '5m', // '1m', '5m', '1h'
  from: '1704067200',
  to: '1704153600',
});

Live (Delayed) Prices

Get the latest 1-minute OHLCV bar with a 15-20 minute delay. Supports multiple tickers in a single request.

// Single ticker
const live = await client.realTime('AAPL.US');

// Multiple tickers in one call
const liveMulti = await client.realTime('AAPL.US', { s: 'MSFT.US,GOOG.US' });

US Extended Delayed Quotes

Batch delayed quotes for US equities with bid/ask, last trade, 52-week extremes, market cap, P/E, dividends, and more. See the Live API docs for the full field list.

const usQuotes = await client.usQuoteDelayed({ s: 'AAPL,MSFT,GOOG' });

Bulk EOD Data

Download end-of-day prices for an entire exchange in a single request.

const bulkUs = await client.bulkEod('US', { date: '2024-12-31' });

Dividends, Splits & Market Cap

// Historical dividends
const dividends = await client.dividends('AAPL.US', { from: '2020-01-01' });

// Historical splits
const splits = await client.splits('AAPL.US');

// Historical market capitalization
const marketCap = await client.historicalMarketCap('AAPL.US', { from: '2024-01-01' });

Fundamentals

Retrieve full company fundamentals — general info, financial statements, valuation metrics, earnings, and more. You can filter specific sections to reduce payload size.

// Full company fundamentals
const fundamentals = await client.fundamentals('AAPL.US');

// Filter specific sections
const general = await client.fundamentals('AAPL.US', { filter: 'General' });
const financials = await client.fundamentals('AAPL.US', { filter: 'Financials' });

// Bulk fundamentals for an exchange
const bulkFund = await client.bulkFundamentals('US', { symbols: 'AAPL,MSFT,GOOG' });

// Company logo (PNG or SVG)
const logoPng = await client.logo('AAPL.US');       // returns ArrayBuffer
const logoSvg = await client.logoSvg('AAPL.US');    // returns ArrayBuffer

Calendar Events

Access upcoming and historical earnings, IPOs, splits, and dividends through the calendar API.

// Upcoming earnings
const earnings = await client.calendar.earnings({
  from: '2025-03-01',
  to: '2025-03-31',
  symbols: 'AAPL.US,MSFT.US',
});

// Earnings trends
const trends = await client.calendar.trends({ symbols: 'AAPL.US,MSFT.US' });

// Upcoming IPOs
const ipos = await client.calendar.ipos({ from: '2025-03-01', to: '2025-06-01' });

// Upcoming splits
const calSplits = await client.calendar.splits({ from: '2025-03-01', to: '2025-06-01' });

News & Sentiment

// Financial news for a ticker
const news = await client.news({ s: 'AAPL.US', limit: 10 });

// Filter by topic tag
const techNews = await client.news({ t: 'technology', limit: 20 });

// Sentiment data over time
const sentiment = await client.sentiments({ s: 'AAPL.US', from: '2025-01-01' });

// Trending keywords from financial news
const weights = await client.newsWordWeights({
  s: 'AAPL.US',
  'filter[date_from]': '2025-01-01',
  'filter[date_to]': '2025-01-31',
});

Technical Indicators

Calculate over 20 technical indicators directly through the API: SMA, EMA, WMA, MACD, RSI, Stochastic, Bollinger Bands, ADX, ATR, CCI, SAR, and more.

const sma = await client.technical('AAPL.US', {
  function: 'sma',
  period: 50,
  from: '2025-01-01',
  order: 'a',
});

const rsi = await client.technical('AAPL.US', {
  function: 'rsi',
  period: 14,
  from: '2025-01-01',
});

const bbands = await client.technical('AAPL.US', {
  function: 'bbands',
  period: 20,
  from: '2025-01-01',
});
// Stock screener with financial filters
const screened = await client.screener({
  sort: 'market_capitalization.desc',
  filters: JSON.stringify([['market_capitalization', '>', 1000000000]]),
  limit: 10,
});

// Search stocks, ETFs, funds, bonds, indices, crypto
const results = await client.search('Apple', {
  limit: 10,
  type: 'stock', // 'all', 'stock', 'etf', 'fund', 'bond', 'index', 'crypto'
});

// ID mapping (ISIN, CUSIP, FIGI, LEI, CIK)
const mapped = await client.idMapping({ 'filter[isin]': 'US0378331005' });

Exchanges

// List all supported exchanges
const exchanges = await client.exchanges.list();

// Get tickers for an exchange
const tickers = await client.exchanges.symbols('US', { type: 'common_stock' });

// Exchange details with trading hours
const details = await client.exchanges.details('US');

// Symbol change history
const changes = await client.exchanges.symbolChangeHistory({ from: '2024-01-01' });

Macro & Economic Data

// Macroeconomic indicators (GDP, inflation, unemployment, etc.)
const gdp = await client.macroIndicator('USA', { indicator: 'gdp_current_usd' });
const inflation = await client.macroIndicator('USA', { indicator: 'inflation_consumer_prices_annual' });

// Economic events calendar
const events = await client.economicEvents({
  from: '2025-03-01',
  to: '2025-03-31',
  country: 'US',
});

US Treasury Rates

const bills = await client.treasury.billRates({ from: '2025-01-01' });
const yields = await client.treasury.yieldRates({ from: '2025-01-01' });
const longTerm = await client.treasury.longTermRates({ from: '2025-01-01' });
const realYield = await client.treasury.realYieldRates({ from: '2025-01-01' });

WebSocket (Real-Time Streaming)

Stream real-time market data via WebSocket. Four feeds are available: us (US trades), us-quote (US quotes), forex, and crypto. The client auto-reconnects with exponential backoff on connection loss.

const ws = client.websocket('us', ['AAPL', 'TSLA', 'MSFT']);

ws.on('data', (tick) => {
  console.log(`${tick.s}: $${tick.p} x${tick.v} @ ${new Date(tick.t)}`);
});

ws.on('error', (err) => console.error(err));
ws.on('close', () => console.log('Disconnected'));
ws.on('reconnectFailed', () => console.log('All reconnect attempts exhausted'));

// Subscribe/unsubscribe dynamically
ws.subscribe(['GOOG']);
ws.unsubscribe(['TSLA']);

// Close when done
ws.close();

WebSocket options:

OptionTypeDefaultDescription
maxReconnectAttemptsnumber5Maximum reconnection attempts before giving up
reconnectIntervalnumber3000Base interval in milliseconds between reconnect attempts
const ws = client.websocket('forex', ['EURUSD', 'GBPUSD'], {
  maxReconnectAttempts: 10,
  reconnectInterval: 5000,
});

Marketplace APIs

Access third-party data providers through the EODHD Marketplace: Unicorn Bay (options, S&P Global indices, tick data, logos), Trading Hours, PRAAMS (investment analytics), and InvestVerte (ESG data).

US Tick-Level Data

const ticks = await client.ticks({ s: 'AAPL', from: 1704067200, to: 1704070800 });

US Options (Unicorn Bay)

// List underlying symbols with options data
const symbols = await client.marketplace.unicornbay.options.underlyingSymbols({
  'page[limit]': 100,
});

// Options contracts
const contracts = await client.marketplace.unicornbay.options.contracts({
  'filter[underlying_symbol]': 'AAPL',
  'filter[type]': 'call',
  'filter[exp_date_from]': '2025-06-01',
  'page[limit]': 50,
});

// Options EOD data
const optionsEod = await client.marketplace.unicornbay.options.eod({
  'filter[underlying_symbol]': 'AAPL',
  'filter[exp_date_eq]': '2025-06-20',
});

S&P Global Indices (Unicorn Bay)

// List all S&P/Dow Jones indices
const indices = await client.marketplace.unicornbay.spglobal.list();

// Index components (current)
const components = await client.marketplace.unicornbay.spglobal.components('GSPC.INDX');

// Historical components
const historical = await client.marketplace.unicornbay.spglobal.components('GSPC.INDX', {
  historical: true,
  from: '2024-01-01',
  to: '2024-12-31',
});

Trading Hours

const markets = await client.marketplace.tradinghours.markets();
const details = await client.marketplace.tradinghours.details({ market: 'US.NASDAQ' });
const status = await client.marketplace.tradinghours.status({ market: 'US.NASDAQ' });
const lookup = await client.marketplace.tradinghours.lookup({ 'filter[symbol]': 'AAPL' });

Investment Analytics (PRAAMS)

// Equity risk scoring
const equityRisk = await client.marketplace.praams.analyseEquityByTicker('AAPL.US');

// Bond analysis
const bondAnalysis = await client.marketplace.praams.analyseBond('US912828Z880');

// Smart equity screener
const equities = await client.marketplace.praams.exploreEquity(
  { skip: 0, take: 20 },
  { regions: ['North America'], sectors: ['Technology'] },
);

ESG Data (InvestVerte)

const companies = await client.marketplace.investverte.companies();
const esg = await client.marketplace.investverte.esg('AAPL.US', { year: 2024 });
const countryEsg = await client.marketplace.investverte.country('US');
const sectorEsg = await client.marketplace.investverte.sector('Technology');

Error Handling

The SDK provides a structured error hierarchy. All API errors extend EODHDError with status code, error code, and retryability information. Transient errors (429, 5xx) are automatically retried with exponential backoff.

Error ClassWhenRetryable
EODHDErrorBase class for all API errorsDepends on status code
EODHDAuthErrorInvalid or missing API token (401/403)No
EODHDRateLimitErrorRate limit exceeded (429)Yes
EODHDNetworkErrorNetwork connectivity issuesYes
EODHDTimeoutErrorRequest exceeded timeoutYes
import {
  EODHDClient,
  EODHDError,
  EODHDAuthError,
  EODHDRateLimitError,
} from 'eodhd';

try {
  const data = await client.eod('INVALID.XX');
} catch (err) {
  if (err instanceof EODHDRateLimitError) {
    console.log('Rate limited, retry after:', err.retryAfter);
  } else if (err instanceof EODHDAuthError) {
    console.log('Check your API token');
  } else if (err instanceof EODHDError) {
    console.log(err.statusCode);  // HTTP status code
    console.log(err.code);        // 'auth_error' | 'rate_limit' | 'network_error' | ...
    console.log(err.retryable);   // boolean
  }
}

TypeScript Support

The library is written in TypeScript with strict mode enabled. All methods, parameters, and responses are fully typed — you get autocompletion and compile-time checks out of the box.

import {
  EODHDClient,
  EodDataPoint,
  RealTimeQuote,
  SearchResult,
  FundamentalsData,
  NewsArticle,
} from 'eodhd';

const client = new EODHDClient({ apiToken: 'YOUR_API_TOKEN' });

const prices: EodDataPoint[] = await client.eod('AAPL.US');
const quote: RealTimeQuote = await client.realTime('AAPL.US');
const results: SearchResult[] = await client.search('Apple');
const fund: FundamentalsData = await client.fundamentals('AAPL.US');
const news: NewsArticle[] = await client.news({ s: 'AAPL.US' });

Requirements

RequirementDetails
Node.js>= 20 (uses native fetch)
Deno / BunSupported out of the box
BrowsersModern browsers with fetch support
WebSocket (Node.js)Optional ws package (browsers use native WebSocket)
Module formatESM and CommonJS dual-published
Tree-shakingSupported (sideEffects: false)

API Coverage

The SDK provides typed methods for every EODHD API endpoint:

CategoryMethods
Historical & Price Dataeod, intraday, realTime, usQuoteDelayed, bulkEod, dividends, splits, historicalMarketCap, ticks
Fundamentalsfundamentals, bulkFundamentals, logo, logoSvg
Calendarcalendar.earnings, calendar.trends, calendar.ipos, calendar.splits, calendar.dividends
News & Sentimentnews, sentiments, newsWordWeights
Technical Indicatorstechnical (SMA, EMA, RSI, MACD, Bollinger Bands, and 15+ more)
Screening & Searchscreener, search, idMapping
Exchangesexchanges.list, exchanges.symbols, exchanges.details, exchanges.symbolChangeHistory
Macro & EconomicmacroIndicator, economicEvents
Treasurytreasury.billRates, treasury.yieldRates, treasury.longTermRates, treasury.realYieldRates
Corporate ActionsinsiderTransactions
CBOE Europecboe.indices, cboe.index
WebSocketwebsocket (us, us-quote, forex, crypto feeds)
MarketplaceUnicorn Bay (options, S&P indices, tick data, logos), Trading Hours, PRAAMS, InvestVerte
Useruser

Sign up & Get Data