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

# Year-to-Date Best and Worst Performers

> Find the NGX stocks that have gained or lost the most since the start of the year.

The YTD performers endpoint ranks every NGX stock by its return from the first trading day of the year to today. This example fetches the top 10 gainers and top 10 losers for the current year.

**Endpoint:** `GET /market/ytd-performers` (Growth plan)

## Fetch the top 10 YTD gainers

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.ngnmarket.com/v1/market/ytd-performers?type=best&limit=10" \
    -H "Authorization: Bearer ngm_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    'https://api.ngnmarket.com/v1/market/ytd-performers?type=best&limit=10',
    { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } }
  );
  const { data } = await res.json();
  // data.data → ranked list of top gainers
  // data.year, data.year_start_date
  ```

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

  res = requests.get(
      'https://api.ngnmarket.com/v1/market/ytd-performers',
      params={'type': 'best', 'limit': 10},
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

### Sample response (trimmed)

```json theme={null}
{
  "success": true,
  "data": {
    "type": "best",
    "year": 2026,
    "is_past_year": false,
    "year_start_date": "2026-01-02",
    "total": 10,
    "data": [
      {
        "symbol": "OKOMUOIL",
        "company_name": "Okomu Oil Palm",
        "sector": "Agriculture",
        "year_start_price": 290.00,
        "year_start_date": "2026-01-02",
        "current_price": 400.70,
        "end_date": "2026-04-17",
        "ytd_pct": 38.17
      },
      {
        "symbol": "GTCO",
        "company_name": "Guaranty Trust Holding Co.",
        "sector": "Banking",
        "year_start_price": 41.20,
        "year_start_date": "2026-01-02",
        "current_price": 53.05,
        "end_date": "2026-04-17",
        "ytd_pct": 28.76
      }
    ]
  }
}
```

## Fetch the top 10 YTD losers

Change `type` to `worst`:

```bash curl theme={null}
curl "https://api.ngnmarket.com/v1/market/ytd-performers?type=worst&limit=10" \
  -H "Authorization: Bearer ngm_live_YOUR_KEY"
```

## Look up a historical year

Pass `year` to get YTD performance for a past year. The `end_date` in the response will reflect the last available trading day of that year:

```bash curl theme={null}
curl "https://api.ngnmarket.com/v1/market/ytd-performers?type=best&year=2025&limit=10" \
  -H "Authorization: Bearer ngm_live_YOUR_KEY"
```

<Card title="YTD performers reference" icon="book" href="/api-reference/market/ytd-performers">
  Full parameter list for `GET /market/ytd-performers`
</Card>