Market Data

Read-only market data across 14 African exchanges — ETFs, currency-correct price charts, 50-symbol batch quotes, exchange open/closed status, top movers, holiday calendars, the exchange directory, and EOD OHLCV candles. Data-key safe.

Everything here is read-only and data-key safe (pk_data_). Expand your product with ETFs listed across African markets (e.g. Satrix on the JSE) and render rich price charts for both stocks and ETFs.

Examples use the production base https://mystocks.africa/api/v1/partner. To run any of them against the sandbox, swap the base for https://mystocks.africa/api/sandbox/v1/partner and use your sk_sandbox_ key.

ETFs catalog

Query listed ETFs via the /etfs endpoints. Responses carry fund-specific metadata such as expense ratios, asset classes, geographical focus, risk levels, and top holdings.

curl "https://mystocks.africa/api/v1/partner/etfs?exchange=JSE" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "etfs": [
    {
      "id": "STXEME.ZA",
      "symbol": "STXEME.ZA",
      "name": "Satrix MSCI Emerging Markets ETF",
      "exchange": "JSE",
      "currency": "ZAR",
      "price": 75.0,
      "usdPrice": 4.55,
      "assetType": "ETF",
      "fundMetadata": {
        "brand": "Satrix",
        "expenseRatio": 0.38,
        "geographicalFocus": "Global Emerging Markets",
        "indexTracked": "MSCI Emerging Markets Index",
        "riskLevel": "HIGH",
        "managementStyle": "PASSIVE"
      }
    }
  ],
  "count": 1
}

Mapped price charts

Retrieve pre-computed, currency-correct charts via the /chart endpoints — no manual date-grid math. Price values are returned in their native local trading currency for precise UI alignment, alongside converted USD histories. Works for both stocks (GET /stocks/SCOM.KE/chart?period=1y) and ETFs (GET /etfs/STXEME.ZA/chart?period=3m).

curl "https://mystocks.africa/api/v1/partner/etfs/STXEME.ZA/chart?period=3m" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "symbol": "STXEME.ZA",
  "currency": "ZAR",
  "period": "3m",
  "labels": ["2026-03-01", "2026-04-01", "2026-05-23"],
  "prices": [73.5, 74.2, 75.0],
  "priceHistory": [
    { "date": "2026-05-23T19:59:41.000Z", "open": 74.6, "high": 75.2, "low": 74.3, "price": 75.0, "close": 75.0, "usdPrice": 4.55, "volume": 24000 }
  ]
}

Batch quotes (up to 50 symbols)

Query up to 50 comma-separated stock or ETF symbols in a single roundtrip with ?symbols=A,B,C. Use ?symbol=X&exchange=Y for a single symbol — the response unwraps to a plain object in data and returns 404 if not found. In batch mode, unresolved symbols are listed in not_found rather than failing the whole request. Sending more than 50 returns 400 BATCH_LIMIT_EXCEEDED with max and received. volume is always an integer — 0 for instruments with no trades today, never null.

curl "https://mystocks.africa/api/v1/partner/market/quotes?symbols=SCOM.KE,GLD.ZA,INVALID_XYZ" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "data": [
    { "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "currency": "KES", "price": 16.5, "usd_price": 0.0126, "change": 0.25, "change_pct": 0.015385, "volume": 4210000, "market_status": "OPEN" },
    { "symbol": "GLD.ZA", "name": "NewGold Issuer ETF", "exchange": "JSE", "currency": "ZAR", "price": 410.0, "usd_price": 24.85, "change": -1.5, "change_pct": -0.003643, "volume": 0, "market_status": "OPEN" }
  ],
  "not_found": ["INVALID_XYZ"],
  "meta": { "request_id": "4a3f9c1e-7b2d-4e8a-9f06-1c5d3e2b7a04", "timestamp": "2026-06-04T09:42:00.000Z" }
}

Market status & holidays

GET /market/status tells you whether an exchange is currently open and when it next opens. Status is computed from live exchange schedules and the holiday calendar; when an exchange is closed for a public holiday the response includes a holiday reason string. Omit ?exchange= to receive status for all 14 supported exchanges plus a top-level anyOpen boolean.

curl "https://mystocks.africa/api/v1/partner/market/status?exchange=NSE" \
  -H "Authorization: Bearer pk_live_<your_key>"

