Add card + grade combinations to your price watchlist.

Watched cards' price changes flow through POST /v1/cards/watchlist-updates. Omit grade_label to watch all grades for a card (one watchlist slot). Adding is idempotent: entries already on the list return success with a note.

Request fields:

• items — list, required. 1-100 entries per request.
• items[].card_id — string, required. CardHedge card ID (from card-search, card-match, etc.), or "*" for watch-all (Elite and Enterprise only; see Watching the whole catalog below).
• items[].grade_label — string, optional. Grade exactly as used across the API (e.g. "PSA 10", "Raw"). Omit to watch all grades.

Behavior

• Always returns HTTP 200 with per-item results — an unknown card_id or an invalid item fails individually without affecting the rest of the batch. Check results[].success and results[].error.
• Idempotent: re-adding an existing entry succeeds with note: "already on watchlist" and does not consume another slot.
• Redundancy notes: adding a specific grade when an all-grades entry already covers that card succeeds, with a note saying so.
• Tier caps: total watchlist size is capped by subscription tier (Unlimited + API and Pro 1,000; Elite and Enterprise 10,000). Exceeding the cap fails the whole request with HTTP 400 — remove entries or upgrade.
• watchlist_size and watchlist_cap in the response tell you where you stand.

Watching the whole catalog (watch-all)

To receive every price change for every card, add the "*" entry instead of listing cards (Elite and Enterprise tiers only; other tiers get a per-item error):

curl -X POST -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"items": [{"card_id": "*"}]}' \
     "https://api.cardhedger.com/v1/cards/watchlist"

• It uses one watchlist slot and cannot carry a grade_label.
• watchlist-updates then carries every change across the catalog — thousands an hour — so keep looping while has_more is true.
• Start with from_now. A first call without a cursor walks the entire catalog from the beginning (millions of rows, thousands of pages). Send {"from_now": true} instead, or {"from_time": "<ISO 8601 time>"} to start at a point in time, then poll with the cursor you get back. Skip this only if you want that full snapshot.
• include_fmv works on a watch-all key once you are caught up; see watchlist-updates.
• To stop, DELETE /v1/cards/watchlist with {"items": [{"card_id": "*"}]} (or {"clear_all": true}).

Example

curl -X POST -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"items": [{"card_id": "1586812246197x228181943611293700", "grade_label": "PSA 10"}]}' \
     "https://api.cardhedger.com/v1/cards/watchlist"