F
FMP Node Wrapper
← Back to Home

FMP Tools Documentation

Tool Reference

OpenAI Agents Integration

Learn how to integrate FMP Tools with OpenAI Agents to create autonomous AI agents with financial data capabilities.

Overview

The OpenAI Agents integration allows you to build sophisticated AI agents that can access real-time financial data. Perfect for creating autonomous financial analysis tools, investment research assistants, and market monitoring systems.

Prerequisites

Before you begin, make sure you have:

  • FMP API Key - Get your free API key from Financial Modeling Prep (10% discount on paid plans)
  • OpenAI API Key - Required for the AI model (get from OpenAI Platform)
  • Node.js 18+ - Required for OpenAI Agents
  • @openai/agents - Version 0.1.0 or 0.1.1 only (other versions are not compatible)
  • zod - Version ^3.25.76 (required for schema validation)

Installation

Install the required packages:

⚠️ Important Version Requirements:

  • @openai/agents: Must be exactly version 0.1.0 or 0.1.1
  • zod: Must be version ^3.25.76

Quick Start

1. Set Environment Variables

Create a .env.local file in your project root:

.env.local

2. Basic Usage with OpenAI Agents

app/api/agent/route.ts

3. Create Agent Component

components/agent-chat.tsx

4. Use in Your App

app/page.tsx

Available Tools

FMP Tools provides comprehensive financial tools organized into categories:

📊 Quote Tools

  • getStockQuote - Real-time stock quotes and price data

🏢 Company Tools

  • getCompanyProfile - Comprehensive company profiles and information
  • getCompanySharesFloat - Company shares float and liquidity data
  • getCompanyExecutiveCompensation - Executive compensation information

💰 Financial Tools

  • getBalanceSheet - Balance sheet statements (annual/quarterly)
  • getIncomeStatement - Income statements (annual/quarterly)
  • getCashFlowStatement - Cash flow statements (annual/quarterly)
  • getKeyMetrics - Key financial metrics and KPIs (annual/quarterly)
  • getFinancialRatios - Financial ratios and metrics (annual/quarterly)
  • getEnterpriseValue - Enterprise value calculations (annual/quarterly)
  • getCashflowGrowth - Cash flow growth analysis (annual/quarterly)
  • getIncomeGrowth - Income growth analysis (annual/quarterly)

📈 Market Tools

  • getMarketPerformance - Overall market performance data
  • getSectorPerformance - Sector performance data
  • getGainers - Top gaining stocks
  • getLosers - Top losing stocks
  • getMostActive - Most actively traded stocks

🏛️ Economic Tools

  • getTreasuryRates - Treasury rates and yields
  • getEconomicIndicators - Economic indicators including GDP, CPI, unemployment, inflation, retail sales, consumer sentiment, durable goods, housing starts, vehicle sales, and more

📋 ETF Tools

  • getETFHoldings - Holdings for a specific ETF
  • getETFProfile - ETF profile and information

📅 Calendar Tools

  • getEarningsCalendar - Upcoming earnings calendar
  • getEconomicCalendar - Economic calendar events

🏛️ Congressional Tools

  • getSenateTrading - Recent Senate trading activity by symbol
  • getHouseTrading - Recent House trading activity by symbol
  • getSenateTradingByName - Senate trading by politician name
  • getHouseTradingByName - House trading by politician name
  • getSenateTradingRSSFeed - Senate trading RSS feed with pagination
  • getHouseTradingRSSFeed - House trading RSS feed with pagination

🏢 Institutional Tools

  • getInstitutionalHolders - Institutional holders for a company

👤 Insider Tools

  • getInsiderTrading - Insider trading data for a company

📊 Stock Tools

  • getMarketCap - Market capitalization for a company
  • getStockSplits - Historical stock splits for a company
  • getDividendHistory - Dividend history and payments for a company

View detailed tool categories →

Advanced Configuration

Using Specific Tool Categories

Using Individual Tools

Custom Agent Configuration

Example Use Cases

Financial Analysis Assistant

Market Research Bot

Company Research Specialist

Tool Structure

All tools in the OpenAI provider are structured as arrays, making them easy to combine and filter:

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 include built-in error handling and validation:

  • Input Validation: All tools use Zod schemas to validate input parameters
  • API Error Handling: Graceful handling of FMP API errors and rate limits
  • User-Friendly Messages: Clear error messages for debugging and user feedback

Version Compatibility

OpenAI Agents Version Requirements

⚠️ Critical: FMP Tools only works with specific versions of @openai/agents:

  • ✅ Supported: @openai/agents@0.1.0 and @openai/agents@0.1.1
  • ❌ Not Supported: Any other versions (including newer versions)

Zod Version Requirements

⚠️ Important: The zod package must be compatible with the schema validation:

  • ✅ Supported: zod@^3.25.76 or zod@^4.0.0
  • ❌ Not Supported: Older versions of zod

Common Installation Issues

If you encounter errors like:

  • Invalid schema for function 'getStockQuote': schema must be a JSON Schema of 'type: "object"'
  • Module not found: @openai/agents
  • TypeError: Cannot read property 'tool' of undefined

Solution: Ensure you're using the exact versions specified above.

Performance Considerations

  • Tool Selection: Only include the tools you need to reduce agent complexity
  • Rate Limiting: Be mindful of FMP API rate limits in production
  • Caching: Consider implementing caching for frequently requested data

Migration from Vercel AI

If you're migrating from the Vercel AI provider:

  1. Import Changes: Change from fmp-ai-tools/vercel-ai to fmp-ai-tools/openai
  2. Tool Usage: Tools are now arrays instead of objects
  3. Framework: Use OpenAI Agents instead of Vercel AI SDK

Next Steps

Related Resources