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

``bash
npm install fmp-ai-tools


or

pnpm add fmp-ai-tools

or

yarn add fmp-ai-tools
`

$3

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

`bash


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

$3

⚠️ 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

$3

`typescript
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();
}
`

$3

`typescript
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:

`bash
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.

$3

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

Two logging modes controlled by environment variables:

#### Full Logging Mode

`bash
FMP_TOOLS_LOG_API_RESULTS=true
`

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

#### Data-Only Logging Mode

`bash
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

$3

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

$3

- getCompanyProfile - Get comprehensive company profile and information

$3

- 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)

$3

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

$3

- 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

$3

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

$3

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

$3

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

$3

- 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

$3

- getInstitutionalHolders - Get institutional holders for a company

$3

- 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:

$3

`typescript
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,
});
`

$3

`typescript
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,
});
`

$3

`typescript
// 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:

`bash


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:

`typescript
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