# Watchlist ## Get Watchlists `WatchlistGetWatchlistsResponse v1().watchlist().getWatchlists(WatchlistGetWatchlistsParamsparams = WatchlistGetWatchlistsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/watchlists` List watchlists for the authenticated user ### Parameters - `WatchlistGetWatchlistsParams params` - `Optional pageSize` The number of items to return per page. Only used when page_token is not provided. - `Optional pageToken` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class WatchlistGetWatchlistsResponse:` - `List data` - `String id` The unique identifier for the watchlist. - `LocalDateTime createdAt` The timestamp when the watchlist was created. - `String name` The user-provided watchlist name. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistGetWatchlistsParams; import com.clear_street.api.models.v1.watchlist.WatchlistGetWatchlistsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistGetWatchlistsResponse response = client.v1().watchlist().getWatchlists(); } } ``` #### 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 `WatchlistGetWatchlistByIdResponse v1().watchlist().getWatchlistById(WatchlistGetWatchlistByIdParamsparams = WatchlistGetWatchlistByIdParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `WatchlistGetWatchlistByIdParams params` - `Optional watchlistId` ### Returns - `class WatchlistGetWatchlistByIdResponse:` - `WatchlistDetail data` Detailed watchlist with all items - `String id` Watchlist ID - `LocalDateTime createdAt` Creation timestamp - `List items` Items in the watchlist - `String id` Item ID - `LocalDateTime addedAt` When the item was added - `Optional addedPrice` Price when the item was added - `Optional instrument` Instrument details - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional> optionsExpiryDates` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments - `String name` Watchlist name ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistGetWatchlistByIdParams; import com.clear_street.api.models.v1.watchlist.WatchlistGetWatchlistByIdResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistGetWatchlistByIdResponse response = client.v1().watchlist().getWatchlistById("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 `WatchlistCreateWatchlistResponse v1().watchlist().createWatchlist(WatchlistCreateWatchlistParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/v1/watchlists` Create Watchlist ### Parameters - `WatchlistCreateWatchlistParams params` - `String name` The desired watchlist name. ### Returns - `class WatchlistCreateWatchlistResponse:` - `WatchlistEntry data` Represents a user watchlist. - `String id` The unique identifier for the watchlist. - `LocalDateTime createdAt` The timestamp when the watchlist was created. - `String name` The user-provided watchlist name. ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistCreateWatchlistParams; import com.clear_street.api.models.v1.watchlist.WatchlistCreateWatchlistResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistCreateWatchlistParams params = WatchlistCreateWatchlistParams.builder() .name("name") .build(); WatchlistCreateWatchlistResponse response = client.v1().watchlist().createWatchlist(params); } } ``` #### 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 `JsonValue v1().watchlist().deleteWatchlist(WatchlistDeleteWatchlistParamsparams = WatchlistDeleteWatchlistParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `WatchlistDeleteWatchlistParams params` - `Optional watchlistId` ### Returns - `class WatchlistDeleteWatchlistResponse:` ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistDeleteWatchlistParams; import com.clear_street.api.models.v1.watchlist.WatchlistDeleteWatchlistResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistDeleteWatchlistResponse response = client.v1().watchlist().deleteWatchlist("550e8400-e29b-41d4-a716-446655440000"); } } ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `WatchlistAddWatchlistItemResponse v1().watchlist().addWatchlistItem(WatchlistAddWatchlistItemParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `WatchlistAddWatchlistItemParams params` - `Optional watchlistId` - `String instrumentId` OEMS instrument UUID ### Returns - `class WatchlistAddWatchlistItemResponse:` - `AddWatchlistItemData data` Response data for adding a watchlist item - `String itemId` ID of the created item ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistAddWatchlistItemParams; import com.clear_street.api.models.v1.watchlist.WatchlistAddWatchlistItemResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistAddWatchlistItemParams params = WatchlistAddWatchlistItemParams.builder() .watchlistId("550e8400-e29b-41d4-a716-446655440000") .instrumentId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") .build(); WatchlistAddWatchlistItemResponse response = client.v1().watchlist().addWatchlistItem(params); } } ``` #### Response ```json { "data": { "item_id": "770e8400-e29b-41d4-a716-446655440002" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist Item `JsonValue v1().watchlist().deleteWatchlistItem(WatchlistDeleteWatchlistItemParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `WatchlistDeleteWatchlistItemParams params` - `String watchlistId` - `Optional itemId` ### Returns - `class WatchlistDeleteWatchlistItemResponse:` ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.watchlist.WatchlistDeleteWatchlistItemParams; import com.clear_street.api.models.v1.watchlist.WatchlistDeleteWatchlistItemResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); WatchlistDeleteWatchlistItemParams params = WatchlistDeleteWatchlistItemParams.builder() .watchlistId("550e8400-e29b-41d4-a716-446655440000") .itemId("660e8400-e29b-41d4-a716-446655440001") .build(); WatchlistDeleteWatchlistItemResponse response = client.v1().watchlist().deleteWatchlistItem(params); } } ``` #### 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 - `String itemId` ID of the created item ### Watchlist Detail - `class WatchlistDetail:` Detailed watchlist with all items - `String id` Watchlist ID - `LocalDateTime createdAt` Creation timestamp - `List items` Items in the watchlist - `String id` Item ID - `LocalDateTime addedAt` When the item was added - `Optional addedPrice` Price when the item was added - `Optional instrument` Instrument details - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional> optionsExpiryDates` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments - `String name` Watchlist name ### Watchlist Entry - `class WatchlistEntry:` Represents a user watchlist. - `String id` The unique identifier for the watchlist. - `LocalDateTime createdAt` The timestamp when the watchlist was created. - `String name` The user-provided watchlist name. ### Watchlist Item Entry - `class WatchlistItemEntry:` A single item in a watchlist - `String id` Item ID - `LocalDateTime addedAt` When the item was added - `Optional addedPrice` Price when the item was added - `Optional instrument` Instrument details - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional> optionsExpiryDates` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments