Historical Market Data

Build stock charts with canonical, date-bounded intraday and daily OHLCV candles plus explicit data-quality metadata.

Use the candles endpoint for new stock-chart integrations:

GET

/stocks/{symbol}/candles

Historical stock candles

Sandbox availablegetStockCandles

Returns chart-ready OHLCV candles in the listing currency, sorted oldest-first. from and to define an inclusive date window; interval selects intraday bucket sizes or daily/weekly/monthly aggregation. African equity observations are exchange-supplied and 15-minute delayed. The API refresh target is 900 seconds during the published coverage window. This is pull-based market data—not a real-time or tick feed. Every listed African equity has EOD data for a line chart; complete reported OHLCV is instrument-dependent. Intraday candles are built only from observations captured after the intraday rollout; missing observations are never interpolated. The current delayed capture can be materially coarser than the requested 15m or 1h bucket, so inspect SPARSE_INTRADAY_COVERAGE, samplingCadenceSeconds, and intradayObservationCount before rendering an intraday chart. Older daily source rows may contain only close, or omit volume. Use each candle's volumeAvailable and the series coverage metadata before enabling volume-dependent indicators. Prices are raw and unadjusted for splits and dividends. MyStocks holds market-data rights for every supported exchange, so endpoint availability is not gated by missing exchange licences. Authenticated partners may display these candles to their end-users under their Partner Agreement. Raw-feed redistribution, bulk export, and standalone data products remain governed by that agreement and applicable downstream-use terms.

Parameters

symbolstringpathRequired

Exchange-qualified ticker (recommended) or an unambiguous bare ticker.

Example: SCOM.KE

interval15m | 1h | 1d | 1w | 1moquery

Candle bucket interval. 15m and 1h never interpolate missing observations and may be sparse on the delayed capture; 1mo means one calendar month. 1m is not supported.

Example: 1d

fromstringquery

Inclusive start date. Defaults to 30 calendar days ago.

Example: 2026-01-01

tostringquery

Inclusive end date. Defaults to today.

Example: 2026-08-10

adjustmentrawquery

Price-adjustment mode. Only raw, unadjusted exchange prices are currently available.

Example: raw

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

symbolstringRequired

Example: "SCOM.KE"

namestring | nullRequired

Example: "Safaricom PLC"

exchangestring | nullRequired

Example: "NSE"

currencystringRequired

Example: "KES"

interval15m | 1h | 1d | 1w | 1moRequired

adjustmentrawRequired

candlesobject[]Required

candles[].timestampstringRequired

UTC start of the 15-minute, hourly, daily, ISO-week, or calendar-month bucket.

Example: "2026-08-03T00:00:00.000Z"

candles[].opennumberRequired

Example: 16.2

candles[].highnumberRequired

Example: 16.75

candles[].lownumberRequired

Example: 16.1

candles[].closenumberRequired

Example: 16.5

candles[].volumeintegerRequired

Reported or sampled volume in the candle bucket. Check volumeAvailable before using it.

Example: 2450000

candles[].ohlcAvailablebooleanRequired

True when OHLC was reported or sampled; false when open/high/low are close-derived fallbacks.

candles[].volumeAvailablebooleanRequired

True when the source supplied volume for every observation in this candle.

metaobjectRequired

meta.request_idstring

Unique identifier for this request. Include in support tickets for tracing.

Example: "4f6e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"

meta.timestampstring

ISO 8601 UTC timestamp of when the response was generated.

Example: "2026-06-04T10:23:45.123Z"

meta.exchangestring | null

Exchange code the request was scoped to, when applicable.

Example: "NSE"

meta.symbolstring | null

Ticker symbol the request was scoped to, when applicable.

Example: "SCOM.KE"

meta.fromstringRequired

meta.tostringRequired

meta.countintegerRequired

meta.sourcedelayed_eod | delayed_intradayRequired

meta.asOfstring | nullRequired

Timestamp of the latest returned candle, or null when the range is empty.

meta.ohlcQualityreported | mixed | close_derived | sampledRequired

meta.ohlcAvailablebooleanRequired

meta.ohlcCoveragePctnumberRequired

