Watchlists

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

GET /users/{userId}/watchlist

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

curl https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist \
  -H "x-api-key: pk_live_KEY"

{ "data": [{ "assetId": "scom_ke_01", "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "sourceType": "LISTED_STOCK", "price": 16.25, "usdPrice": 0.1258, "change": 1.56, "currency": "KES", "addedAt": "2026-06-06T08:00:00Z" }], "count": 1 }

Add to a watchlist

POST /users/{userId}/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.

curl -X POST https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist \
  -H "x-api-key: pk_live_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"SCOM.KE"}'

{ "assetId": "scom_ke_01", "symbol": "SCOM.KE", "name": "Safaricom PLC", "exchange": "NSE", "addedAt": "2026-06-06T08:00:00Z" }

Remove from a watchlist

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

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

curl -X DELETE https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist/SCOM.KE \
  -H "x-api-key: pk_live_KEY"