// Public holiday — forced closed
{ "exchange": "NSE", "name": "Nairobi Securities Exchange", "currency": "KES", "isOpen": false, "status": "CLOSED", "localOpen": "09:00", "localClose": "15:00", "timezone": "Africa/Nairobi", "nextOpen": "2026-06-02T06:00:00.000Z", "holiday": "Madaraka Day", "checkedAt": "2026-06-01T10:00:00.000Z" }

GET /market/holidays returns forward-looking closure dates for any exchange and range (from, to; defaults to today through +12 months, max 2 years). Combine the two: status tells you if the market is open right now, holidays gives you the calendar for scheduling logic.

{
  "data": [
    { "exchange": "NSE", "date": "2026-10-20", "reason": "Mashujaa Day" },
    { "exchange": "NSE", "date": "2026-12-25", "reason": "Christmas Day" }
  ],
  "count": 2,
  "from": "2026-06-06",
  "to": "2026-12-31"
}

Top movers

Top price-change movers for any exchange — sorted by change_pct descending (gainers) or ascending (losers). Paginated via page and limit. Only instruments with a recorded changePct appear.

Field	Type	Required	Description
exchange	string	Yes	Exchange code, e.g. NSE.
direction	string	No	gainers \| losers (default: gainers).
limit	integer	No	1–100, default 10.
page	integer	No	1-based, default 1.

curl "https://mystocks.africa/api/v1/partner/market/movers?exchange=NSE&direction=gainers&limit=5&page=1" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "data": [
    { "symbol": "EABL.KE", "name": "East African Breweries", "exchange": "NSE", "currency": "KES", "price": 185.0, "change_pct": 0.057143, "volume": 312000, "market_status": "OPEN" }
  ],
  "meta": { "exchange": "NSE", "direction": "gainers", "page": 1, "totalCount": 48, "perPage": 5, "hasNext": true }
}

The snake_case meta aliases (total_count, per_page, has_next) are deprecated — removal 2026-10-01.

Exchange directory

Returns all supported exchanges with trading hours, currencies, settlement cycles, and live OPEN/CLOSED status in one call. mic is the ISO 10383 operating Market Identifier Code; settlement summarizes the cycle (T+2 for EGX, T+3 for all others). The same mic appears on GET /stocks/{symbol} and GET /companies/{symbol} as exchangeMic.

curl "https://mystocks.africa/api/v1/partner/market/exchanges" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "data": [
    { "code": "NSE", "mic": "XNAI", "name": "Nairobi Securities Exchange", "country": "KE", "currency": "KES", "timezone": "Africa/Nairobi", "trading_hours": { "open": "09:00", "close": "15:00" }, "settlement": { "cycle": "T+3", "cycleDays": 3 }, "market_status": "OPEN" },
    { "code": "EGX", "mic": "XCAI", "name": "Egyptian Exchange", "country": "EG", "currency": "EGP", "timezone": "Africa/Cairo", "trading_hours": { "open": "10:00", "close": "14:30" }, "settlement": { "cycle": "T+2", "cycleDays": 2 }, "market_status": "CLOSED" }
  ]
}

EOD OHLCV candles

End-of-day OHLCV candles for any symbol over a custom date range. open, high, and low are null until intraday data becomes available for that session — check ohlc_available before rendering a candlestick.

Field	Type	Required	Description
symbol	string	Yes	Exchange-qualified symbol, e.g. SCOM.KE.
exchange	string	Yes	Exchange code, e.g. NSE.
from	string	No	Start date (YYYY-MM-DD, UTC).
to	string	No	End date (YYYY-MM-DD, UTC).
interval	string	No	Candle interval — currently only 1d supported.

curl "https://mystocks.africa/api/v1/partner/market/ohlcv?symbol=SCOM.KE&exchange=NSE&from=2026-06-01&to=2026-06-06" \
  -H "Authorization: Bearer pk_live_<your_key>"

{
  "data": [
    { "date": "2026-06-02", "open": null, "high": null, "low": null, "close": 16.25, "volume": 3820000, "ohlc_available": false },
    { "date": "2026-06-03", "open": 16.3, "high": 16.75, "low": 16.1, "close": 16.5, "volume": 4210000, "ohlc_available": true }
  ],
  "meta": { "symbol": "SCOM.KE", "exchange": "NSE", "interval": "1d" }
}

Every market endpoint lives under /market/* (quotes, movers, exchanges, ohlcv, status, settlement, holidays). The old /market-data/* paths remain working aliases but are deprecated — use /market/* in new code.