FMP Node API Wrapper

A comprehensive Node.js wrapper for the Financial Modeling Prep (FMP) API with full TypeScript support and organized endpoint structure.

📖 Visit the Documentation for detailed information.

🔧 For development information, contributing guidelines, and project details, visit the main repository.

Features

• 🚀 Complete TypeScript Support - Full type safety for all API responses
• 📦 Organized Structure - Clean separation of concerns with dedicated modules
• 🔧 Easy to Use - Simple, intuitive API with minimal boilerplate
• 📊 Comprehensive Coverage - Support for all FMP stable endpoints
• 🛡️ Input Validation - Built-in validation for all parameters
• 🎯 Modular Design - Import only what you need
• 🧪 Comprehensive Testing - Full test suite with 45+ tests covering all endpoints
• 📈 Real-time Data - Access to live market data and financial statements

Installation

npm install fmp-node-api
# or
yarn add fmp-node-api
# or
pnpm add fmp-node-api

Quick Start

import { FMP } from 'fmp-node-api';

// Option 1: Use environment variable (recommended)
const fmp = new FMP(); // Automatically uses FMP_API_KEY from environment

// Option 2: Provide API key directly
const fmp = new FMP({ apiKey: 'your-api-key' });

// Option 3: Provide partial config with environment variable fallback
const fmp = new FMP({ timeout: 15000 }); // Uses FMP_API_KEY from environment

// Get stock quote
const quote = await fmp.quote.getQuote('AAPL');

// Get financial statements
const incomeStatement = await fmp.financial.getIncomeStatement({
  symbol: 'AAPL',
  period: 'annual',
});

// Get forex data
const forexQuote = await fmp.quote.getQuote('EURUSD');

Configuration

The FMP client supports multiple ways to configure your API key:

Environment Variable (Recommended)

Set the FMP_API_KEY environment variable in your .env file or system environment:

# .env file
FMP_API_KEY=your-api-key-here

# Or set in your system
export FMP_API_KEY=your-api-key-here

Then initialize the client without any parameters:

import { FMP } from 'fmp-node-api';

const fmp = new FMP(); // Automatically uses FMP_API_KEY

Direct Configuration

Provide the API key directly in the constructor:

import { FMP } from 'fmp-node-api';

const fmp = new FMP({
  apiKey: 'your-api-key-here',
  timeout: 10000, // optional
});

Mixed Configuration

You can provide partial configuration and let the client fall back to environment variables:

import { FMP } from 'fmp-node-api';

const fmp = new FMP({
  timeout: 15000, // custom timeout
  // apiKey will be loaded from FMP_API_KEY environment variable
});

Configuration Options

interface FMPConfig {
  apiKey?: string; // Optional: API key (falls back to FMP_API_KEY env var)
  timeout?: number; // Optional: Request timeout in milliseconds (default: 10000)
}

API Structure

The library is organized into logical modules for easy navigation and usage:

Main Client

import { FMP } from 'fmp-node-api';

// Using environment variable (recommended)
const fmp = new FMP();

// Or with explicit configuration
const fmp = new FMP({
  apiKey: 'your-api-key',
  timeout: 10000, // optional
});

Available Modules

• fmp.quote - Quote data for stocks, forex, crypto, commodities, and ETFs
• fmp.stock - Stock market data (market cap, splits, dividends, real-time prices)
• fmp.financial - Financial statements (income, balance sheet, cash flow)
• fmp.company - Company information and profiles
• fmp.etf - ETF data and holdings
• fmp.mutualFund - Mutual fund data
• fmp.economic - Economic indicators
• fmp.market - Market-wide data and performance
• fmp.aftermarket - Extended-hours (pre/post-market) trade and quote data
• fmp.list - Stock lists and indices
• fmp.screener - Stock screener with filters and available exchanges/sectors/industries/countries
• fmp.calendar - Earnings and economic calendar
• fmp.senateHouse - Congressional trading data
• fmp.institutional - Form 13F filings and institutional ownership
• fmp.insider - Insider trading data
• fmp.sec - SEC filings and industry classification
• fmp.news - Financial news articles (general, stock, crypto, forex; by symbol or latest)

Usage Examples

Quote Data

