# FMP Data Client
[](https://github.com/MehdiZare/fmp-data/actions/workflows/ci.yml)
[](https://pypi.org/project/fmp-data/)
[](https://pypi.org/project/fmp-data/)
[](https://codecov.io/gh/MehdiZare/fmp-data)
[](https://github.com/astral-sh/uv)
[](https://opensource.org/licenses/MIT)
A Python client for the Financial Modeling Prep (FMP) API with comprehensive logging, rate limiting, and error handling. Built with UV for fast, reliable dependency management and modern Python development practices.
## Why UV?
This project uses UV as the primary package management tool for several key benefits:
- **Lightning-fast performance** - 10-100x faster than pip and pip-tools
- **Deterministic builds** with lock files ensuring reproducible environments
- **Drop-in pip replacement** with familiar commands and workflows
- **Virtual environment management** that's transparent and reliable
- **Built in Rust** for maximum performance and reliability
- **Dependency resolution** that prevents conflicts before they happen
## Features
- Simple and intuitive interface
- Built-in rate limiting
- Comprehensive logging
- Async support
- Type hints and validation with Pydantic
- Automatic retries with exponential backoff
- 85%+ test coverage with comprehensive test suite
- Secure API key handling
- Support for all major FMP endpoints
- Detailed error messages
- Configurable retry strategies
- **Langchain Integration**
- **MCP Server Support**
## Getting an API Key
To use this library, you'll need an API key from Financial Modeling Prep (FMP). You can:
- Get a [free API key from FMP](https://site.financialmodelingprep.com/pricing-plans?couponCode=mehdi)
- All paid plans come with a 10% discount.
## Installation
### Using UV (Recommended)
```bash
# Basic installation
uv pip install fmp-data
# With Langchain integration
uv pip install "fmp-data[langchain]"
# With MCP server support
uv pip install "fmp-data[mcp]"
# With both integrations
uv pip install "fmp-data[langchain,mcp]"
```
### Using pip
```bash
# Basic installation
pip install fmp-data
# With extras
pip install fmp-data[langchain]
pip install fmp-data[mcp]
pip install fmp-data[langchain,mcp]
```
## MCP Server (Claude Desktop Integration)
Model Context Protocol (MCP) server provides financial data access through a standardized protocol, enabling Claude Desktop to query FMP data seamlessly.
### Quick Setup for Claude Desktop
```bash
# Install with MCP support
pip install fmp-data[mcp]
# Run interactive setup wizard
fmp-mcp setup
```
The setup wizard will automatically configure Claude Desktop with FMP Data tools. After setup, restart Claude Desktop and try asking: "What's the current price of AAPL?"
### Manual Configuration
```bash
# Set your API key
export FMP_API_KEY=your_api_key_here
# Run the MCP server
fmp-mcp
```
For detailed setup instructions, see [MCP Setup Guide](examples/MCP_SETUP_GUIDE.md).
### Available Commands
```bash
fmp-mcp setup # Interactive setup wizard
fmp-mcp status # Check server status
fmp-mcp test # Test connection
fmp-mcp list # List available tools
```
### Configuration Profiles
Choose from pre-configured tool sets:
- **Default** - Complete toolkit
- **Minimal** - Essential tools only
### Custom Configuration
```bash
# Environment variables
export FMP_API_KEY=your_api_key_here
export FMP_MCP_MANIFEST=/path/to/custom/manifest.py
# Custom manifest example (manifest.py)
TOOLS = [
"company.profile",
"company.search",
"market.quote",
"fundamental.income_statement",
"fundamental.balance_sheet"
]
```
### Integration with AI Assistants
The MCP server exposes FMP endpoints as tools that can be used by MCP-compatible AI assistants:
```python
from fmp_data.mcp.server import create_app
# Create MCP server with default tools
app = create_app()
# Create with custom tools
app = create_app(tools=["company.profile", "market.quote"])
# Create with manifest file
app = create_app(tools="/path/to/manifest.py")
```
### Available Tools
The server supports all FMP endpoints through a simple naming convention:
- `company.profile` - Get company profiles
- `company.search` - Search companies
- `market.quote` - Get real-time quotes
- `fundamental.income_statement` - Financial statements
- `technical.indicators` - Technical analysis
- And many more...
## Langchain Integration
### Prerequisites
- FMP API Key (`FMP_API_KEY`) - [Get one here](https://site.financialmodelingprep.com/pricing-plans?couponCode=mehdi)
- OpenAI API Key (`OPENAI_API_KEY`) - Required for embeddings
### Quick Start with Vector Store
```python
from fmp_data import create_vector_store
# Initialize the vector store
vector_store = create_vector_store(
fmp_api_key="YOUR_FMP_API_KEY", # pragma: allowlist secret
openai_api_key="YOUR_OPENAI_API_KEY" # pragma: allowlist secret
)
# Example queries
queries = [
"what is the price of Apple stock?",
"what was the revenue of Tesla last year?",
"what's new in the market?"
]
# Search for relevant endpoints and tools
for query in queries:
print(f"\nQuery: {query}")
# Get tools formatted for OpenAI
tools = vector_store.get_tools(query, provider="openai")
print("\nMatching Tools:")
for tool in tools:
print(f"Name: {tool.get('name')}")
print(f"Description: {tool.get('description')}")
print("Parameters:", tool.get('parameters'))
print()
# You can also search endpoints directly
results = vector_store.search(query)
print("\nRelevant Endpoints:")
for result in results:
print(f"Endpoint: {result.name}")
print(f"Score: {result.score:.2f}")
print()
```
### Alternative Setup: Using Configuration
```python
from fmp_data import FMPDataClient, ClientConfig
from fmp_data.lc.config import LangChainConfig
from fmp_data.lc.embedding import EmbeddingProvider
# Configure with LangChain support
config = LangChainConfig(
api_key="YOUR_FMP_API_KEY", # pragma: allowlist secret
embedding_provider=EmbeddingProvider.OPENAI,
embedding_api_key="YOUR_OPENAI_API_KEY", # pragma: allowlist secret
embedding_model="text-embedding-3-small"
)
# Create client with LangChain config
client = FMPDataClient(config=config)
# Create vector store using the client
vector_store = client.create_vector_store()
# Search for relevant endpoints
results = vector_store.search("show me Tesla's financial metrics")
for result in results:
print(f"Found endpoint: {result.name}")
print(f"Relevance score: {result.score:.2f}")
```
### Interactive Example
Try out the LangChain integration in our interactive Colab notebook:
[](link-to-your-colab-notebook)
This notebook demonstrates how to:
- Build an intelligent financial agent using fmp-data and LangChain
- Access real-time market data through natural language queries
- Use semantic search to select relevant financial tools
- Create multi-turn conversations about financial data
### Environment Variables
You can also configure the integration using environment variables:
```bash
# Required
export FMP_API_KEY=your_fmp_api_key_here
export OPENAI_API_KEY=your_openai_api_key_here
# Optional
export FMP_EMBEDDING_PROVIDER=openai
export FMP_EMBEDDING_MODEL=text-embedding-3-small
```
### Features
- Semantic search across all FMP endpoints
- Auto-conversion to LangChain tools
- Query endpoints using natural language
- Relevance scoring for search results
- Automatic caching of embeddings
- Persistent vector store for faster lookups
## Quick Start
```python
from fmp_data import FMPDataClient, ClientConfig, LoggingConfig
from fmp_data.exceptions import FMPError, RateLimitError, AuthenticationError
# Method 1: Initialize with direct API key
client = FMPDataClient(api_key="your_api_key_here") # pragma: allowlist secret
# Method 2: Initialize from environment variable (FMP_API_KEY)
client = FMPDataClient.from_env()
# Method 3: Initialize with custom configuration
config = ClientConfig(
api_key="your_api_key_here", #pragma: allowlist secret
timeout=30,
max_retries=3,
base_url="https://financialmodelingprep.com",
logging=LoggingConfig(level="INFO")
)
client = FMPDataClient(config=config)
# Using with context manager (recommended)
with FMPDataClient(api_key="your_api_key_here") as client: # pragma: allowlist secret
try:
# Get company profile
profile = client.company.get_profile("AAPL")
print(f"Company: {profile.company_name}")
print(f"Industry: {profile.industry}")
print(f"Market Cap: ${profile.mkt_cap:,.2f}")
# Search companies
results = client.company.search("Tesla", limit=5)
for company in results:
print(f"{company.symbol}: {company.name}")
except RateLimitError as e:
print(f"Rate limit exceeded. Wait {e.retry_after} seconds")
except AuthenticationError:
print("Invalid API key")
except FMPError as e:
print(f"API error: {e}")
# Client is automatically closed after the with block
```
## Available Client Modules
The FMP Data Client provides access to all FMP API endpoints through specialized client modules:
- **company**: Company profiles, executives, employee counts, peers
- **market**: Real-time quotes, historical prices, market hours
- **fundamental**: Financial statements (income, balance sheet, cash flow)
- **technical**: Technical indicators (SMA, EMA, RSI, MACD, etc.)
- **intelligence**: Market news, SEC filings, press releases
- **institutional**: Institutional holdings, insider trading
- **investment**: ETF and mutual fund data
- **alternative**: Crypto, forex, and commodity data
- **economics**: Economic indicators and calendar data
## Key Components
### 1. Company Information
```python
from fmp_data import FMPDataClient
with FMPDataClient.from_env() as client:
# Get company profile
profile = client.company.get_profile("AAPL")
# Get company executives
executives = client.company.get_executives("AAPL")
# Search companies
results = client.company.search_ticker("apple", limit=5)
# Get employee count history
employees = client.company.get_employee_count("AAPL")
# Get company peers
peers = client.company.get_company_peers("AAPL")
```
### 2. Financial Statements
```python
from fmp_data import FMPDataClient
with FMPDataClient.from_env() as client:
# Get income statements
income_stmt = client.fundamental.get_income_statement(
"AAPL",
period="quarter", # or "annual"
limit=4
)
# Get balance sheets
balance_sheet = client.fundamental.get_balance_sheet(
"AAPL",
period="annual"
)
# Get cash flow statements
cash_flow = client.fundamental.get_cash_flow_statement("AAPL")
```
### 3. Market Data
```python
from fmp_data import FMPDataClient
from datetime import date
with FMPDataClient.from_env() as client:
# Get real-time quote
quote = client.company.get_quote("TSLA")
# Get historical prices
history = client.company.get_historical_price(
"TSLA",
start_date=date(2023, 1, 1),
end_date=date(2023, 12, 31)
)
# Get intraday prices
intraday = client.company.get_historical_price_intraday(
"TSLA",
interval="5min",
start_date=date(2024, 1, 1)
)
```
### 4. Technical Indicators
```python
from fmp_data import FMPDataClient
from datetime import date
with FMPDataClient.from_env() as client:
# Simple Moving Average
sma = client.technical.get_sma(
"AAPL",
period_length=20,
timeframe="1day"
)
# RSI (Relative Strength Index)
rsi = client.technical.get_rsi(
"AAPL",
period_length=14,
timeframe="1day"
)
# MACD
macd = client.technical.get_macd(
"AAPL",
fast_period=12,
slow_period=26,
signal_period=9
)
```
### 5. Alternative Data
```python
from fmp_data import FMPDataClient
with FMPDataClient.from_env() as client:
# Crypto quotes
btc = client.alternative.get_crypto_quote("BTCUSD")
# Forex quotes
eurusd = client.alternative.get_forex_quote("EURUSD")
# Commodity quotes
gold = client.alternative.get_commodity_quote("GCUSD")
```
### 6. Institutional and Intelligence Data
```python
from fmp_data import FMPDataClient
with FMPDataClient.from_env() as client:
# Institutional holdings
holders = client.institutional.get_institutional_holders("AAPL")
# Insider trading
insider = client.institutional.get_insider_trading("AAPL")
# Market news
news = client.intelligence.get_stock_news("TSLA", limit=10)
# SEC filings
filings = client.intelligence.get_sec_filings("AAPL", type="10-K")
```
### 7. Async Support (Coming Soon)
Note: Async support is currently under development and will be available in a future release.
## Configuration
### Environment Variables
```bash
# Required
FMP_API_KEY=your_api_key_here
# Optional
FMP_BASE_URL=https://financialmodelingprep.com
FMP_TIMEOUT=30
FMP_MAX_RETRIES=3
# Rate Limiting
FMP_DAILY_LIMIT=250
FMP_REQUESTS_PER_SECOND=10
FMP_REQUESTS_PER_MINUTE=300
# Logging
FMP_LOG_LEVEL=INFO
FMP_LOG_PATH=/path/to/logs
FMP_LOG_MAX_BYTES=10485760
FMP_LOG_BACKUP_COUNT=5
# MCP Server
FMP_MCP_MANIFEST=/path/to/custom/manifest.py
```
### Custom Configuration
```python
from fmp_data import FMPDataClient, ClientConfig, LoggingConfig, RateLimitConfig, LogHandlerConfig
config = ClientConfig(
api_key="your_api_key_here", # pragma: allowlist secret
timeout=30,
max_retries=3,
base_url="https://financialmodelingprep.com",
rate_limit=RateLimitConfig(
daily_limit=250,
requests_per_second=10,
requests_per_minute=300
),
logging=LoggingConfig(
level="DEBUG",
handlers={
"console": LogHandlerConfig(
class_name="StreamHandler",
level="INFO",
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
),
"file": LogHandlerConfig(
class_name="RotatingFileHandler",
level="DEBUG",
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
handler_kwargs={
"filename": "fmp.log",
"maxBytes": 10485760,
"backupCount": 5
}
)
}
)
)
client = FMPDataClient(config=config)
```
## Error Handling
```python
from fmp_data import FMPDataClient
from fmp_data.exceptions import (
FMPError,
RateLimitError,
AuthenticationError,
ValidationError,
ConfigError
)
try:
with FMPDataClient.from_env() as client:
profile = client.company.get_profile("INVALID")
except RateLimitError as e:
print(f"Rate limit exceeded. Wait {e.retry_after} seconds")
print(f"Status code: {e.status_code}")
print(f"Response: {e.response}")
except AuthenticationError as e:
print("Invalid API key or authentication failed")
print(f"Status code: {e.status_code}")
except ValidationError as e:
print(f"Invalid parameters: {e.message}")
except ConfigError as e:
print(f"Configuration error: {e.message}")
except FMPError as e:
print(f"General API error: {e.message}")
```
## Development Setup
### Prerequisites
- Python 3.10+
- UV (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)
### Setup
1. Clone the repository:
```bash
git clone https://github.com/MehdiZare/fmp-data.git
cd fmp-data
```
2. Install dependencies with UV:
```bash
# Create virtual environment and install all dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install package in editable mode with all extras
uv pip install -e ".[langchain,mcp]" --all-extras
# Install development dependencies
uv pip install --group dev -e .
```
3. Set up pre-commit hooks:
```bash
pre-commit install
```
5. Set up environment variables:
```bash
# Create .env file
echo "FMP_API_KEY=your_api_key_here" > .env
```
## Running Tests
### Basic Test Commands
```bash
# Run all tests with coverage
pytest --cov=fmp_data
# Run tests with coverage report
pytest --cov=fmp_data --cov-report=html
# Run specific test file
pytest tests/unit/test_client.py
# Run tests with verbose output
pytest -v
# Run integration tests (requires API key)
FMP_TEST_API_KEY=your_test_api_key pytest tests/integration/
# Using make commands (if available)
make test # Run unit tests
make test-cov # Run tests with coverage
make test-all # Run all tests for all Python versions
```
### Development Commands
```bash
# Format code with ruff and black
ruff format fmp_data tests
black fmp_data tests
# Lint with ruff
ruff check fmp_data tests --fix
# Type checking with mypy
mypy fmp_data
# Run all quality checks
pre-commit run --all-files
# Using make commands (recommended)
make fix # Auto-fix all issues
make lint # Run linting
make typecheck # Run type checking
make check # Run all checks
make test # Run tests
make test-cov # Run tests with coverage report
make ci # Run full CI checks locally
```
### Building and Publishing
```bash
# Build the package
uv build
# Or using Python build
python -m build
# Check package before publishing
twine check dist/*
# Publish to PyPI (maintainers only)
twine upload dist/*
# Using make commands
make build # Build package
make build-check # Build and verify
```
### UV Configuration
```bash
# Create virtual environment
uv venv
# Activate virtual environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install/upgrade packages
uv pip install --upgrade package-name
# Sync dependencies from pyproject.toml
uv pip sync pyproject.toml
# Export requirements.txt (if needed)
uv pip freeze > requirements.txt
# Compile requirements (fast dependency resolution)
uv pip compile pyproject.toml -o requirements.txt
```
View the latest test coverage report [here](https://codecov.io/gh/MehdiZare/fmp-data).
## Contributing
We welcome contributions! Please follow these steps:
### Getting Started
1. Fork the repository
2. Clone your fork:
```bash
git clone https://github.com/yourusername/fmp-data.git
cd fmp-data
```
3. Set up development environment:
```bash
# Create and activate virtual environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies with UV
uv pip install -e ".[langchain,mcp]" --all-extras
# Install pre-commit hooks
pre-commit install
```
### Making Changes
1. Create a feature branch:
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes and ensure quality:
```bash
# Format code
ruff format fmp_data tests
black fmp_data tests
# Fix linting issues
ruff check fmp_data tests --fix
# Run type checking
mypy fmp_data
# Run tests
pytest --cov=fmp_data
# Or use make commands
make fix # Fix all auto-fixable issues
make check # Run all checks
```
3. Commit your changes:
```bash
git add .
git commit -m "feat: add your feature description"
```
4. Push and create a pull request
### Requirements
Please ensure your contributions meet these requirements:
- Tests pass: `pytest` or `make test`
- Code is formatted: `ruff format` and `black` or `make fix`
- Code passes linting: `ruff check` or `make lint`
- Type hints are included for all functions
- Documentation is updated for new features
- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
- Test coverage remains above 80%
### Running Quality Checks
```bash
# Run all quality checks at once
pre-commit run --all-files
# Or use make commands (recommended)
make check # Run all checks
make fix # Fix all auto-fixable issues
make test # Run tests
make test-cov # Run tests with coverage
# Or run individual checks
ruff check fmp_data tests
black --check fmp_data tests
mypy fmp_data
pytest --cov=fmp_data
```
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## Acknowledgments
- Financial Modeling Prep for providing the API
- Contributors to the project
- Open source packages used in this project
## Support
- GitHub Issues: [Create an issue](https://github.com/MehdiZare/fmp-data/issues)
- Documentation: [Read the docs](./docs)
## Examples
### Interactive Notebooks
- [Financial Agent Tutorial](https://colab.research.google.com/drive/1cSyLX-j9XhyrXyVJ2HwMZJvPy1Lf2CuA?usp=sharing): Build an intelligent financial agent with LangChain integration
- [Basic Usage Examples](./examples): Simple code examples demonstrating key features
### Code Examples
```python
# Basic usage example
from fmp_data import FMPDataClient
with FMPDataClient.from_env() as client:
# Get company profile
profile = client.company.get_profile("AAPL")
print(f"Company: {profile.company_name}")
```
## Release Notes
See [CHANGELOG.md](./CHANGELOG.md) for a list of changes in each release.
Raw data
{
"_id": null,
"home_page": null,
"name": "fmp-data",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": "Mehdi Zare <mehdizare@users.noreply.github.com>",
"keywords": "api, financial, financial data, fmp, market-data, stock market, stocks",
"author": null,
"author_email": "Mehdi Zare <mehdizare@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/69/a8/f1d86e71fb39cd47473059c8d59929020fe3a702d28f067863ce2a1067db/fmp_data-1.0.2.tar.gz",
"platform": null,
"description": "# FMP Data Client\n\n[](https://github.com/MehdiZare/fmp-data/actions/workflows/ci.yml)\n[](https://pypi.org/project/fmp-data/)\n[](https://pypi.org/project/fmp-data/)\n[](https://codecov.io/gh/MehdiZare/fmp-data)\n[](https://github.com/astral-sh/uv)\n[](https://opensource.org/licenses/MIT)\n\nA Python client for the Financial Modeling Prep (FMP) API with comprehensive logging, rate limiting, and error handling. Built with UV for fast, reliable dependency management and modern Python development practices.\n\n## Why UV?\n\nThis project uses UV as the primary package management tool for several key benefits:\n- **Lightning-fast performance** - 10-100x faster than pip and pip-tools\n- **Deterministic builds** with lock files ensuring reproducible environments\n- **Drop-in pip replacement** with familiar commands and workflows\n- **Virtual environment management** that's transparent and reliable\n- **Built in Rust** for maximum performance and reliability\n- **Dependency resolution** that prevents conflicts before they happen\n\n## Features\n\n- Simple and intuitive interface\n- Built-in rate limiting\n- Comprehensive logging\n- Async support\n- Type hints and validation with Pydantic\n- Automatic retries with exponential backoff\n- 85%+ test coverage with comprehensive test suite\n- Secure API key handling\n- Support for all major FMP endpoints\n- Detailed error messages\n- Configurable retry strategies\n- **Langchain Integration**\n- **MCP Server Support**\n\n## Getting an API Key\n\nTo use this library, you'll need an API key from Financial Modeling Prep (FMP). You can:\n- Get a [free API key from FMP](https://site.financialmodelingprep.com/pricing-plans?couponCode=mehdi)\n- All paid plans come with a 10% discount.\n\n## Installation\n\n### Using UV (Recommended)\n\n```bash\n# Basic installation\nuv pip install fmp-data\n\n# With Langchain integration\nuv pip install \"fmp-data[langchain]\"\n\n# With MCP server support\nuv pip install \"fmp-data[mcp]\"\n\n# With both integrations\nuv pip install \"fmp-data[langchain,mcp]\"\n```\n\n### Using pip\n\n```bash\n# Basic installation\npip install fmp-data\n\n# With extras\npip install fmp-data[langchain]\npip install fmp-data[mcp]\npip install fmp-data[langchain,mcp]\n```\n\n## MCP Server (Claude Desktop Integration)\n\nModel Context Protocol (MCP) server provides financial data access through a standardized protocol, enabling Claude Desktop to query FMP data seamlessly.\n\n### Quick Setup for Claude Desktop\n\n```bash\n# Install with MCP support\npip install fmp-data[mcp]\n\n# Run interactive setup wizard\nfmp-mcp setup\n```\n\nThe setup wizard will automatically configure Claude Desktop with FMP Data tools. After setup, restart Claude Desktop and try asking: \"What's the current price of AAPL?\"\n\n### Manual Configuration\n\n```bash\n# Set your API key\nexport FMP_API_KEY=your_api_key_here\n\n# Run the MCP server\nfmp-mcp\n```\n\nFor detailed setup instructions, see [MCP Setup Guide](examples/MCP_SETUP_GUIDE.md).\n\n### Available Commands\n\n```bash\nfmp-mcp setup # Interactive setup wizard\nfmp-mcp status # Check server status\nfmp-mcp test # Test connection\nfmp-mcp list # List available tools\n```\n\n### Configuration Profiles\n\nChoose from pre-configured tool sets:\n- **Default** - Complete toolkit\n- **Minimal** - Essential tools only\n\n### Custom Configuration\n\n```bash\n# Environment variables\nexport FMP_API_KEY=your_api_key_here\nexport FMP_MCP_MANIFEST=/path/to/custom/manifest.py\n\n# Custom manifest example (manifest.py)\nTOOLS = [\n \"company.profile\",\n \"company.search\",\n \"market.quote\",\n \"fundamental.income_statement\",\n \"fundamental.balance_sheet\"\n]\n```\n\n### Integration with AI Assistants\n\nThe MCP server exposes FMP endpoints as tools that can be used by MCP-compatible AI assistants:\n\n```python\nfrom fmp_data.mcp.server import create_app\n\n# Create MCP server with default tools\napp = create_app()\n\n# Create with custom tools\napp = create_app(tools=[\"company.profile\", \"market.quote\"])\n\n# Create with manifest file\napp = create_app(tools=\"/path/to/manifest.py\")\n```\n\n### Available Tools\n\nThe server supports all FMP endpoints through a simple naming convention:\n- `company.profile` - Get company profiles\n- `company.search` - Search companies\n- `market.quote` - Get real-time quotes\n- `fundamental.income_statement` - Financial statements\n- `technical.indicators` - Technical analysis\n- And many more...\n\n## Langchain Integration\n\n### Prerequisites\n- FMP API Key (`FMP_API_KEY`) - [Get one here](https://site.financialmodelingprep.com/pricing-plans?couponCode=mehdi)\n- OpenAI API Key (`OPENAI_API_KEY`) - Required for embeddings\n\n### Quick Start with Vector Store\n\n```python\nfrom fmp_data import create_vector_store\n\n# Initialize the vector store\nvector_store = create_vector_store(\n fmp_api_key=\"YOUR_FMP_API_KEY\", # pragma: allowlist secret\n openai_api_key=\"YOUR_OPENAI_API_KEY\" # pragma: allowlist secret\n)\n\n# Example queries\nqueries = [\n \"what is the price of Apple stock?\",\n \"what was the revenue of Tesla last year?\",\n \"what's new in the market?\"\n]\n\n# Search for relevant endpoints and tools\nfor query in queries:\n print(f\"\\nQuery: {query}\")\n\n # Get tools formatted for OpenAI\n tools = vector_store.get_tools(query, provider=\"openai\")\n\n print(\"\\nMatching Tools:\")\n for tool in tools:\n print(f\"Name: {tool.get('name')}\")\n print(f\"Description: {tool.get('description')}\")\n print(\"Parameters:\", tool.get('parameters'))\n print()\n\n # You can also search endpoints directly\n results = vector_store.search(query)\n print(\"\\nRelevant Endpoints:\")\n for result in results:\n print(f\"Endpoint: {result.name}\")\n print(f\"Score: {result.score:.2f}\")\n print()\n```\n\n### Alternative Setup: Using Configuration\n\n```python\nfrom fmp_data import FMPDataClient, ClientConfig\nfrom fmp_data.lc.config import LangChainConfig\nfrom fmp_data.lc.embedding import EmbeddingProvider\n\n# Configure with LangChain support\nconfig = LangChainConfig(\n api_key=\"YOUR_FMP_API_KEY\", # pragma: allowlist secret\n embedding_provider=EmbeddingProvider.OPENAI,\n embedding_api_key=\"YOUR_OPENAI_API_KEY\", # pragma: allowlist secret\n embedding_model=\"text-embedding-3-small\"\n)\n\n# Create client with LangChain config\nclient = FMPDataClient(config=config)\n\n# Create vector store using the client\nvector_store = client.create_vector_store()\n\n# Search for relevant endpoints\nresults = vector_store.search(\"show me Tesla's financial metrics\")\nfor result in results:\n print(f\"Found endpoint: {result.name}\")\n print(f\"Relevance score: {result.score:.2f}\")\n```\n\n### Interactive Example\nTry out the LangChain integration in our interactive Colab notebook:\n[](link-to-your-colab-notebook)\n\nThis notebook demonstrates how to:\n- Build an intelligent financial agent using fmp-data and LangChain\n- Access real-time market data through natural language queries\n- Use semantic search to select relevant financial tools\n- Create multi-turn conversations about financial data\n\n### Environment Variables\nYou can also configure the integration using environment variables:\n```bash\n# Required\nexport FMP_API_KEY=your_fmp_api_key_here\nexport OPENAI_API_KEY=your_openai_api_key_here\n\n# Optional\nexport FMP_EMBEDDING_PROVIDER=openai\nexport FMP_EMBEDDING_MODEL=text-embedding-3-small\n```\n\n### Features\n- Semantic search across all FMP endpoints\n- Auto-conversion to LangChain tools\n- Query endpoints using natural language\n- Relevance scoring for search results\n- Automatic caching of embeddings\n- Persistent vector store for faster lookups\n\n## Quick Start\n\n```python\nfrom fmp_data import FMPDataClient, ClientConfig, LoggingConfig\nfrom fmp_data.exceptions import FMPError, RateLimitError, AuthenticationError\n\n# Method 1: Initialize with direct API key\nclient = FMPDataClient(api_key=\"your_api_key_here\") # pragma: allowlist secret\n\n# Method 2: Initialize from environment variable (FMP_API_KEY)\nclient = FMPDataClient.from_env()\n\n# Method 3: Initialize with custom configuration\nconfig = ClientConfig(\n api_key=\"your_api_key_here\", #pragma: allowlist secret\n timeout=30,\n max_retries=3,\n base_url=\"https://financialmodelingprep.com\",\n logging=LoggingConfig(level=\"INFO\")\n)\nclient = FMPDataClient(config=config)\n\n# Using with context manager (recommended)\nwith FMPDataClient(api_key=\"your_api_key_here\") as client: # pragma: allowlist secret\n try:\n # Get company profile\n profile = client.company.get_profile(\"AAPL\")\n print(f\"Company: {profile.company_name}\")\n print(f\"Industry: {profile.industry}\")\n print(f\"Market Cap: ${profile.mkt_cap:,.2f}\")\n\n # Search companies\n results = client.company.search(\"Tesla\", limit=5)\n for company in results:\n print(f\"{company.symbol}: {company.name}\")\n\n except RateLimitError as e:\n print(f\"Rate limit exceeded. Wait {e.retry_after} seconds\")\n except AuthenticationError:\n print(\"Invalid API key\")\n except FMPError as e:\n print(f\"API error: {e}\")\n\n# Client is automatically closed after the with block\n```\n\n## Available Client Modules\n\nThe FMP Data Client provides access to all FMP API endpoints through specialized client modules:\n\n- **company**: Company profiles, executives, employee counts, peers\n- **market**: Real-time quotes, historical prices, market hours\n- **fundamental**: Financial statements (income, balance sheet, cash flow)\n- **technical**: Technical indicators (SMA, EMA, RSI, MACD, etc.)\n- **intelligence**: Market news, SEC filings, press releases\n- **institutional**: Institutional holdings, insider trading\n- **investment**: ETF and mutual fund data\n- **alternative**: Crypto, forex, and commodity data\n- **economics**: Economic indicators and calendar data\n\n## Key Components\n\n### 1. Company Information\n```python\nfrom fmp_data import FMPDataClient\n\nwith FMPDataClient.from_env() as client:\n # Get company profile\n profile = client.company.get_profile(\"AAPL\")\n\n # Get company executives\n executives = client.company.get_executives(\"AAPL\")\n\n # Search companies\n results = client.company.search_ticker(\"apple\", limit=5)\n\n # Get employee count history\n employees = client.company.get_employee_count(\"AAPL\")\n\n # Get company peers\n peers = client.company.get_company_peers(\"AAPL\")\n```\n\n### 2. Financial Statements\n```python\nfrom fmp_data import FMPDataClient\n\nwith FMPDataClient.from_env() as client:\n # Get income statements\n income_stmt = client.fundamental.get_income_statement(\n \"AAPL\",\n period=\"quarter\", # or \"annual\"\n limit=4\n )\n\n # Get balance sheets\n balance_sheet = client.fundamental.get_balance_sheet(\n \"AAPL\",\n period=\"annual\"\n )\n\n # Get cash flow statements\n cash_flow = client.fundamental.get_cash_flow_statement(\"AAPL\")\n```\n\n### 3. Market Data\n```python\nfrom fmp_data import FMPDataClient\nfrom datetime import date\n\nwith FMPDataClient.from_env() as client:\n # Get real-time quote\n quote = client.company.get_quote(\"TSLA\")\n\n # Get historical prices\n history = client.company.get_historical_price(\n \"TSLA\",\n start_date=date(2023, 1, 1),\n end_date=date(2023, 12, 31)\n )\n\n # Get intraday prices\n intraday = client.company.get_historical_price_intraday(\n \"TSLA\",\n interval=\"5min\",\n start_date=date(2024, 1, 1)\n )\n```\n\n### 4. Technical Indicators\n```python\nfrom fmp_data import FMPDataClient\nfrom datetime import date\n\nwith FMPDataClient.from_env() as client:\n # Simple Moving Average\n sma = client.technical.get_sma(\n \"AAPL\",\n period_length=20,\n timeframe=\"1day\"\n )\n\n # RSI (Relative Strength Index)\n rsi = client.technical.get_rsi(\n \"AAPL\",\n period_length=14,\n timeframe=\"1day\"\n )\n\n # MACD\n macd = client.technical.get_macd(\n \"AAPL\",\n fast_period=12,\n slow_period=26,\n signal_period=9\n )\n```\n\n### 5. Alternative Data\n```python\nfrom fmp_data import FMPDataClient\n\nwith FMPDataClient.from_env() as client:\n # Crypto quotes\n btc = client.alternative.get_crypto_quote(\"BTCUSD\")\n\n # Forex quotes\n eurusd = client.alternative.get_forex_quote(\"EURUSD\")\n\n # Commodity quotes\n gold = client.alternative.get_commodity_quote(\"GCUSD\")\n```\n\n### 6. Institutional and Intelligence Data\n```python\nfrom fmp_data import FMPDataClient\n\nwith FMPDataClient.from_env() as client:\n # Institutional holdings\n holders = client.institutional.get_institutional_holders(\"AAPL\")\n\n # Insider trading\n insider = client.institutional.get_insider_trading(\"AAPL\")\n\n # Market news\n news = client.intelligence.get_stock_news(\"TSLA\", limit=10)\n\n # SEC filings\n filings = client.intelligence.get_sec_filings(\"AAPL\", type=\"10-K\")\n```\n\n### 7. Async Support (Coming Soon)\nNote: Async support is currently under development and will be available in a future release.\n\n## Configuration\n\n### Environment Variables\n```bash\n# Required\nFMP_API_KEY=your_api_key_here\n\n# Optional\nFMP_BASE_URL=https://financialmodelingprep.com\nFMP_TIMEOUT=30\nFMP_MAX_RETRIES=3\n\n# Rate Limiting\nFMP_DAILY_LIMIT=250\nFMP_REQUESTS_PER_SECOND=10\nFMP_REQUESTS_PER_MINUTE=300\n\n# Logging\nFMP_LOG_LEVEL=INFO\nFMP_LOG_PATH=/path/to/logs\nFMP_LOG_MAX_BYTES=10485760\nFMP_LOG_BACKUP_COUNT=5\n\n# MCP Server\nFMP_MCP_MANIFEST=/path/to/custom/manifest.py\n```\n\n### Custom Configuration\n```python\nfrom fmp_data import FMPDataClient, ClientConfig, LoggingConfig, RateLimitConfig, LogHandlerConfig\n\nconfig = ClientConfig(\n api_key=\"your_api_key_here\", # pragma: allowlist secret\n timeout=30,\n max_retries=3,\n base_url=\"https://financialmodelingprep.com\",\n rate_limit=RateLimitConfig(\n daily_limit=250,\n requests_per_second=10,\n requests_per_minute=300\n ),\n logging=LoggingConfig(\n level=\"DEBUG\",\n handlers={\n \"console\": LogHandlerConfig(\n class_name=\"StreamHandler\",\n level=\"INFO\",\n format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n ),\n \"file\": LogHandlerConfig(\n class_name=\"RotatingFileHandler\",\n level=\"DEBUG\",\n format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\",\n handler_kwargs={\n \"filename\": \"fmp.log\",\n \"maxBytes\": 10485760,\n \"backupCount\": 5\n }\n )\n }\n )\n)\n\nclient = FMPDataClient(config=config)\n```\n\n## Error Handling\n\n```python\nfrom fmp_data import FMPDataClient\nfrom fmp_data.exceptions import (\n FMPError,\n RateLimitError,\n AuthenticationError,\n ValidationError,\n ConfigError\n)\ntry:\n with FMPDataClient.from_env() as client:\n profile = client.company.get_profile(\"INVALID\")\n\nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Wait {e.retry_after} seconds\")\n print(f\"Status code: {e.status_code}\")\n print(f\"Response: {e.response}\")\n\nexcept AuthenticationError as e:\n print(\"Invalid API key or authentication failed\")\n print(f\"Status code: {e.status_code}\")\n\nexcept ValidationError as e:\n print(f\"Invalid parameters: {e.message}\")\n\nexcept ConfigError as e:\n print(f\"Configuration error: {e.message}\")\n\nexcept FMPError as e:\n print(f\"General API error: {e.message}\")\n```\n\n## Development Setup\n\n### Prerequisites\n- Python 3.10+\n- UV (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/MehdiZare/fmp-data.git\ncd fmp-data\n```\n\n2. Install dependencies with UV:\n```bash\n# Create virtual environment and install all dependencies\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install package in editable mode with all extras\nuv pip install -e \".[langchain,mcp]\" --all-extras\n\n# Install development dependencies\nuv pip install --group dev -e .\n```\n\n3. Set up pre-commit hooks:\n```bash\npre-commit install\n```\n\n5. Set up environment variables:\n```bash\n# Create .env file\necho \"FMP_API_KEY=your_api_key_here\" > .env\n```\n\n## Running Tests\n\n### Basic Test Commands\n\n```bash\n# Run all tests with coverage\npytest --cov=fmp_data\n\n# Run tests with coverage report\npytest --cov=fmp_data --cov-report=html\n\n# Run specific test file\npytest tests/unit/test_client.py\n\n# Run tests with verbose output\npytest -v\n\n# Run integration tests (requires API key)\nFMP_TEST_API_KEY=your_test_api_key pytest tests/integration/\n\n# Using make commands (if available)\nmake test # Run unit tests\nmake test-cov # Run tests with coverage\nmake test-all # Run all tests for all Python versions\n```\n\n### Development Commands\n\n```bash\n# Format code with ruff and black\nruff format fmp_data tests\nblack fmp_data tests\n\n# Lint with ruff\nruff check fmp_data tests --fix\n\n# Type checking with mypy\nmypy fmp_data\n\n# Run all quality checks\npre-commit run --all-files\n\n# Using make commands (recommended)\nmake fix # Auto-fix all issues\nmake lint # Run linting\nmake typecheck # Run type checking\nmake check # Run all checks\nmake test # Run tests\nmake test-cov # Run tests with coverage report\nmake ci # Run full CI checks locally\n```\n\n### Building and Publishing\n\n```bash\n# Build the package\nuv build\n\n# Or using Python build\npython -m build\n\n# Check package before publishing\ntwine check dist/*\n\n# Publish to PyPI (maintainers only)\ntwine upload dist/*\n\n# Using make commands\nmake build # Build package\nmake build-check # Build and verify\n```\n\n### UV Configuration\n\n```bash\n# Create virtual environment\nuv venv\n\n# Activate virtual environment\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install/upgrade packages\nuv pip install --upgrade package-name\n\n# Sync dependencies from pyproject.toml\nuv pip sync pyproject.toml\n\n# Export requirements.txt (if needed)\nuv pip freeze > requirements.txt\n\n# Compile requirements (fast dependency resolution)\nuv pip compile pyproject.toml -o requirements.txt\n```\n\nView the latest test coverage report [here](https://codecov.io/gh/MehdiZare/fmp-data).\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n### Getting Started\n\n1. Fork the repository\n2. Clone your fork:\n```bash\ngit clone https://github.com/yourusername/fmp-data.git\ncd fmp-data\n```\n\n3. Set up development environment:\n```bash\n# Create and activate virtual environment\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies with UV\nuv pip install -e \".[langchain,mcp]\" --all-extras\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Making Changes\n\n1. Create a feature branch:\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n2. Make your changes and ensure quality:\n```bash\n# Format code\nruff format fmp_data tests\nblack fmp_data tests\n\n# Fix linting issues\nruff check fmp_data tests --fix\n\n# Run type checking\nmypy fmp_data\n\n# Run tests\npytest --cov=fmp_data\n\n# Or use make commands\nmake fix # Fix all auto-fixable issues\nmake check # Run all checks\n```\n\n3. Commit your changes:\n```bash\ngit add .\ngit commit -m \"feat: add your feature description\"\n```\n\n4. Push and create a pull request\n\n### Requirements\n\nPlease ensure your contributions meet these requirements:\n- Tests pass: `pytest` or `make test`\n- Code is formatted: `ruff format` and `black` or `make fix`\n- Code passes linting: `ruff check` or `make lint`\n- Type hints are included for all functions\n- Documentation is updated for new features\n- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)\n- Test coverage remains above 80%\n\n### Running Quality Checks\n\n```bash\n# Run all quality checks at once\npre-commit run --all-files\n\n# Or use make commands (recommended)\nmake check # Run all checks\nmake fix # Fix all auto-fixable issues\nmake test # Run tests\nmake test-cov # Run tests with coverage\n\n# Or run individual checks\nruff check fmp_data tests\nblack --check fmp_data tests\nmypy fmp_data\npytest --cov=fmp_data\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n## Acknowledgments\n\n- Financial Modeling Prep for providing the API\n- Contributors to the project\n- Open source packages used in this project\n\n## Support\n\n- GitHub Issues: [Create an issue](https://github.com/MehdiZare/fmp-data/issues)\n- Documentation: [Read the docs](./docs)\n\n## Examples\n\n### Interactive Notebooks\n- [Financial Agent Tutorial](https://colab.research.google.com/drive/1cSyLX-j9XhyrXyVJ2HwMZJvPy1Lf2CuA?usp=sharing): Build an intelligent financial agent with LangChain integration\n- [Basic Usage Examples](./examples): Simple code examples demonstrating key features\n\n### Code Examples\n\n```python\n# Basic usage example\nfrom fmp_data import FMPDataClient\n\nwith FMPDataClient.from_env() as client:\n # Get company profile\n profile = client.company.get_profile(\"AAPL\")\n print(f\"Company: {profile.company_name}\")\n```\n\n## Release Notes\n\nSee [CHANGELOG.md](./CHANGELOG.md) for a list of changes in each release.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for the Financial Modeling Prep API",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://mehdizare.github.io/fmp-data/",
"Homepage": "https://github.com/MehdiZare/fmp-data",
"Repository": "https://github.com/MehdiZare/fmp-data"
},
"split_keywords": [
"api",
" financial",
" financial data",
" fmp",
" market-data",
" stock market",
" stocks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "134c3d9c749717ebae33411d381128366632f2e380de8446271946c13816837b",
"md5": "0f5a53c6c78edf815d9d9d72790850be",
"sha256": "ed346ae15fb288f0072fc624f3e81346bd6731fac32f56b6a96e78131f7f8724"
},
"downloads": -1,
"filename": "fmp_data-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f5a53c6c78edf815d9d9d72790850be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 210085,
"upload_time": "2025-08-18T03:00:24",
"upload_time_iso_8601": "2025-08-18T03:00:24.041888Z",
"url": "https://files.pythonhosted.org/packages/13/4c/3d9c749717ebae33411d381128366632f2e380de8446271946c13816837b/fmp_data-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "69a8f1d86e71fb39cd47473059c8d59929020fe3a702d28f067863ce2a1067db",
"md5": "84a69b5bed632d8e2ca004a983cc1ac8",
"sha256": "93360d1b752482d237d3950ee378306d030ad0f45f1fae53a6c3778c64255a70"
},
"downloads": -1,
"filename": "fmp_data-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "84a69b5bed632d8e2ca004a983cc1ac8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 254457,
"upload_time": "2025-08-18T03:00:25",
"upload_time_iso_8601": "2025-08-18T03:00:25.565797Z",
"url": "https://files.pythonhosted.org/packages/69/a8/f1d86e71fb39cd47473059c8d59929020fe3a702d28f067863ce2a1067db/fmp_data-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 03:00:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MehdiZare",
"github_project": "fmp-data",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fmp-data"
}
JSON
