> ## 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.
# Top Trades
> Retrieve the most actively traded NGX stocks.
This endpoint returns a ranked list of the most actively traded NGX securities for a trading session, ordered by naira value traded. Pass a `date` (`YYYY-MM-DD`) to retrieve data for a specific session; omit it to get the most recent available day.
Each entry includes the stock symbol, company name, [`logo_url`](/guides/company-logos), sector, `market_cap`, share volume, naira value, closing price, price change percentage, and trade count. Use this endpoint to surface the day's most liquid names or to power a market-activity widget.
For a specific session, pass `date` as `YYYY-MM-DD`:
```bash curl theme={null}
curl "https://api.ngnmarket.com/v1/market/top-trades?date=2026-04-17" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```javascript JavaScript theme={null}
const url = new URL('https://api.ngnmarket.com/v1/market/top-trades');
url.searchParams.set('date', '2026-04-17');
const res = await fetch(url, {
headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' },
});
const { data } = await res.json();
```
```python Python theme={null}
import requests
res = requests.get(
'https://api.ngnmarket.com/v1/market/top-trades',
params={'date': '2026-04-17'},
headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
)
data = res.json()['data']
```
## OpenAPI
````yaml GET /market/top-trades
openapi: 3.1.0
info:
title: NGN Market API
version: '1.0'
description: >
The NGN Market API provides programmatic access to Nigerian Exchange Group
(NGX) market data, including equities, forex rates, company profiles,
indices, bonds, and financial news.
## Base URL
All endpoints are served from:
```
https://api.ngnmarket.com/v1
```
## Authentication
Every request requires a Bearer token in the `Authorization` header:
```
Authorization: Bearer ngm_live_YOUR_KEY
```
Generate and manage your API keys from the [developer
dashboard](https://ngnmarket.com/developer).
## Plans & Quotas
| Plan | Monthly Calls | Requests/min | Price |
| :--- | ---: | ---: | :--- |
| Free | 3,000 | 30 | Free |
| Hobby | 10,000 | 60 | ₦15,000/mo |
| Starter | 100,000 | 120 | ₦50,000/mo |
| Growth | 500,000 | 200 | ₦200,000/mo |
| Business | 2,000,000 | 300 | ₦700,000/mo |
| Enterprise | Unlimited | Unlimited | Custom |
Every response includes a `meta` object showing your current usage and
remaining quota. Exceeding the per-minute rate limit returns `429
RATE_LIMITED`. Exceeding the monthly quota returns `429 QUOTA_EXCEEDED`.
## Response Envelope
All responses use a consistent JSON envelope:
```json
{
"success": true,
"data": { ... },
"meta": {
"plan": "starter",
"calls_used": 4821,
"calls_remaining": 95179,
"reset_at": "2026-05-01T00:00:00.000Z"
}
}
```
contact:
name: NGN Market Support
email: support@ngnmarket.com
url: https://ngnmarket.com
license:
name: Proprietary
servers:
- url: https://api.ngnmarket.com/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Market
description: >-
Daily market snapshots, top trades, movers, market breadth, sectors, and
YTD performers.
- name: Companies
description: >-
Browse, search, and retrieve profiles, price charts, and financial
statements for NGX-listed companies.
- name: Forex
description: Current and historical NGN exchange rates against major currencies.
- name: Indices
description: >-
All NGX market indices, including list, detail with constituents, and
historical chart data.
- name: ETFs
description: >-
NGX-listed Exchange Traded Funds and ETPs — list, full fund detail, and
historical daily price data.
- name: Bonds
description: >-
NGX-listed bond instruments with issuer details, coupon rates, and
maturity dates.
- name: Disclosures
description: >-
Official corporate filings from NGX-listed companies (financial
statements, AGM notices, board meetings, director dealings, earnings
forecasts). Sourced from NGX Group and updated twice daily.
- name: Blog
description: >-
Published NGN Market blog posts. List, search, and filter by category or
company.
- name: Dividends
description: >-
Market-wide NGX dividend calendar. Browse upcoming and recently paid
dividends across all listed companies with optional search and pagination.
- name: Account
description: >-
Quota status, 30-day request analytics, and paginated request logs for the
authenticated user.
paths:
/market/top-trades:
get:
tags:
- Market
summary: Most traded NGX stocks
description: >
Returns a ranked list of the most actively traded NGX securities by
naira value for a given session. Each entry includes the stock symbol,
company name, sector, share volume, naira value, current price, and
price change percentage. Omit `date` to get the current or most recent
session.
During trading hours (Monday–Friday, 09:00–16:00 WAT) this reflects live
intraday activity, refreshed every 20 minutes.
**Plan required:** Starter
operationId: getTopTrades
parameters:
- name: date
in: query
description: >-
Trading date in `YYYY-MM-DD` format. Omit for the most recent
available session.
required: false
schema:
type: string
format: date
example: '2026-04-17'
- name: limit
in: query
description: Number of stocks to return. Maximum is `50`.
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Top trades retrieved successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/TopTrades'
examples:
top2Trades:
summary: Top 2 most traded stocks
value:
success: true
data:
date: '2026-04-17'
data:
- rank: 1
symbol: DANGCEM
company_name: Dangote Cement
logo_url: >-
https://cdn.jsdelivr.net/gh/ngnmarket/ngx-logos/dist/png/DANGCEM.png
sector: Industrial Goods
market_cap: 4872900000000
volume: 12847291
value_traded: 1821093847
price: 302.5
price_change_percent: 1.34
trades: 2041
- rank: 2
symbol: GTCO
company_name: Guaranty Trust Holding Co.
logo_url: >-
https://cdn.jsdelivr.net/gh/ngnmarket/ngx-logos/dist/png/GTCO.png
sector: Banking
market_cap: 1562000000000
volume: 9183047
value_traded: 487291034
price: 53.05
price_change_percent: -0.47
trades: 1802
meta:
plan: starter
calls_used: 102
calls_remaining: 99898
reset_at: '2026-05-01T00:00:00.000Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/PlanRequired'
'429':
$ref: '#/components/responses/QuotaExceeded'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
SuccessEnvelope:
type: object
required:
- success
properties:
success:
type: boolean
const: true
meta:
$ref: '#/components/schemas/Meta'
TopTrades:
type: object
properties:
date:
type: string
format: date
data:
type: array
items:
type: object
properties:
rank:
type: integer
symbol:
type: string
company_name:
type: string
logo_url:
type: string
description: URL of the company logo image.
sector:
type: string
nullable: true
market_cap:
type: number
nullable: true
description: Current market capitalisation (NGN).
volume:
type: integer
value_traded:
type: number
price:
type: number
price_change_percent:
type: number
trades:
type: integer
Meta:
type: object
description: Quota and plan metadata included on every authenticated response.
properties:
plan:
type: string
description: Current plan name.
enum:
- free
- starter
- growth
- business
- enterprise
example: starter
calls_used:
type: integer
description: Total calls made this calendar month across all your keys.
example: 4821
calls_remaining:
type: integer
description: Calls remaining before your quota is exhausted.
example: 95179
reset_at:
type: string
format: date-time
description: ISO 8601 UTC timestamp of your next quota reset (1st of next month).
example: '2026-05-01T00:00:00.000Z'
ErrorEnvelope:
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error identifier.
example: NOT_FOUND
message:
type: string
description: Human-readable error description.
example: Resource not found.
required_plan:
type: string
description: _(PLAN_REQUIRED only)_ Minimum plan needed.
current_plan:
type: string
description: _(PLAN_REQUIRED only)_ Your current plan.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
missingKey:
summary: Missing Authorization header
value:
success: false
error:
code: MISSING_API_KEY
message: 'Provide your API key via: Authorization: Bearer '
invalidKey:
summary: Invalid or revoked key
value:
success: false
error:
code: INVALID_API_KEY
message: API key not found or revoked.
PlanRequired:
description: Endpoint requires a higher plan.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PLAN_REQUIRED
message: This endpoint requires a starter plan or higher.
required_plan: starter
current_plan: free
QuotaExceeded:
description: Monthly call limit reached.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorEnvelope'
- type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
example:
success: false
error:
code: QUOTA_EXCEEDED
message: >-
Monthly call limit of 100,000 reached. Resets on
2026-05-01T00:00:00.000Z.
meta:
plan: starter
calls_used: 100000
calls_remaining: 0
reset_at: '2026-05-01T00:00:00.000Z'
ServerError:
description: Unexpected server-side failure. Safe to retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: SERVER_ERROR
message: Something went wrong on our end. Please try again.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: ngm_live_*
description: >
Pass your API key as a Bearer token: `Authorization: Bearer
ngm_live_YOUR_KEY`.
Generate keys at
[ngnmarket.com/dashboard/developer](https://ngnmarket.com/developer).
````