Watchlists

Each sub-account has an isolated watchlist. Let users save stocks and load them with delayed prices and day-change data for a personalized market overview.

Each sub-account has an isolated watchlist. Use it to let your users save stocks they want to track, then load it alongside delayed prices to power a personalized market overview screen. Watchlist entries include price and day-change percent when available; use the quote timestamp and freshness metadata before presenting the value as current.

Get a watchlist

Returns all watchlisted stocks for a sub-account, ordered by most recently added.

GET

/users/{userId}/watchlist

List sub-account watchlist

Full endpoint documentation

Sandbox availablelistWatchlist

Returns the watchlist for a sub-account, including delayed price and day-change for each stock where available.

Parameters

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

dataobject[]

data[].assetIdstring

data[].symbolstring

data[].namestring

data[].exchangestring

data[].sourceTypestring

Example: "LISTED_STOCK"

data[].addedAtstring

data[].pricenumber

Live local-currency price (omitted if unavailable).

data[].usdPricenumber

data[].changenumber

Day change percent.

data[].currencystring

countinteger

metaobject

Standard response metadata included on every market-data envelope.

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"

Response codes

200Watchlist items with delayed prices and freshness metadata.

Sandbox playground

Read-only sandbox request

userId Required · pathSandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "assetId": {
            "type": "string"
          },
          "symbol": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "exchange": {
            "type": "string"
          },
          "sourceType": {
            "type": "string",
            "example": "LISTED_STOCK"
          },
          "addedAt": {
            "type": "string",
            "format": "date-time"
          },
          "price": {
            "type": "number",
            "description": "Live local-currency price (omitted if unavailable)."
          },
          "usdPrice": {
            "type": "number"
          },
          "change": {
            "type": "number",
            "description": "Day change percent."
          },
          "currency": {
            "type": "string"
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "meta": {
      "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"
        }
      }
    }
  }
}

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

Add to a watchlist

Adds a stock to the sub-account watchlist. The symbol is auto-resolved to its canonical exchange-qualified form — pass SCOM and get back SCOM.KE. Returns 409 if the stock is already on the watchlist.

POST

/users/{userId}/watchlist

Add symbol to watchlist

Full endpoint documentation

Sandbox availableaddToWatchlist

Adds a stock to a sub-account's watchlist. The symbol is resolved to its canonical exchange-qualified form (e.g. "SCOM" → "SCOM.KE"). Returns 409 if already present.

Parameters

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

symbolstringRequired

Ticker symbol (exchange-qualified preferred, e.g. SCOM.KE).

Example: "SCOM.KE"

Response fields

assetIdstring

symbolstring

namestring

exchangestring

addedAtstring

metaobject

Standard response metadata included on every market-data envelope.

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"

Response codes

201Symbol added to watchlist.

409Symbol already on watchlist.

Request reference

Sandbox available

userId Required · path

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "assetId": {
      "type": "string"
    },
    "symbol": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "exchange": {
      "type": "string"
    },
    "addedAt": {
      "type": "string",
      "format": "date-time"
    },
    "meta": {
      "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"
        }
      }
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "symbol": "SCOM.KE"
}'

Remove from a watchlist

Removes a stock from the sub-account watchlist. Returns 204 No Content on success, 404 if the symbol is not on the watchlist.

DELETE

/users/{userId}/watchlist/{symbol}

Remove symbol from watchlist

Full endpoint documentation

Sandbox availableremoveFromWatchlist

Removes a stock from a sub-account's watchlist. Returns 404 if the symbol is not on the watchlist.

Parameters

userIdstringpathRequired

Example: usr_abc123

symbolstringpathRequired

Exchange-qualified ticker symbol (e.g. SCOM.KE).

Example: SCOM.KE

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Example: dep_user42_1743152580

Response fields

See the response format and API Reference for this endpoint.

Response codes

204Symbol removed. No response body.

404Symbol not on watchlist or sub-account not found.

Request reference

Sandbox available

userId Required · pathsymbol Required · path

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist/%7Bsymbol%7D

Open in API Tester API Reference

Response format

Symbol removed. No response body.

curl -X DELETE 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist/%7Bsymbol%7D' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

Watchlists

Get a watchlist

Parameters

Headers

Response fields

Response codes

Add to a watchlist

Parameters

Headers

Request body

Response fields

Response codes

Remove from a watchlist

Parameters

Headers

Response fields

Response codes

On this page