# AGENTS Source: https://docs.ngnmarket.com/AGENTS > **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project. > For Mintlify product knowledge (components, configuration, writing standards), > install the Mintlify skill: `npx skills add https://mintlify.com/docs` # Documentation project instructions ## About this project * This is a documentation site built on [Mintlify](https://mintlify.com) * Pages are MDX files with YAML frontmatter * Configuration lives in `docs.json` * Run `mint dev` to preview locally * Run `mint broken-links` to check links ## Terminology ## Style preferences * Use active voice and second person ("you") * Keep sentences concise — one idea per sentence * Use sentence case for headings * Bold for UI elements: Click **Settings** * Code formatting for file names, commands, paths, and code references ## Content boundaries # Paginated request log history Source: https://docs.ngnmarket.com/account/paginated-request-log-history get /account/logs Returns a paginated, reverse-chronological list of authenticated API requests made by the user over the last 30 days. Filter by status class or endpoint path using query parameters. **Plan required:** Starter or higher # Quota status and 30-day analytics Source: https://docs.ngnmarket.com/account/quota-status-and-30-day-analytics get /account/usage Returns the authenticated user's current quota status and a 30-day analytics summary. **Plan required:** Free (available to all plans) # Agent Quickstart Source: https://docs.ngnmarket.com/agent-quickstart Paste one prompt into your coding agent to find where NGX market data would replace hardcoded values, scrapers, or manual calculations in your codebase. This page gives your coding agent (Claude Code, Cursor, or similar) a single prompt that installs the NGN Market skill, scans your repository for integration opportunities, and proposes changes without editing anything until you approve. Create a free account at [ngnmarket.com](https://ngnmarket.com) and verify your email. You can use the free plan for basic integrations, but most endpoints require a paid plan. After signing in, go to your [developer dashboard](https://ngnmarket.com/developer) and copy your API key. It looks like `ngm_live_XXXXXXXXXXXXXXXXXXXX`. Store your API key in an environment variable called `NGNMARKET_API_KEY`. For example, on macOS or Linux: ```bash theme={null} export NGNMARKET_API_KEY="ngm_live_XXXXXXXXXXXXXXXXXXXX" ``` On Windows (PowerShell): ```powershell theme={null} $env:NGNMARKET_API_KEY="ngm_live_XXXXXXXXXXXXXXXXXXXX" ``` Run your agent in the repo you want scanned, then paste this in.

Paste this into your agent's chat, in the repo you want scanned.

