# Watchlist ## Get Watchlists `$ clear-street v1:watchlist get-watchlists` **get** `/v1/watchlists` List watchlists for the authenticated user ### 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 - `V1WatchlistGetWatchlistsResponse: BaseResponse` - `data: 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. ### Example ```cli clear-street v1:watchlist get-watchlists \ --api-key 'My 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 `$ clear-street v1:watchlist get-watchlist-by-id` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `--watchlist-id: string` Watchlist ID ### Returns - `V1WatchlistGetWatchlistByIDResponse: BaseResponse` - `data: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 ```cli clear-street v1:watchlist get-watchlist-by-id \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 ``` #### 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 `$ clear-street v1:watchlist create-watchlist` **post** `/v1/watchlists` Create Watchlist ### Parameters - `--name: string` The desired watchlist name. ### Returns - `V1WatchlistNewWatchlistResponse: BaseResponse` - `data: 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. ### Example ```cli clear-street v1:watchlist create-watchlist \ --api-key 'My API Key' \ --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 `$ clear-street v1:watchlist delete-watchlist` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `--watchlist-id: string` Watchlist ID ### Returns - `V1WatchlistDeleteWatchlistResponse: unknown` ### Example ```cli clear-street v1:watchlist delete-watchlist \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `$ clear-street v1:watchlist add-watchlist-item` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `--watchlist-id: string` Watchlist ID - `--instrument-id: string` OEMS instrument UUID ### Returns - `V1WatchlistAddWatchlistItemResponse: BaseResponse` - `data: object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Example ```cli clear-street v1:watchlist add-watchlist-item \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 \ --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 `$ clear-street v1:watchlist delete-watchlist-item` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `--watchlist-id: string` Watchlist ID - `--item-id: string` Item ID ### Returns - `V1WatchlistDeleteWatchlistItemResponse: unknown` ### Example ```cli clear-street v1:watchlist delete-watchlist-item \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 \ --item-id 660e8400-e29b-41d4-a716-446655440001 ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `add_watchlist_item_data: object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Detail - `watchlist_detail: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 - `watchlist_entry: 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 - `watchlist_entry_list: 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 - `watchlist_item_entry: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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