meta.flatCandlePctnumberRequired

meta.volumeAvailablebooleanRequired

meta.volumeCoveragePctnumberRequired

meta.volumeStatusunavailable | partial | completeRequired

meta.zeroVolumePctnumberRequired

meta.qualityStatuscomplete | partial | degraded | unavailableRequired

meta.qualityIssuesstring[]Required

meta.recommendedChartTypecandlestick | line | noneRequired

Server recommendation derived from price quality. Any missing OHLC, a flat-candle rate of 25% or more, or sparse intraday observations produces line; incomplete volume alone does not prevent candlesticks.

meta.samplingCadenceSecondsinteger | null

Median observed same-session gap between source snapshots, not a promised target cadence.

Example: 14400

meta.intradayObservationCountinteger | null

Source observations available for the requested intraday window before bucketing.

meta.coverageStartsAtstring | null

meta.adjustedfalseRequired

meta.sandboxboolean

Response codes

200Historical candles and data-quality metadata.

400Invalid date, interval, adjustment, or interval-specific date range.

401Unauthorized.

404Symbol not found or ambiguous.

Sandbox playground

Read-only sandbox request

symbol Required · pathinterval Optional · queryfrom Optional · queryto Optional · queryadjustment Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/stocks/%7Bsymbol%7D/candles

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "required": [
    "symbol",
    "name",
    "exchange",
    "currency",
    "interval",
    "adjustment",
    "candles",
    "meta"
  ],
  "properties": {
    "symbol": {
      "type": "string",
      "example": "SCOM.KE"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Safaricom PLC"
    },
    "exchange": {
      "type": [
        "string",
        "null"
      ],
      "example": "NSE"
    },
    "currency": {
      "type": "string",
      "example": "KES"
    },
    "interval": {
      "type": "string",
      "enum": [
        "15m",
        "1h",
        "1d",
        "1w",
        "1mo"
      ]
    },
    "adjustment": {
      "type": "string",
      "enum": [
        "raw"
      ]
    },
    "candles": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A chart-ready OHLCV candle in the instrument's listing currency.",
        "required": [
          "timestamp",
          "open",
          "high",
          "low",
          "close",
          "volume",
          "ohlcAvailable",
          "volumeAvailable"
        ],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "UTC start of the 15-minute, hourly, daily, ISO-week, or calendar-month bucket.",
            "example": "2026-08-03T00:00:00.000Z"
          },
          "open": {
            "type": "number",
            "example": 16.2
          },
          "high": {
            "type": "number",
            "example": 16.75
          },
          "low": {
            "type": "number",
            "example": 16.1
          },
          "close": {
            "type": "number",
            "example": 16.5
          },
          "volume": {
            "type": "integer",
            "description": "Reported or sampled volume in the candle bucket. Check volumeAvailable before using it.",
            "example": 2450000
          },
          "ohlcAvailable": {
            "type": "boolean",
            "description": "True when OHLC was reported or sampled; false when open/high/low are close-derived fallbacks."
          },
          "volumeAvailable": {
            "type": "boolean",
            "description": "True when the source supplied volume for every observation in this candle."
          }
        }
      }
    },
    "meta": {
      "allOf": [
        {
          "type": "object",
          "description": "Standard response metadata included on every market-data envelope.",
          "properties": {
            "request_id": {
              "type": "string",
              "format": "uuid",
              "description": "Unique identifier for this request. Include in support tickets for tracing.",
              "example": "4f6e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"
            },
            "timestamp": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 UTC timestamp of when the response was generated.",
              "example": "2026-06-04T10:23:45.123Z"
            },
            "exchange": {
              "type": [
                "string",
                "null"
              ],
              "description": "Exchange code the request was scoped to, when applicable.",
              "example": "NSE"
            },
            "symbol": {
              "type": [
                "string",
                "null"
              ],
              "description": "Ticker symbol the request was scoped to, when applicable.",
              "example": "SCOM.KE"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "from",
            "to",
            "count",
            "source",
            "asOf",
            "ohlcQuality",
            "ohlcAvailable",
            "ohlcCoveragePct",
            "flatCandlePct",
            "volumeAvailable",
            "volumeCoveragePct",
            "volumeStatus",
            "zeroVolumePct",
            "qualityStatus",
            "qualityIssues",
            "recommendedChartType",
            "adjusted"
          ],
          "properties": {
            "from": {
              "type": "string",
              "format": "date"
            },
            "to": {
              "type": "string",
              "format": "date"
            },
            "count": {
              "type": "integer"
            },
            "source": {
              "type": "string",
              "enum": [
                "delayed_eod",
                "delayed_intraday"
              ]
            },
            "asOf": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Timestamp of the latest returned candle, or null when the range is empty."
            },
            "ohlcQuality": {
              "type": "string",
              "enum": [
                "reported",
                "mixed",
                "close_derived",
                "sampled"
              ]
            },
            "ohlcAvailable": {
              "type": "boolean"
            },
            "ohlcCoveragePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "flatCandlePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "volumeAvailable": {
              "type": "boolean"
            },
            "volumeCoveragePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "volumeStatus": {
              "type": "string",
              "enum": [
                "unavailable",
                "partial",
                "complete"
              ]
            },
            "zeroVolumePct": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "qualityStatus": {
              "type": "string",
              "enum": [
                "complete",
                "partial",
                "degraded",
                "unavailable"
              ]
            },
            "qualityIssues": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "NO_CHART_DATA",
                  "OHLC_UNAVAILABLE",
                  "OHLC_PARTIAL",
                  "FLAT_SERIES",
                  "HIGH_FLAT_CANDLE_RATE",
                  "VOLUME_UNAVAILABLE",
                  "VOLUME_PARTIAL",
                  "HIGH_ZERO_VOLUME_RATE",
                  "SPARSE_INTRADAY_COVERAGE"
                ]
              }
            },
            "recommendedChartType": {
              "type": "string",
              "enum": [
                "candlestick",
                "line",
                "none"
              ],
              "description": "Server recommendation derived from price quality. Any missing OHLC, a flat-candle rate of 25% or more, or sparse intraday observations produces `line`; incomplete volume alone does not prevent candlesticks."
            },
            "samplingCadenceSeconds": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Median observed same-session gap between source snapshots, not a promised target cadence.",
              "example": 14400
            },
            "intradayObservationCount": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Source observations available for the requested intraday window before bucketing."
            },
            "coverageStartsAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "adjusted": {
              "type": "boolean",
              "enum": [
                false
              ]
            },
            "sandbox": {
              "type": "boolean"
            }
          }
        }
      ]
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/stocks/%7Bsymbol%7D/candles' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

