# Watchlist ## Get Watchlists `client.V1.Watchlist.GetWatchlists(ctx, query) (*V1WatchlistGetWatchlistsResponse, error)` **get** `/v1/watchlists` List watchlists for the authenticated user ### Parameters - `query V1WatchlistGetWatchlistsParams` - `PageSize param.Field[int64]` The number of items to return per page. Only used when page_token is not provided. - `PageToken param.Field[string]` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `type V1WatchlistGetWatchlistsResponse struct{…}` - `Data WatchlistEntryList` - `ID string` The unique identifier for the watchlist. - `CreatedAt Time` The timestamp when the watchlist was created. - `Name string` The user-provided watchlist name. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.GetWatchlists(context.TODO(), clearstreet.V1WatchlistGetWatchlistsParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Watchlist.GetWatchlistByID(ctx, watchlistID) (*V1WatchlistGetWatchlistByIDResponse, error)` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `watchlistID string` ### Returns - `type V1WatchlistGetWatchlistByIDResponse struct{…}` - `Data WatchlistDetail` Detailed watchlist with all items - `ID string` Watchlist ID - `CreatedAt Time` Creation timestamp - `Items []WatchlistItemEntry` Items in the watchlist - `ID string` Item ID - `AddedAt Time` When the item was added - `AddedPrice string` Price when the item was added - `Instrument Instrument` Instrument details - `ID string` Unique OEMS instrument identifier (UUID) - `CountryOfIssue string` The ISO country code of the instrument's issue - `Currency string` The ISO currency code in which the instrument is traded - `EasyToBorrow bool` Indicates if the instrument is classified as Easy-To-Borrow - `IsLiquidationOnly bool` Indicates if the instrument is liquidation only and cannot be bought - `IsMarginable bool` Indicates if the instrument is marginable - `IsRestricted bool` Indicates if the instrument is restricted from trading - `IsShortProhibited bool` Indicates if short selling is prohibited for the instrument - `IsThresholdSecurity bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `IsTradable bool` 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 string` Average daily share volume from the security definition. - `Expiry Time` The expiration date for options instruments - `InstrumentType SecurityType` The type of security (e.g., Common Stock, ETF) - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `LongMarginRate string` The percent of a long position's value you must post as margin - `Name string` The full name of the instrument or its issuer - `NotionalAdv 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. - `OptionsExpiryDates []Time` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `PreviousClose string` Last close price from the security definition. - `ShortMarginRate string` The percent of a short position's value you must post as margin - `StrikePrice string` The strike price for options instruments - `Name string` Watchlist name ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.GetWatchlistByID(context.TODO(), "550e8400-e29b-41d4-a716-446655440000") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Watchlist.NewWatchlist(ctx, body) (*V1WatchlistNewWatchlistResponse, error)` **post** `/v1/watchlists` Create Watchlist ### Parameters - `body V1WatchlistNewWatchlistParams` - `Name param.Field[string]` The desired watchlist name. ### Returns - `type V1WatchlistNewWatchlistResponse struct{…}` - `Data WatchlistEntry` Represents a user watchlist. - `ID string` The unique identifier for the watchlist. - `CreatedAt Time` The timestamp when the watchlist was created. - `Name string` The user-provided watchlist name. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.NewWatchlist(context.TODO(), clearstreet.V1WatchlistNewWatchlistParams{ Name: "name", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Watchlist.DeleteWatchlist(ctx, watchlistID) (*V1WatchlistDeleteWatchlistResponse, error)` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `watchlistID string` ### Returns - `type V1WatchlistDeleteWatchlistResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.DeleteWatchlist(context.TODO(), "550e8400-e29b-41d4-a716-446655440000") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `client.V1.Watchlist.AddWatchlistItem(ctx, watchlistID, body) (*V1WatchlistAddWatchlistItemResponse, error)` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `watchlistID string` - `body V1WatchlistAddWatchlistItemParams` - `InstrumentID param.Field[InstrumentIDOrSymbol]` OEMS instrument UUID ### Returns - `type V1WatchlistAddWatchlistItemResponse struct{…}` - `Data AddWatchlistItemData` Response data for adding a watchlist item - `ItemID string` ID of the created item ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.AddWatchlistItem( context.TODO(), "550e8400-e29b-41d4-a716-446655440000", clearstreet.V1WatchlistAddWatchlistItemParams{ InstrumentID: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json { "data": { "item_id": "770e8400-e29b-41d4-a716-446655440002" }, "error": null, "metadata": { "request_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg" } } ``` ## Delete Watchlist Item `client.V1.Watchlist.DeleteWatchlistItem(ctx, itemID, body) (*V1WatchlistDeleteWatchlistItemResponse, error)` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `itemID string` - `body V1WatchlistDeleteWatchlistItemParams` - `WatchlistID param.Field[string]` Watchlist ID ### Returns - `type V1WatchlistDeleteWatchlistItemResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Watchlist.DeleteWatchlistItem( context.TODO(), "660e8400-e29b-41d4-a716-446655440001", clearstreet.V1WatchlistDeleteWatchlistItemParams{ WatchlistID: "550e8400-e29b-41d4-a716-446655440000", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `type AddWatchlistItemData struct{…}` Response data for adding a watchlist item - `ItemID string` ID of the created item ### Watchlist Detail - `type WatchlistDetail struct{…}` Detailed watchlist with all items - `ID string` Watchlist ID - `CreatedAt Time` Creation timestamp - `Items []WatchlistItemEntry` Items in the watchlist - `ID string` Item ID - `AddedAt Time` When the item was added - `AddedPrice string` Price when the item was added - `Instrument Instrument` Instrument details - `ID string` Unique OEMS instrument identifier (UUID) - `CountryOfIssue string` The ISO country code of the instrument's issue - `Currency string` The ISO currency code in which the instrument is traded - `EasyToBorrow bool` Indicates if the instrument is classified as Easy-To-Borrow - `IsLiquidationOnly bool` Indicates if the instrument is liquidation only and cannot be bought - `IsMarginable bool` Indicates if the instrument is marginable - `IsRestricted bool` Indicates if the instrument is restricted from trading - `IsShortProhibited bool` Indicates if short selling is prohibited for the instrument - `IsThresholdSecurity bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `IsTradable bool` 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 string` Average daily share volume from the security definition. - `Expiry Time` The expiration date for options instruments - `InstrumentType SecurityType` The type of security (e.g., Common Stock, ETF) - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `LongMarginRate string` The percent of a long position's value you must post as margin - `Name string` The full name of the instrument or its issuer - `NotionalAdv 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. - `OptionsExpiryDates []Time` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `PreviousClose string` Last close price from the security definition. - `ShortMarginRate string` The percent of a short position's value you must post as margin - `StrikePrice string` The strike price for options instruments - `Name string` Watchlist name ### Watchlist Entry - `type WatchlistEntry struct{…}` Represents a user watchlist. - `ID string` The unique identifier for the watchlist. - `CreatedAt Time` The timestamp when the watchlist was created. - `Name string` The user-provided watchlist name. ### Watchlist Entry List - `type WatchlistEntryList []WatchlistEntry` - `ID string` The unique identifier for the watchlist. - `CreatedAt Time` The timestamp when the watchlist was created. - `Name string` The user-provided watchlist name. ### Watchlist Item Entry - `type WatchlistItemEntry struct{…}` A single item in a watchlist - `ID string` Item ID - `AddedAt Time` When the item was added - `AddedPrice string` Price when the item was added - `Instrument Instrument` Instrument details - `ID string` Unique OEMS instrument identifier (UUID) - `CountryOfIssue string` The ISO country code of the instrument's issue - `Currency string` The ISO currency code in which the instrument is traded - `EasyToBorrow bool` Indicates if the instrument is classified as Easy-To-Borrow - `IsLiquidationOnly bool` Indicates if the instrument is liquidation only and cannot be bought - `IsMarginable bool` Indicates if the instrument is marginable - `IsRestricted bool` Indicates if the instrument is restricted from trading - `IsShortProhibited bool` Indicates if short selling is prohibited for the instrument - `IsThresholdSecurity bool` Indicates if the instrument is on the Regulation SHO Threshold Security List - `IsTradable bool` 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 string` Average daily share volume from the security definition. - `Expiry Time` The expiration date for options instruments - `InstrumentType SecurityType` The type of security (e.g., Common Stock, ETF) - `const SecurityTypeCommonStock SecurityType = "COMMON_STOCK"` - `const SecurityTypePreferredStock SecurityType = "PREFERRED_STOCK"` - `const SecurityTypeOption SecurityType = "OPTION"` - `const SecurityTypeCash SecurityType = "CASH"` - `const SecurityTypeOther SecurityType = "OTHER"` - `LongMarginRate string` The percent of a long position's value you must post as margin - `Name string` The full name of the instrument or its issuer - `NotionalAdv 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. - `OptionsExpiryDates []Time` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `PreviousClose string` Last close price from the security definition. - `ShortMarginRate string` The percent of a short position's value you must post as margin - `StrikePrice string` The strike price for options instruments