Skip to content
Clear Street Clear Street
Start Trading
API Reference
V1

Watchlist

Create and manage watchlists.

Get Watchlists
v1.watchlist.get_watchlists(WatchlistGetWatchlistsParams**kwargs) -> WatchlistGetWatchlistsResponse
GET/v1/watchlists
Get Watchlist By ID
v1.watchlist.get_watchlist_by_id(strwatchlist_id) -> WatchlistGetWatchlistByIDResponse
GET/v1/watchlists/{watchlist_id}
Create Watchlist
v1.watchlist.create_watchlist(WatchlistCreateWatchlistParams**kwargs) -> WatchlistCreateWatchlistResponse
POST/v1/watchlists
Delete Watchlist
v1.watchlist.delete_watchlist(strwatchlist_id) -> WatchlistDeleteWatchlistResponse
DELETE/v1/watchlists/{watchlist_id}
Add Watchlist Item
v1.watchlist.add_watchlist_item(strwatchlist_id, WatchlistAddWatchlistItemParams**kwargs) -> WatchlistAddWatchlistItemResponse
POST/v1/watchlists/{watchlist_id}/items
Delete Watchlist Item
v1.watchlist.delete_watchlist_item(stritem_id, WatchlistDeleteWatchlistItemParams**kwargs) -> WatchlistDeleteWatchlistItemResponse
DELETE/v1/watchlists/{watchlist_id}/items/{item_id}
ModelsExpand Collapse
class AddWatchlistItemData: …

Response data for adding a watchlist item

item_id: str

ID of the created item

formatuuid
class WatchlistDetail: …

Detailed watchlist with all items

id: str

Watchlist ID

formatuuid
created_at: datetime

Creation timestamp

formatdate-time
items: List[WatchlistItemEntry]

Items in the watchlist

id: str

Item ID

formatuuid
added_at: datetime

When the item was added

formatdate-time
added_price: Optional[str]

Price when the item was added When a null/undefined value is observed, it indicates that there is no available data.

instrument: Optional[Instrument]

Instrument details When a null/undefined value is observed, it indicates that there is no available data.

id: str

Unique instrument identifier (UUID)

formatuuid
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_fractionable: bool

Indicates if the instrument supports fractional-quantity orders

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_ptp: bool

Indicates if the instrument is a publicly traded partnership (PTP). PTP sales are subject to a 10% withholding tax for non-US tax residents.

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. When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedexpiry: Optional[date]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

formatdate
instrument_type: Optional[SecurityType]

The type of security (e.g., Common Stock, ETF) When a null/undefined value is observed, it indicates that there is no available data.

One of the following:
"COMMON_STOCK"
"OPTION"
"CASH"
long_margin_rate: Optional[str]

The percent of a long position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

name: Optional[str]

The full name of the instrument or its issuer When a null/undefined value is observed, it indicates that there is no available data.

notional_adv: Optional[str]

Notional average daily volume (ADV multiplied by previous close price). When a null/undefined value is observed, it indicates that there is no available data.

options_expiry_dates: Optional[List[date]]

Available options expiration dates for this instrument. Present only when include_options_expiry_dates=true in the request. When a null/undefined value is observed, it indicates it does not apply.

previous_close: Optional[str]

Last close price from the security definition. When a null/undefined value is observed, it indicates that there is no available data.

short_margin_rate: Optional[str]

The percent of a short position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedstrike_price: Optional[str]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

name: str

Watchlist name

class WatchlistEntry: …

Represents a user watchlist.

id: str

The unique identifier for the watchlist.

formatuuid
created_at: datetime

The timestamp when the watchlist was created.

formatdate-time
name: str

The user-provided watchlist name.

List[WatchlistEntry]
id: str

The unique identifier for the watchlist.

formatuuid
created_at: datetime

The timestamp when the watchlist was created.

formatdate-time
name: str

The user-provided watchlist name.

class WatchlistItemEntry: …

A single item in a watchlist

id: str

Item ID

formatuuid
added_at: datetime

When the item was added

formatdate-time
added_price: Optional[str]

Price when the item was added When a null/undefined value is observed, it indicates that there is no available data.

instrument: Optional[Instrument]