// Get real-time quote for any asset type
const quote = await fmp.quote.getQuote('AAPL');

// Get multiple quotes
const quotes = await fmp.quote.getQuotes(['AAPL', 'MSFT', 'GOOGL']);

// Get a short quote (price, change, volume only)
const shortQuote = await fmp.quote.getQuoteShort('AAPL');

// Get historical prices
const historical = await fmp.quote.getHistoricalPrice({
  symbol: 'AAPL',
  from: '2024-01-01',
  to: '2024-12-31',
});

// Get intraday data
const intraday = await fmp.quote.getIntraday({
  symbol: 'AAPL',
  interval: '1hour',
  from: '2024-01-01',
  to: '2024-01-02',
});

Stock Data

// Get market capitalization
const marketCap = await fmp.stock.getMarketCap('AAPL');

// Get stock splits
const splits = await fmp.stock.getStockSplits('AAPL');

// Get dividend history
const dividends = await fmp.stock.getDividendHistory('AAPL');

// Get real-time price data
const realTimePrice = await fmp.stock.getRealTimePrice(['AAPL', 'MSFT', 'GOOGL']);

// Get full real-time price data
const fullRealTimeData = await fmp.stock.getRealTimePriceForMultipleStocks([
  'AAPL',
  'MSFT',
  'GOOGL',
]);

// Get price change across horizons (1D, 5D, 1M ... 10Y, max)
const priceChange = await fmp.stock.getPriceChange('AAPL');

Financial Statements

// Get income statement
const income = await fmp.financial.getIncomeStatement({
  symbol: 'AAPL',
  period: 'annual',
  limit: 10,
});

// Get balance sheet
const balance = await fmp.financial.getBalanceSheet({
  symbol: 'AAPL',
  period: 'quarter',
});

// Get cash flow statement
const cashFlow = await fmp.financial.getCashFlowStatement({
  symbol: 'AAPL',
  period: 'annual',
});

// Get key metrics
const metrics = await fmp.financial.getKeyMetrics({ symbol: 'AAPL' });

// Get financial ratios
const ratios = await fmp.financial.getFinancialRatios({ symbol: 'AAPL' });

Market Data

// Get market hours + open/closed status for all exchanges
const hours = await fmp.market.getMarketHours();

// Get market performance
const performance = await fmp.market.getMarketPerformance();

// Get gainers and losers
const gainers = await fmp.market.getGainers();
const losers = await fmp.market.getLosers();

// Get most active stocks
const mostActive = await fmp.market.getMostActive();

// Get a sector-performance snapshot for a date
const sectors = await fmp.market.getSectorPerformance({ date: '2024-06-10' });

// Get an industry P/E snapshot for a date
const industryPE = await fmp.market.getIndustryPESnapshot({ date: '2024-06-10' });

Aftermarket Data

// Get the latest extended-hours trade
const trade = await fmp.aftermarket.getTrade('AAPL');

// Get the latest extended-hours bid/ask quote
const aftermarketQuote = await fmp.aftermarket.getQuote('AAPL');

Economic Indicators

// Get treasury rates
const treasury = await fmp.economic.getTreasuryRates({
  from: '2024-01-01',
  to: '2024-12-31',
});

// Get economic indicators by name (GDP, CPI, federalFunds, unemploymentRate, …)
const gdp = await fmp.economic.getEconomicIndicators({
  name: 'GDP',
  from: '2024-01-01',
  to: '2024-12-31',
});
const cpi = await fmp.economic.getEconomicIndicators({ name: 'CPI' });
const unemployment = await fmp.economic.getEconomicIndicators({ name: 'unemploymentRate' });

Other Asset Classes

// Forex
const forexQuote = await fmp.quote.getQuote('EURUSD');

// Cryptocurrency
const cryptoQuote = await fmp.quote.getQuote('BTCUSD');

// Symbol lists
const stocks = await fmp.list.getStockList();
const etfs = await fmp.list.getETFList();
const crypto = await fmp.list.getCryptoList();
const indexes = await fmp.list.getAvailableIndexes();

// Earnings calendar
const earnings = await fmp.calendar.getEarningsCalendar({
  from: '2024-01-01',
  to: '2024-12-31',
});

// Economic calendar
const economic = await fmp.calendar.getEconomicCalendar({
  from: '2024-01-01',
  to: '2024-12-31',
});

// Company profile
const companyProfile = await fmp.company.getCompanyProfile('AAPL');

Stock Screener

// Filter stocks by multiple criteria
const results = await fmp.screener.getScreener({
  marketCapMoreThan: 10000000000,
  sector: 'Technology',
  isActivelyTrading: true,
  limit: 50,
});

// Lookups for available filter values
const exchanges = await fmp.screener.getAvailableExchanges();
const sectors = await fmp.screener.getAvailableSectors();
const industries = await fmp.screener.getAvailableIndustries();
const countries = await fmp.screener.getAvailableCountries();

News

// Latest news by asset class
const stockNews = await fmp.news.getStockNews({ from: '2024-01-01', to: '2024-01-31' });
const cryptoNews = await fmp.news.getCryptoNews({ limit: 50 });
const forexNews = await fmp.news.getForexNews({ limit: 50 });

// FMP-authored articles
const articles = await fmp.news.getArticles({ page: 1, limit: 20 });

// News for specific symbols
const aaplNews = await fmp.news.getStockNewsBySymbol({ symbols: ['AAPL', 'MSFT'] });

Testing

This package includes comprehensive tests for all endpoints. There are two test scripts available:

Local Development

pnpm test

• Uses Jest to run all tests
• Fully mocked and deterministic — no network and no API key required
• Live API validation is handled separately by pnpm test:live (see below)

Running Specific Tests

# Run only unit tests (client + main FMP class)
pnpm test:unit

# Run tests for specific endpoints
pnpm test:stock
pnpm test:financial
pnpm test:market
pnpm test:quote
pnpm test:economic
pnpm test:list
pnpm test:calendar
pnpm test:company

# Run all endpoint tests
pnpm test:endpoints

# Inspect one endpoint's raw response against the live API
pnpm test:endpoint <name>

# Validate response shapes against the live API (needs FMP_API_KEY)
pnpm test:live

Response Format

All API methods return a standardized response format:

interface APIResponse<T> {
  success: boolean;
  data: T | null;
  error: string | null;
  status: number;
}

Example Response

{
  success: true,
  data: {
    symbol: 'AAPL',
    price: 150.25,
    change: 2.15,
    changePercent: 1.45,
    // ... other fields
  },
  error: null,
  status: 200
}

Error Handling

try {
  const quote = await fmp.quote.getQuote('INVALID');

  if (!quote.success) {
    console.error('API Error:', quote.error);
    return;
  }

  if (quote.data) {
    console.log('Quote:', quote.data);
  }
} catch (error) {
  console.error('Network Error:', error);
}

Type Safety

The library provides full TypeScript support with comprehensive type definitions included in the main package:

import { Quote, MarketCap, IncomeStatement } from 'fmp-node-api';

// All responses are properly typed
const quote: APIResponse<Quote> = await fmp.quote.getQuote('AAPL');
const marketCap: APIResponse<MarketCap> = await fmp.stock.getMarketCap('AAPL');
const income: APIResponse<IncomeStatement[]> = await fmp.financial.getIncomeStatement({
  symbol: 'AAPL',
});

All API responses and parameters are fully typed for complete type safety.

Utilities

The library includes helpful utilities for data formatting and validation:

import {
  formatCurrency,
  formatPercentage,
  formatLargeNumber,
  formatDate,
  formatVolume,
} from 'fmp-node-api';

// Format financial data
const formattedPrice = formatCurrency(150.25); // "$150.25"
const formattedChange = formatPercentage(1.45); // "1.45%"
const formattedMarketCap = formatLargeNumber(2500000000); // "2.50B"
const formattedVolume = formatVolume(1500000); // "1.50M"
const formattedDate = formatDate('2024-01-15'); // "2024-01-15"

Advanced Usage

Custom Client Configuration

import { FMPClient } from 'fmp-node-api';

// Using environment variable
const client = new FMPClient({
  timeout: 15000, // optional, apiKey from FMP_API_KEY env var
});

// Or with explicit API key
const client = new FMPClient({
  apiKey: 'your-api-key',
  timeout: 15000, // optional
});