Parameters and range limits

Parameter	Values	Limit
`interval`	`15m`, `1h`, `1d`, `1w`, `1mo`	15-minute: 31 days; hourly: 90 days; daily: 366 days; weekly: 1,826 days; monthly: 3,653 days
`from`	`YYYY-MM-DD`	Inclusive; defaults to 30 days ago
`to`	`YYYY-MM-DD`	Inclusive; defaults to today
`adjustment`	`raw`	Raw exchange prices only

15m and 1h are bucket sizes, not a promise that every bucket contains an observation. The current delayed capture can be materially coarser (the August 2026 partner test observed roughly three snapshots per trading day), so these intervals are not yet suitable for a continuous intraday chart. Coverage begins when capture was deployed, the API never interpolates gaps, and SPARSE_INTRADAY_COVERAGE tells clients to use a line chart or suppress the intraday option. Inspect samplingCadenceSeconds (the median observed same-session gap) and intradayObservationCount. 1mo means one calendar month; 1m is not supported. Weekly buckets start on Monday; monthly buckets start on the first calendar day. Candles are returned oldest-first.

Data quality

African equity observations are supplied by the exchanges on a 15-minute-delayed basis. The API is pull-based and targets a 15-minute refresh cadence during the published coverage window; it is not a real-time or tick-by-tick feed, and there is no WebSocket candle stream. Inspect meta.asOf rather than treating response time as market time. MyStocks has full exchange data rights—the delay is a feed characteristic, not a licensing gap.

