# Watchlist ## Get Watchlists **get** `/v1/watchlists` List watchlists for the authenticated user ### Query Parameters - `page_size: optional number` The number of items to return per page. Only used when page_token is not provided. - `page_token: optional string` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `data: WatchlistEntryList` - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Example ```http curl https://api.clearstreet.com/v1/watchlists \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "created_at": "2025-01-15T10:00:00.000000000Z", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Tech Stocks" }, { "created_at": "2025-01-10T14:30:00.000000000Z", "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Dividend Portfolio" } ], "error": null, "metadata": { "next_page_token": null, "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "total_items": 2, "total_pages": 1 } } ``` ## Get Watchlist By ID **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Path Parameters - `watchlist_id: string` ### Returns - `data: WatchlistDetail` Detailed watchlist with all items - `id: string` Watchlist ID - `created_at: string` Creation timestamp - `items: array of WatchlistItemEntry` Items in the watchlist - `id: string` Item ID - `added_at: string` When the item was added - `added_price: optional string` Price when the item was added - `instrument: optional Instrument` Instrument details - `id: string` Unique OEMS instrument identifier (UUID) - `country_of_issue: string` The ISO country code of the instrument's issue - `currency: string` The ISO currency code in which the instrument is traded - `easy_to_borrow: boolean` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: boolean` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: boolean` Indicates if the instrument is marginable - `is_restricted: boolean` Indicates if the instrument is restricted from trading - `is_short_prohibited: boolean` Indicates if short selling is prohibited for the instrument - `is_threshold_security: boolean` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: boolean` Indicates if the instrument is tradable - `symbol: string` The trading symbol for the instrument - `venue: string` The MIC code of the primary listing venue - `adv: optional string` Average daily share volume from the security definition. - `expiry: optional string` The expiration date for options instruments - `instrument_type: optional SecurityType` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: optional string` The percent of a long position's value you must post as margin - `name: optional string` The full name of the instrument or its issuer - `notional_adv: optional string` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: optional array of string` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: optional string` Last close price from the security definition. - `short_margin_rate: optional string` The percent of a short position's value you must post as margin - `strike_price: optional string` The strike price for options instruments - `name: string` Watchlist name ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "created_at": "2025-01-15T10:00:00.000000000Z", "id": "550e8400-e29b-41d4-a716-446655440000", "items": [ { "added_at": "2025-01-16T09:30:00.000000000Z", "added_price": "150.25", "id": "660e8400-e29b-41d4-a716-446655440001", "instrument": { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_short_prohibited": false, "is_threshold_security": false, "is_tradable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } } ], "name": "Tech Stocks" }, "error": null, "metadata": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } } ``` ## Create Watchlist **post** `/v1/watchlists` Create Watchlist ### Body Parameters - `name: string` The desired watchlist name. ### Returns - `data: WatchlistEntry` Represents a user watchlist. - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Example ```http curl https://api.clearstreet.com/v1/watchlists \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "name": "name" }' ``` #### Response ```json { "data": { "created_at": "2025-01-23T12:00:00.000000000Z", "id": "770e8400-e29b-41d4-a716-446655440002", "name": "Growth Stocks" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Path Parameters - `watchlist_id: string` ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Path Parameters - `watchlist_id: string` ### Body Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID/items \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "instrument_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }' ``` #### Response ```json { "data": { "item_id": "770e8400-e29b-41d4-a716-446655440002" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist Item **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Path Parameters - `watchlist_id: string` - `item_id: string` ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID/items/$ITEM_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `AddWatchlistItemData object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Detail - `WatchlistDetail object { id, created_at, items, name }` Detailed watchlist with all items - `id: string` Watchlist ID - `created_at: string` Creation timestamp - `items: array of WatchlistItemEntry` Items in the watchlist - `id: string` Item ID - `added_at: string` When the item was added - `added_price: optional string` Price when the item was added - `instrument: optional Instrument` Instrument details - `id: string` Unique OEMS instrument identifier (UUID) - `country_of_issue: string` The ISO country code of the instrument's issue - `currency: string` The ISO currency code in which the instrument is traded - `easy_to_borrow: boolean` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: boolean` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: boolean` Indicates if the instrument is marginable - `is_restricted: boolean` Indicates if the instrument is restricted from trading - `is_short_prohibited: boolean` Indicates if short selling is prohibited for the instrument - `is_threshold_security: boolean` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: boolean` Indicates if the instrument is tradable - `symbol: string` The trading symbol for the instrument - `venue: string` The MIC code of the primary listing venue - `adv: optional string` Average daily share volume from the security definition. - `expiry: optional string` The expiration date for options instruments - `instrument_type: optional SecurityType` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: optional string` The percent of a long position's value you must post as margin - `name: optional string` The full name of the instrument or its issuer - `notional_adv: optional string` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: optional array of string` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: optional string` Last close price from the security definition. - `short_margin_rate: optional string` The percent of a short position's value you must post as margin - `strike_price: optional string` The strike price for options instruments - `name: string` Watchlist name ### Watchlist Entry - `WatchlistEntry object { id, created_at, name }` Represents a user watchlist. - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Watchlist Entry List - `WatchlistEntryList = array of WatchlistEntry` - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Watchlist Item Entry - `WatchlistItemEntry object { id, added_at, added_price, instrument }` A single item in a watchlist - `id: string` Item ID - `added_at: string` When the item was added - `added_price: optional string` Price when the item was added - `instrument: optional Instrument` Instrument details - `id: string` Unique OEMS instrument identifier (UUID) - `country_of_issue: string` The ISO country code of the instrument's issue - `currency: string` The ISO currency code in which the instrument is traded - `easy_to_borrow: boolean` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: boolean` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: boolean` Indicates if the instrument is marginable - `is_restricted: boolean` Indicates if the instrument is restricted from trading - `is_short_prohibited: boolean` Indicates if short selling is prohibited for the instrument - `is_threshold_security: boolean` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: boolean` Indicates if the instrument is tradable - `symbol: string` The trading symbol for the instrument - `venue: string` The MIC code of the primary listing venue - `adv: optional string` Average daily share volume from the security definition. - `expiry: optional string` The expiration date for options instruments - `instrument_type: optional SecurityType` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: optional string` The percent of a long position's value you must post as margin - `name: optional string` The full name of the instrument or its issuer - `notional_adv: optional string` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: optional array of string` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: optional string` Last close price from the security definition. - `short_margin_rate: optional string` The percent of a short position's value you must post as margin - `strike_price: optional string` The strike price for options instruments ### Watchlist Get Watchlists Response - `WatchlistGetWatchlistsResponse = BaseResponse` - `data: WatchlistEntryList` - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Watchlist Get Watchlist By ID Response - `WatchlistGetWatchlistByIDResponse = BaseResponse` - `data: WatchlistDetail` Detailed watchlist with all items - `id: string` Watchlist ID - `created_at: string` Creation timestamp - `items: array of WatchlistItemEntry` Items in the watchlist - `id: string` Item ID - `added_at: string` When the item was added - `added_price: optional string` Price when the item was added - `instrument: optional Instrument` Instrument details - `id: string` Unique OEMS instrument identifier (UUID) - `country_of_issue: string` The ISO country code of the instrument's issue - `currency: string` The ISO currency code in which the instrument is traded - `easy_to_borrow: boolean` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: boolean` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: boolean` Indicates if the instrument is marginable - `is_restricted: boolean` Indicates if the instrument is restricted from trading - `is_short_prohibited: boolean` Indicates if short selling is prohibited for the instrument - `is_threshold_security: boolean` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: boolean` Indicates if the instrument is tradable - `symbol: string` The trading symbol for the instrument - `venue: string` The MIC code of the primary listing venue - `adv: optional string` Average daily share volume from the security definition. - `expiry: optional string` The expiration date for options instruments - `instrument_type: optional SecurityType` The type of security (e.g., Common Stock, ETF) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `long_margin_rate: optional string` The percent of a long position's value you must post as margin - `name: optional string` The full name of the instrument or its issuer - `notional_adv: optional string` Notional ADV (`adv × previous_close`). The primary liquidity signal used by `/instruments/search` ranking. Computed at response time so it stays consistent with whatever `adv` and `previous_close` show. - `options_expiry_dates: optional array of string` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: optional string` Last close price from the security definition. - `short_margin_rate: optional string` The percent of a short position's value you must post as margin - `strike_price: optional string` The strike price for options instruments - `name: string` Watchlist name ### Watchlist Create Watchlist Response - `WatchlistCreateWatchlistResponse = BaseResponse` - `data: WatchlistEntry` Represents a user watchlist. - `id: string` The unique identifier for the watchlist. - `created_at: string` The timestamp when the watchlist was created. - `name: string` The user-provided watchlist name. ### Watchlist Delete Watchlist Response - `WatchlistDeleteWatchlistResponse = unknown` ### Watchlist Add Watchlist Item Response - `WatchlistAddWatchlistItemResponse = BaseResponse` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Delete Watchlist Item Response - `WatchlistDeleteWatchlistItemResponse = unknown`