API product catalogPan-African Market Data & Intelligence

Top gainers & losers

Pan-African Market Data & Intelligence

GET

/market/movers

Sandbox availablegetMarketMovers

Returns the top price movers (gainers or losers) for a given exchange, sorted by percentage change. Results are paginated (meta uses camelCase totalCount/perPage/hasNext; the snake_case aliases are deprecated, removal 2026-10-01). Also available at GET /market-data/movers (deprecated alias, identical handler).

Parameters

exchangestringqueryRequired

Exchange code (NSE, NGX, JSE, GSE, BRVM, ZSE, BSE, LUSE, EGX, DSE, USE, MSE, CSE, SEM).

Example: NSE

directiongainers | losersquery

"gainers" for top price increases, "losers" for top price decreases. Default: gainers.

Example: gainers

limitintegerquery

Number of results to return. Default 10, max 100.

Example: 10

pageintegerquery

Example: 1

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

dataobject[]

data[].idstring

Unique stock identifier.

Example: "SCOM.KE"

data[].symbolstring

Exchange-qualified ticker symbol.

Example: "SCOM.KE"

data[].namestring

Full company name.

Example: "Safaricom PLC"

data[].slugstring | null

URL-safe identifier. Interchangeable with symbol.

Example: "safaricom"

data[].exchangestring

Exchange code: NSE, NGX, JSE, GSE, BRVM, ZSE, BSE, LUSE, EGX, DSE, USE, MSE, CSE, SEM.

Example: "NSE"

data[].exchangeMicstring | null

ISO 10383 operating Market Identifier Code for the listing exchange.

Example: "XNAI"

data[].currencystring

Local trading currency.

Example: "KES"

data[].sectorstring | null

Example: "Telecommunications"

data[].assetTypeSTOCK | ETF

data[].listingStatusACTIVE | SUSPENDED | DELISTED

data[].pricenumber | null

Latest price in local currency.

Example: 16.5

data[].usdPricenumber | null

Latest price converted to USD at live spot rate.

Example: 0.1274

data[].changenumber | null

Absolute price change from previous close.

Example: 0.25

data[].changePctnumber | null

Percentage price change from previous close.

Example: 1.54

data[].opennumber | null

Session opening price in local currency.

data[].dayHighnumber | null

Intraday high in local currency.

data[].dayLownumber | null

Intraday low in local currency.

data[].volumeinteger | null

Current session trading volume.

data[].previousClosenumber | null

Prior session closing price.

data[].logoUrlstring | null

Self-hosted SVG logo. Safe to use as img src.

Example: "https://mystocks.africa/logos/scom-ke.svg"

data[].lastPriceUpdatestring | null

data[].marketStatusstring

Exchange state at quote time: OPEN or CLOSED. Present on /market/quotes and /market/movers responses.

data[].bidnumber | null

Best bid. Currently always null (no order-book depth in the data source).

data[].asknumber | null

Best ask. Currently always null (no order-book depth in the data source).

data[].dataFreshnessSecondsinteger | null

Seconds since the last price update. Present on /market/quotes and /market/movers responses.

data[].asOfstring | null

Timestamp of the exchange observation — NOT when the API answered. African equity data is 15-minute delayed and the API refresh target is 900 seconds, so display and evaluate freshness against this value.

data[].staleboolean

True when the price is older than two refresh intervals (30 minutes). The feed for this symbol is genuinely behind — do not trust the price for pricing a trade.

data[].dataQualityobject

The published market-data freshness contract. African equity quotes are supplied by the exchanges on a 15-minute-delayed basis, not in real time. MyStocks holds full exchange data rights. The API refresh target is 900 seconds during the published coverage window, with an end-of-day pass after market close.

metaobject

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.directiongainers | losers

meta.pageinteger

meta.totalCountinteger

Total number of stocks with price change data on this exchange.

meta.perPageinteger

meta.hasNextboolean

meta.total_countinteger

Deprecated alias of totalCount — removed 2026-10-01.

meta.per_pageinteger

Deprecated alias of perPage — removed 2026-10-01.

meta.has_nextboolean

Deprecated alias of hasNext — removed 2026-10-01.

Response codes

200Top movers for the requested exchange and direction.

400Missing or invalid parameters.

401Unauthorized.

Sandbox playground

Read-only sandbox request

