fmp-py-client 0.1.0
Async Python client for Financial Modeling Prep API
License: MIT
Requires Python: >=3.12
Keywords: finance, api, stocks, financial-data, async, httpx

# fmp-py-client

[![PyPI version](https://img.shields.io/pypi/v/fmp-py-client.svg)](https://pypi.org/project/fmp-py-client/)
[![Python versions](https://img.shields.io/pypi/pyversions/fmp-py-client.svg)](https://pypi.org/project/fmp-py-client/)
[![License](https://img.shields.io/pypi/l/fmp-py-client.svg)](https://github.com/cbian/fmp-py-client/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://cbian.github.io/fmp-py-client/)

A fully asynchronous Python client for the [Financial Modeling Prep API](https://financialmodelingprep.com/). Access 180+ financial data endpoints with a modern, type-safe interface.

## Features

- **Async/await support** - Built on `httpx` for high-performance concurrent requests
- **Fully typed** - Complete type hints for IDE autocomplete and static analysis
- **180+ endpoints** - Stocks, financials, ETFs, crypto, forex, economics, and more
- **Clean API** - Intuitive method names that mirror the FMP API structure
- **Robust error handling** - Custom exceptions with detailed error information

## Installation

```bash
pip install fmp-py-client
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add fmp-py-client
```

## Quick Start

```python
import asyncio
from fmp_py_client import AsyncFMPClient

async def main():
    async with AsyncFMPClient("your-api-key") as client:
        # Get a stock quote
        quote = await client.quote("AAPL")
        print(f"Apple: ${quote[0]['price']}")

        # Get company profile
        profile = await client.profile("AAPL")
        print(f"Market Cap: ${profile[0]['mktCap']:,}")

        # Search for companies
        results = await client.search_name("Tesla", limit=5)
        for company in results:
            print(f"{company['symbol']}: {company['name']}")

asyncio.run(main())
```

## API Coverage

| Category | Examples |
|----------|----------|
| **Quotes** | Real-time quotes, aftermarket, batch quotes |
| **Company** | Profiles, executives, peers, screener |
| **Financials** | Income statements, balance sheets, cash flow |
| **Metrics** | Key metrics, ratios, financial scores |
| **Historical** | EOD prices, intraday charts (1min to 4hr) |
| **Calendar** | Dividends, splits, earnings, IPOs |
| **Market** | Stock lists, ETFs, mutual funds, indices |
| **News** | Company news, sentiment analysis |
| **Technical** | SMA, EMA, RSI, MACD, Bollinger Bands |
| **Valuation** | DCF, enterprise values |
| **SEC** | Filings, insider trading |
| **Economics** | Treasury rates, economic calendar |

## Error Handling

```python
from fmp_py_client import (
    AsyncFMPClient,
    FMPAuthenticationError,
    FMPRateLimitError,
    FMPNotFoundError,
)

async with AsyncFMPClient("your-api-key") as client:
    try:
        quote = await client.quote("AAPL")
    except FMPAuthenticationError:
        print("Invalid API key")
    except FMPRateLimitError as e:
        print(f"Rate limited. Retry after {e.retry_after}s")
    except FMPNotFoundError:
        print("Symbol not found")
```

## Documentation

Full documentation is available at [cbian.github.io/fmp-py-client](https://cbian.github.io/fmp-py-client/).

- [Getting Started](https://cbian.github.io/fmp-py-client/getting-started/installation/)
- [API Reference](https://cbian.github.io/fmp-py-client/api/overview/)
- [Examples](https://cbian.github.io/fmp-py-client/examples/basic-usage/)

## Requirements

- Python 3.12+
- An API key from [Financial Modeling Prep](https://financialmodelingprep.com/) (free tier available)

## License

MIT