# Stocks

> Delayed and historical price data for equities and ETFs across supported African exchanges — quotes, charts, news pulse, company fundamentals, canonical tickers, and curated market intelligence. All read-only and data-key safe.

Delayed and historical price data for equities and ETFs across all supported African exchanges.
`GET /stocks` returns equity data; `GET /etfs` mirrors the same shape for ETFs. All price endpoints
accept exchange-qualified symbols (`SCOM.KE`) and bare tickers (`SCOM`) when unambiguous.

<Callout type="info">
  Examples use the production base. Swap `/api/v1/partner` for `/api/sandbox/v1/partner` (and an
  `sk_sandbox_` key) to run any of them against the sandbox. Both environments read the same
  exchange-supplied, 15-minute-delayed feed. The API refresh target is 900 seconds; inspect `asOf`
  and `stale` on every quote and never label the price real-time.
</Callout>

## List stocks

<MethodTag m="GET" /> `/stocks`

Returns a cursor-paginated catalogue of tradeable equities. Follow `nextCursor` while `hasMore` is
`true`; narrow the catalogue with the filters below.

<ParamTable fields={[
  { name: 'exchange',  type: 'string', desc: 'Filter by exchange code: NSE, NGX, JSE, GSE, BRVM, ZSE, BSE, LUSE, EGX, DSE, USE, MSE, CSE, SEM.' },
  { name: 'sector',    type: 'string', desc: 'Filter by sector name (e.g. Banking, Telecommunications).' },
  { name: 'assetType', type: 'string', desc: 'STOCK or ETF.' },
  { name: 'search',    type: 'string', desc: 'Free-text match against symbol or company name.' },
  { name: 'limit',     type: 'integer', desc: 'Page size. Default 50, maximum 100.' },
  { name: 'cursor',    type: 'string', desc: 'Opaque cursor returned as nextCursor by the previous page.' },
]} />

```bash
curl "https://mystocks.africa/api/v1/partner/stocks?exchange=NSE" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "stocks": [{ "id": "SCOM.KE", "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "currency": "KES", "sector": "Telecommunications", "assetType": "STOCK", "listingStatus": "ACTIVE", "price": 16.5, "usdPrice": 0.0126, "change": 0.25, "changePct": 1.54, "volume": 4210000, "lastPriceUpdate": "2026-06-04T09:45:00Z" }], "count": 1, "totalCount": null, "totalCountExact": false, "hasMore": true, "nextCursor": "opaque_cursor" }
```

## Single quote

<MethodTag m="GET" /> `/stocks/{symbol}`

Delayed quote for a single stock. Returns the full `StockSummary` shape plus `open`, `dayHigh`,
`dayLow`, `previousClose`, `volume`, and a self-hosted `logoUrl`. The symbol path accepts
exchange-qualified (`SCOM.KE`), slug (`safaricom`), or bare ticker (`SCOM`).

```bash
curl "https://mystocks.africa/api/v1/partner/stocks/DANGCEM.NG" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "id": "SCOM.KE", "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "currency": "KES", "sector": "Telecommunications", "assetType": "STOCK", "listingStatus": "ACTIVE", "price": 16.5, "usdPrice": 0.0126, "change": 0.25, "changePct": 1.54, "open": 16.2, "dayHigh": 16.75, "dayLow": 16.1, "previousClose": 16.25, "volume": 4210000, "exchangeMic": "XNAI", "lastPriceUpdate": "2026-06-04T09:45:00Z" }
```

## Price chart

<MethodTag m="GET" /> `/stocks/{symbol}/candles`

The canonical stock-chart contract is [`GET /stocks/{symbol}/candles`](/partners/docs/historical-market-data).
Its response reports per-candle `ohlcAvailable` and series-level `qualityStatus`, `qualityIssues`,
`ohlcCoveragePct`, `volumeCoveragePct`, and `recommendedChartType`. Use those fields to choose a
candlestick, line, or unavailable state instead of assuming every listed symbol has complete OHLCV.
It returns universal EOD closes plus OHLCV where available, in the listing currency with instrument and quality metadata. Intraday bucket requests can be sparse; inspect `SPARSE_INTRADAY_COVERAGE` and observed cadence.