Some older history contains close and volume but no reported open, high, or low. The endpoint keeps the schema chart-safe by using close for those missing fields and makes that provenance explicit:

`meta.ohlcQuality`	Meaning
`reported`	Every returned daily source row contains reported OHLC values.
`mixed`	The range combines reported OHLC and close-derived legacy rows.
`close_derived`	Open, high, and low were derived from close for all source rows.
`sampled`	Intraday OHLC was calculated from delayed observations captured inside the bucket.

Check each candle's ohlcAvailable before rendering it as a candlestick. meta.ohlcCoveragePct and meta.flatCandlePct make symbol-level validation unnecessary: qualityStatus=degraded with FLAT_SERIES means the source has no usable range variance for that requested window. Fall back to a line chart or display an unavailable state; do not invent wicks.

Check each candle's volumeAvailable before using its volume. meta.volumeStatus is complete, partial, or unavailable, while meta.volumeCoveragePct reports series coverage. A numeric zero is not evidence that volume exists. Disable VWAP and volume-derived indicators for incomplete series. Missing trading dates are not zero-price candles; exchanges close for weekends, holidays, suspensions, and data gaps.

qualityStatus summarizes the requested symbol and window. Always inspect qualityIssues; a listed instrument can legitimately have no chart history, and thinly traded instruments can have genuine flat or zero-volume sessions. The API reports these conditions instead of silently presenting them as complete OHLCV. Use recommendedChartType (candlestick, line, or none) for a safe default without maintaining your own symbol allow-list.

`qualityStatus`	Partner behavior
`complete`	Candlestick and volume rendering is supported for the requested window.
`partial`	Render only features whose availability and coverage checks pass.
`degraded`	Prefer a line chart or an explicit unavailable state; inspect `qualityIssues`.
`unavailable`	No candles exist for the requested symbol and date window.

The API marks a series degraded when OHLC coverage is below 80%, volume coverage is below 50%, at least 25% of five or more candles are flat, or intraday observations are too sparse for the requested bucket. It recommends a line chart whenever any candle lacks reported OHLC, at least 25% are flat, or intraday coverage is sparse. Missing volume alone does not prevent candlesticks; hide the volume layer instead. A high flat-candle rate can reflect an illiquid security or a close-only source; it is a quality signal, not permission to manufacture intraday ranges.

Adjustments and indicators

Candles are currently unadjusted for splits, consolidations, rights issues, and dividends. The API accepts only adjustment=raw and reports meta.adjusted=false; requesting another mode returns a validation error. Use the Corporate Governance API to retrieve corporate actions when you need to calculate an adjusted series.

SMA, EMA, RSI, MACD, drawing tools, and annotations are presentation or derived-analytics concerns and are not calculated by this endpoint. Calculate them from the returned candles in your client or analytics service, and retain the candle-quality flags with any derived output.

Endpoint guide

Endpoint	Recommended use
`GET /stocks/{symbol}/candles`	Canonical stock-chart endpoint; explicit dates, a stable OHLCV schema, intraday and daily intervals.
`GET /stocks/{symbol}/chart`	Deprecated compatibility shape; migrate to `/candles` before 2026-10-01.
`GET /stocks/{symbol}/history`	Deprecated period-based history; migrate to `/candles` before 2026-10-01.
`GET /market/ohlcv`	Cross-market query form when symbol and exchange are separate inputs.
`GET /market-data/ohlcv`	Deprecated alias of `/market/ohlcv`.

/stocks/{symbol}/prices and /stocks/{symbol}/ohlc are not Partner API routes and have never been part of the documented contract. Use /stocks/{symbol}/candles; do not probe guessed aliases.

Licensing

MyStocks holds market-data rights for every supported exchange. Missing or degraded candles are an ingestion/data-quality incident, not an exchange-licensing limitation.

Authenticated sandbox and production keys can call the candles endpoint. Displaying the returned candles inside your application for your end-users is included subject to your Partner Agreement and required attribution; it does not require a separate bulk-data agreement. Redistributing raw data, offering a standalone feed, bulk exporting history, or sublicensing it does require additional data rights. See Data Licensing.