# Watchlist ## Get Watchlists `v1.watchlist.get_watchlists(WatchlistGetWatchlistsParams**kwargs) -> WatchlistGetWatchlistsResponse` **get** `/v1/watchlists` List watchlists for the authenticated user ### Parameters - `page_size: Optional[int]` The number of items to return per page. Only used when page_token is not provided. - `page_token: Optional[Union[str, Base64FileInput]]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class WatchlistGetWatchlistsResponse: …` - `data: WatchlistEntryList` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.get_watchlists() print(response) ``` #### 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 `v1.watchlist.get_watchlist_by_id(strwatchlist_id) -> WatchlistGetWatchlistByIDResponse` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `watchlist_id: str` ### Returns - `class WatchlistGetWatchlistByIDResponse: …` - `data: WatchlistDetail` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` 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[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` 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[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.get_watchlist_by_id( "550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### 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 `v1.watchlist.create_watchlist(WatchlistCreateWatchlistParams**kwargs) -> WatchlistCreateWatchlistResponse` **post** `/v1/watchlists` Create Watchlist ### Parameters - `name: str` The desired watchlist name. ### Returns - `class WatchlistCreateWatchlistResponse: …` - `data: WatchlistEntry` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.create_watchlist( name="name", ) print(response) ``` #### 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 `v1.watchlist.delete_watchlist(strwatchlist_id) -> object` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `watchlist_id: str` ### Returns - `object` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.delete_watchlist( "550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `v1.watchlist.add_watchlist_item(strwatchlist_id, WatchlistAddWatchlistItemParams**kwargs) -> WatchlistAddWatchlistItemResponse` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `watchlist_id: str` - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `class WatchlistAddWatchlistItemResponse: …` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: str` ID of the created item ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.add_watchlist_item( watchlist_id="550e8400-e29b-41d4-a716-446655440000", instrument_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response) ``` #### Response ```json { "data": { "item_id": "770e8400-e29b-41d4-a716-446655440002" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist Item `v1.watchlist.delete_watchlist_item(stritem_id, WatchlistDeleteWatchlistItemParams**kwargs) -> object` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `watchlist_id: str` - `item_id: str` ### Returns - `object` ### Example ```python from clear_street import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.watchlist.delete_watchlist_item( item_id="660e8400-e29b-41d4-a716-446655440001", watchlist_id="550e8400-e29b-41d4-a716-446655440000", ) print(response) ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `class AddWatchlistItemData: …` Response data for adding a watchlist item - `item_id: str` ID of the created item ### Watchlist Detail - `class WatchlistDetail: …` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` 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[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` 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[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Watchlist Entry - `class WatchlistEntry: …` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Entry List - `List[WatchlistEntry]` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Item Entry - `class WatchlistItemEntry: …` A single item in a watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` 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[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` 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[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments ### Watchlist Get Watchlists Response - `class WatchlistGetWatchlistsResponse: …` - `data: WatchlistEntryList` - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Get Watchlist By ID Response - `class WatchlistGetWatchlistByIDResponse: …` - `data: WatchlistDetail` Detailed watchlist with all items - `id: str` Watchlist ID - `created_at: datetime` Creation timestamp - `items: List[WatchlistItemEntry]` Items in the watchlist - `id: str` Item ID - `added_at: datetime` When the item was added - `added_price: Optional[str]` Price when the item was added - `instrument: Optional[Instrument]` Instrument details - `id: str` Unique OEMS instrument identifier (UUID) - `country_of_issue: str` The ISO country code of the instrument's issue - `currency: str` The ISO currency code in which the instrument is traded - `easy_to_borrow: bool` Indicates if the instrument is classified as Easy-To-Borrow - `is_liquidation_only: bool` Indicates if the instrument is liquidation only and cannot be bought - `is_marginable: bool` Indicates if the instrument is marginable - `is_restricted: bool` Indicates if the instrument is restricted from trading - `is_short_prohibited: bool` Indicates if short selling is prohibited for the instrument - `is_threshold_security: bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `is_tradable: bool` Indicates if the instrument is tradable - `symbol: str` The trading symbol for the instrument - `venue: str` The MIC code of the primary listing venue - `adv: Optional[str]` Average daily share volume from the security definition. - `expiry: Optional[date]` 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[str]` The percent of a long position's value you must post as margin - `name: Optional[str]` The full name of the instrument or its issuer - `notional_adv: Optional[str]` 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[List[date]]` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `previous_close: Optional[str]` Last close price from the security definition. - `short_margin_rate: Optional[str]` The percent of a short position's value you must post as margin - `strike_price: Optional[str]` The strike price for options instruments - `name: str` Watchlist name ### Watchlist Create Watchlist Response - `class WatchlistCreateWatchlistResponse: …` - `data: WatchlistEntry` Represents a user watchlist. - `id: str` The unique identifier for the watchlist. - `created_at: datetime` The timestamp when the watchlist was created. - `name: str` The user-provided watchlist name. ### Watchlist Add Watchlist Item Response - `class WatchlistAddWatchlistItemResponse: …` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: str` ID of the created item