> ## 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.

# Stock Quote

> Get real-time stock price and basic information

## Overview

Retrieve current stock price, market data, and key metrics for any publicly traded stock. This endpoint provides comprehensive real-time information powered by Financial Modeling Prep.

<Info>
  This endpoint uses FMP as the primary data source for reliability. A YFinance alternative is available at `/api/v1/stock/{symbol}/yfinance`.
</Info>

## Parameters

<ParamField path="symbol" type="string" required>
  Stock ticker symbol (e.g., AAPL, MSFT, GOOGL, TSLA)
</ParamField>

## Response

<ResponseField name="symbol" type="string">
  The stock ticker symbol
</ResponseField>

<ResponseField name="price" type="number">
  Current stock price in USD
</ResponseField>

<ResponseField name="change" type="number">
  Price change from previous close
</ResponseField>

<ResponseField name="changesPercentage" type="number">
  Percentage change from previous close
</ResponseField>

<ResponseField name="dayLow" type="number">
  Lowest price during current trading day
</ResponseField>

<ResponseField name="dayHigh" type="number">
  Highest price during current trading day
</ResponseField>

<ResponseField name="yearHigh" type="number">
  52-week high price
</ResponseField>

<ResponseField name="yearLow" type="number">
  52-week low price
</ResponseField>

<ResponseField name="marketCap" type="number">
  Market capitalization in USD
</ResponseField>

<ResponseField name="volume" type="number">
  Current day trading volume
</ResponseField>

<ResponseField name="avgVolume" type="number">
  Average trading volume
</ResponseField>

<ResponseField name="exchange" type="string">
  Stock exchange (e.g., NASDAQ, NYSE)
</ResponseField>

<ResponseField name="source" type="string">
  Data source identifier ("FMP")
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO timestamp of the response
</ResponseField>

## Examples

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

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

  response = requests.get("https://stocks-dev.up.railway.app/api/v1/stock/AAPL")
  data = response.json()

  print(f"Apple Stock: ${data['price']}")
  print(f"Change: {data['change']} ({data['changesPercentage']:.2f}%)")
  print(f"Market Cap: ${data['marketCap']:,}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://stocks-dev.up.railway.app/api/v1/stock/AAPL');
  const data = await response.json();

  console.log(`Apple Stock: $${data.price}`);
  console.log(`Change: ${data.change} (${data.changesPercentage.toFixed(2)}%)`);
  console.log(`Market Cap: $${data.marketCap.toLocaleString()}`);
  ```

  ```php PHP theme={null}
  <?php
  $response = file_get_contents('https://stocks-dev.up.railway.app/api/v1/stock/AAPL');
  $data = json_decode($response, true);

  echo "Apple Stock: $" . $data['price'] . "\n";
  echo "Change: " . $data['change'] . " (" . $data['changesPercentage'] . "%)\n";
  echo "Market Cap: $" . number_format($data['marketCap']) . "\n";
  ?>
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "symbol": "AAPL",
  "price": 201.08,
  "change": 0.08,
  "changesPercentage": 0.039801,
  "dayLow": 200.62,
  "dayHigh": 203.22,
  "yearHigh": 260.1,
  "yearLow": 169.21,
  "marketCap": 3003290664000,
  "priceAvg50": 202.6222,
  "priceAvg200": 223.33345,
  "volume": 70534466,
  "avgVolume": 62515124,
  "exchange": "NASDAQ",
  "open": 201.895,
  "previousClose": 201,
  "eps": 7.09,
  "pe": 28.36,
  "sharesOutstanding": 14935800000,
  "timestamp": "2025-06-28T18:42:12.471731",
  "source": "FMP"
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Symbol (404)">
    ```json theme={null}
    {
      "detail": "404: Failed to fetch quote for INVALID"
    }
    ```
  </Accordion>

  <Accordion title="Rate Limited (429)">
    ```json theme={null}
    {
      "error": "Rate limit exceeded",
      "detail": "Too many requests. Please try again later.",
      "retry_after": 60
    }
    ```
  </Accordion>

  <Accordion title="Server Error (500)">
    ```json theme={null}
    {
      "error": "Internal server error",
      "detail": "Unable to fetch stock data at this time"
    }
    ```
  </Accordion>
</AccordionGroup>

## MCP Protocol Usage

For AI agents using the Model Context Protocol:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "fmp_get_stock_quote",
    "arguments": {
      "symbol": "AAPL"
    }
  }
}
```

## Alternative Endpoints

<CardGroup cols={2}>
  <Card title="YFinance Quote" icon="python">
    `/api/v1/stock/{symbol}/yfinance`

    Uses YFinance library (may be rate limited)
  </Card>

  <Card title="Company Overview" icon="building">
    `/api/v1/stock/{symbol}/overview`

    Detailed company information and metrics
  </Card>
</CardGroup>

## Rate Limits

| Plan         | Requests/Day | Requests/Minute |
| ------------ | ------------ | --------------- |
| Free         | 250          | 5               |
| Starter      | 1,000        | 20              |
| Professional | 10,000       | 100             |

## Use Cases

<AccordionGroup>
  <Accordion title="Portfolio Tracking">
    Monitor real-time prices for portfolio holdings and calculate current values.
  </Accordion>

  <Accordion title="Trading Applications">
    Display current market data and price movements for trading decisions.
  </Accordion>

  <Accordion title="Financial Dashboards">
    Create live financial dashboards with current stock prices and market data.
  </Accordion>

  <Accordion title="AI Financial Analysis">
    Provide real-time market data to AI agents for financial analysis and recommendations.
  </Accordion>
</AccordionGroup>

## Related Endpoints

* [Company Overview](/api-reference/stock/overview) - Detailed company information
* [Historical Data](/api-reference/stock/historical) - Historical price data
* [Market Gainers](/api-reference/market/gainers) - Top performing stocks