Instrument details When a null/undefined value is observed, it indicates that there is no available data.

id: str

Unique instrument identifier (UUID)

formatuuid
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_fractionable: bool

Indicates if the instrument supports fractional-quantity orders

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_ptp: bool

Indicates if the instrument is a publicly traded partnership (PTP). PTP sales are subject to a 10% withholding tax for non-US tax residents.

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. When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedexpiry: Optional[date]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

formatdate
instrument_type: Optional[SecurityType]

The type of security (e.g., Common Stock, ETF) When a null/undefined value is observed, it indicates that there is no available data.

One of the following:
"COMMON_STOCK"
"OPTION"
"CASH"
long_margin_rate: Optional[str]

The percent of a long position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

name: Optional[str]

The full name of the instrument or its issuer When a null/undefined value is observed, it indicates that there is no available data.

notional_adv: Optional[str]

Notional average daily volume (ADV multiplied by previous close price). When a null/undefined value is observed, it indicates that there is no available data.

options_expiry_dates: Optional[List[date]]

Available options expiration dates for this instrument. Present only when include_options_expiry_dates=true in the request. When a null/undefined value is observed, it indicates it does not apply.

previous_close: Optional[str]

Last close price from the security definition. When a null/undefined value is observed, it indicates that there is no available data.

short_margin_rate: Optional[str]

The percent of a short position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedstrike_price: Optional[str]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

class WatchlistGetWatchlistsResponse: …
id: str

The unique identifier for the watchlist.

formatuuid
created_at: datetime

The timestamp when the watchlist was created.

formatdate-time
name: str

The user-provided watchlist name.

class WatchlistGetWatchlistByIDResponse: …

Detailed watchlist with all items

id: str

Watchlist ID

formatuuid
created_at: datetime

Creation timestamp

formatdate-time
items: List[WatchlistItemEntry]

Items in the watchlist

id: str

Item ID

formatuuid
added_at: datetime

When the item was added

formatdate-time
added_price: Optional[str]

Price when the item was added When a null/undefined value is observed, it indicates that there is no available data.

instrument: Optional[Instrument]

Instrument details When a null/undefined value is observed, it indicates that there is no available data.

id: str

Unique instrument identifier (UUID)

formatuuid
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_fractionable: bool

Indicates if the instrument supports fractional-quantity orders

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_ptp: bool

Indicates if the instrument is a publicly traded partnership (PTP). PTP sales are subject to a 10% withholding tax for non-US tax residents.

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. When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedexpiry: Optional[date]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

formatdate
instrument_type: Optional[SecurityType]

The type of security (e.g., Common Stock, ETF) When a null/undefined value is observed, it indicates that there is no available data.

One of the following:
"COMMON_STOCK"
"OPTION"
"CASH"
long_margin_rate: Optional[str]

The percent of a long position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

name: Optional[str]

The full name of the instrument or its issuer When a null/undefined value is observed, it indicates that there is no available data.

notional_adv: Optional[str]

Notional average daily volume (ADV multiplied by previous close price). When a null/undefined value is observed, it indicates that there is no available data.

options_expiry_dates: Optional[List[date]]

Available options expiration dates for this instrument. Present only when include_options_expiry_dates=true in the request. When a null/undefined value is observed, it indicates it does not apply.

previous_close: Optional[str]

Last close price from the security definition. When a null/undefined value is observed, it indicates that there is no available data.

short_margin_rate: Optional[str]

The percent of a short position’s value you must post as margin When a null/undefined value is observed, it indicates that there is no available data.

Deprecatedstrike_price: Optional[str]

Deprecated. Always null. When a null/undefined value is observed, it indicates it does not apply.

name: str

Watchlist name

class WatchlistCreateWatchlistResponse: …

Represents a user watchlist.

id: str

The unique identifier for the watchlist.

formatuuid
created_at: datetime

The timestamp when the watchlist was created.

formatdate-time
name: str

The user-provided watchlist name.

class WatchlistDeleteWatchlistResponse: …
data: None
class WatchlistAddWatchlistItemResponse: …

Response data for adding a watchlist item

item_id: str

ID of the created item

formatuuid
class WatchlistDeleteWatchlistItemResponse: …
data: None