> ## 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.
# Upcoming Dividends
> Browse NGX-listed companies with upcoming ex-dividend dates.
This endpoint returns a paginated list of NGX-listed companies whose ex-dividend date falls on or after today, ordered chronologically by ex-dividend date. Use it to build a dividend calendar, screen for near-term income opportunities, or alert users before key dates.
Use `page` and `limit` for pagination (up to 100 records per page).
For example, to fetch the first page of upcoming dividends:
```bash curl theme={null}
curl "https://api.ngnmarket.com/v1/dividends/upcoming?limit=20&page=1" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```javascript JavaScript theme={null}
const url = new URL('https://api.ngnmarket.com/v1/dividends/upcoming');
url.searchParams.set('limit', '20');
url.searchParams.set('page', '1');
const res = await fetch(url, {
headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' },
});
const { data } = await res.json();
// data.dividends — array of upcoming dividend records
// data.total — total matching records
```
```python Python theme={null}
import requests
res = requests.get(
'https://api.ngnmarket.com/v1/dividends/upcoming',
params={'limit': 20, 'page': 1},
headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
)
data = res.json()['data']
```
If no upcoming dividends are scheduled, `dividends` will be an empty array and `total` will be `0`. This endpoint requires a Starter plan or higher.
## OpenAPI
````yaml GET /dividends/upcoming
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:
/dividends/upcoming:
get:
tags:
- Dividends
summary: Upcoming dividends
description: >
Returns a paginated list of NGX-listed companies with upcoming
ex-dividend dates (on or after today), ordered chronologically. Use this
to build a dividend calendar or screen for near-term income
opportunities.
**Plan required:** Starter
operationId: getDividendsUpcoming
parameters:
- name: page
in: query
description: Page number (1-based).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Records per page (1–100).
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: Upcoming dividends retrieved successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
type: object
properties:
dividends:
type: array
items:
$ref: '#/components/schemas/DividendCalendarEntry'
page:
type: integer
example: 1
total:
type: integer
description: Total number of matching records.
example: 38
total_pages:
type: integer
example: 2
examples:
upcoming:
summary: Upcoming dividend calendar
value:
success: true
data:
dividends:
- symbol: DANGCEM
company_name: Dangote Cement Plc
sector: Industrial Goods
ex_dividend_date: '2026-06-17'
dividend: 45
type: Cash
payment_date: '2026-07-01'
yield: 4.14
- symbol: GTCO
company_name: Guaranty Trust Holding Company Plc
sector: Financial Services
ex_dividend_date: '2026-06-24'
dividend: 3
type: Cash
payment_date: '2026-07-08'
yield: 5.3
page: 1
total: 38
total_pages: 2
meta:
plan: starter
calls_used: 15
calls_remaining: 99985
reset_at: '2026-06-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'
DividendCalendarEntry:
type: object
properties:
symbol:
type: string
description: NGX ticker symbol.
example: DANGCEM
company_name:
type: string
nullable: true
description: Full company name.
example: Dangote Cement Plc
sector:
type: string
nullable: true
description: NGX sector classification.
example: Industrial Goods
ex_dividend_date:
type: string
format: date
description: The cutoff date to qualify for the dividend.
example: '2026-06-17'
dividend:
type: number
nullable: true
description: Dividend amount in NGN per share.
example: 45
type:
type: string
nullable: true
description: Dividend type (e.g. Cash, Stock, Special, Mixed).
example: Cash
payment_date:
type: string
format: date
nullable: true
description: Date the dividend is credited to shareholders.
example: '2026-07-01'
yield:
type: number
nullable: true
description: Trailing dividend yield (%) at time of declaration.
example: 4.14
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).
````