<ParamTable fields={[
  { name: 'interval', type: 'string', required: false, desc: '15m, 1h, 1d, 1w, or 1mo. Defaults to 1d.' },
  { name: 'from', type: 'date', required: false, desc: 'Inclusive YYYY-MM-DD start date.' },
  { name: 'to', type: 'date', required: false, desc: 'Inclusive YYYY-MM-DD end date.' },
]} />

The `/stocks/{symbol}/chart` and `/history` routes are deprecated compatibility shapes scheduled for
removal on 2026-10-01. New integrations should not depend on their parallel-array schemas.

## News pulse

<MethodTag m="GET" /> `/stocks/{symbol}/pulse`

Recent news headlines, corporate announcements, and analyst sentiment for a stock. Use it to populate
a "News" tab or price-movement explanation in your UI.

```bash
curl "https://mystocks.africa/api/v1/partner/stocks/SCOM.KE/pulse" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "symbol": "SCOM.KE", "pulse": [{ "id": "pulse_abc", "title": "Safaricom H1 profit up 14%", "summary": "Safaricom posted KES 23.4bn net profit for H1 2026, driven by M-PESA revenue growth.", "source": "MyStocks Africa", "publishedAt": "2026-06-03T08:00:00Z", "url": "https://mystocks.africa/market-intel/safaricom-h1-2026" }], "count": 1 }
```

## Company profiles

<MethodTag m="GET" /> `/companies/{symbol}`

Company fundamentals: description, sector, market cap, P/E ratio, EPS, 52-week high/low, and financial
highlights. Also available as a list via `GET /companies` with `?exchange=` and `?sector=` filters.

```bash
curl "https://mystocks.africa/api/v1/partner/companies/MTN.ZA" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "sector": "Telecommunications", "description": "Safaricom PLC is the largest telecoms provider in East Africa and pioneer of M-PESA mobile money.", "marketCap": 1360000000, "pe": 12.4, "eps": 1.33, "high52w": 19.8, "low52w": 12.5, "dividendYield": 6.2, "sharesOutstanding": 40065000000, "exchangeMic": "XNAI" }
```

`GET /companies/{symbol}/news` returns curated news and regulatory announcements (same shape as
`/pulse`, sourced from exchange filings and newswires; supports `?limit=` and `?cursor=`).

<MethodTag m="GET" /> `/companies/tickers`

Cursor-paginated canonical ticker list containing each symbol, slug, display name, and exchange. Use
it to build a local symbol-resolution map or search index, following `nextCursor` until `hasMore` is
`false`.

```json
{ "tickers": [{ "symbol": "DANGCEM.NG", "slug": "dangote-cement", "name": "Dangote Cement", "exchange": "NGX" }, { "symbol": "EABL.KE", "slug": "eabl", "name": "East African Breweries", "exchange": "NSE" }], "count": 2, "totalCount": null, "totalCountExact": false, "hasMore": true, "nextCursor": "opaque_cursor" }
```

## Market intelligence

<MethodTag m="GET" /> `/market-intel` · <MethodTag m="GET" /> `/market-intel/{id}`

Editorial market-intelligence articles and exchange announcements curated by the MyStocks research
team. Filter the list by `?exchange=NGX` or `?symbol=SCOM.KE` (returns `{ articles, count }`, newest
first). The detail route resolves by document ID or URL slug and includes the full `body` field.

<ParamTable fields={[
  { name: 'symbol',   type: 'string',  required: false, desc: 'Filter to articles tagged with a stock symbol, e.g. SCOM.KE.' },
  { name: 'exchange', type: 'string',  required: false, desc: 'Filter articles by exchange code, e.g. NGX, NSE.' },
  { name: 'limit',    type: 'integer', required: false, desc: 'Max results. Default 20, max 100.' },
]} />

```bash
curl "https://mystocks.africa/api/v1/partner/market-intel?exchange=NGX" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "articles": [{ "id": "intel_ngx_q2", "title": "NGX Q2 2026 Market Wrap", "summary": "NGX All-Share Index gained 4.2% in Q2 led by banking and cement sectors.", "slug": "ngx-q2-2026-market-wrap", "category": "macro", "exchange": "NGX", "source": "MyStocks Africa", "publishedAt": "2026-06-01T08:00:00Z" }], "count": 1 }
```