> ## 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.
# Market-Wide Director Dealings
> Structured director-dealings feed across covered NGX-listed companies.
Returns structured director-dealings data across covered NGX-listed companies, sorted newest first. Use this endpoint when you want to scan activity across companies instead of requesting one company at a time.
This endpoint requires a Business plan.
You can filter by symbol, transaction direction, insider type, minimum value, or date range. Coverage is partial because not every listed company has director-dealings filings available in our dataset, and the response includes a `coverage_note` to make this clear.
```bash Market-wide, buys over ₦50m theme={null}
curl "https://api.ngnmarket.com/v1/insiders?side=buy&minValue=50000000" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```bash One company, via the market feed theme={null}
curl "https://api.ngnmarket.com/v1/insiders?symbol=GTCO" \
-H "Authorization: Bearer ngm_live_YOUR_KEY"
```
```javascript JavaScript theme={null}
const res = await fetch(
'https://api.ngnmarket.com/v1/insiders?side=buy&minValue=50000000',
{ 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/insiders',
params={'side': 'buy', 'minValue': 50000000},
headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
)
data = res.json()['data']
```
Combine `side`, `insider`, `minValue`, and `from`/`to` to build queries like "buys over ₦10m by directors or executives in the last 30 days" without iterating every company yourself.
To find groups of multiple insiders trading the same symbol in the same direction within a given period, use [`GET /insiders/clusters`](/api-reference/insiders/clusters).
## OpenAPI
````yaml GET /insiders
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 |
| Pro | 250,000 | 120 | ₦100,000/mo |
| Business | 2,000,000 | 300 | ₦300,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-15T23:57: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: Insiders
description: >-
Structured director-dealings data extracted from NGX PDMR filings.
Per-company and market-wide feeds, aggregated data, and cluster detection
for insiders trading the same symbol and direction within a window.
Distinct from the raw `/disclosures` feed, which only returns filing
metadata.
- 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:
/insiders:
get:
tags:
- Insiders
summary: Market-wide director dealings
description: >
Returns structured director-dealings data across covered NGX-listed
companies, sorted newest first. Use this endpoint when you want to scan
activity across companies instead of requesting one company at a time.
Coverage is partial because not every listed company has
director-dealings filings available in our dataset. The response
includes a `coverage_note` to make this clear.
**Plan required:** Business
operationId: listInsiders
parameters:
- name: symbol
in: query
description: Filter to one company.
schema:
type: string
example: GTCO
- name: search
in: query
description: Match insider name, company name, or ticker.
schema:
type: string
- name: side
in: query
description: Filter by transaction direction.
schema:
type: string
enum:
- buy
- sell
- name: insider
in: query
description: Filter by insider-type bucket.
schema:
type: string
enum:
- directors
- executives
- employees
- connected
- shareholders
- other
- name: from
in: query
schema:
type: string
format: date
example: '2026-01-01'
- name: to
in: query
schema:
type: string
format: date
example: '2026-12-31'
- name: minValue
in: query
description: Minimum transaction value in NGN.
schema:
type: number
example: 10000000
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
responses:
'200':
description: Market-wide director dealings retrieved successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DirectorDealing'
pagination:
$ref: '#/components/schemas/PaginationExtended'
coverage_note:
type: string
example: >-
Director-dealings coverage is partial: not every
listed company has filings on record. Use GET
/v1/companies to check a symbol's listing status.
examples:
marketFeed:
summary: Recent buys over ₦50m, market-wide
value:
success: true
data:
data:
- id: 280
disclosure_id: 2271
company_symbol: FIRSTHOLDCO
company_name: FIRST HOLDCO PLC
insider_name: Calvados Global Services Limited
insider_slug: calvados-global-services-limited
insider_position: >-
Company Related to a Significant Shareholder, Mr.
Olufemi Otedola, CON
insider_type: related_party
is_corporate_insider: true
notification_type: initial
transaction_type: purchase
side: buy
is_open_market: true
acquired_or_disposed: A
instrument_type: ordinary_shares
total_volume: 147737699
average_price: 140
total_value: 20683277860
total_value_reported: null
currency: NGN
shares_owned_after: null
shares_owned_after_source: null
letter_date: '2026-08-16'
transaction_date_from: '2026-08-13'
transaction_date_to: null
date_suspect: false
place_of_transaction: Lagos
days_to_file: 4
days_letter_to_disclosure: 1
tranche_count: 1
tranches:
- volume: 147737699
price: 140
price_low: null
price_high: null
date: '2026-08-14'
is_scanned: false
extraction_confidence: high
extraction_notes: >-
The insider 'Calvados Global Services Limited' is a
company related to Mr. Olufemi Otedola, CON, who is
Chairman of the Board of Directors. Designated
insider_type as 'related_party'.
document_url: >-
https://doclib.ngxgroup.com/Financial_NewsDocs/65_FirstHoldCo_Plc_-_Notification_of_Insider_Dealing_-_Calvados-_August_17_2026.pdf
disclosure_title: FIRST HOLDCO PLC DIRECTORSDEALINGS
disclosed_at: '2026-08-17'
price_at_txn: null
current_price: 126
pagination:
page: 1
limit: 1
total: 436
pages: 436
has_next: true
has_prev: false
coverage_note: >-
Director-dealings coverage is partial: not every listed
company has filings on record. Use GET /v1/companies to
check a symbol's listing status.
meta:
plan: business
calls_used: 21
calls_remaining: 1999979
reset_at: '2026-10-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidParam'
'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'
DirectorDealing:
type: object
description: >-
A single structured director-dealings filing, extracted from an NGX PDMR
disclosure PDF.
properties:
id:
type: integer
disclosure_id:
type: integer
description: Foreign key to the underlying corporate_disclosures filing.
company_symbol:
type: string
company_name:
type: string
insider_name:
type: string
insider_slug:
type: string
description: >-
Stable, normalised identifier for this insider. Collapses
name-spelling variants, e.g. "MR. X" and "X", to one identity.
insider_position:
type: string
nullable: true
insider_type:
type: string
description: >-
Raw taxonomy value. Belongs to one of the insider-type buckets used
by the `insider` filter (directors, executives, employees,
connected, shareholders, other).
example: executive_director
is_corporate_insider:
type: boolean
notification_type:
type: string
nullable: true
transaction_type:
type: string
description: >-
Raw taxonomy value (e.g. `purchase`, `sale`,
`staff_scheme_purchase`).
side:
type: string
enum:
- buy
- sell
- other
description: Derived classification of transaction_type.
is_open_market:
type: boolean
acquired_or_disposed:
type: string
nullable: true
instrument_type:
type: string
nullable: true
total_volume:
type: number
nullable: true
average_price:
type: number
nullable: true
description: NGN, unless currency is set.
total_value:
type: number
nullable: true
total_value_reported:
type: number
nullable: true
currency:
type: string
example: NGN
shares_owned_after:
type: number
nullable: true
shares_owned_after_source:
type: string
nullable: true
letter_date:
type: string
format: date
nullable: true
transaction_date_from:
type: string
format: date
nullable: true
transaction_date_to:
type: string
format: date
nullable: true
date_suspect:
type: boolean
description: >-
True when the extraction pipeline flagged this filing's date as
unreliable.
place_of_transaction:
type: string
nullable: true
days_to_file:
type: integer
nullable: true
description: Days between the transaction date and the NGX filing date.
days_letter_to_disclosure:
type: integer
nullable: true
tranche_count:
type: integer
tranches:
type: array
description: >-
Per-tranche volume/price/date breakdown, when the filing reports the
transaction in multiple tranches.
items:
type: object
properties:
volume:
type: number
nullable: true
price:
type: number
nullable: true
price_low:
type: number
nullable: true
price_high:
type: number
nullable: true
date:
type: string
format: date
nullable: true
is_scanned:
type: boolean
description: >-
True if the source filing was a scanned image rather than
machine-readable text.
extraction_confidence:
type: string
nullable: true
enum:
- high
- medium
- low
extraction_notes:
type: string
nullable: true
document_url:
type: string
description: Direct URL to the source PDF on the NGX document library.
disclosure_title:
type: string
disclosed_at:
type: string
format: date
price_at_txn:
type: number
nullable: true
description: Closing price on transaction_date_from.
current_price:
type: number
nullable: true
description: Latest known price for the company.
PaginationExtended:
type: object
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 20
total:
type: integer
example: 42
pages:
type: integer
example: 3
has_next:
type: boolean
example: true
has_prev:
type: boolean
example: false
Meta:
type: object
description: Quota and plan metadata included on every authenticated response.
properties:
plan:
type: string
description: Current plan name.
enum:
- free
- hobby
- starter
- pro
- 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 (your account's
billing renewal date, not the calendar month start).
example: '2026-06-15T23:57: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:
InvalidParam:
description: Invalid or malformed query parameter.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: INVALID_PARAM
message: from must be in YYYY-MM-DD format.
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-15T23:57: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).
````