> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for all Financial MCP Server endpoints and tools

## Overview

The Financial MCP Server provides 32 comprehensive financial tools through both MCP protocol and REST API endpoints. This reference covers all available functionality.

<CardGroup cols={2}>
  <Card title="REST API" icon="code">
    Traditional HTTP endpoints for web applications
  </Card>

  <Card title="MCP Protocol" icon="robot">
    Native integration for AI agents and tools
  </Card>
</CardGroup>

## Base URLs

<CodeGroup>
  ```bash Local Development theme={null}
  http://localhost:8001
  ```

  ```bash Production (Railway) theme={null}
  https://stocks-dev.up.railway.app
  ```

  ```bash Custom Domain theme={null}
  https://api.yourcompany.com
  ```
</CodeGroup>

## API Architecture

### REST API Structure

All REST endpoints follow this pattern:

```
https://stocks-dev.up.railway.app/api/v1/{category}/{action}
```

**Categories:**

* `stock` - Individual stock data and analysis
* `market` - Market-wide data and trends
* `fmp` - Financial Modeling Prep professional tools
* `crypto` - Cryptocurrency data
* `screener` - Stock screening and filtering

### MCP Protocol Structure

MCP tools are called using the standard MCP format:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "parameter": "value"
    }
  }
}
```

## Data Sources

<AccordionGroup>
  <Accordion title="YFinance Tools (6 tools)">
    **Source**: Yahoo Finance via Python library\
    **Cost**: Free\
    **Rate Limits**: Subject to Yahoo Finance limits\
    **Reliability**: Good for basic data, may get rate limited

    **Available Tools:**

    * `get_stock_quote` - Real-time stock quotes
    * `get_company_overview` - Company information and metrics
    * `get_time_series_daily` - Historical price data
    * `search_symbol` - Symbol search and lookup
    * `get_recommendations` - Analyst recommendations
    * `get_insider_transactions` - Insider trading data
  </Accordion>

  <Accordion title="FMP Tools (26 tools)">
    **Source**: Financial Modeling Prep API\
    **Cost**: Free tier (250 requests/day), paid plans available\
    **Rate Limits**: Based on subscription tier\
    **Reliability**: Professional-grade, highly reliable

    **Categories:**

    * **Core Financial Data** (4 tools): Statements, metrics, DCF, quotes
    * **Market Data** (4 tools): Gainers, losers, active stocks, sectors
    * **Advanced Screening** (6 tools): Stock screener, search, news, etc.
    * **Options & Technical** (4 tools): Options chains, technical indicators
    * **International & Alternative** (4 tools): Global markets, crypto, commodities
    * **Professional Analytics** (4 tools): Analyst data, government trades
  </Accordion>
</AccordionGroup>

## Response Format

All endpoints return JSON responses with consistent structure:

### Success Response

```json theme={null}
{
  "symbol": "AAPL",
  "price": 201.08,
  "change": 0.08,
  "timestamp": "2025-06-28T18:42:12.471731",
  "source": "FMP"
}
```

### Error Response

```json theme={null}
{
  "error": "Stock symbol not found",
  "detail": "The symbol 'INVALID' was not found in our database",
  "timestamp": "2025-06-28T18:42:12.471731"
}
```

### Paginated Response

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "has_next": true
  }
}
```

## Rate Limiting

<Info>
  Rate limits vary by data source and subscription tier.
</Info>

| Source   | Free Tier            | Paid Tier            |
| -------- | -------------------- | -------------------- |
| YFinance | Yahoo Finance limits | Yahoo Finance limits |
| FMP      | 250 requests/day     | Up to 10,000+/day    |

### Rate Limit Headers

```http theme={null}
X-RateLimit-Limit: 250
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1640995200
```

## Error Codes

| Code | Description  | Solution                     |
| ---- | ------------ | ---------------------------- |
| 400  | Bad Request  | Check request parameters     |
| 401  | Unauthorized | Verify API key               |
| 404  | Not Found    | Check symbol/endpoint exists |
| 429  | Rate Limited | Wait and retry, upgrade plan |
| 500  | Server Error | Contact support              |

## Interactive Documentation

Visit your server's `/docs` endpoint for interactive Swagger UI documentation:

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/ntg-c0edb0d4/images/swagger-ui.png" alt="Interactive API Documentation" />
</Frame>

**Features:**

* Try endpoints directly in browser
* View request/response schemas
* Copy cURL commands
* Test with your API key

## Quick Start Examples

<CodeGroup>
  ```bash Get Stock Quote theme={null}
  curl "https://stocks-dev.up.railway.app/api/v1/stock/AAPL"
  ```

  ```bash Market Gainers theme={null}
  curl "https://stocks-dev.up.railway.app/api/v1/market/gainers"
  ```

  ```bash Screen Stocks theme={null}
  curl "https://stocks-dev.up.railway.app/api/v1/screener?sector=Technology&min_market_cap=1000000000"
  ```

  ```python Python SDK theme={null}
  import requests

  # Get stock quote
  response = requests.get("https://stocks-dev.up.railway.app/api/v1/stock/AAPL")
  data = response.json()
  print(f"AAPL: ${data['price']}")
  ```

  ```javascript JavaScript/Node.js theme={null}
  const response = await fetch('https://stocks-dev.up.railway.app/api/v1/stock/AAPL');
  const data = await response.json();
  console.log(`AAPL: $${data.price}`);
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Stock Data APIs" icon="chart-line" href="/api-reference/stock/quote">
    Real-time quotes, company data, and historical information
  </Card>

  <Card title="Market Data APIs" icon="trending-up" href="/api-reference/market/gainers">
    Market-wide trends, gainers, losers, and sector performance
  </Card>

  <Card title="FMP Professional Tools" icon="building" href="/api-reference/fmp/financials">
    Advanced financial statements, metrics, and analysis
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key setup and authentication methods
  </Card>
</CardGroup>