openapi: 3.2.0
info:
title: Clear Street Trading Watchlist API
description: 'A unified, secure, and high-performance RESTful API for all client interactions with the Active trading platform.
This specification provides a single source of truth for the API surface, covering order management, trade execution, market data, and account services.
### Authentication
All endpoints require authentication via a JWT Bearer token provided in the `Authorization` header.
### Response Structure
All responses, both for success and error, adhere to a standard envelope structure:
- `data`: Contains the response payload on success, or `null` on error.
- `error`: Contains a structured error object on failure, or `null` on success.
- `metadata`: Contains the `request_id` and pagination information.
### WebSockets
Real-time market data is available via WebSocket connections, which are not formally described in this OpenAPI specification. The following operations are available:
- `market-data-l1-subscribe`: To start receiving L1 market data updates for a set of symbols.
- `market-data-l1-unsubscribe`: To stop receiving L1 market data updates.'
contact:
name: Clear Street API Support
url: https://clearstreet.io/contact
email: concierge@clearstreet.com
license:
name: Proprietary
url: https://clearstreet.io/terms
version: 2025-10-31
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
security:
- BearerAuth: []
tags:
- name: Watchlist
description: Create and manage watchlists.
paths:
/v1/watchlists:
get:
tags:
- Watchlist
summary: Get Watchlists
description: List watchlists for the authenticated user
operationId: get_watchlists
parameters:
- name: page_size
in: query
description: The number of items to return per page. Only used when page_token is not provided.
required: false
schema:
type: integer
format: int64
default: 1000
maximum: 1000
minimum: 1
- name: page_token
in: query
description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
required: false
schema:
type: string
format: byte
description: Base64URL-encoded pagination token
example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
responses:
'200':
description: List of watchlists
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/WatchlistEntryList'
type: object
examples:
WatchlistList:
summary: List of user's watchlists
value:
data:
- created_at: 2025-01-15 10:00:00+00:00
id: 550e8400-e29b-41d4-a716-446655440000
name: Tech Stocks
- created_at: 2025-01-10 14:30:00+00:00
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
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
post:
tags:
- Watchlist
summary: Create Watchlist
operationId: create_watchlist
requestBody:
description: Watchlist configuration
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWatchlistRequest'
required: true
responses:
'200':
description: Watchlist created successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/WatchlistEntry'
type: object
examples:
NewWatchlist:
summary: Newly created watchlist
value:
data:
created_at: 2025-01-23 12:00:00+00:00
id: 770e8400-e29b-41d4-a716-446655440002
name: Growth Stocks
error: null
metadata:
request_id: b2c3d4e5-f6a7-8901-2345-678901bcdefg
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedPayload:
summary: Malformed JSON in request body
value:
error:
code: 400
message: 'Failed to parse the request body as JSON: trailing comma at line 3 column 1'
metadata:
request_id: 72348112-c92d-4610-829a-f769c82a9a0f
'409':
description: Resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
WatchlistAlreadyExists:
summary: Duplicate resource
value:
error:
code: 409
message: Resource already exists
metadata:
request_id: 0efec74c-7d58-4fef-b73b-df50731e4f6b
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/watchlists/{watchlist_id}:
get:
tags:
- Watchlist
summary: Get Watchlist By ID
description: Get a watchlist by ID with all its items
operationId: get_watchlist_by_id
parameters:
- name: watchlist_id
in: path
description: Watchlist ID
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Watchlist details with items
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/WatchlistDetail'
type: object
examples:
WatchlistWithItems:
summary: Watchlist with instrument items
value:
data:
created_at: 2025-01-15 10:00:00+00:00
id: 550e8400-e29b-41d4-a716-446655440000
items:
- added_at: 2025-01-16 09:30:00+00:00
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_fractionable: false
is_liquidation_only: false
is_marginable: true
is_ptp: 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
'404':
description: Watchlist not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
WatchlistNotFound:
summary: Watchlist does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: 8e6cec7b-342c-4231-a4f0-e650b48db699
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
delete:
tags:
- Watchlist
summary: Delete Watchlist
description: Delete a watchlist and all its items
operationId: delete_watchlist
parameters:
- name: watchlist_id
in: path
description: Watchlist ID
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Watchlist deleted successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
type: 'null'
examples:
DeletedWatchlist:
summary: Watchlist deleted successfully
value:
data: null
metadata:
request_id: cb824f1b-ea6e-4045-8169-9503be2b24d7
'404':
description: Watchlist not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
WatchlistNotFound:
summary: Watchlist does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: b8e5824d-391f-448c-a183-9d1582170a1c
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/watchlists/{watchlist_id}/items:
post:
tags:
- Watchlist
summary: Add Watchlist Item
description: Add an instrument to a watchlist
operationId: add_watchlist_item
parameters:
- name: watchlist_id
in: path
description: Watchlist ID
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
requestBody:
description: Instrument to add
content:
application/json:
schema:
$ref: '#/components/schemas/AddWatchlistItemRequest'
required: true
responses:
'200':
description: Item added successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/AddWatchlistItemData'
type: object
examples:
ItemAdded:
summary: Instrument added to watchlist
value:
data:
item_id: 770e8400-e29b-41d4-a716-446655440002
error: null
metadata:
request_id: b2c3d4e5-f6a7-8901-2345-678901bcdefg
'400':
description: Invalid request or watchlist is full
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedPayload:
summary: Malformed JSON in request body
value:
error:
code: 400
message: 'Failed to parse the request body as JSON: trailing comma at line 3 column 1'
metadata:
request_id: 3dc2f3ee-b66f-4b4e-9206-2c7f8aa933f6
WatchlistAtCapacity:
summary: Watchlist exceeds maximum item limit
value:
error:
code: 400
message: Watchlist cannot exceed 1000 items
metadata:
request_id: d9766cbe-74fa-4cc7-a0a8-9a7dd5b5294c
'404':
description: Watchlist or instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument does not exist
value:
error:
code: 404
message: 'Instrument not found: 69fcb40a-1812-4856-b2d3-97dec805efee'
metadata:
request_id: 6cf943be-2a63-4af5-85f4-60c14ffcee08
WatchlistNotFound:
summary: Watchlist does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: ce99b89c-e465-423c-959c-73c8305f9244
'409':
description: Instrument already exists in watchlist
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentAlreadyExistsInWatchlist:
summary: Instrument already exists in watchlist
value:
error:
code: 409
message: Instrument already exists in watchlist
metadata:
request_id: 95d49456-75c6-480a-9695-fae2b1a8befd
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/watchlists/{watchlist_id}/items/{item_id}:
delete:
tags:
- Watchlist
summary: Delete Watchlist Item
description: Delete an instrument from a watchlist
operationId: delete_watchlist_item
parameters:
- name: watchlist_id
in: path
description: Watchlist ID
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
- name: item_id
in: path
description: Item ID
required: true
schema:
type: string
format: uuid
example: 660e8400-e29b-41d4-a716-446655440001
responses:
'200':
description: Item deleted successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
type: 'null'
examples:
DeletedWatchlistItem:
summary: Watchlist item deleted successfully
value:
data: null
metadata:
request_id: 5b0709e3-5868-4116-9a84-26f1b8c30503
'404':
description: Watchlist or item not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
WatchlistItemNotFound:
summary: Watchlist or watchlist item was not found
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: 8462e079-739c-421b-b2d2-35cf007b4fc7
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ApiError:
type: object
description: A direct mapping of tonic::Status, for use in HTTP responses.
required:
- code
- message
properties:
code:
type: integer
format: int32
description: 'The error code is used to identify the nature of the error. It corresponds
to an HTTP status code.'
example: 400
minimum: 0
details:
$ref: '#/components/schemas/ErrorDetails'
description: 'Additional error details, if any. This can include structured information
such as field violations or error metadata.'
message:
type: string
description: A human-readable message providing more details about the error.
example: Order quantity must be greater than zero
AddWatchlistItemRequest:
type: object
description: Request to add an instrument to a watchlist
required:
- instrument_id
properties:
instrument_id:
$ref: '#/components/schemas/InstrumentIdOrSymbol'
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
ResponseMetadata:
type: object
description: 'Metadata for the response. This will always contain a request ID which can be used to identify
the request to Clear Street for tracing, and optionally may include pagination data.'
required:
- request_id
properties:
next_page_token:
oneOf:
- type: 'null'
- type: string
format: byte
description: Base64URL-encoded pagination token
description: 'A token that can be used to retrieve the next page of results, if any.
The token contains opaque pagination state.
Filtering and sorting parameters must be provided with each request.'
page_number:
type:
- integer
- 'null'
format: int32
description: Pagination. Included if this was a GET (list) response
example: '1'
minimum: 0
previous_page_token:
oneOf:
- type: 'null'
- type: string
format: byte
description: Base64URL-encoded pagination token
description: 'A token that can be used to retrieve the previous page of results, if any.
The token contains opaque pagination state.
Filtering and sorting parameters must be provided with each request.'
request_id:
type: string
description: A unique ID for this request, generated upon ingestion of the request.
total_items:
type:
- integer
- 'null'
format: int64
description: Total number of items available (not just in this page).
example: '42'
minimum: 0
total_pages:
type:
- integer
- 'null'
format: int32
description: Total number of pages available.
example: '5'
minimum: 0
InstrumentIdOrSymbol:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
AddWatchlistItemData:
type: object
description: Response data for adding a watchlist item
required:
- item_id
properties:
item_id:
type: string
format: uuid
description: ID of the created item
SecurityType:
type: string
description: Security type
enum:
- COMMON_STOCK
- INDEX
- OPTION
- CASH
CreateWatchlistRequest:
type: object
description: Create watchlist request payload.
required:
- name
properties:
name:
type: string
description: The desired watchlist name.
BaseResponse:
type: object
required:
- metadata
properties:
error:
oneOf:
- oneOf:
- type: 'null'
- $ref: '#/components/schemas/ApiError'
description: Structured error details when the request is unsuccessful.
metadata:
$ref: '#/components/schemas/ResponseMetadata'
description: Response metadata, including the request ID and optional pagination info.
WatchlistDetail:
type: object
description: Detailed watchlist with all items
required:
- id
- name
- created_at
- items
properties:
created_at:
type: string
format: date-time
description: Creation timestamp
id:
type: string
format: uuid
description: Watchlist ID
items:
type: array
items:
$ref: '#/components/schemas/WatchlistItemEntry'
description: Items in the watchlist
name:
type: string
description: Watchlist name
WatchlistEntryList:
type: array
items:
$ref: '#/components/schemas/WatchlistEntry'
Instrument:
allOf:
- type: object
required:
- id
- symbol
- venue
- country_of_issue
- currency
- is_marginable
- easy_to_borrow
- is_short_prohibited
- is_threshold_security
- is_liquidation_only
- is_tradable
- is_fractionable
- is_ptp
properties:
adv:
type:
- string
- 'null'
description: 'Average daily share volume from the security definition.
When a null/undefined value is observed, it indicates that there is no available data.'
example: '75000000'
country_of_issue:
type: string
description: The ISO country code of the instrument's issue
example: US
currency:
type: string
description: The ISO currency code in which the instrument is traded
example: USD
easy_to_borrow:
type: boolean
description: Indicates if the instrument is classified as Easy-To-Borrow
example: true
id:
type: string
format: uuid
description: Unique instrument identifier (UUID)
example: 0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b
instrument_type:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/SecurityType'
description: 'The type of security (e.g., Common Stock, ETF)
When a null/undefined value is observed, it indicates that there is no available data.'
is_fractionable:
type: boolean
description: Indicates if the instrument supports fractional-quantity orders
example: false
is_liquidation_only:
type: boolean
description: Indicates if the instrument is liquidation only and cannot be bought
example: false
is_marginable:
type: boolean
description: Indicates if the instrument is marginable
example: true
is_ptp:
type: boolean
description: 'Indicates if the instrument is a publicly traded partnership (PTP).
PTP sales are subject to a 10% withholding tax for non-US tax residents.'
example: false
is_short_prohibited:
type: boolean
description: Indicates if short selling is prohibited for the instrument
example: false
is_threshold_security:
type: boolean
description: Indicates if the instrument is on the Regulation SHO Threshold Security List
example: false
is_tradable:
type: boolean
description: Indicates if the instrument is tradable
example: true
long_margin_rate:
type:
- string
- 'null'
description: '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.'
example: '0.25'
name:
type:
- string
- 'null'
description: 'The full name of the instrument or its issuer
When a null/undefined value is observed, it indicates that there is no available data.'
example: Apple Inc.
notional_adv:
type:
- string
- 'null'
description: '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.'
example: '15815250000'
previous_close:
type:
- string
- 'null'
description: 'Last close price from the security definition.
When a null/undefined value is observed, it indicates that there is no available data.'
example: '210.87'
short_margin_rate:
type:
- string
- 'null'
description: '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.'
example: '0.25'
symbol:
type: string
description: The trading symbol for the instrument
example: AAPL
venue:
type: string
description: The MIC code of the primary listing venue
example: XNMS
example:
country_of_issue: US
currency: USD
easy_to_borrow: true
id: 0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b
instrument_type: COMMON_STOCK
is_fractionable: false
is_liquidation_only: false
is_marginable: true
is_ptp: false
is_short_prohibited: false
is_threshold_security: false
is_tradable: true
long_margin_rate: '0.25'
name: Apple Inc.
short_margin_rate: '0.25'
symbol: AAPL
venue: XNMS
- type: object
properties:
options_expiry_dates:
type:
- array
- 'null'
items:
type: string
format: date
description: '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.'
description: Represents a tradable financial instrument.
example:
country_of_issue: US
currency: USD
easy_to_borrow: true
id: 0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b
instrument_type: COMMON_STOCK
is_fractionable: false
is_liquidation_only: false
is_marginable: true
is_ptp: false
is_short_prohibited: false
is_threshold_security: false
is_tradable: true
long_margin_rate: '0.25'
name: Apple Inc.
short_margin_rate: '0.25'
symbol: AAPL
venue: XNMS
WatchlistItemEntry:
type: object
description: A single item in a watchlist
required:
- id
- added_at
properties:
added_at:
type: string
format: date-time
description: When the item was added
added_price:
type:
- string
- 'null'
description: 'Price when the item was added
When a null/undefined value is observed, it indicates that there is no available data.'
id:
type: string
format: uuid
description: Item ID
instrument:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Instrument'
description: 'Instrument details
When a null/undefined value is observed, it indicates that there is no available data.'
WatchlistEntry:
type: object
description: Represents a user watchlist.
required:
- id
- name
- created_at
properties:
created_at:
type: string
format: date-time
description: The timestamp when the watchlist was created.
id:
type: string
format: uuid
description: The unique identifier for the watchlist.
name:
type: string
description: The user-provided watchlist name.
ErrorDetails:
type: array
items:
type: object
additionalProperties: true
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT