FMP AI Tools

AI tools for Financial Modeling Prep (FMP) Node API - compatible with Vercel AI SDK, OpenAI Agents, and more.

This package provides pre-built AI tools that can be used with various AI frameworks. For direct API access, use the fmp-node-api package.

Installation

npm install fmp-ai-tools
# or
pnpm add fmp-ai-tools
# or
yarn add fmp-ai-tools

Peer Dependencies

This package requires the following peer dependencies to be installed in your project:

# For Vercel AI SDK
npm install ai zod
# or
pnpm add ai zod
# or
yarn add ai zod

Required versions:

• ai: ^5.0.0
• zod: ^3.25.76

⚠️ Common Issue: If you encounter the error Invalid schema for function 'getStockQuote': schema must be a JSON Schema of 'type: "object"', got 'type: "None"', it means you have a version mismatch between ai and zod. Make sure you're using compatible versions as listed above.

Version Compatibility

OpenAI Agents Compatibility

⚠️ Important: This package requires @openai/agents version ^0.1.0 or higher due to breaking changes in the API.

If you're using an older version, you'll encounter errors like:

Quick Start

Vercel AI SDK (Recommended)

import { openai } from '@ai-sdk/openai';
import { streamText, convertToModelMessages, stepCountIs } from 'ai';
import { fmpTools } from 'fmp-ai-tools/vercel-ai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai('gpt-4o-mini'),
    messages: convertToModelMessages(messages),
    tools: fmpTools,
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}

OpenAI Agents

import { Agent } from '@openai/agents';
import { fmpTools } from 'fmp-ai-tools/openai';

const agent = new Agent({
  name: 'Financial Analyst',
  instructions: 'You are a financial analyst with access to real-time market data.',
  tools: fmpTools,
});

const result = await agent.run({
  messages: [
    {
      role: 'user',
      content:
        'Get the current stock quote for Apple (AAPL) and show me their latest balance sheet',
    },
  ],
});

Configuration

Important: You must set your FMP API key as an environment variable for the tools to work:

FMP_API_KEY=your_api_key_here

Get your API key from Financial Modeling Prep and get your API key. This link will get you 10% off.

The tools internally use the fmp-node-api library, which reads this environment variable to authenticate with the Financial Modeling Prep API.

Debugging and Logging

⚠️ Development Only: These logging features are intended for debugging and development, not production use.

Two logging modes controlled by environment variables:

Full Logging Mode

FMP_TOOLS_LOG_API_RESULTS=true

Logs: tool name, input parameters, result summary with token count, execution time.

Data-Only Logging Mode

FMP_TOOLS_LOG_DATA_ONLY=true

Logs: result summary and formatted JSON response data.

Example Output

Full Logging:

🔧 getStockQuote: object (~28 tokens)
⏱️ Execution Time: 245ms

Data-Only Logging:

📤 Result: { "symbol": "AAPL", "price": 150.25, ... }

Note: Both modes are disabled by default. Use only during development.

Available Tools

Quote Tools

• getStockQuote - Get real-time stock quote for a company

Company Tools

• getCompanyProfile - Get comprehensive company profile and information

Financial Tools

• getBalanceSheet - Get balance sheet statements (annual/quarterly)
• getIncomeStatement - Get income statements (annual/quarterly)
• getCashFlowStatement - Get cash flow statements (annual/quarterly)
• getFinancialRatios - Get financial ratios and metrics (annual/quarterly)

Stock Tools

• getMarketCap - Get market capitalization for a company
• getStockSplits - Get historical stock splits for a company
• getDividendHistory - Get dividend history and payments for a company

Market Tools

• getMarketPerformance - Get overall market performance data
• getSectorPerformance - Get sector performance data
• getGainers - Get top gaining stocks
• getLosers - Get top losing stocks
• getMostActive - Get most actively traded stocks

Economic Tools

• getTreasuryRates - Get treasury rates and yields
• getEconomicIndicators - Get economic indicators (GDP, CPI, unemployment, etc.)

ETF Tools

• getETFHoldings - Get holdings for a specific ETF
• getETFProfile - Get ETF profile and information

Calendar Tools

• getEarningsCalendar - Get upcoming earnings calendar
• getEconomicCalendar - Get economic calendar events

Senate & House Trading Tools

• getSenateTrading - Get recent Senate trading activity
• getHouseTrading - Get recent House trading activity
• getSenateTradingByName - Get Senate trading by politician name
• getHouseTradingByName - Get House trading by politician name
• getSenateTradingRSSFeed - Get Senate trading RSS feed
• getHouseTradingRSSFeed - Get House trading RSS feed

Institutional Tools

• getInstitutionalHolders - Get institutional holders for a company

Insider Trading Tools

• getInsiderTrading - Get insider trading data for a company

Using Individual Tools

You can import and use specific tool categories or individual tools from either provider:

Import Specific Categories (Vercel AI)

import { quoteTools, financialTools, marketTools } from 'fmp-ai-tools/vercel-ai';

// Use only quote and financial tools
const selectedTools = {
  ...quoteTools,
  ...financialTools,
};

// Use with Vercel AI SDK
const result = streamText({
  model: openai('gpt-4o-mini'),
  messages: convertToModelMessages(messages),
  tools: selectedTools,
});

Import Specific Categories (OpenAI)

import { quoteTools, financialTools, marketTools } from 'fmp-ai-tools/openai';

// Use only quote and financial tools
const selectedTools = [...quoteTools, ...financialTools];

// Use with OpenAI Agents
const agent = new Agent({
  name: 'Financial Analyst',
  instructions: 'You are a financial analyst with access to real-time market data.',
  tools: selectedTools,
});

Import Individual Tools

// Vercel AI SDK
import { getStockQuote, getCompanyProfile } from 'fmp-ai-tools/vercel-ai';

// OpenAI Agents
import { getStockQuote, getCompanyProfile } from 'fmp-ai-tools/openai';

Example Tool Usage

Here are some example prompts you can use with the tools:

Stock Analysis:

"Get the current stock quote for Apple (AAPL) and show me their latest balance sheet"

Market Research:

"What are the top gaining stocks today and show me the overall market performance?"

Economic Analysis:

"Get the current treasury rates and show me the latest GDP data"

ETF Research:

"Show me the holdings of SPY ETF and get its profile information"

Financial Analysis:

"Get Apple's income statement, cash flow statement, and financial ratios for the last year"

Tool Parameters

Each tool accepts specific parameters. Here are some common ones:

• symbol - Stock/ETF symbol (e.g., "AAPL", "SPY")
• period - For financial statements: "annual" or "quarter"
• from - Start date in YYYY-MM-DD format
• to - End date in YYYY-MM-DD format
• name - For economic indicators: specific indicator name

Error Handling

The tools handle API errors gracefully and will return informative error messages if:

• The API key is invalid or missing
• The requested data is not available
• Rate limits are exceeded
• Invalid parameters are provided

Testing Tools

Test individual tools:

# Test specific tools
pnpm test:tool getStockQuote
pnpm test:tool getCompanyProfile
pnpm test:tool getBalanceSheet
pnpm test:tool getMarketPerformance

For Direct API Access

If you need direct access to the FMP API without AI tools, use the fmp-node-api package:

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

const fmp = new FMP({ apiKey: 'your_api_key_here' });

// Direct API calls
const quote = await fmp.quote.getQuote('AAPL');
const profile = await fmp.company.getCompanyProfile('AAPL');

License

MIT