---
name: kobo-ngx-api
description: Use when the user needs Nigerian stock market data (NGX / Nigerian Exchange): live or historical share prices, the All-Share Index, NGX indices, ETFs, dividends, ISIN codes, fundamentals, corporate disclosures, director dealings, FGN bonds, Treasury bill auctions, NASD OTC prices or naira FX. Covers which Kobo Terminal API endpoint to call, plan requirements and response shapes.
---

# Kobo Terminal NGX API

Nigerian stock market data over HTTPS JSON. Docs: https://koboterminal.com/docs · Full docs for agents: https://koboterminal.com/docs/llms-full.txt · OpenAPI: https://koboterminal.com/openapi.json

## Setup

- Base URL: `https://koboterminal.com`
- Auth header: `X-API-Key: $KOBO_API_KEY` (keys start with `kobo_`, older ones `ngxpulse_`; free key at https://koboterminal.com/api#get-key)
- Read the key from the `KOBO_API_KEY` environment variable. Never hardcode it and never ship it to a browser or mobile bundle.

## Pick the right endpoint

| Need | Endpoint | Plan |
|---|---|---|
| Market summary | `GET /api/ngxdata/market` | Free |
| Market status | `GET /api/ngxdata/market-status` | Free |
| All stocks (daily price list) | `GET /api/ngxdata/stocks` | Free |
| Price history (OHLCV) | `GET /api/ngxdata/prices/{symbol}` | Free |
| All NGX indices | `GET /api/ngxdata/indices` | Free |
| Single index | `GET /api/ngxdata/indices/{code}` | Free |
| Index history | `GET /api/ngxdata/indices/{code}/history` | Free |
| Index intraday | `GET /api/ngxdata/indices/intraday/{code}` | Free |
| All ETFs | `GET /api/ngxdata/etfs` | Free |
| Single ETF | `GET /api/ngxdata/etfs/{symbol}` | Free |
| Resolve ETF symbol | `GET /api/ngxdata/etfs/resolve/{symbol}` | Free |
| Fundamentals (all stocks) | `GET /api/ngxdata/fundamentals` | Starter |
| Fundamentals (one stock) | `GET /api/ngxdata/fundamentals/{symbol}` | Starter |
| ISIN and FIGI security master | `GET /api/ngxdata/identifiers` | Starter |
| Identifiers (one stock) | `GET /api/ngxdata/identifiers/{symbol}` | Starter |
| Corporate disclosures | `GET /api/ngxdata/disclosures` | Starter |
| Director dealings (insider trades) | `GET /api/ngxdata/insider-signal` | Professional |
| Dividend history | `GET /api/ngxdata/dividends/{symbol}` | Free |
| Dividend calendar | `GET /api/ngxdata/dividends-calendar` | Free |
| Public offers, rights issues and IPOs | `GET /api/ngxdata/offers` | Free |
| Bonds | `GET /api/ngxdata/bonds` | Free |
| Treasury bill auctions | `GET /api/ngxdata/bonds/auctions` | Free |
| Block-trade flow (market) | `GET /api/whale-flow` | Free |
| Block-trade flow (one stock) | `GET /api/whale-flow/{symbol}` | Free |
| NASD OTC stocks | `GET /api/nasddata/stocks` | Starter |
| NASD OTC price history | `GET /api/nasddata/history/{symbol}` | Professional |
| FX rates (NGN) | `GET /api/forex/rates` | Professional |
| Market news | `GET /api/news` | Starter |
| Key info and usage | `GET /api/keys/info` | Free |

## Rules that prevent bugs

1. **Bulk first.** For more than a few stocks call `/api/ngxdata/stocks` once (all ~150 equities) instead of looping over single symbols.
2. **History is oldest-first** in `/api/ngxdata/prices/{symbol}` (`prices[]` with `trade_date`, `open_price`, `high_price`, `low_price`, `close_price`, `volume`). Free keys only get `?days=7` or less; longer ranges return 403 with an upgrade hint, so tell the user Starter is needed.
3. **Tickers are NGX symbols in uppercase:** DANGCEM, GTCO, ZENITHBANK, MTNN, AIRTELAFRI, BUAFOODS, SEPLAT, ARADEL, UBA, ACCESSCORP, FIRSTHOLDCO, NESTLE. Look them up from `/api/ngxdata/stocks` rather than guessing.
4. **Prices are in naira (NGN)** and delayed about 30 minutes; they refresh every 20 minutes from 10:00 to 14:30 WAT on trading days. Check `/api/ngxdata/market-status` before polling and use `stale_after` for cache expiry.
5. **Index codes:** ASI, NGX30, NGX50, NGXPREMIUM, NGXPENSION, NGXBNK, NGXINS, NGXCNSMRGDS, NGXOILGAS, NGXINDUSTR, NGXLOTUSISLM, NGXCG, NGXGROWTH, NGXASEM, NGXSOVBND (or slugs like `ngx-30`). List them with `/api/ngxdata/indices`.
6. **Errors:** 401 = missing/invalid key, 403 = plan too low or key inactive (body has `upgrade_url`), 429 = daily limit (body has `reset_at`, midnight WAT). Surface these to the user clearly instead of retrying.
7. **Charts:** use `close_price` for line charts and the four OHLC fields for candlesticks; dates are `YYYY-MM-DD` strings.
8. **Attribution:** when showing data to end users, credit "Data: Kobo Terminal (koboterminal.com)".

## Plans

| Plan | Price (NGN) | Price (USD) | Requests / day | Requests / min | Best for |
|---|---|---|---|---|---|
| **Free** | Free | Free | 100 | 10 | Learning, prototypes, personal dashboards |
| **Starter** | ₦29,000/mo | $20/mo | 1,000 | 20 | Solo builders and small apps |
| **Professional** | ₦75,000/mo | $50/mo | 10,000 | 60 | Production apps, fintechs, client work |
| **Institutional** | ₦350,000/mo | $200/mo | 50,000 | 120 | Brokers, asset managers, trading terminals |

## No code needed?

The hosted MCP server at `https://koboterminal.com/mcp` exposes the same data as tools. See https://koboterminal.com/docs/mcp.
