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

Package detail

fmp-ai-tools

readme