exchange Required · querydirection Optional · querylimit Optional · querypage Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/market/movers

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "SCOM.KE",
            "description": "Unique stock identifier."
          },
          "symbol": {
            "type": "string",
            "example": "SCOM.KE",
            "description": "Exchange-qualified ticker symbol."
          },
          "name": {
            "type": "string",
            "example": "Safaricom PLC",
            "description": "Full company name."
          },
          "slug": {
            "type": [
              "string",
              "null"
            ],
            "example": "safaricom",
            "description": "URL-safe identifier. Interchangeable with symbol."
          },
          "exchange": {
            "type": "string",
            "example": "NSE",
            "description": "Exchange code: NSE, NGX, JSE, GSE, BRVM, ZSE, BSE, LUSE, EGX, DSE, USE, MSE, CSE, SEM."
          },
          "exchangeMic": {
            "type": [
              "string",
              "null"
            ],
            "example": "XNAI",
            "description": "ISO 10383 operating Market Identifier Code for the listing exchange."
          },
          "currency": {
            "type": "string",
            "example": "KES",
            "description": "Local trading currency."
          },
          "sector": {
            "type": [
              "string",
              "null"
            ],
            "example": "Telecommunications"
          },
          "assetType": {
            "type": "string",
            "enum": [
              "STOCK",
              "ETF"
            ]
          },
          "listingStatus": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "SUSPENDED",
              "DELISTED"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "example": 16.5,
            "description": "Latest price in local currency."
          },
          "usdPrice": {
            "type": [
              "number",
              "null"
            ],
            "example": 0.1274,
            "description": "Latest price converted to USD at live spot rate."
          },
          "change": {
            "type": [
              "number",
              "null"
            ],
            "example": 0.25,
            "description": "Absolute price change from previous close."
          },
          "changePct": {
            "type": [
              "number",
              "null"
            ],
            "example": 1.54,
            "description": "Percentage price change from previous close."
          },
          "open": {
            "type": [
              "number",
              "null"
            ],
            "description": "Session opening price in local currency."
          },
          "dayHigh": {
            "type": [
              "number",
              "null"
            ],
            "description": "Intraday high in local currency."
          },
          "dayLow": {
            "type": [
              "number",
              "null"
            ],
            "description": "Intraday low in local currency."
          },
          "volume": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Current session trading volume."
          },
          "previousClose": {
            "type": [
              "number",
              "null"
            ],
            "description": "Prior session closing price."
          },
          "logoUrl": {
            "type": [
              "string",
              "null"
            ],
            "example": "https://mystocks.africa/logos/scom-ke.svg",
            "description": "Self-hosted SVG logo. Safe to use as img src."
          },
          "lastPriceUpdate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "marketStatus": {
            "type": "string",
            "description": "Exchange state at quote time: OPEN or CLOSED. Present on /market/quotes and /market/movers responses."
          },
          "bid": {
            "type": [
              "number",
              "null"
            ],
            "description": "Best bid. Currently always null (no order-book depth in the data source)."
          },
          "ask": {
            "type": [
              "number",
              "null"
            ],
            "description": "Best ask. Currently always null (no order-book depth in the data source)."
          },
          "dataFreshnessSeconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds since the last price update. Present on /market/quotes and /market/movers responses."
          },
          "asOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp of the exchange observation — NOT when the API answered. African equity data is 15-minute delayed and the API refresh target is 900 seconds, so display and evaluate freshness against this value.\n"
          },
          "stale": {
            "type": "boolean",
            "description": "True when the price is older than two refresh intervals (30 minutes). The feed for this symbol is genuinely behind — do not trust the price for pricing a trade.\n"
          },
          "dataQuality": {
            "type": "object",
            "description": "The published market-data freshness contract. African equity quotes are supplied by the exchanges on a 15-minute-delayed basis, not in real time. MyStocks holds full exchange data rights. The API refresh target is 900 seconds during the published coverage window, with an end-of-day pass after market close.\n",
            "required": [
              "asOf",
              "ageSeconds",
              "stale",
              "delayMode",
              "delayMinutes",
              "refreshIntervalSeconds",
              "provider",
              "disclaimer"
            ],
            "properties": {
              "asOf": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Timestamp of the exchange observation, not the time the API response was generated."
              },
              "ageSeconds": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Age of the price in seconds (now − asOf)."
              },
              "stale": {
                "type": "boolean",
                "description": "True when the price is older than two refresh intervals."
              },
              "delayMode": {
                "type": "string",
                "enum": [
                  "DELAYED",
                  "END_OF_DAY"
                ],
                "description": "DELAYED — exchange-supplied data in the 15-minute-delayed latency class. END_OF_DAY — outside the window; this is the most recent close, not a live quote.\n"
              },
              "delayMinutes": {
                "type": "integer",
                "example": 15,
                "description": "Exchange feed latency class in minutes. This is distinct from the API refresh target."
              },
              "refreshIntervalSeconds": {
                "type": "integer",
                "example": 900,
                "description": "Target interval between API ingestion refreshes during the published coverage window."
              },
              "provider": {
                "type": "string",
                "enum": [
                  "mstocks",
                  "mansa"
                ],
                "description": "MyStocks ingestion connector for this exchange feed. This field does not describe exchange licensing or partner entitlement."
              },
              "disclaimer": {
                "type": "string",
                "description": "Plain-English statement of what this price is and is not."
              }
            }
          }
        },
        "description": "Canonical stock/quote shape returned by /stocks, /stocks/{symbol}, /market/quotes, and /market/movers. NOTE: /market/quotes and /market/movers also emit DEPRECATED snake_case aliases (usd_price, prev_close, change_pct, asset_type, listing_status, high, low, market_status, timestamp, data_freshness_seconds, logo) for backward compatibility — these are scheduled for removal on 2026-10-01. Use the camelCase fields above.\n"
      }
    },
    "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",
          "properties": {
            "direction": {
              "type": "string",
              "enum": [
                "gainers",
                "losers"
              ]
            },
            "page": {
              "type": "integer"
            },
            "totalCount": {
              "type": "integer",
              "description": "Total number of stocks with price change data on this exchange."
            },
            "perPage": {
              "type": "integer"
            },
            "hasNext": {
              "type": "boolean"
            },
            "total_count": {
              "type": "integer",
              "deprecated": true,
              "description": "Deprecated alias of totalCount — removed 2026-10-01."
            },
            "per_page": {
              "type": "integer",
              "deprecated": true,
              "description": "Deprecated alias of perPage — removed 2026-10-01."
            },
            "has_next": {
              "type": "boolean",
              "deprecated": true,
              "description": "Deprecated alias of hasNext — removed 2026-10-01."
            }
          }
        }
      ]
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/market/movers' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

GET /market/holidays

GET /market/ohlcv