// Use individual endpoint classes
const stockEndpoints = new StockEndpoints(client);
const marketCap = await stockEndpoints.getMarketCap('AAPL');

Direct API Calls

const client = fmp.getClient();
const response = await client.get('/quote/AAPL');

Testing

The library includes a comprehensive test suite with extensive coverage across all endpoints, types, and utilities:

Available Test Scripts

# Run all tests
pnpm test

# Run specific test categories
pnpm test:unit          # Unit tests (client, main FMP class)
pnpm test:endpoints     # All endpoint tests (mocked)
pnpm test:stock         # Stock endpoint tests only
pnpm test:financial     # Financial endpoint tests only
pnpm test:market        # Market endpoint tests only
pnpm test:quote         # Quote endpoint tests only
pnpm test:economic      # Economic endpoint tests only
pnpm test:list          # List endpoint tests only
pnpm test:calendar      # Calendar endpoint tests only
pnpm test:company       # Company endpoint tests only

# Manual testing with real API calls
pnpm test:endpoint      # Run a specific endpoint against the live API

# Development
pnpm test:watch         # Watch mode for development
pnpm test:coverage      # Generate coverage report

Note: Additional endpoint-specific test scripts (test:etf, test:mutual-fund, test:senate-house, test:institutional, test:insider, test:sec) are also available, both here and at the repo root.

Live API shape check (test:live)

