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

# Market Gainers

> Get the biggest stock market gainers of the day

## Overview

Retrieve the top performing stocks with the highest percentage gains for the current trading day. This endpoint provides real-time market data to identify trending and high-momentum stocks.

<Info>
  Data is updated in real-time during market hours and shows after-hours performance when markets are closed.
</Info>

## Parameters

This endpoint requires no parameters and returns the top market gainers.

## Response

<ResponseField name="gainers" type="array">
  Array of top gaining stocks

  <Expandable title="Gainer Object">
    <ResponseField name="ticker" type="string">
      Stock ticker symbol
    </ResponseField>

    <ResponseField name="changes" type="number">
      Absolute price change in USD
    </ResponseField>

    <ResponseField name="price" type="string">
      Current stock price
    </ResponseField>

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

    <ResponseField name="companyName" type="string">
      Full company name
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

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

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

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

  print("📈 Top Market Gainers:")
  for gainer in data['gainers'][:5]:
      print(f"{gainer['ticker']}: +{gainer['changesPercentage']}% (${gainer['price']})")
  ```

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

  console.log("📈 Top Market Gainers:");
  data.gainers.slice(0, 5).forEach(gainer => {
      console.log(`${gainer.ticker}: +${gainer.changesPercentage}% ($${gainer.price})`);
  });
  ```

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

  echo "📈 Top Market Gainers:\n";
  foreach (array_slice($data['gainers'], 0, 5) as $gainer) {
      echo $gainer['ticker'] . ": +" . $gainer['changesPercentage'] . "% ($" . $gainer['price'] . ")\n";
  }
  ?>
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "gainers": [
    {
      "ticker": "JEM",
      "changes": 0.57,
      "price": "6.3",
      "changesPercentage": "9.94764",
      "companyName": "707 Cayman Holdings Limited Ordinary Shares"
    },
    {
      "ticker": "TIPT",
      "changes": 2.23,
      "price": "24.72",
      "changesPercentage": "9.91552",
      "companyName": "Tiptree Inc."
    },
    {
      "ticker": "GDXD",
      "changes": 1.89,
      "price": "21.05",
      "changesPercentage": "9.86849",
      "companyName": "MicroSectors Gold Miners -3X Inverse Leveraged ETN"
    }
  ]
}
```

## MCP Protocol Usage

For AI agents using the Model Context Protocol:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "fmp_get_market_gainers",
    "arguments": {
      "random_string": "dummy"
    }
  }
}
```

<Info>
  The `random_string` parameter is required due to MCP protocol requirements but can be any value.
</Info>

## Use Cases

<AccordionGroup>
  <Accordion title="Day Trading">
    Identify high-momentum stocks for potential day trading opportunities.
  </Accordion>

  <Accordion title="Market Analysis">
    Analyze market trends and sector rotation by examining top gainers.
  </Accordion>

  <Accordion title="News Correlation">
    Cross-reference gainers with news events to understand market drivers.
  </Accordion>

  <Accordion title="Screening">
    Use as a starting point for further fundamental or technical analysis.
  </Accordion>
</AccordionGroup>

## Rate Limits

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

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Market Losers" icon="trending-down" href="/api-reference/market/losers">
    Get the biggest market losers of the day
  </Card>

  <Card title="Most Active" icon="activity" href="/api-reference/market/active">
    Stocks with highest trading volume
  </Card>

  <Card title="Sector Performance" icon="chart-pie" href="/api-reference/market/sectors">
    Performance by market sector
  </Card>

  <Card title="Stock Screener" icon="filter" href="/api-reference/fmp/screening">
    Custom stock screening with filters
  </Card>
</CardGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="Service Unavailable (503)">
    ```json theme={null}
    {
      "error": "Market data temporarily unavailable",
      "detail": "Please try again in a few moments"
    }
    ```
  </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>
</AccordionGroup>

## Market Hours

<Info>
  **Market Hours**: 9:30 AM - 4:00 PM ET (Monday-Friday)\
  **Pre-Market**: 4:00 AM - 9:30 AM ET\
  **After-Hours**: 4:00 PM - 8:00 PM ET
</Info>

Data reflects the most recent trading session and includes after-hours movements when markets are closed.