> ## 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.
# US Market Movers
> Top gaining and losing US tickers for the current session.
Returns the top gaining and losing US tickers by current-session change percent, drawn from live quotes rather than a per-date historical query — US quotes only ever hold the current snapshot, unlike NGX's per-date equity table.
Restricted to common stock and ADRs, and to quotes no more than one hour older than the freshest quote in the dataset, so illiquid securities with stale or erratic prices don't dominate the ranking.
## OpenAPI
````yaml GET /us/market/movers
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) and US market data, including equities, ETFs, 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 | Nigeria | Everywhere else |
| :--- | ---: | ---: | :--- | :--- |
| Free | 3,000 | 30 | Free | Free |
| Hobby | 10,000 | 60 | ₦15,000/mo | $15/mo |
| Starter | 100,000 | 120 | ₦50,000/mo | $49/mo |
| Pro | 250,000 | 120 | ₦100,000/mo | $99/mo |
| Business | 2,000,000 | 300 | ₦300,000/mo | $299/mo |
| Enterprise | Unlimited | Unlimited | Custom | Custom |
Nigerian customers pay in NGN through Paystack. Customers elsewhere pay in
USD through Stripe. Both regions receive the same endpoint access and shared
monthly allowance.
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.
- name: US Market
description: >-
US equities, ETFs, ADRs and market indices — ticker reference data,
current quotes, historical daily price charts, market status, and
holidays. Sourced from a separate US dataset; financial statements and
options data are not yet available for US tickers.
paths:
/us/market/movers:
get:
tags:
- US Market
summary: Top US gainers and losers
description: >
Returns the top gaining and losing US tickers by current-session
`change_pct`, drawn from live quotes rather than a per-date historical
query (US quotes hold only the current snapshot, unlike NGX's per-date
equity table).
Restricted to common stock and ADRs, and to quotes no more than one hour
older than the freshest quote in the dataset, to keep illiquid
securities with stale or erratic prices out of the ranking.
**Plan required:** Starter
operationId: getUsMarketMovers
parameters:
- name: type
in: query
schema:
type: string
enum:
- gainers
- losers
description: Omit to return both.
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 50
default: 10
responses:
'200':
description: Movers retrieved successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/UsMovers'
'400':
description: Invalid `type` or `limit`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'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'
UsMovers:
type: object
properties:
top_gainers:
type: array
items:
$ref: '#/components/schemas/UsMoverItem'
top_losers:
type: array
items:
$ref: '#/components/schemas/UsMoverItem'
summary:
type: object
properties:
total_gainers:
type: integer
total_losers:
type: integer
biggest_gainer:
type: object
nullable: true
properties:
symbol:
type: string
change_pct:
type: number
biggest_loser:
type: object
nullable: true
properties:
symbol:
type: string
change_pct:
type: number
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.
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 in the current usage period 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'
market:
type: string
enum:
- US
description: Present on US endpoint responses.
currency:
type: string
enum:
- USD
description: Quote currency. Present on US endpoint responses.
as_of:
type: string
format: date-time
nullable: true
description: >-
Oldest quote timestamp represented in a US response, or `null` when
it contains no quote timestamps.
newest:
type: string
format: date-time
nullable: true
description: >-
Newest quote timestamp represented in a US response, or `null` when
it contains no quote timestamps.
UsMoverItem:
type: object
properties:
symbol:
type: string
example: AAPL
name:
type: string
example: Apple Inc.
sector:
type: string
nullable: true
logo_url:
type: string
nullable: true
last_price:
type: number
nullable: true
prev_close:
type: number
nullable: true
change_abs:
type: number
nullable: true
change_pct:
type: number
nullable: true
volume:
type: integer
nullable: true
market_cap:
type: number
nullable: true
is_delayed:
type: boolean
quote_time:
type: string
format: date-time
nullable: true
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-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).
````