test:live validates real FMP responses against the canonical Zod schemas in fmp-node-types — catching renamed/missing/changed fields and version-mismatch 404s, not just "did it respond". Unlike test:endpoint (which prints one endpoint's raw JSON), test:live runs many cases and prints a classified summary.

Run from the repo root (it builds fmp-node-types first so the runner uses fresh schemas):

pnpm test:live                                   # all seeded cases
pnpm test:live --category quote,stock            # only these categories
pnpm test:live --endpoint getQuote               # cases whose name matches
pnpm test:live --dry-run                         # list cases, make NO API calls
pnpm test:live --category financial --max-calls 10

Each result is classified:

• PASS — response matches the schema
• FAIL — an expected field is missing or has the wrong (non-null) type
• SKIP — plan-locked (HTTP 402/403) or rate/quota limited (429)
• DRIFT — extra top-level fields, or a non-nullable field came back null

Flags: --delay <ms> (default 400) paces calls; --max-calls <n> (default 50) caps live calls; --include-locked also runs cases marked planLocked; --fail-on-drift makes DRIFT fail the exit code. The runner is sequential and throttled to stay within limited API plans — the first full run doubles as a calibration pass: mark any consistently plan-locked endpoints planLocked: true in scripts/live/manifest.ts so later default runs skip them. Exits non-zero when any case FAILs.

Coverage note: the seeded manifest currently covers the quote, stock, financial, and market categories. The classifier logic is unit-tested in src/__tests__/live/validate.test.ts (no API key needed).

Development

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• FMP API key

Setup

# Clone the repository
git clone <repository-url>
cd fmp-node-wrapper

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Add your FMP_API_KEY to .env

# Build the package
pnpm build

# Run tests
pnpm test

Available Scripts

# Build
pnpm build              # Build the package
pnpm dev                # Watch mode for development

# Testing
pnpm test               # Run all tests (mocked, deterministic)
pnpm test:watch         # Watch mode
pnpm test:coverage      # Coverage report
pnpm test:live          # Validate response shapes against the live API
pnpm test:endpoint      # Inspect one endpoint's raw response (live)
pnpm test:unit          # Run unit tests
pnpm test:endpoints     # Run all endpoint tests
pnpm test:stock         # Run stock endpoint tests
pnpm test:financial     # Run financial endpoint tests
pnpm test:market        # Run market endpoint tests
pnpm test:quote         # Run quote endpoint tests
pnpm test:economic      # Run economic endpoint tests
pnpm test:list          # Run list endpoint tests
pnpm test:calendar      # Run calendar endpoint tests
pnpm test:company       # Run company endpoint tests

# Code Quality
pnpm lint               # Run ESLint
pnpm lint:fix           # Fix linting issues
pnpm format             # Format code with Prettier
pnpm format:check       # Check code formatting
pnpm type-check         # TypeScript type checking

# Utilities
pnpm clean              # Clean build artifacts

File Structure

src/
├── client.ts              # Base HTTP client (v3/v4/stable axios instances)
├── fmp.ts                 # Main FMP class (wires up all endpoint classes)
├── index.ts               # Main exports
├── types-only.ts          # Types-only entry point (fmp-node-api/types)
├── shared.ts              # Shared error types
├── endpoints/             # API endpoint classes (one per category)
│   ├── quote.ts
│   ├── stock.ts
│   ├── financial.ts
│   ├── company.ts
│   ├── etf.ts
│   ├── mutual-fund.ts
│   ├── economic.ts
│   ├── market.ts
│   ├── list.ts
│   ├── screener.ts
│   ├── calendar.ts
│   ├── senate-house.ts
│   ├── institutional.ts
│   ├── insider.ts
│   ├── sec.ts
│   └── news.ts
├── utils/                 # Utility functions
│   ├── validation.ts      # Input validation
│   ├── formatting.ts      # Data formatting
│   ├── constants.ts       # API constants
│   ├── helpers.ts         # Shared helpers
│   ├── debug.ts           # Debug logging
│   └── utils.ts           # Misc utilities
├── live/                  # Live-check classifier (dev-only; not exported/shipped)
│   └── validate.ts        # Relaxed validator / classifier (PASS/FAIL/SKIP/DRIFT)
└── __tests__/             # Jest tests (client, fmp, integration, endpoints/, utils/, live/)

scripts/
├── test-endpoint.ts       # Manual live-API endpoint inspector (raw JSON, one endpoint)
└── live/                  # Live-API shape-check tool (pnpm test:live)
    ├── run.ts             # CLI runner (flags, throttle, budget, summary)
    ├── manifest.ts        # Data-driven registry of cases (endpoint + inputs + schema)
    └── tsconfig.json      # Type-checks the runner (pnpm type-check:live)

Contributing

We welcome contributions! This is a community-driven project, and your help is greatly appreciated.

Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes following our development guidelines
4. Run quality checks: pnpm lint && pnpm test && pnpm type-check
5. Open a Pull Request with a clear description of your changes

Development Setup

# Install dependencies
pnpm install

# Set up environment
cp .env.example .env
# Add your FMP_API_KEY to .env

# Build and test
pnpm build
pnpm test

Getting Help

• 📖 Contributing Guide: Detailed guidelines and development setup
• 🐛 Issues: Report bugs or request features
• 📚 Documentation: Check the docs first

Before Contributing

• [ ] Read the Contributing Guide
• [ ] Check existing issues to avoid duplicates
• [ ] Test with the latest version of the library
• [ ] Follow our coding standards and testing requirements

Issues and Support

Reporting Issues

Before creating an issue, please:

1. Check existing issues to avoid duplicates
2. Search the documentation for solutions
3. Test with the latest version of the library
4. Provide a minimal reproduction of the problem

Issue Guidelines

• Be specific: Provide clear, actionable information
• Include examples: Code examples help reproduce issues
• Check versions: Mention Node.js and library versions
• Separate concerns: Don't mix multiple issues in one report

Support Channels

• 🐛 GitHub Issues: For bug reports and feature requests
• 📧 FMP Official Support: For issues with the underlying FMP API service

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions, please visit the GitHub repository.

Disclaimer

This package is not affiliated with, endorsed by, or sponsored by Financial Modeling Prep (FMP). This is an independent, community-developed Node.js wrapper for the FMP API.

Important Legal Information

• No Affiliation: This library is developed independently and is not officially associated with Financial Modeling Prep
• No Warranty: This software is provided "as is" without any warranties, express or implied
• User Responsibility: Users are responsible for:
  • Complying with FMP's terms of service and API usage limits
  • Obtaining and maintaining valid API keys from Financial Modeling Prep
  • Ensuring their usage complies with applicable laws and regulations
• Limitation of Liability: The developers of this wrapper are not responsible for:
  • Any issues with the underlying FMP API service
  • Data accuracy or availability from the FMP API
  • Any financial losses or damages resulting from the use of this library
  • API rate limiting, downtime, or service interruptions
• Official Support: For official support, documentation, or API issues, please contact Financial Modeling Prep directly at their official channels