# 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

<MethodTag m="GET" /> `/users/{userId}/watchlist`

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

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

```json
{ "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

<MethodTag m="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.

<ParamTable fields={[
  { name: 'symbol', type: 'string', required: true, desc: 'Ticker symbol. Exchange-qualified (SCOM.KE) preferred. Bare tickers (SCOM) are auto-resolved.' },
]} />

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

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

## Remove from a watchlist

<MethodTag m="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.

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