```text theme={null} Install and use the NGN Market API skill, then audit this repository for places where it should replace what's currently there. Follow these steps in order: 1. Confirm an NGNMARKET_API_KEY environment variable is set. If it isn't, stop and tell me to get one from https://ngnmarket.com/developer before continuing. 2. Install the skill file by following https://docs.ngnmarket.com/install-skill (prefer `npx skills add -g https://docs.ngnmarket.com/skill.md` if the `skills` CLI is available; otherwise use the manual curl install for whichever agent you are). 3. Scan this repository for NGX/Nigerian-market data patterns that the API could replace. Look specifically for: - Hardcoded stock prices or static price objects (e.g. sample NGX tickers with fixed prices in fixtures, seed data, or demo components) - Static JSON shaped like OHLCV history (arrays/objects with open, high, low, close, volume, or timestamp + price fields for a stock symbol) - Manually maintained lists of NGX companies, sectors, or tickers - Homegrown NGN/USD (or other currency) conversion math, or a hardcoded exchange rate constant - Manually typed or manually updated dividend dates/calendars - Scraped or manually sourced company logos for NGX-listed tickers - Custom sorting/filtering logic that recomputes "top gainers" or "top losers" from raw price data - Hand-parsed NGX news, press releases, or corporate disclosure text - A polling loop (setInterval, cron, or similar) re-fetching NGX prices, indices, forex, disclosures, or dividends on a timer, where a WebSocket channel could push updates instead 4. For each match, report: the file and line number, what it's currently doing, which NGN Market API endpoint would replace it (from the skill's recipe table), which plan tier that endpoint requires, and a one-line reason it's a better approach (freshness, correctness, maintenance cost). Present this list and WAIT for my approval — do not edit any files yet. 5. Once I approve (whether that's "do all of them", specific items, or none), make only the approved changes. If nothing in this repo matches, or after you're done, suggest 3-5 concrete integrations and 2-3 side-project ideas that would make sense given this codebase's actual stack and purpose. ```
The prompt is written to stop and show you its findings first. Expect a list like: ``` src/data/demo-prices.json:1-40 — hardcoded prices for 12 NGX tickers → replace with GET /companies (free plan) → reason: demo data goes stale; live endpoint always current src/lib/convertNaira.js:8 — hardcoded USD/NGN rate (1500) → replace with GET /forex/current (free plan) → reason: fixed rate drifts from the real exchange rate daily ``` Approve what you want, skip the rest. Your agent should not touch anything you didn't sign off on. This scans for **patterns**, not exact matches. Review every suggestion before approving. The agent has no special access to your code beyond what it can already read; nothing is uploaded or shared with NGN Market. Manual install paths per agent, if you'd rather skip the CLI Full worked examples for the most common integrations # Account Logs Source: https://docs.ngnmarket.com/api-reference/account/logs GET /account/logs Paginated request log history for your API key. Returns a paginated list of your authenticated API requests from the last 30 days. Each log entry shows the HTTP method, endpoint path, status code, latency, requesting IP address, and timestamp. Logs are returned in reverse chronological order (most recent first). You can filter by status class or endpoint path using query parameters. **Plan required:** Starter or higher. Free plan callers receive a `403 PLAN_REQUIRED` response. Log entries are retained for **30 days** for Starter and above. Entries older than 30 days are automatically pruned. # Account Usage Source: https://docs.ngnmarket.com/api-reference/account/usage GET /account/usage Retrieve your current quota status and 30-day analytics. Returns your current quota status and a 30-day analytics summary scoped to the authenticated user. All data is read from `api_request_logs`, so it reflects only authenticated requests. Calls that failed auth or were blocked before reaching a route are not counted. This endpoint is available on all plans including Free. It does not consume a quota call. ## Analytics window All analytics fields (`daily`, `top_endpoints`, `status_breakdown`) cover the **last 30 calendar days** from the current date. The quota fields (`calls_used`, `calls_limit`, `calls_remaining`) reflect the current billing month, which resets on the 1st. # Get Blog Post Source: https://docs.ngnmarket.com/api-reference/blog/post-detail GET /blog/posts/{slug} Retrieve the full detail record for a single post: rich author profile, named taxonomies, and a content preview. Returns a richer record than the list endpoints. The author field is a full object (bio, website, social links, avatar URL) rather than just a name. `categories`, `tags`, and `companies` each come with a display `name` alongside the `slug` or `symbol`, so you can render them without a second lookup. `content.html` gives you the article's "Key Highlights" section (heading plus bullet list) if one exists, or the first 500 characters of plain text as a fallback, this is a preview, not the full article body. `url` is the canonical link to the full article on [ngnmarket.com/blog](https://ngnmarket.com/blog). Use slugs from any list or [search](/api-reference/blog/search) response. # List Blog Posts Source: https://docs.ngnmarket.com/api-reference/blog/posts GET /blog/posts Paginated, filterable feed of all published NGN Market blog posts. Returns a paginated, date-descending feed of published posts. Each page contains up to 20 posts, and each post includes a canonical `url` linking to the full article on [ngnmarket.com/blog](https://ngnmarket.com/blog). You can filter the feed using any combination of `category`, `company`, and `tag`. For example, `?category=markets&company=DANGCEM` returns posts in the **markets** category that are also tagged to **DANGCEM**. For the rich author profile, named taxonomies, and content preview, call [`GET /blog/posts/{slug}`](/api-reference/blog/post-detail). ## Available categories Pass one of these slugs to the `category` query param. | Slug | Name | | :----------------- | :--------------- | | `markets` | Markets | | `corporate-news` | Corporate News | | `economy` | Economy | | `industries` | Industries | | `technology` | Technology | | `personal-finance` | Personal Finance | | `product-updates` | Product Updates | ## Available tags Pass one of these slugs to the `tag` query param. | Slug | Name | | :-------------- | :------------ | | `stocks` | Stocks | | `crypto` | Crypto | | `exchange-rate` | Exchange Rate | | `inflation` | Inflation | | `cbn` | CBN | | `earnings` | Earnings | | `energy` | Energy | | `banking` | Banking | | `fintech` | Fintech | | `t-bills` | T-Bills | | `fg` | FG | | `dividends` | Dividends | | `ngn-market` | NGN Market | ## Filtering by company The `company` param takes the NGX stock ticker symbol of a listed company. For example, use `DANGCEM` for Dangote Cement, `MTNN` for MTN Nigeria, `GTCO` for Guaranty Trust, or `BUACEMENT` for BUA Cement. The lookup is case-insensitive, so `dangcem` and `DANGCEM` return the same posts. If you are not sure what a company's ticker is, you can fetch the full list of valid symbols from [`GET /companies/identifiers`](/api-reference/companies/identifiers). ## Combining filters Filters compose, so you can ask for posts in the **markets** category that are also tagged to **DANGCEM**: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/blog/posts?category=markets&company=DANGCEM" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/blog/posts'); url.searchParams.set('category', 'markets'); url.searchParams.set('company', 'DANGCEM'); 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/blog/posts', params={'category': 'markets', 'company': 'DANGCEM'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Search Blog Posts Source: https://docs.ngnmarket.com/api-reference/blog/search GET /blog/search Full-text search across all published posts with AI query expansion and relevance scoring. Searches all published posts by keyword. Queries are automatically expanded using AI, so searching `"MTNN"` will find articles about "MTN Nigeria", and `"gtbank"` will surface "Guaranty Trust" results. Each result includes a `relevanceScore` and a canonical `url` linking to the full article on [ngnmarket.com/blog](https://ngnmarket.com/blog). Narrow results to a date window with `fromDate` and `toDate`, and cap the number of hits with `limit` (max 10): ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/blog/search?q=Dangote%20Cement&fromDate=2026-01-01&limit=10" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/blog/search'); url.searchParams.set('q', 'Dangote Cement'); url.searchParams.set('fromDate', '2026-01-01'); url.searchParams.set('limit', '10'); 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/blog/search', params={'q': 'Dangote Cement', 'fromDate': '2026-01-01', 'limit': 10}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` If you want posts for a specific NGX-listed stock, use [GET /blog/posts?company=SYMBOL](/api-reference/blog/posts) instead. It's a direct lookup on the `companies` field and doesn't require a search query. # List Bonds Source: https://docs.ngnmarket.com/api-reference/bonds/list GET /bonds Retrieve a paginated list of NGX-listed bonds. This endpoint returns a paginated list of bonds listed on the Nigerian Exchange (NGX). Each record includes the bond's ISIN, issuer name, bond type, coupon rate, maturity date, and opening price. You can narrow results with optional search and type filters. Results are sorted by bond type priority (Federal Government bonds first, then state, then corporate), then by maturity date ascending. This endpoint requires a Starter plan or higher. # Price Chart Source: https://docs.ngnmarket.com/api-reference/companies/chart GET /companies/{symbol}/chart Retrieve historical price series for an NGX-listed company. The chart endpoint returns daily price history for a company. Each data point includes a timestamp and date, plus close price. Where available, it also includes the full OHLCV fields, VWAP (volume-weighted average price), trade count, and daily change. How far back you can go depends on your plan. Hobby gets 2 years, Starter gets 5, and Pro, Business, and Enterprise get the full record, which for some companies goes back to the 1990s. If your `from` date reaches further back than your plan allows, the response doesn't error, it just returns data starting from the earliest date your plan permits. Check `start_date` in the statistics block if you need to confirm what you actually got back. Use `from` and `to` (`YYYY-MM-DD`) to narrow results to a specific date range, or use the `period` parameter to request a named time window (`7d`, `30d`, `90d`, `1y`, `5y`, `all`). Three `format` options let you pick the shape that fits your charting library: * `detailed` (default): full objects per day. Includes `price` as an alias for `close` for backward compatibility, plus `open`, `high`, `low`, `close`, `volume`, `value_traded`, `vwap`, `trade_count`, `change`, `change_percent`. * `chart`: compact `[timestamp, close]` arrays. Backward-compatible with the previous API behaviour, suited for line charts. * `ohlcv`: compact `[timestamp, open, high, low, close, volume]` arrays. Pass this directly to TradingView Lightweight Charts, ApexCharts, or Highcharts candlestick series. `close` is the only field guaranteed to be present on every data point. Depending on the company and date, `open`, `high`, `low`, `volume`, `value_traded`, `vwap`, `trade_count`, `change`, and `change_percent` may come back as `null`. This means no intraday range data is available for that specific day. It does not mean the day itself is missing or that the value is zero. This applies in both `detailed` (named fields) and `ohlcv` (positional array, where a `null` appears in place of the missing element) formats. When rendering a candlestick chart, check for `null` before drawing the candle body and fall back to a marker or line segment on the close price for those points. See the [candlestick chart guide](/guides/candlestick-chart#handling-missing-ohlc-data) to understand better. A statistics block summarises the full range (first and last price, min, max, and total change) so you can render a summary card without extra computation. For example, to fetch one year of DANGCEM data in candlestick format: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/DANGCEM/chart?period=1y&format=ohlcv" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/DANGCEM/chart'); url.searchParams.set('period', '1y'); url.searchParams.set('format', 'ohlcv'); 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/companies/DANGCEM/chart', params={'period': '1y', 'format': 'ohlcv'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` Step-by-step guide showing how to fetch OHLCV data and render it as an interactive candlestick chart with TradingView Lightweight Charts. Includes a live demo, vanilla JS, and a React component. # Company Profile Source: https://docs.ngnmarket.com/api-reference/companies/detail GET /companies/{symbol} Retrieve the full profile for an NGX-listed company. The company detail endpoint returns what you need to build a full company page: current price data, 52-week range, market cap, trailing EPS, sector classification, contact details, and a plain-language business description. It also returns valuation and liquidity ratios computed from the latest available financial statements, so you don't need to calculate these yourself: `pb_ratio` (current price divided by book value per share), `debt_to_equity` (total liabilities divided by shareholders' equity), `current_ratio` (current assets divided by current liabilities), and `dividend_yield` (based on the most recent ex-dividend date). All ratio fields are `null` when the underlying financial data is not yet available for the company. The response also includes `logo_url`, a ready-to-use PNG for the company's logo. Need a different format or size? See the [company logos guide](/guides/company-logos). The ticker symbol lookup is case-insensitive, so `dangcem`, `DANGCEM`, and `DangCem` all resolve to the same company. This endpoint requires a Hobby plan or higher. # Company Disclosures Source: https://docs.ngnmarket.com/api-reference/companies/disclosures GET /companies/{symbol}/disclosures Corporate filings scoped to a specific NGX-listed company. Returns all corporate disclosures for a single company identified by its NGX ticker symbol. This is equivalent to calling [`GET /disclosures?symbol={symbol}`](/api-reference/disclosures/list) but is the preferred endpoint when building company-specific views such as a stock detail page. Coverage goes back to July 2014 for companies that were already listed then, which is as far back as NGX's own filing system has records. Results are sorted newest first by default. Use the `type` filter to narrow to a specific filing category, or the `from`/`to` params for a date range. ```bash All disclosures for GTCO theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/disclosures" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```bash Financial statements only theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/disclosures?type=Financial+Statements" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const symbol = 'GTCO'; const res = await fetch( `https://api.ngnmarket.com/v1/companies/${symbol}/disclosures?type=Financial+Statements`, { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); ``` ```python Python theme={null} import requests symbol = 'GTCO' res = requests.get( f'https://api.ngnmarket.com/v1/companies/{symbol}/disclosures', params={'type': 'Financial Statements'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Dividend History Source: https://docs.ngnmarket.com/api-reference/companies/dividends GET /companies/{symbol}/dividends Retrieve the full dividend history for an NGX-listed company. This endpoint returns the complete dividend history for an NGX-listed company, ordered from most recent to oldest. Each record includes the ex-dividend date, dividend amount (in NGN per share), dividend type, payment date, and trailing yield at time of declaration. Use `from` and `to` to filter by date range, or `limit` to cap the number of records returned (max 100). Omitting all parameters returns as much history as your plan allows. Depth depends on plan: Starter gets 5 years, and Pro, Business, and Enterprise get the full record. If `from` reaches further back than your plan permits, the response doesn't error, it just starts from the earliest ex-dividend date your plan can see. For example, to fetch DANGCEM's last 10 dividends: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/DANGCEM/dividends?limit=10" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/DANGCEM/dividends'); url.searchParams.set('limit', '10'); 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/companies/DANGCEM/dividends', params={'limit': 10}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` To fetch all dividends declared between two dates: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/ZENITHBANK/dividends?from=2020-01-01&to=2024-12-31" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/ZENITHBANK/dividends'); url.searchParams.set('from', '2020-01-01'); url.searchParams.set('to', '2024-12-31'); 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/companies/ZENITHBANK/dividends', params={'from': '2020-01-01', 'to': '2024-12-31'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` If a company has no dividend history on record, `dividends` will be an empty array and `count` will be `0`. This endpoint requires a Starter plan or higher, see above for how much history each plan returns. # Financial Statements Source: https://docs.ngnmarket.com/api-reference/companies/financials GET /companies/{symbol}/financials Retrieve income statements, balance sheets, cash flow, and ratios. The financials endpoint returns the complete set of financial statements filed by a company on the NGX for every reporting period available. This includes the income statement, balance sheet, cash flow statement, and computed financial ratios. Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. Results are ordered from most recent to oldest, with annual full-year statements appearing before quarterly results for the same year. This endpoint requires a Business plan or higher. For example, to fetch GTCO's quarterly statements for 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/financials?periodType=quarterly&year=2025" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('year', '2025'); 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/companies/GTCO/financials', params={'periodType': 'quarterly', 'year': 2025}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Balance Sheet Source: https://docs.ngnmarket.com/api-reference/companies/financials-balance-sheet GET /companies/{symbol}/financials/balance-sheet Retrieve just the balance sheet for an NGX-listed company. This endpoint returns just the balance sheet for every reporting period available, ordered from most recent to oldest. It's the same data you'd find under `balance_sheet` in the combined financials endpoint, returned on its own so you're not paying for the income statement, cash flow, and ratios sections when you only need assets, liabilities, and equity figures. Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. This endpoint requires a Business plan or higher. For example, to fetch GTCO's quarterly balance sheets for 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/financials/balance-sheet?periodType=quarterly&year=2025" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials/balance-sheet'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('year', '2025'); 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/companies/GTCO/financials/balance-sheet', params={'periodType': 'quarterly', 'year': 2025}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Cash Flow Statement Source: https://docs.ngnmarket.com/api-reference/companies/financials-cash-flow GET /companies/{symbol}/financials/cash-flow Retrieve just the cash flow statement for an NGX-listed company. This endpoint returns just the cash flow statement for every reporting period available, ordered from most recent to oldest. It's the same data you'd find under `cash_flow` in the combined financials endpoint, returned on its own so you're not paying for the income statement, balance sheet, and ratios sections when you only need operating, investing, and financing cash flows. Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. This endpoint requires a Business plan or higher. For example, to fetch GTCO's quarterly cash flow statements for 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/financials/cash-flow?periodType=quarterly&year=2025" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials/cash-flow'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('year', '2025'); 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/companies/GTCO/financials/cash-flow', params={'periodType': 'quarterly', 'year': 2025}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Financial Statement Growth Source: https://docs.ngnmarket.com/api-reference/companies/financials-growth GET /companies/{symbol}/financials/growth Year-over-year growth rates for income statement, cash flow, and balance sheet line items. This endpoint returns period-over-period growth rates for revenue, profit, cash flow, and balance sheet line items, for every reporting period available. By default, growth is computed **year-over-year against the same period label**, FY 2025 vs FY 2024, Q2 2025 vs Q2 2024, not sequentially. Sequential quarter-over-quarter comparison is noisy for seasonal businesses, so year-over-year is the safer default. Pass `compare=sequential` if you specifically want each period compared against the one immediately before it instead. A growth rate comes back as `null` rather than a number in two situations: when there's no comparable prior period (the oldest period on file has nothing to compare against), and when the prior period's value was negative or zero. "Percent growth" from a loss or from zero isn't a meaningful figure, a company swinging from a ₦164B loss to a ₦105B profit isn't "growing 164%", so we don't pretend it is. The one exception is `dividends_paid_growth`, which is compared by magnitude rather than signed value, since `dividends_paid` is stored as a negative outflow by accounting convention, not because a company is in distress. Use `periodType` (`annual` or `quarterly`) to restrict to one reporting cadence, omit it to get both together. `year` filters to a specific fiscal year, and `limit` caps the number of records returned. This endpoint requires a Pro plan or higher. Depth depends on plan. Pro gets the last 3 years, annual only, `periodType` and `year` are ignored at this tier. Business and Enterprise get the full history, both annual and quarterly. Note that `compare=sequential` is only meaningfully different from the year-over-year default once quarterly data is available, comparing one annual period to the one right before it lands on the same result as comparing it to the same period last year, so this parameter mostly matters once you're on Business. For example, to fetch the last 3 years of annual growth for Nestlé Nigeria: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth?periodType=annual&limit=3" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth'); url.searchParams.set('periodType', 'annual'); url.searchParams.set('limit', '3'); 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/companies/NESTLE/financials/growth', params={'periodType': 'annual', 'limit': 3}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` To compare each quarter against the one right before it instead of the same quarter last year: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth?periodType=quarterly&compare=sequential" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('compare', 'sequential'); 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/companies/NESTLE/financials/growth', params={'periodType': 'quarterly', 'compare': 'sequential'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Income Statement Source: https://docs.ngnmarket.com/api-reference/companies/financials-income GET /companies/{symbol}/financials/income Retrieve just the income statement for an NGX-listed company. This endpoint returns just the income statement for every reporting period available, ordered from most recent to oldest. It's the same data you'd find under `income_statement` in the combined financials endpoint, returned on its own so you're not paying for the balance sheet, cash flow, and ratios sections when you only need revenue and earnings figures. Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. This endpoint requires a Pro plan or higher. Depth depends on plan. Pro gets the last 3 years, annual only, `periodType` and `year` are ignored at this tier since the response is already capped to the most recent annual figures. Business and Enterprise get the full history, both annual and quarterly. For example, to fetch GTCO's quarterly income statements for 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/financials/income?periodType=quarterly&year=2025" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials/income'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('year', '2025'); 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/companies/GTCO/financials/income', params={'periodType': 'quarterly', 'year': 2025}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Financial Ratios Source: https://docs.ngnmarket.com/api-reference/companies/financials-ratios GET /companies/{symbol}/financials/ratios Retrieve just the computed financial ratios for an NGX-listed company. This endpoint returns just the computed financial ratios for every reporting period available, ordered from most recent to oldest. It's the same data you'd find under `ratios` in the combined financials endpoint, returned on its own so you're not paying for the income statement, balance sheet, and cash flow sections when you only need margins, returns, and per-share figures. Some ratios (gross margin, operating margin, net profit margin, return on equity, return on assets) are stored directly from the filed statements. The rest (current ratio, debt to equity, interest coverage, free cash flow margin, book value per share, free cash flow per share, revenue per share) are computed at request time from the underlying statements. A ratio comes back as `null` when one of its inputs isn't available for that period. Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. This endpoint requires a Starter plan or higher. Depth depends on plan. Starter gets the most recent annual period only, essentially the current year. Pro extends that to the last 3 years, annual only. On both of these tiers, `periodType` and `year` are ignored since the response is already capped to a fixed, recent window. Business and Enterprise get the full history, both annual and quarterly, with `periodType` and `year` fully respected. For example, to fetch GTCO's quarterly ratios for 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/GTCO/financials/ratios?periodType=quarterly&year=2025" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials/ratios'); url.searchParams.set('periodType', 'quarterly'); url.searchParams.set('year', '2025'); 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/companies/GTCO/financials/ratios', params={'periodType': 'quarterly', 'year': 2025}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Trailing Twelve Month Financials Source: https://docs.ngnmarket.com/api-reference/companies/financials-ttm GET /companies/{symbol}/financials/ttm Rolling TTM financials, computed from the 4 most recent discrete quarters. This endpoint returns trailing-twelve-month (TTM) financials, computed by summing the 4 most recent discrete quarters on file. It's shaped a little differently from the other financials endpoints: by default it returns a single rolling snapshot, not a list of filed reporting periods, since TTM means "the last four quarters as of right now," not a specific period a company filed. The income statement and cash flow sections are genuine sums across the 4 quarters. The balance sheet section is **not** summed, it's just the latest quarter's snapshot, since assets and liabilities don't add across periods the way revenue or cash flow does. Ratios are computed from the summed flow figures against that latest balance sheet. Pass `limit` to get a rolling window of TTM snapshots instead of just the latest one. This is useful for charting a smoothed trend, TTM revenue at each of the last 8 quarter-ends, for example, without the seasonal noise you'd get from raw quarterly figures. Each snapshot includes `quarters_included`, listing exactly which 4 quarters were summed, so if a company has a gap in its reporting history you'll see it rather than get a silently wrong number. This endpoint needs 4 consecutive discrete quarters on file (`Q1`–`Q4`, not cumulative 9M or H1 figures) to compute anything. Companies without that history return a `404` rather than a fallback built from annual figures, which wouldn't actually be trailing twelve months. For example, to fetch the latest TTM snapshot for Nestlé Nigeria: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }); const { data } = await res.json(); const latest = data.data[0]; // latest.income_statement_ttm.revenue — trailing 12 month revenue // latest.quarters_included — which 4 quarters were summed ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` To chart a rolling TTM revenue trend over the last two years of quarter-ends: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm?limit=8" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm'); url.searchParams.set('limit', '8'); const res = await fetch(url, { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }); const { data } = await res.json(); // data.data — 8 rolling TTM snapshots, most recent first ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/companies/NESTLE/financials/ttm', params={'limit': 8}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` This endpoint requires a Business plan or higher. # Ticker Symbols Source: https://docs.ngnmarket.com/api-reference/companies/identifiers GET /companies/identifiers Retrieve all NGX ticker symbols, names, and ISIN identifiers. The identifiers endpoint returns every company listed on the Nigerian Exchange in a single lightweight response, no pagination needed. Each entry includes the ticker symbol, company name, and international securities identifier. This is the most efficient way to populate a company picker, validate user input, or seed a local lookup table. # List Companies Source: https://docs.ngnmarket.com/api-reference/companies/list GET /companies Retrieve a paginated, filterable list of all NGX-listed companies. The list endpoint returns all companies currently listed on the Nigerian Exchange Group (NGX). You can paginate through results, narrow them to a specific sector, or search by company name or ticker symbol. Each company includes its current price, market capitalisation, trading volume, and percentage changes across multiple time frames, plus a `logo_url` you can drop straight into an `` tag. Sort and filter options let you rank companies by any of these fields. `logo_url` is a 200×200 PNG served from a CDN, ready to use with no setup. If you need WebP, favicon-sized ICOs, or logos bundled into your own build, see the [company logos guide](/guides/company-logos). For example, to fetch the 25 largest Financial Services companies sorted by market cap: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies?sector=Financial%20Services&limit=25&sort=market_cap&order=desc" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies'); url.searchParams.set('sector', 'Financial Services'); url.searchParams.set('limit', '25'); url.searchParams.set('sort', 'market_cap'); url.searchParams.set('order', 'desc'); 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/companies', params={ 'sector': 'Financial Services', 'limit': 25, 'sort': 'market_cap', 'order': 'desc', }, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` Use `search` instead of `sector` for partial-match lookups by ticker or name (`search=DAN` matches `DANGCEM`). # Company News Source: https://docs.ngnmarket.com/api-reference/companies/news GET /companies/{symbol}/news Retrieve recent news articles for an NGX-listed company by ticker symbol. This endpoint returns recent news articles for a specific NGX-listed company, identified by its NGX ticker symbol. Articles are sourced in real time from Nigerian financial news outlets. Use `limit` to control how many articles are returned (default 5, max 10), and `maxAge` to set the maximum article age in days (default 90). Each article includes `pub_date`, `days_old`, and `time_ago` fields for convenient age display. News is fetched live on each request, so response times may be slightly higher than data endpoints. For example, to fetch the 10 most recent DANGCEM articles from the last 30 days: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/DANGCEM/news?limit=10&maxAge=30" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/companies/DANGCEM/news'); url.searchParams.set('limit', '10'); url.searchParams.set('maxAge', '30'); 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/companies/DANGCEM/news', params={'limit': 10, 'maxAge': 30}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` If no articles are found within the configured age window, the data array is empty. This endpoint requires a Starter plan or higher. # List Disclosures Source: https://docs.ngnmarket.com/api-reference/disclosures/list GET /disclosures Paginated feed of official corporate filings from NGX-listed companies. Returns official corporate filings sourced from the NGX Group document library, updated twice daily. Every disclosure includes a direct `document_url` link to the source PDF. Coverage goes back to July 2014, which is as far back as NGX's own filing system has records. There's nothing before that to fetch, not even from NGX directly. Results are sorted newest first by default. Use `GET /disclosures/types` to discover all valid values for the `type` filter. ## Submission types | Type | Description | | :------------------------------------- | :----------------------------------------------------- | | `Financial Statements` | Quarterly and annual audited financial reports | | `Corporate Actions` | Major company announcements and corporate events | | `Board Meeting (BM)` | Board meeting notices, results, and resolutions | | `Annual General Meeting (AGM)` | AGM notices, results, and resolutions | | `Extra-Ordinary General Meeting (EGM)` | Emergency or special shareholder meetings | | `DirectorsDealings` | Insider trading and director share transaction reports | | `EarningForcast` | Earnings guidance and forecast filings | ## Filtering by company Use the `symbol` param to scope results to a single company. If you're building a stock detail view, [`GET /companies/{symbol}/disclosures`](/api-reference/companies/disclosures) is a cleaner alternative. ## Example requests ```bash Filter by company and type theme={null} curl "https://api.ngnmarket.com/v1/disclosures?symbol=GTCO&type=Financial+Statements" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```bash Date range theme={null} curl "https://api.ngnmarket.com/v1/disclosures?from=2026-01-01&to=2026-03-31" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/disclosures?symbol=MTNN&limit=10', { 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/disclosures', params={'symbol': 'GTCO', 'type': 'Financial Statements'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Disclosure Types Source: https://docs.ngnmarket.com/api-reference/disclosures/types GET /disclosures/types All submission types in the database with document counts. Returns every submission type that exists in the database along with its document count. Use the `type` values directly as the `type` filter on [`GET /disclosures`](/api-reference/disclosures/list) or [`GET /companies/{symbol}/disclosures`](/api-reference/companies/disclosures). This endpoint is useful for building filter UIs — fetch the types once, render them as options, and pass the selected value as the `type` param. ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/disclosures/types" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/disclosures/types', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }); const { data } = await res.json(); // data.data => [{ type: "Financial Statements", count: 301 }, ...] ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/disclosures/types', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) types = res.json()['data']['data'] ``` # Recent Dividends Source: https://docs.ngnmarket.com/api-reference/dividends/recent GET /dividends/recent Browse NGX-listed companies whose ex-dividend date fell within the last 60 days. This endpoint returns a paginated list of NGX-listed companies whose ex-dividend date fell within the last 60 days, ordered chronologically. Use it to see which dividends have recently gone ex, when payments are expected, and to track dividend activity across the market. Use `page` and `limit` for pagination (up to 100 records per page). For example, to fetch the first page of recent ex-dividend activity: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/dividends/recent?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/recent'); 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 recent dividend records // data.total — total matching records ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/dividends/recent', params={'limit': 20, 'page': 1}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` The window is fixed at 60 days before today. If no dividends went ex in that period, `dividends` will be an empty array and `total` will be `0`. This endpoint requires a Starter plan or higher. # Upcoming Dividends Source: https://docs.ngnmarket.com/api-reference/dividends/upcoming GET /dividends/upcoming 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. # ETF Chart Source: https://docs.ngnmarket.com/api-reference/etfs/chart GET /etfs/{symbol}/chart Retrieve historical daily price data for any NGX-listed ETF or ETP. This endpoint returns a time series of daily closing prices for a specific NGX ETF or ETP. Use `period` for a named lookback window (`7d`, `30d`, `90d`, `1y`, `5y`, `all`) or supply `from` and `to` for a custom date range. In `detailed` format each row includes OHLCV data alongside a `normalized` field that rebases the price to 100 at the start of the requested period, useful for comparing two ETFs on the same scale. The `chart` format returns compact `[date, price]` pairs suited for line charting libraries. The `statistics` block includes `return_1m`, `return_3m`, `return_1y`, and `return_ytd`, percentage returns versus fixed historical reference points, computed independently of the `period` you requested. This endpoint requires a Starter plan or higher. Depth also depends on plan: Starter gets 5 years, and Pro, Business, and Enterprise get the full record. Ask for more than your plan allows and the response quietly starts from the earliest date it can, rather than returning an error. For example, to fetch one year of STANBICETF30 daily closes in chart-ready format: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/etfs/STANBICETF30/chart?period=1y&format=chart" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/etfs/STANBICETF30/chart'); url.searchParams.set('period', '1y'); url.searchParams.set('format', 'chart'); 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/etfs/STANBICETF30/chart', params={'period': '1y', 'format': 'chart'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # ETF Detail Source: https://docs.ngnmarket.com/api-reference/etfs/detail GET /etfs/{symbol} Retrieve full details for a single NGX-listed ETF or ETP. This endpoint returns the full profile for a specific NGX-listed ETF or ETP: ISIN, fund manager, index tracked, trustee, custodian, and liquidity provider, alongside the latest OHLCV snapshot, 52-week price range, average 3-month volume, and period change percentages. Symbols are case-insensitive. This endpoint requires a Starter plan or higher. # List ETFs Source: https://docs.ngnmarket.com/api-reference/etfs/list GET /etfs Retrieve all NGX-listed Exchange Traded Funds and ETPs with current prices and period performance. This endpoint returns a snapshot of every ETF and ETP listed on the Nigerian Exchange (NGX), including the current price, daily change, and period performance metrics (7-day, YTD, 52-week). Use it to build ETF screeners, populate a fund overview dashboard, or discover available symbols before querying detail or chart data. Supports pagination and optional search by fund name, ticker symbol, or fund manager. All plan tiers can access this endpoint. # Current Forex Rates Source: https://docs.ngnmarket.com/api-reference/forex/current GET /forex/current Retrieve the latest NGN exchange rates against all supported currencies. This endpoint returns the most recent NGN exchange rates for all supported currencies. Each rate object includes `rate` (how many NGN one unit of the foreign currency costs, so `1603.50` means \$1 = ₦1,603.50), `inverse_rate` (how much foreign currency ₦1 buys, e.g. `0.000624`), and `daily_change` plus `daily_change_percent` for movement since the previous day. Rates are sourced from NGN Market's live data feed and reflect the latest available market close. This endpoint accepts no query parameters. # Historical Forex Rates Source: https://docs.ngnmarket.com/api-reference/forex/history GET /forex/history Retrieve historical NGN exchange rates by currency pair and date range. This endpoint gives you historical exchange rate data between NGN and any supported currency pair. You can narrow results by currency code, date range (`from`/`to`), and record count, making it straightforward to populate charts, backtest models, or power rate-change alerts. The `source` and `target` parameters default to `USD` and `NGN` respectively. Pass both to query any supported pair in either direction. This endpoint requires a Hobby plan or higher. How far back you can go depends on your plan. Hobby gets 2 years, Starter gets 5, and Pro, Business, and Enterprise get the full record. A `from` date older than your plan allows won't error, the response just starts from the earliest date you're entitled to, so check the returned dates rather than assuming the request failed. For example, to fetch GBP/NGN rates for Q1 2026: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/forex/history?source=GBP&target=NGN&from=2026-01-01&to=2026-03-31" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/forex/history'); url.searchParams.set('source', 'GBP'); url.searchParams.set('target', 'NGN'); url.searchParams.set('from', '2026-01-01'); url.searchParams.set('to', '2026-03-31'); 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/forex/history', params={ 'source': 'GBP', 'target': 'NGN', 'from': '2026-01-01', 'to': '2026-03-31', }, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Index Chart Source: https://docs.ngnmarket.com/api-reference/indices/chart GET /indices/{symbol}/chart Retrieve historical daily closing values for any NGX market index. This endpoint returns a time series of daily closing values for a specific NGX market index. Narrow the result set with `from` and `to` date parameters, or use `period` (`7d`, `30d`, `90d`, `1y`, `5y`, `all`) to request a named time window. In `detailed` format, each data point includes a `normalized_value` field that rebases the index to 100 at the start of the requested period, useful for comparing two indices on the same scale in a single chart. The statistics block also includes `return_1m`, `return_3m`, `return_1y`, and `return_ytd`, percentage returns versus fixed historical reference points, computed independently of the `period` you requested. Use `format=chart` for compact `[timestamp, value]` arrays suited for line charting libraries. How far back you can go depends on your plan. Hobby gets 2 years, Starter gets 5, and Pro, Business, and Enterprise get the full record. Ask for more than your plan allows and you won't get an error, the response just starts from the earliest date you're entitled to, so check the returned dates if you need to confirm the actual range. For example, to fetch one year of NGX 30 closes in chart-ready format: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/indices/NGX30/chart?period=1y&format=chart" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/indices/NGX30/chart'); url.searchParams.set('period', '1y'); url.searchParams.set('format', 'chart'); 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/indices/NGX30/chart', params={'period': '1y', 'format': 'chart'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Index Detail Source: https://docs.ngnmarket.com/api-reference/indices/detail GET /indices/{symbol} Retrieve the full detail for a single NGX market index. This endpoint returns the full detail record for a specific NGX market index: current value and daily change, a description of the index methodology, and data on its constituent securities. Use it when you need to display a full index profile or determine which stocks make up a given index. Symbols are case-insensitive. This endpoint requires a Starter plan or higher. # List Indices Source: https://docs.ngnmarket.com/api-reference/indices/list GET /indices Retrieve all NGX market indices with current values and daily change. This endpoint returns a snapshot of every NGX market index tracked by NGN Market, including the current index value and the day's percentage change. Use it to build dashboards, populate a market overview screen, or check which indices are available before querying detail or chart data. This endpoint accepts no query parameters and requires no minimum plan. # API Reference Source: https://docs.ngnmarket.com/api-reference/introduction All NGN Market API endpoints. The NGN Market API provides programmatic access to Nigerian Exchange Group (NGX) market data. All endpoints share a common base URL, authentication scheme, and response envelope. Snapshots, ASI, top trades, gainers, sector rotation Profiles, price charts, and financial statements NGN exchange rates and all NGX market indices ## Base URL ``` https://api.ngnmarket.com/v1 ``` Need prices or these other channels pushed to you instead of polling? See the [WebSocket API](/websocket/introduction). ## Authentication Every endpoint except `/health` requires a Bearer token in the `Authorization` header: ``` Authorization: Bearer ngm_live_YOUR_KEY ``` ```bash curl theme={null} curl https://api.ngnmarket.com/v1/market/snapshot \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/market/snapshot', { 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/snapshot', headers={ 'Authorization': 'Bearer ngm_live_YOUR_KEY' } ) data = res.json() ``` Get your key from the [developer dashboard](https://ngnmarket.com/developer). Never expose your API key in client-side code or commit it to version control. If a key is compromised, revoke it from the dashboard immediately. ## HTTP Response Codes | Code | Meaning | | :---: | :---------------------------------------------------------------------------- | | `200` | Request succeeded | | `401` | Missing or invalid API key | | `403` | Endpoint requires a higher plan, or request IP is not in this key's allowlist | | `404` | Resource or route not found | | `429` | Monthly quota exceeded | | `500` | Unexpected server error | ## Response Envelope Every response (success or error) uses the same JSON envelope: ```json theme={null} { "success": true, "data": { }, "meta": { "plan": "starter", "calls_used": 4821, "calls_remaining": 95179, "reset_at": "2026-05-01T00:00:00.000Z" } } ``` The `meta` object is included on every response, so you can check `calls_remaining` and `reset_at` without a separate request to `/account/usage`. # Available Dates Source: https://docs.ngnmarket.com/api-reference/market/available-dates GET /market/available-dates List dates for which NGX market data is available. Use this endpoint to discover which trading dates are available in the dataset before querying other market endpoints. Dates are listed in reverse chronological order. Each entry includes the closing ASI value and a convenience label (`today`, `yesterday`, `latest`, or `previous`) for the most recent entries. This is useful for building date pickers or validating user-supplied dates before making downstream requests. # Market Breadth Source: https://docs.ngnmarket.com/api-reference/market/breadth GET /market/breadth List NGX trading dates with market breadth data. The breadth endpoint returns a list of NGX trading sessions enriched with market breadth data: the total number of securities that traded, how many advanced, how many declined, and how many closed unchanged on each day. Use `from` and `to` to query a specific date range, or `limit` to get the most recent N sessions. Use this endpoint to identify historically active sessions, power a calendar view of market activity, or filter date ranges before querying snapshot or movers data. This endpoint requires a **Pro** plan or higher. # Market Holidays Source: https://docs.ngnmarket.com/api-reference/market/holidays GET /market/holidays List NGX public holidays when the exchange is closed. Returns the public holidays that the NGX is closed for, as maintained by the NGN Market team. These are the same holidays reflected in the [`GET /market/status`](/api-reference/market/status) `reason: holiday` response. By default only upcoming holidays (today or later) are returned. Pass `upcoming=false` to retrieve past holidays as well. ```bash curl theme={null} # Upcoming holidays (default) curl "https://api.ngnmarket.com/v1/market/holidays" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" # All holidays including past curl "https://api.ngnmarket.com/v1/market/holidays?upcoming=false" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/market/holidays', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }); const { data } = await res.json(); // data.holidays — array of { id, date, name, created_at } // data.count — total number of holidays returned ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/market/holidays', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] for h in data['holidays']: print(h['date'], h['name']) ``` Each holiday object contains the `date` in `YYYY-MM-DD` format and the `name` of the holiday. Use this list to pre-compute non-trading days in your application rather than polling the status endpoint on each day. # Market Movers Source: https://docs.ngnmarket.com/api-reference/market/movers GET /market/movers Retrieve the top gaining and losing NGX stocks for any trading date. The movers endpoint returns the biggest movers on the NGX for a given trading session — top gainers sorted by percentage gain and top losers sorted by percentage decline. Each entry includes [`logo_url`](/guides/company-logos), `market_cap`, previous close, today's closing price, absolute and percentage change, volume, value traded, and trade count. Use the `type` filter to request only `gainers` or `losers` when building separate leaderboards. For example, to fetch the top 5 gainers for a specific session: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/movers?type=gainers&limit=5&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/movers'); url.searchParams.set('type', 'gainers'); url.searchParams.set('limit', '5'); 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/movers', params={'type': 'gainers', 'limit': 5, 'date': '2026-04-17'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Sectors Source: https://docs.ngnmarket.com/api-reference/market/sectors GET /market/sectors Retrieve sector-level performance. The sectors endpoint shows you which parts of the NGX market are gaining traction and which are pulling back. For every sector it calculates the average price change across all constituent companies over three windows (one day, seven days, and 52 weeks) along with aggregate market capitalisation, value traded, total share volume, and a breadth count of advancers, decliners, and unchanged stocks. Use this data to identify rotational flows between sectors or to build sector-performance heat maps. # Market Snapshot Source: https://docs.ngnmarket.com/api-reference/market/snapshot GET /market/snapshot Retrieve the daily NGX market summary. The snapshot endpoint summarizes a single NGX trading day in one request. You get the All Share Index (ASI) level (`asi`), its absolute and percentage change, naira value traded, total deals, share volume, and a market capitalisation breakdown across equities, bonds, and ETFs. The response also includes: * `breadth`: how many securities advanced, declined, or were unchanged in that session, plus the advance/decline ratio. * `ytd_asi_change_percent`: ASI return from the first trading day of the year, useful for YTD performance widgets. * `turnover_rate`: value traded as a percentage of equity market cap, a quick liquidity signal. * `total_listed_securities`: total companies listed on NGX. * `session`: NGX trading hours (`10:00–14:30 WAT`). When no date is supplied the API returns the most recent available trading day automatically. To pull a specific historical day, pass `date` as `YYYY-MM-DD`: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/snapshot?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/snapshot'); 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/snapshot', params={'date': '2026-04-17'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` If the date is a weekend, public holiday, or any other non-trading day, the API responds with `404 NOT_FOUND`. You can confirm valid dates with [`GET /market/available-dates`](/api-reference/market/available-dates). # Market Status Source: https://docs.ngnmarket.com/api-reference/market/status GET /market/status Check whether the NGX is currently open or closed. The status endpoint tells you whether the Nigerian Exchange (NGX) is currently trading, and if not, exactly why and when it will next open. All times are computed in the **Africa/Lagos** timezone (WAT, UTC+1). The NGX trading session runs **Monday–Friday, 09:00–16:00 WAT**, excluding public holidays. ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/status" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/market/status', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }); const { data } = await res.json(); console.log(data.is_open, data.reason); ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/market/status', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] print(data['is_open'], data['reason']) ``` ### The `reason` field | Value | Meaning | | ------------- | --------------------------------------------------------------------------------------- | | `open` | The market is currently trading. | | `pre_market` | Today is a trading day but the 09:00 open has not yet occurred. | | `after_hours` | Today was a trading day; the 16:00 close has passed. | | `weekend` | Today is Saturday or Sunday. | | `holiday` | Today is a public holiday. The `holiday` object will contain the holiday name and date. | When `is_open` is `false`, the `next_open` object tells you the date, UTC timestamp, and human-readable label for the next opening. For holiday closures, the `holiday` object provides the name of the holiday. # Top Trades Source: https://docs.ngnmarket.com/api-reference/market/top-trades GET /market/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'] ``` # YTD Performers Source: https://docs.ngnmarket.com/api-reference/market/ytd-performers GET /market/ytd-performers Retrieve the best or worst performing NGX stocks year-to-date, with start price, current price, and percentage return. The YTD performers endpoint ranks NGX-listed stocks by their year-to-date return, calculated from the first available trading day of the year through to the most recent session. You can request the best performers, the worst performers, or both together. Each entry includes the year-start price and date, the current closing price, and the total percentage return for the year so far. Historical years are also supported via the `year` parameter, making this endpoint useful for annual reviews as well as live tracking. For example, to pull the 20 worst performers of 2025: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/ytd-performers?type=worst&year=2025&limit=20" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const url = new URL('https://api.ngnmarket.com/v1/market/ytd-performers'); url.searchParams.set('type', 'worst'); url.searchParams.set('year', '2025'); url.searchParams.set('limit', '20'); 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/ytd-performers', params={'type': 'worst', 'year': 2025, 'limit': 20}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] ``` # Authentication Source: https://docs.ngnmarket.com/authentication Learn how to generate an API key on NGN Market. Every request to the NGN Market API must include a valid API key in the `Authorization` header. The API validates the key on every request and returns an error immediately if it is missing, malformed, or revoked. ## Generate an API key API keys are created and managed from your [developer dashboard](https://ngnmarket.com/developer). 1. Log in at [ngnmarket.com](https://ngnmarket.com) 2. Go to **Dashboard** → **Developer** 3. Click **Generate API key**, give it a name, and confirm 4. Copy the key immediately. Your key will look like this: ``` ngm_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 ``` Copy your key before leaving the page. If you lose it, revoke it and generate a new one. ## Attach the key to requests Pass your key in the `Authorization` header using the Bearer scheme on every request: ``` Authorization: Bearer ngm_live_YOUR_KEY ``` ```bash cURL theme={null} curl https://api.ngnmarket.com/v1/market/snapshot \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/market/snapshot', { headers: { 'Authorization': 'Bearer ngm_live_YOUR_KEY' } }); const data = await res.json(); ``` ```typescript TypeScript theme={null} const res = await fetch('https://api.ngnmarket.com/v1/market/snapshot', { headers: { 'Authorization': 'Bearer ngm_live_YOUR_KEY' } }); const data: Record = await res.json(); ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/market/snapshot', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'} ) print(res.json()) ``` The [WebSocket API](/websocket/introduction) is the one exception to the header rule above. Browsers can't set a custom header on a WebSocket handshake, so it takes your key as a `?api_key=` query parameter instead. ## Managing your keys From the [developer dashboard](https://ngnmarket.com/developer), you can view all your keys (name, creation date, last used), create up to 5 active keys per account, each named so you can tell which app or environment it belongs to, and revoke a key at any time. Revoking a key invalidates it immediately, any request using a revoked key returns `INVALID_API_KEY` from that point on, and revoked keys stay visible in the dashboard for your audit trail. Create one key per app or environment (e.g. "Production", "Staging", "Local dev"). If a key is ever exposed, you can revoke just that one without affecting the others. All keys on your account share a single monthly quota pool. Quota usage is tracked per account, not per key. See [Rate limits](/rate-limits) for details. ## Authentication errors | Error code | Status | Cause | | :---------------- | :----: | :---------------------------------------------------------------- | | `MISSING_API_KEY` | 401 | `Authorization` header is missing or not in `Bearer ` format | | `INVALID_API_KEY` | 401 | Key not found, already revoked, or does not start with `ngm_` | ```json theme={null} { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API key not found or revoked." } } ``` # AI-powered blog post search Source: https://docs.ngnmarket.com/blog/ai-powered-blog-post-search get /blog/search Full-text search across all published blog posts with AI-powered query expansion via Google Gemini. A search for `Dangote` also matches posts referencing `DANGCEM`. Falls back to plain keyword matching if AI is unavailable. Results are ordered by relevance score. **Plan required:** Free # Blog post detail Source: https://docs.ngnmarket.com/blog/blog-post-detail get /blog/posts/{slug} Returns the full detail record for a single post: rich author profile, named taxonomy objects (categories, tags, and companies each with a display name and slug), and a `content.html` preview (the article's "Key Highlights" section if present, or the first 500 characters of plain text as a fallback). The full article is available at the canonical `url` on ngnmarket.com. Use slugs from any list or search response. **Plan required:** Free # Paginated blog post list Source: https://docs.ngnmarket.com/blog/paginated-blog-post-list get /blog/posts Returns a paginated list of published NGN Market blog posts sorted by publication date (newest first). Each page contains up to 20 posts. Filter the feed using any combination of `category`, `company`, and `tag` query parameters. All filters are optional and combinable (e.g. `?category=markets&company=DANGCEM`). **Plan required:** Free # NGX-listed bond instruments Source: https://docs.ngnmarket.com/bonds/ngx-listed-bond-instruments get /bonds Returns a paginated list of bonds listed on the Nigerian Exchange with ISIN, issuer, type, coupon rate, maturity date, and opening price. Filter by search term or bond type. **Plan required:** Starter # Changelog Source: https://docs.ngnmarket.com/changelog API additions, endpoint improvements, and schema changes. ## Disclosures now go back to 2014 [`GET /disclosures`](/api-reference/disclosures/list) and [`GET /companies/:symbol/disclosures`](/api-reference/companies/disclosures) used to only return filings from this year. Both now return everything NGX's own filing system has on record, back to July 2014. Nothing changed about how you call these endpoints, no new parameters and no plan restrictions. The data was just missing before. If you've cached results or built anything that assumed disclosures only went back to January, it's worth a re-fetch. ## WebSocket API You can now receive live updates over a persistent WebSocket connection instead of polling. Six channels are available: prices, market snapshot, indices, forex rates, corporate disclosures, and dividends. Prices, snapshot, indices, and forex are available on every plan, including Free. What scales by plan is how many connections you can hold open at once, and, on the prices channel, how many symbols one connection can request. WebSocket connections don't count against your monthly REST quota. See the new [WebSocket](/websocket/introduction) section for connection details, message formats for every channel, limits, and error codes. ## New financials endpoints You can now fetch individual parts of a company's financials without requesting the full financials response. [`GET /companies/:symbol/financials`](/api-reference/companies/financials) isn't changing. It still returns the income statement, balance sheet, cash flow, and ratios together in one request. If you only need one of those datasets, there are now six more focused endpoints: * [`GET /companies/:symbol/financials/income`](/api-reference/companies/financials-income) returns the income statement. * [`GET /companies/:symbol/financials/balance-sheet`](/api-reference/companies/financials-balance-sheet) returns the balance sheet. * [`GET /companies/:symbol/financials/cash-flow`](/api-reference/companies/financials-cash-flow) returns the cash flow statement. * [`GET /companies/:symbol/financials/ratios`](/api-reference/companies/financials-ratios) returns pre-calculated financial ratios. * [`GET /companies/:symbol/financials/ttm`](/api-reference/companies/financials-ttm) returns trailing twelve-month figures calculated from four consecutive discrete quarters. * [`GET /companies/:symbol/financials/growth`](/api-reference/companies/financials-growth) returns period-over-period growth rates. It compares year over year by default, or sequentially when you pass `compare=sequential`. So if your app only needs ratios or a cash flow statement, you can request that directly and skip the rest of the financials payload. Plan requirements for each endpoint are listed on [Plans](/plans). ## Historical data depth now depends on your plan How far back you can query chart and history endpoints now depends on your plan. Hobby accounts can request up to 2 years of historical data. Starter accounts get up to 5 years. Pro and higher can access the full available history with no plan-based cutoff. These limits apply to company charts, forex history, index charts, ETF charts, and dividend history. If you request a range that goes further back than your plan allows, the API won't reject the request. It'll start from the earliest date available to your plan and return the data from there. Responses now also include `start_date` and `end_date`, so you can see the exact date range that came back. If you were already a paying customer before August 12, 2026, your existing historical access stays unchanged for four months from launch. The new limits apply immediately to new signups and will apply to existing paid accounts once that four-month period ends. See [Historical data depth](/plans#historical-data-depth) for the full breakdown. ## Pro replaces Growth We've retired the Growth plan and replaced it with Pro. Pro costs ₦100,000/month and includes 250,000 API calls per month with a rate limit of 120 requests per minute. If you're already on Growth, you'll be moved to Pro automatically at the new price. You don't need to make any changes to your account. [`GET /market/breadth`](/api-reference/market/breadth), [`GET /market/sectors`](/api-reference/market/sectors), and [`GET /market/ytd-performers`](/api-reference/market/ytd-performers) now require Pro or higher. These endpoints previously required Growth. See [Plans](/plans) for the full plan comparison. ## Dividend history backfilled for several tickers [`GET /companies/:symbol/dividends`](/api-reference/companies/dividends) was returning little or no data for a number of tickers, including SEPLAT, NESTLE, ZENITHBANK, and AIRTELAFRI, even though other symbols on the same endpoint already went back years. These are all backfilled now, most going back well over a decade. ## AI agent support If you're using an AI coding agent with the NGN Market API, you can now install a skill that gives it the API context it needs before it starts working. The skill is available at [`docs.ngnmarket.com/skill.md`](https://docs.ngnmarket.com/skill.md) and works with Claude Code, Cursor, Windsurf, and other agents that support skills. Once installed, the agent knows the API base URL, authentication format, plan tiers, and which endpoints to use for common tasks. For example, it can map a request for a live price ticker, candlestick chart, currency converter, or dividend calendar to the right endpoint and method. [Install the agent skill](/install-skill) covers the CLI install with `npx skills add -g`, along with manual installation for Claude Code, Cursor, Windsurf, and agents using the shared `.agents/skills/` convention. There's also an [Agent quickstart](/agent-quickstart) if you want to use it on an existing project. The quickstart includes a copyable prompt that installs the skill and checks your repository for hardcoded NGX prices, stale forex rates, and manually maintained company or dividend data. It then suggests which API endpoints you can use instead. It waits for your approval before changing any files. ## ETF endpoints You can now access NGX-listed ETFs and ETPs through three dedicated endpoints: one for the full list, one for individual fund details, and one for historical prices. ### GET /etfs Available on **all plans**, including Free. [`GET /etfs`](/api-reference/etfs/list) returns a snapshot of all 12 ETFs and ETPs listed on the NGX. For each fund, you'll get its current price, daily change, 7-day, YTD, and 52-week performance, today's volume and naira value traded, average 3-month volume, fund manager, and benchmark index. You can paginate the results, search by fund name, ticker, or fund manager, and sort by any numeric field. ### GET /etfs/:symbol Requires a **Starter plan** or higher. Use [`GET /etfs/:symbol`](/api-reference/etfs/detail) when you need the full details for one ETF. For example: ``` GET /etfs/STANBICETF30 ``` The response includes the current OHLCV snapshot and 52-week range, along with the ISIN, fund manager, index tracked, fund sponsor, trustee, custodian, liquidity provider, and website. It also includes period change percentages and average 3-month volume. ### GET /etfs/:symbol/chart Requires a **Starter plan** or higher. [`GET /etfs/:symbol/chart`](/api-reference/etfs/chart) returns daily price history for an ETF. For example: ``` GET /etfs/STANBICETF30/chart ``` Use `period` for one of the predefined ranges: `7d`, `30d`, `90d`, `1y`, `5y`, or `all`. If you need an exact range, pass `from` and `to` instead. For a compact chart response, `format=chart` returns `[date, price]` pairs. `format=detailed` returns full OHLCV rows and a `normalized_value` for each date. The normalized value rebases the ETF price to 100 at the beginning of the requested period, which makes it easier to compare performance between funds. The `statistics` block also includes `return_1m`, `return_3m`, `return_1y`, and `return_ytd`. These use fixed reference points regardless of the period you request. ## More data from existing endpoints A number of existing endpoints now return more of the data you'd otherwise have to calculate or fetch separately. ### Company charts now return full OHLCV data [`GET /companies/:symbol/chart`](/api-reference/companies/chart) used to return only the closing price for each day. It now returns the full daily candle: `open`, `high`, `low`, `close`, `volume`, `value_traded`, `vwap`, `trade_count`, `change`, and `change_percent`. If you're already using `price`, you don't need to change anything. The field remains available as an alias for `close`. There's also a new `format=ohlcv` option that returns each candle as: ```json theme={null} [timestamp, open, high, low, close, volume] ``` This format can be used directly with charting libraries such as Apache ECharts, ApexCharts, Highcharts, and Plotly. ### Market snapshot now includes breadth data [`GET /market/snapshot`](/api-reference/market/snapshot) now gives you a broader view of the trading session. The response includes advances, declines, unchanged count, the advance/decline ratio, YTD ASI return, turnover rate, total listed securities, and NGX session open and close times. ### Company profiles now include more valuation ratios [`GET /companies/:symbol`](/api-reference/companies/detail) now includes `pb_ratio`, `debt_to_equity`, `current_ratio`, and `dividend_yield`. They're calculated from the latest available financial statements. If there isn't enough financial data to calculate one of the values, that field returns `null`. ### Movers and top trades now include logos and market cap [`GET /market/movers`](/api-reference/market/movers) and [`GET /market/top-trades`](/api-reference/market/top-trades) now include `logo_url` and `market_cap` for each entry. ### Forex responses now include the inverse rate [`GET /forex/current`](/api-reference/forex/current) now returns `inverse_rate` for each currency. The regular rate tells you how many naira one unit of a foreign currency is worth. `inverse_rate` gives you the other side of that conversion: how much foreign currency ₦1 buys. ### Index charts now include period returns and normalized values [`GET /indices/:symbol/chart`](/api-reference/indices/chart) now includes `return_1m`, `return_3m`, `return_1y`, and `return_ytd` in the `statistics` block. When you use `format=detailed`, each data point also includes `normalized_value`. This rebases the index to 100 at the start of the requested period. If you're comparing indices with very different absolute values, you can use the normalized values to plot them on the same scale and compare their relative performance. # All NGX ticker symbols Source: https://docs.ngnmarket.com/companies/all-ngx-ticker-symbols get /companies/identifiers Returns every company listed on the NGX in a single lightweight response with no pagination. Each entry includes the ticker symbol, company name, and international securities identifier (ISIN). Ideal for populating dropdowns or building lookup tables. **Plan required:** Free # Browse NGX-listed companies Source: https://docs.ngnmarket.com/companies/browse-ngx-listed-companies get /companies Returns a paginated, filterable list of all NGX-listed companies with current price data. Filter by sector, search by name or ticker, sort by market cap, price, or other fields, and apply market-cap range filters. Price fields (`current_price`, `price_change`, `volume`, etc.) reflect the most recent intraday data. Prices are refreshed **every 20 minutes during NGX trading hours (Monday–Friday, 09:00–16:00 WAT)**. Outside trading hours, values reflect the most recent session close. **Plan required:** Free # Company news by ticker symbol Source: https://docs.ngnmarket.com/companies/company-news-by-ticker-symbol get /companies/{symbol}/news Returns recent news articles for a specific company identified by its NGX ticker symbol. Articles are sourced in real time from Nigerian financial outlets. Older articles are excluded based on the `maxAge` parameter. **Plan required:** Starter # Disclosures by company Source: https://docs.ngnmarket.com/companies/disclosures-by-company get /companies/{symbol}/disclosures Returns corporate disclosures for a specific NGX-listed company. Equivalent to `GET /disclosures?symbol={symbol}` but scoped to a single company. **Plan required:** Free # Financial statements Source: https://docs.ngnmarket.com/companies/financial-statements get /companies/{symbol}/financials Returns the complete set of financial statements filed by a company (income statement, balance sheet, cash flow statement, and computed financial ratios) for every reporting period available. Results are ordered from most recent to oldest. **Plan required:** Business # Full company profile Source: https://docs.ngnmarket.com/companies/full-company-profile get /companies/{symbol} Returns everything you need to build a comprehensive company page: current price data, 52-week range, market cap, trailing EPS, sector and sub-sector classification, contact details, and a business description. The ticker symbol lookup is case-insensitive. Price data is refreshed **every 20 minutes during NGX trading hours (Monday–Friday, 09:00–16:00 WAT)**. The `last_updated` field in the response indicates exactly when the price was last written. Outside trading hours, values reflect the most recent session close. **Plan required:** Hobby The path is `/v1/companies/:symbol`, not `/v1/stocks/:symbol`. The website URL `ngnmarket.com/stocks/SYMBOL` is a frontend route — the API uses a different path. # Historical price series Source: https://docs.ngnmarket.com/companies/historical-price-series get /companies/{symbol}/chart Returns the complete OHLCV (open, high, low, close, volume) history for a company sourced from daily exchange data. Each data point includes a Unix timestamp, calendar date, and full OHLCV fields plus VWAP, trade count, and daily change. Use `format=chart` for compact `[timestamp, close]` pairs or `format=ohlcv` for candlestick-ready `[timestamp, open, high, low, close, volume]` arrays. **Plan required:** Hobby # Corporate disclosures feed Source: https://docs.ngnmarket.com/disclosures/corporate-disclosures-feed get /disclosures Paginated feed of official corporate filings from NGX-listed companies, sorted newest first. Covers financial statements, AGM notices, board meetings, director dealings, earnings forecasts, and more. Use `/disclosures/types` to get valid `type` filter values with counts. **Plan required:** Free # Disclosure submission types Source: https://docs.ngnmarket.com/disclosures/disclosure-submission-types get /disclosures/types Returns all submission types present in the database with their document counts. Use the `type` values as the `type` filter on `GET /disclosures`. **Plan required:** Free # Errors Source: https://docs.ngnmarket.com/errors All NGN Market API error codes & their HTTP status, and how to fix them. When a request fails, the response sets `success` to `false` and returns an `error` object with a machine-readable `code` and a human-readable `message`. All error responses follow the same envelope described in [Response format](/response-format). This page covers REST errors. [WebSocket](/websocket/introduction) handshakes reuse `MISSING_API_KEY`, `INVALID_API_KEY`, `IP_NOT_ALLOWED`, and `PLAN_REQUIRED` below, plus four codes specific to WebSocket connections. See [WebSocket errors](/websocket/errors). ## Error code reference | Error code | Status | Meaning | | :---------------- | :----: | :--------------------------------------------- | | `MISSING_API_KEY` | 401 | `Authorization` header is missing or malformed | | `INVALID_API_KEY` | 401 | API key not found or has been revoked | | `PLAN_REQUIRED` | 403 | Endpoint requires a higher-tier plan | | `IP_NOT_ALLOWED` | 403 | Request IP is not in this key's allowlist | | `RATE_LIMITED` | 429 | Per-minute request limit exceeded | | `QUOTA_EXCEEDED` | 429 | Monthly call limit reached | | `NOT_FOUND` | 404 | Route or resource does not exist | | `SERVER_ERROR` | 500 | Unexpected error on the server | ## Troubleshooting **What it means:** Your request did not include an `Authorization` header, so the API cannot identify your account. **How to fix it:** Add your API key to every request using the `Authorization` header with the `Bearer` scheme: ```bash theme={null} curl https://api.ngnmarket.com/v1/market/snapshot \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` All endpoints except `/health` require authentication. If you are using an HTTP client or library, check that it is not stripping the `Authorization` header on redirects. Some clients drop headers by default when following a 301 or 302 response. **What it means:** The key in your `Authorization` header was not recognised. This happens when the key does not exist, has been deleted, or has been revoked. **How to fix it:** 1. Open your [developer dashboard](https://ngnmarket.com/developer) and confirm the key is still active. 2. Copy the key value directly from the dashboard to rule out a typo or truncation. 3. Check that you are using the full key, including the `ngm_live_` prefix. 4. If you recently rotated or deleted a key, update all integrations that used the old one. If your key appears valid in the dashboard but still returns this error, contact [support](https://ngnmarket.com/contact). **What it means:** The endpoint you called requires a higher plan than your current one. The error response includes `required_plan` and `current_plan` so you know exactly what is needed: ```json theme={null} { "success": false, "error": { "code": "PLAN_REQUIRED", "message": "This endpoint requires a starter plan or higher.", "required_plan": "starter", "current_plan": "free" } } ``` **How to fix it:** * Check the [Plans](/plans) page to see which endpoints each tier unlocks. * Upgrade to at least the plan named in `required_plan` from your [developer dashboard](https://ngnmarket.com/developer). * If you think you are already on the required plan, confirm your plan tier in the dashboard. **What it means:** Your API key has an IP allowlist configured and the request came from an IP address not on that list. This is an opt-in security feature. Keys with no allowlist entries accept requests from any IP. ```json theme={null} { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "This API key is restricted to specific IP addresses. Check your allowlist in the developer dashboard." } } ``` **How to fix it:** 1. Open your [developer dashboard](https://ngnmarket.com/developer) and navigate to the key that returned this error. 2. Check the IP allowlist configured for that key. 3. Add your current IP address (or CIDR range) to the allowlist, or remove the allowlist entries entirely to allow all IPs. 4. If you are behind a load balancer or proxy, the IP seen by the API may differ from your machine's IP. Check the `X-Forwarded-For` header your proxy sends. **What it means:** Your account has exceeded the per-minute request limit for your plan. This is distinct from `QUOTA_EXCEEDED`, which applies to the monthly call quota. Per-minute limits reset automatically after 60 seconds. ```json theme={null} { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down and try again." } } ``` **How to fix it:** * Wait 60 seconds and retry the request. * Reduce the rate at which your application sends requests to stay within your plan's per-minute cap. See [Rate Limits](/rate-limits) for the limits per plan. * If you consistently hit this limit, consider upgrading to a higher plan. **What it means:** Your account has used all of its monthly API calls. No further requests will succeed until your quota resets or you upgrade. This error includes a `meta` object so you can confirm the reset date: ```json theme={null} { "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" } } ``` **How to fix it:** * **Wait for the reset.** Your quota resets on the 1st of the next month at midnight UTC. The exact time is in `meta.reset_at`. * **Upgrade your plan.** Log in to your [developer dashboard](https://ngnmarket.com/developer) and select a higher plan. Upgrades take effect immediately. See [Plans](/plans) for limits and pricing. To avoid this in future, monitor `meta.calls_remaining` and reduce usage or upgrade before you hit zero. **What it means:** The URL path you requested does not match any route on the API. **How to fix it:** 1. Check the [API Reference](/api-reference/introduction) to confirm the correct path and HTTP method. 2. Make sure any path parameters like `:symbol` are substituted correctly, for example `/companies/DANGCEM` not `/companies/:symbol`. 3. Confirm you are using the correct base URL: `https://api.ngnmarket.com/v1`. 4. Check for trailing slashes or typos. Paths are case-sensitive. **What it means:** An unexpected error occurred on the NGN Market servers. This is not caused by your request and does not count against your quota. **How to fix it:** 1. Retry the request after a short delay. Most server errors are transient. 2. If the error persists for several minutes, check the [NGN Market status page](https://ngnmarket.com/status) for any active incidents. 3. If you can reliably reproduce the error, report it to [support](https://ngnmarket.com/contact) with the endpoint, request details, and approximate time of the failure. ## Frequently asked questions It depends on the error. Requests that fail authentication (`MISSING_API_KEY` or `INVALID_API_KEY`) and requests blocked by rate limits (`RATE_LIMITED` or `QUOTA_EXCEEDED`) do not count against your monthly quota. Requests that pass authentication and quota checks but return `PLAN_REQUIRED`, `NOT_FOUND`, or `SERVER_ERROR` are counted because they were already validated. The API does not send proactive notifications, but you can build your own alerting by reading `meta.calls_remaining` in every response. When it falls below a threshold you define, trigger an alert in your application or monitoring system. Confirm the header is formatted exactly as `Authorization: Bearer ngm_live_YOUR_KEY` with a single space after `Bearer`. Some HTTP clients modify or strip headers. Log the outgoing request headers to verify they are sent correctly, and check that no whitespace or newline characters were introduced when copying the key. # Plot the All Share Index Source: https://docs.ngnmarket.com/examples/asi-chart Fetch NGX All Share Index history and render it as a price chart. The ASI (All Share Index) is the NGX benchmark index. This example fetches the last 90 days of daily values in chart-friendly `[timestamp, value]` format, ready to drop into any charting library like Chart.js, Recharts, or Highcharts. **Endpoint:** `GET /indices/ASI/chart` (Hobby plan) This example only requests 90 days, well within reach of every plan. If you swap in a longer `from`/`to` range, remember history depth is capped by plan (Hobby gets 2 years, Starter gets 5), and the response gets clamped to what your plan allows rather than erroring. See [Historical data depth](/plans#historical-data-depth). ## Fetch 90-day ASI history ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/indices/ASI/chart?period=90d&format=chart" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/indices/ASI/chart?period=90d&format=chart', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.data is an array of [timestamp, value] pairs const chartPoints = data.data; // e.g. [[1744848000000, 105432.18], [1744761600000, 104555.74], ...] ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/indices/ASI/chart', params={'period': '90d', 'format': 'chart'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) chart_points = res.json()['data']['data'] # [[1744848000000, 105432.18], [1744761600000, 104555.74], ...] ``` ## Sample response ```json theme={null} { "success": true, "data": { "symbol": "ASI", "period": "90d", "format": "chart", "count": 63, "data": [ [1736208000000, 101847.29], [1736294400000, 102310.54], [1744848000000, 105432.18] ], "statistics": { "period_change": 3584.89, "period_change_percent": 3.52, "min_value": 101847.29, "max_value": 105432.18, "start_date": "2026-01-07", "end_date": "2026-04-17" } }, "meta": { "plan": "starter", "calls_used": 14, "calls_remaining": 99986, "reset_at": "2026-05-01T00:00:00.000Z" } } ``` ## Use a custom date range Swap `period` for `from` and `to` if you need a specific window: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/indices/ASI/chart?from=2026-01-01&to=2026-03-31&format=chart" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ## Need full OHLCV detail? Drop `format=chart` and use `format=detailed` instead. Each point then includes `date`, `value`, `change`, and `change_percent` fields individually. Full parameter list for `GET /indices/:symbol/chart` # Get a Company Profile and Price Chart Source: https://docs.ngnmarket.com/examples/company-profile Look up a company's full profile, current price, and 30-day price history in two requests. This example fetches the full profile for Dangote Cement (DANGCEM), including sector, market cap, 52-week range, and current price, alongside a 30-day price history. You can substitute any NGX ticker symbol. **Endpoints used:** * `GET /companies/:symbol` (Hobby plan) * `GET /companies/:symbol/chart` (Hobby plan, capped to 2 years of history on that plan) ## Step 1: Fetch the company profile ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/DANGCEM" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/companies/DANGCEM', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.current_price, data.market_cap, data.sector, etc. ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/companies/DANGCEM', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) profile = res.json()['data'] ``` ### Sample response (trimmed) ```json theme={null} { "success": true, "data": { "symbol": "DANGCEM", "company_name": "Dangote Cement Plc", "sector": "Industrial Goods", "current_price": 302.50, "price_change": 4.00, "price_change_percent": 1.34, "market_cap": 5150820750000, "week_52_high": 325.00, "week_52_low": 241.00, "listing_date": "2010-10-26", "isin": "NGDANGCEM006" } } ``` ## Step 2: Fetch the 30-day price chart ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/companies/DANGCEM/chart?period=30d" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/companies/DANGCEM/chart?period=30d', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.data → array of daily price points ``` ```python Python theme={null} res = requests.get( 'https://api.ngnmarket.com/v1/companies/DANGCEM/chart', params={'period': '30d'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) chart = res.json()['data']['data'] ``` ### Sample response (trimmed) ```json theme={null} { "success": true, "data": { "symbol": "DANGCEM", "period": "30d", "count": 22, "data": [ { "date": "2026-04-17", "close_price": 302.50, "change": 4.00, "change_percent": 1.34 }, { "date": "2026-04-16", "close_price": 298.50, "change": -1.50, "change_percent": -0.50 } ], "statistics": { "period_change": 18.50, "period_change_percent": 6.52, "min_price": 278.00, "max_price": 305.00 } } } ``` ## Fetch both calls in parallel In JavaScript you can fire both requests simultaneously: ```javascript JavaScript theme={null} const [profileRes, chartRes] = await Promise.all([ fetch('https://api.ngnmarket.com/v1/companies/DANGCEM', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }), fetch('https://api.ngnmarket.com/v1/companies/DANGCEM/chart?period=30d', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' }, }), ]); const [{ data: profile }, { data: chart }] = await Promise.all([ profileRes.json(), chartRes.json(), ]); ``` All fields returned by `GET /companies/:symbol` Parameters for `GET /companies/:symbol/chart` # Get Forex Rates Source: https://docs.ngnmarket.com/examples/forex-rates Fetch the current USD/NGN rate and 30-day exchange rate history. This example fetches the latest NGN exchange rates against all supported currencies, then drills into the USD/NGN pair for a 30-day history suitable for charting. **Endpoints used:** * `GET /forex/current` (Free plan) * `GET /forex/history` (Hobby plan) ## Fetch current rates Returns live NGN rates against all supported currencies in a single call. ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/forex/current" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/forex/current', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.rates → { USD: 1580.25, GBP: 2012.40, EUR: 1720.60, ... } ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/forex/current', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) rates = res.json()['data']['rates'] usd_rate = rates['USD'] ``` ### Sample response ```json theme={null} { "success": true, "data": { "base": "NGN", "updated_at": "2026-04-17T16:00:00.000Z", "rates": { "USD": 1580.25, "GBP": 2012.40, "EUR": 1720.60, "CAD": 1148.30, "AUD": 1022.15, "GHS": 98.40, "ZAR": 84.70, "CNY": 218.90, "JPY": 10.52, "SAR": 421.10 } }, "meta": { "plan": "free", "calls_used": 5, "calls_remaining": 9995, "reset_at": "2026-05-01T00:00:00.000Z" } } ``` ## Fetch 30-day USD/NGN history Useful for rendering a rate trend chart or calculating how much the naira has moved against the dollar. ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/forex/history?source=USD&target=NGN&period=30d&format=simple" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/forex/history?source=USD&target=NGN&period=30d&format=simple', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.data → [{ date: "2026-04-17", rate: 1580.25 }, ...] ``` ```python Python theme={null} res = requests.get( 'https://api.ngnmarket.com/v1/forex/history', params={'source': 'USD', 'target': 'NGN', 'period': '30d', 'format': 'simple'}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) history = res.json()['data']['data'] # [{'date': '2026-04-17', 'rate': 1580.25}, ...] ``` ### Sample response (trimmed) ```json theme={null} { "success": true, "data": { "source": "USD", "target": "NGN", "period": "30d", "count": 30, "data": [ { "date": "2026-04-17", "rate": 1580.25 }, { "date": "2026-04-16", "rate": 1577.80 }, { "date": "2026-04-15", "rate": 1582.10 } ] } } ``` ## Supported currencies `USD` `EUR` `GBP` `CAD` `AUD` `GHS` `ZAR` `CNY` `JPY` `SAR` `NGN` Pass `source` and `target` in any direction. For example, `source=NGN&target=USD` gives you the inverse rate. `GET /forex/current` parameters `GET /forex/history` parameters # Get a Sector Performance Snapshot Source: https://docs.ngnmarket.com/examples/sector-snapshot Fetch NGX sector-level performance data to identify which parts of the market are moving. The sectors endpoint aggregates price performance across all companies in each NGX sector, giving you a single call that shows which sectors are leading or lagging the market. **Endpoint:** `GET /market/sectors` (Pro plan) ## Fetch all sectors ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/sectors" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/market/sectors', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.sectors → sorted by 1-day change descending // data.summary.top_sector_1d → name of the best-performing sector today ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/market/sectors', headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] sectors = data['sectors'] top_today = data['summary']['top_sector_1d'] ``` ### Sample response (trimmed) ```json theme={null} { "success": true, "data": { "summary": { "top_sector_1d": "Oil & Gas", "top_sector_7d": "Banking" }, "sectors": [ { "sector": "Oil & Gas", "company_count": 8, "total_market_cap": 4829104730200, "total_value_traded": 821093847, "total_volume": 48291030, "change_1d": 2.10, "change_7d": 5.40, "change_52w": 31.20, "breadth": { "advancers": 6, "decliners": 1, "unchanged": 1 } }, { "sector": "Banking", "company_count": 14, "total_market_cap": 7102948201000, "total_value_traded": 1204817293, "total_volume": 102847291, "change_1d": 0.84, "change_7d": 6.10, "change_52w": 44.70, "breadth": { "advancers": 9, "decliners": 3, "unchanged": 2 } } ] } } ``` ## Sort or filter in your code The response is already sorted by `change_1d` descending. If you want a different sort (by 52-week performance or market cap, for example) do it client-side: ```javascript JavaScript theme={null} // Top sectors by 52-week change const byYearly = [...data.sectors].sort((a, b) => b.change_52w - a.change_52w); // Sectors where more stocks declined than advanced (bearish breadth) const bearish = data.sectors.filter( (s) => s.breadth.decliners > s.breadth.advancers ); ``` Full response schema for `GET /market/sectors` # Get Today's Top Movers Source: https://docs.ngnmarket.com/examples/top-movers Fetch the biggest gainers and losers on the NGX for the latest trading session. This example fetches the top 10 gainers and losers for the most recent NGX trading session. Useful for building a daily market summary widget or a leaderboard. **Endpoint:** `GET /market/movers` (Starter plan) ## Fetch gainers and losers Omitting `type` returns both gainers and losers in a single response. ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/movers?limit=10" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ```javascript JavaScript theme={null} const res = await fetch( 'https://api.ngnmarket.com/v1/market/movers?limit=10', { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data } = await res.json(); // data.top_gainers, data.top_losers, data.summary ``` ```python Python theme={null} import requests res = requests.get( 'https://api.ngnmarket.com/v1/market/movers', params={'limit': 10}, headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'}, ) data = res.json()['data'] gainers = data['top_gainers'] losers = data['top_losers'] ``` ### Sample response (trimmed) ```json theme={null} { "success": true, "data": { "trade_date": "2026-04-17", "summary": { "total_gainers": 10, "total_losers": 10, "biggest_gainer": { "symbol": "OKOMUOIL", "change_percent": 9.94 }, "biggest_loser": { "symbol": "TRANSCORP", "change_percent": -9.80 } }, "top_gainers": [ { "symbol": "OKOMUOIL", "company_name": "Okomu Oil Palm", "sector": "Agriculture", "last_close": 364.50, "todays_close": 400.70, "change": 36.20, "change_percent": 9.94, "volume": 287340, "value_traded": 115073718 } ], "top_losers": [ { "symbol": "TRANSCORP", "company_name": "Transnational Corporation", "sector": "Conglomerates", "last_close": 10.20, "todays_close": 9.20, "change": -1.00, "change_percent": -9.80, "volume": 1820450, "value_traded": 16748140 } ] } } ``` ## Fetch only gainers or only losers Pass `type=gainers` or `type=losers` if you only need one side: ```bash curl theme={null} curl "https://api.ngnmarket.com/v1/market/movers?type=gainers&limit=5" \ -H "Authorization: Bearer ngm_live_YOUR_KEY" ``` ## Look up a mover's full profile Once you have a symbol from the movers list, fetch the full company profile: ```javascript JavaScript theme={null} const symbol = data.top_gainers[0].symbol; // e.g. "OKOMUOIL" const profileRes = await fetch( `https://api.ngnmarket.com/v1/companies/${symbol}`, { headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' } } ); const { data: profile } = await profileRes.json(); ``` Full parameter list for `GET /market/movers` # Year-to-Date Best and Worst Performers Source: https://docs.ngnmarket.com/examples/ytd-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` (Pro plan) ## Fetch the top 10 YTD gainers ```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'] ``` ### 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" ``` Full parameter list for `GET /market/ytd-performers` # Historical NGN forex rates Source: https://docs.ngnmarket.com/forex/historical-ngn-forex-rates get /forex/history Returns historical exchange rate data between NGN and any supported currency pair. Narrow results by currency code, date range, and record count. How far back you can query is capped by plan: Hobby gets 2 years of history, Starter gets 5 years, Pro and above get full history. A `from` date outside your plan's allowance is clamped to the earliest date you're entitled to rather than erroring, check `start_date` in the response to see what was actually returned. **Plan required:** Hobby This endpoint is `/v1/forex/history`, not `/v1/forex/rates`. For current rates, see [Live NGN exchange rates](/api-reference/forex/current). # Live NGN exchange rates Source: https://docs.ngnmarket.com/forex/live-ngn-exchange-rates get /forex/current Returns the most recent NGN exchange rates for all supported currencies. Each rate expresses how much of the foreign currency one Nigerian Naira buys (e.g. a USD rate of `0.000623` means ₦1 = $0.000623). **Plan required:** Free # Build a Candlestick Chart Source: https://docs.ngnmarket.com/guides/candlestick-chart Fetch OHLCV data from the NGN Market API and render a professional candlestick chart. The demo above is what you'll have by the end of this guide. It's built with [Apache ECharts](https://echarts.apache.org/) and the NGN Market API's `format=ohlcv` option, which returns data in exactly the shape charting libraries expect. **Endpoint used:** * [`GET /companies/{symbol}/chart`](/api-reference/companies/chart) (Hobby plan) ## Live demo