# V1 ## Domain Types ### Security Type - `SecurityType = "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Security type - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` # Accounts ## Get Accounts **get** `/v1/accounts` List accounts the authenticated user has permission to access ### Query 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 - `data: AccountList` - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Example ```http curl https://api.clearstreet.com/v1/accounts \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_holder_entity_id": 987654321, "close_date": null, "full_name": "Test Trading Account", "id": 19816, "open_date": "2023-01-15", "short_name": "TST-ACCOUNT-01", "status": "ACTIVE", "subtype": "MARGIN", "type": "CUSTOMER" }, { "account_holder_entity_id": 987654322, "close_date": "2024-08-01", "full_name": "Old Test Account", "id": 19817, "open_date": "2021-05-20", "short_name": "TST-ACCOUNT-02-CLOSED", "status": "CLOSED", "subtype": "CASH", "type": "CUSTOMER" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3RfaWQ9MTk4MTc=", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "total_items": 25, "total_pages": 3 } } ``` ## Get Account By ID **get** `/v1/accounts/{account_id}` Fetch account details by ID ### Path Parameters - `account_id: number` ### Returns - `data: Account` Represents a trading account - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "account_holder_entity_id": 987654321, "close_date": null, "full_name": "Test Trading Account", "id": 19816, "open_date": "2023-01-15", "short_name": "TST-ACCOUNT-01", "status": "ACTIVE", "subtype": "MARGIN", "type": "CUSTOMER" }, "error": null, "metadata": { "request_id": "b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f" } } ``` ## Patch Account By ID **patch** `/v1/accounts/{account_id}` Update account risk settings ### Path Parameters - `account_id: number` ### Body Parameters - `risk: optional RiskSettings` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Returns - `data: AccountSettings` - `risk: optional RiskSettings` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{}' ``` #### Response ```json { "data": { "risk": { "max_notional": "5000000.00" } }, "error": null, "metadata": { "request_id": "c8f3e4a5-b2c3-5d4e-9f0a-6b7c8d9e0f1a" } } ``` ## Get Account Balances **get** `/v1/accounts/{account_id}/balances` Fetch account balance information ### Path Parameters - `account_id: number` ### Query Parameters - `top_margin_contributors_limit: optional number` Limit the number of top margin contributors returned by the engine. ### Returns - `data: AccountBalances` Represents the balance details for a trading account - `account_id: number` The unique identifier for the account - `buying_power: string` The total buying power available in the account. - `currency: string` Currency identifier for all monetary values. - `daily_realized_pnl: string` Realized profit or loss since start of day. - `daily_total_pnl: string` Total profit or loss since start of day. - `daily_unrealized_pnl: string` Total unrealized profit or loss across all positions relative to prior close. - `equity: string` The total equity in the account. - `long_market_value: string` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: string` Signed buying-power correction from open orders. - `settled_cash: string` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: string` Start-of-day buying power. - `equity: string` Start-of-day equity. - `long_market_value: string` Start-of-day long market value. - `short_market_value: string` Start-of-day short market value. - `asof: optional string` Timestamp for the start-of-day values. - `day_trade_buying_power: optional string` Start-of-day day-trade buying power. - `maintenance_margin_excess: optional string` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: optional string` Start-of-day maintenance margin requirement. - `trade_cash: optional string` Start-of-day trade cash. - `trade_cash: string` Trade-date effective cash. - `unsettled_credits: string` Trade-date unsettled cash credits. - `unsettled_debits: string` Trade-date unsettled cash debits. - `withdrawable_cash: string` The amount of cash currently available to withdraw. - `margin_details: optional MarginDetails` Margin-account-only details. - `day_trade_count: number` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: string` Initial margin excess for trade-date balances. - `initial_margin_requirement: string` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: string` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: string` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: boolean` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: optional string` The amount of day-trade buying power used during the current trading day. - `top_contributors: optional array of MarginTopContributor` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: string` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: string` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: string` Maintenance margin requirement attributable to this underlying. - `market_value: string` Net market value attributable to this underlying. - `underlying_instrument_id: string` UUID of the underlying security contributing to margin requirement. - `usage: optional MarginDetailsUsage` Current usage totals. - `total: string` The total margin available in the current model. - `used: string` The amount of margin that is currently being utilized. - `multiplier: optional string` Applied multiplier for margin calculations. - `short_market_value: optional string` The total market value of all short positions. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/balances \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "account_id": 19816, "buying_power": "45000.00", "currency": "USD", "daily_realized_pnl": "700.00", "daily_total_pnl": "1250.00", "daily_unrealized_pnl": "550.00", "equity": "100000.00", "long_market_value": "30000.00", "margin_type": "NONE", "open_order_adjustment": "-5000.00", "settled_cash": "60000.00", "sod": { "asof": "2023-09-27", "buying_power": "45000.00", "equity": "100000.00", "long_market_value": "30000.00" }, "trade_cash": "60000.00", "unsettled_credits": "20000.00", "unsettled_debits": "10000.00", "withdrawable_cash": "55000.00" }, "error": null, "metadata": { "request_id": "b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f" } } ``` ## Get Portfolio History **get** `/v1/accounts/{account_id}/portfolio-history` Retrieves daily portfolio history for the specified account. ### Path Parameters - `account_id: number` ### Query Parameters - `start_date: string` Start date for the portfolio history range, in YYYY-MM-DD format. - `end_date: optional string` Defaults to today in America/New_York when omitted. ### Returns - `data: PortfolioHistoryResponse` - `segments: array of PortfolioHistorySegment` - `date: string` The date for this segment - `eod_equity: string` The equity at the end of the trading day. - `realized_pnl: string` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: string` The equity at the start of the trading day. - `unrealized_pnl: string` Sum of the profit and loss from market changes. - `bought_notional: optional string` Amount bought MTM - `day_pnl: optional string` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: optional string` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: optional string` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: optional string` Amount sold MTM ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/portfolio-history \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "segments": [ { "bought_notional": "39800.00", "date": "2026-04-15", "day_pnl": "850.25", "eod_equity": "100850.25", "net_pnl": "850.25", "position_pnl": "-350.25", "realized_pnl": "1200.50", "sod_equity": "100000.00", "sold_notional": "42500.00", "unrealized_pnl": "-350.25" } ] }, "error": null, "metadata": { "request_id": "f076d6f6-10c9-42a0-98c5-18cebc427e80" } } ``` ## Domain Types ### Account - `Account object { id, account_holder_entity_id, full_name, 7 more }` Represents a trading account - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Balances - `AccountBalances object { account_id, buying_power, currency, 16 more }` Represents the balance details for a trading account - `account_id: number` The unique identifier for the account - `buying_power: string` The total buying power available in the account. - `currency: string` Currency identifier for all monetary values. - `daily_realized_pnl: string` Realized profit or loss since start of day. - `daily_total_pnl: string` Total profit or loss since start of day. - `daily_unrealized_pnl: string` Total unrealized profit or loss across all positions relative to prior close. - `equity: string` The total equity in the account. - `long_market_value: string` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: string` Signed buying-power correction from open orders. - `settled_cash: string` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: string` Start-of-day buying power. - `equity: string` Start-of-day equity. - `long_market_value: string` Start-of-day long market value. - `short_market_value: string` Start-of-day short market value. - `asof: optional string` Timestamp for the start-of-day values. - `day_trade_buying_power: optional string` Start-of-day day-trade buying power. - `maintenance_margin_excess: optional string` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: optional string` Start-of-day maintenance margin requirement. - `trade_cash: optional string` Start-of-day trade cash. - `trade_cash: string` Trade-date effective cash. - `unsettled_credits: string` Trade-date unsettled cash credits. - `unsettled_debits: string` Trade-date unsettled cash debits. - `withdrawable_cash: string` The amount of cash currently available to withdraw. - `margin_details: optional MarginDetails` Margin-account-only details. - `day_trade_count: number` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: string` Initial margin excess for trade-date balances. - `initial_margin_requirement: string` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: string` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: string` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: boolean` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: optional string` The amount of day-trade buying power used during the current trading day. - `top_contributors: optional array of MarginTopContributor` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: string` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: string` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: string` Maintenance margin requirement attributable to this underlying. - `market_value: string` Net market value attributable to this underlying. - `underlying_instrument_id: string` UUID of the underlying security contributing to margin requirement. - `usage: optional MarginDetailsUsage` Current usage totals. - `total: string` The total margin available in the current model. - `used: string` The amount of margin that is currently being utilized. - `multiplier: optional string` Applied multiplier for margin calculations. - `short_market_value: optional string` The total market value of all short positions. ### Account Balances Sod - `AccountBalancesSod object { buying_power, equity, long_market_value, 6 more }` - `buying_power: string` Start-of-day buying power. - `equity: string` Start-of-day equity. - `long_market_value: string` Start-of-day long market value. - `short_market_value: string` Start-of-day short market value. - `asof: optional string` Timestamp for the start-of-day values. - `day_trade_buying_power: optional string` Start-of-day day-trade buying power. - `maintenance_margin_excess: optional string` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: optional string` Start-of-day maintenance margin requirement. - `trade_cash: optional string` Start-of-day trade cash. ### Account List - `AccountList = array of Account` - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Settings - `AccountSettings object { risk }` - `risk: optional RiskSettings` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Account Status - `AccountStatus = "ACTIVE" or "INACTIVE" or "CLOSED"` Account status - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` ### Account Subtype - `AccountSubtype = "CASH" or "MARGIN" or "OTHER"` Account subtype classification providing more granular categorization - `"CASH"` - `"MARGIN"` - `"OTHER"` ### Account Type - `AccountType = "CUSTOMER" or "OTHER"` Account type classification - `"CUSTOMER"` - `"OTHER"` ### Margin Details - `MarginDetails object { day_trade_count, initial_margin_excess, initial_margin_requirement, 6 more }` - `day_trade_count: number` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: string` Initial margin excess for trade-date balances. - `initial_margin_requirement: string` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: string` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: string` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: boolean` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: optional string` The amount of day-trade buying power used during the current trading day. - `top_contributors: optional array of MarginTopContributor` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: string` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: string` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: string` Maintenance margin requirement attributable to this underlying. - `market_value: string` Net market value attributable to this underlying. - `underlying_instrument_id: string` UUID of the underlying security contributing to margin requirement. - `usage: optional MarginDetailsUsage` Current usage totals. - `total: string` The total margin available in the current model. - `used: string` The amount of margin that is currently being utilized. ### Margin Details Usage - `MarginDetailsUsage object { total, used }` - `total: string` The total margin available in the current model. - `used: string` The amount of margin that is currently being utilized. ### Margin Top Contributor - `MarginTopContributor object { day_trade_buying_power_usage, initial_margin_requirement, maintenance_margin_requirement, 2 more }` - `day_trade_buying_power_usage: string` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: string` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: string` Maintenance margin requirement attributable to this underlying. - `market_value: string` Net market value attributable to this underlying. - `underlying_instrument_id: string` UUID of the underlying security contributing to margin requirement. ### Margin Type - `MarginType = "OTHER" or "NONE" or "PORTFOLIO_MARGIN" or 6 more` An account's margin type - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` ### Portfolio History Response - `PortfolioHistoryResponse object { segments }` - `segments: array of PortfolioHistorySegment` - `date: string` The date for this segment - `eod_equity: string` The equity at the end of the trading day. - `realized_pnl: string` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: string` The equity at the start of the trading day. - `unrealized_pnl: string` Sum of the profit and loss from market changes. - `bought_notional: optional string` Amount bought MTM - `day_pnl: optional string` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: optional string` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: optional string` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: optional string` Amount sold MTM ### Portfolio History Segment - `PortfolioHistorySegment object { date, eod_equity, realized_pnl, 7 more }` - `date: string` The date for this segment - `eod_equity: string` The equity at the end of the trading day. - `realized_pnl: string` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: string` The equity at the start of the trading day. - `unrealized_pnl: string` Sum of the profit and loss from market changes. - `bought_notional: optional string` Amount bought MTM - `day_pnl: optional string` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: optional string` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: optional string` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: optional string` Amount sold MTM ### Risk Settings - `RiskSettings object { max_notional }` Risk settings for an account - `max_notional: optional string` The maximum notional value available to the account ### Account Get Accounts Response - `AccountGetAccountsResponse = BaseResponse` - `data: AccountList` - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Get Account By ID Response - `AccountGetAccountByIDResponse = BaseResponse` - `data: Account` Represents a trading account - `id: number` The unique identifier for the account - `account_holder_entity_id: number` The account holder entity identifier - `full_name: string` The full legal name of the account - `open_date: string` The date the account was opened - `options_level: number` The options level of the account - `short_name: string` The short name of the account - `status: AccountStatus` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: AccountSubtype` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: AccountType` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Patch Account By ID Response - `AccountPatchAccountByIDResponse = BaseResponse` - `data: AccountSettings` - `risk: optional RiskSettings` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Account Get Account Balances Response - `AccountGetAccountBalancesResponse = BaseResponse` - `data: AccountBalances` Represents the balance details for a trading account - `account_id: number` The unique identifier for the account - `buying_power: string` The total buying power available in the account. - `currency: string` Currency identifier for all monetary values. - `daily_realized_pnl: string` Realized profit or loss since start of day. - `daily_total_pnl: string` Total profit or loss since start of day. - `daily_unrealized_pnl: string` Total unrealized profit or loss across all positions relative to prior close. - `equity: string` The total equity in the account. - `long_market_value: string` The total market value of all long positions. - `margin_type: MarginType` The applicable margin model for the account - `"OTHER"` - `"NONE"` - `"PORTFOLIO_MARGIN"` - `"RISK_BASED_HAIRCUT_BROKER_DEALER"` - `"REG_T"` - `"RISK_BASED_HAIRCUT_MARKET_MAKER"` - `"CIRO"` - `"FUTURES_NLV"` - `"FUTURES_TOT_EQ"` - `open_order_adjustment: string` Signed buying-power correction from open orders. - `settled_cash: string` The amount of cash that is settled and available for withdrawal or trading. - `sod: AccountBalancesSod` Start-of-day snapshot balances. - `buying_power: string` Start-of-day buying power. - `equity: string` Start-of-day equity. - `long_market_value: string` Start-of-day long market value. - `short_market_value: string` Start-of-day short market value. - `asof: optional string` Timestamp for the start-of-day values. - `day_trade_buying_power: optional string` Start-of-day day-trade buying power. - `maintenance_margin_excess: optional string` Start-of-day maintenance margin excess. - `maintenance_margin_requirement: optional string` Start-of-day maintenance margin requirement. - `trade_cash: optional string` Start-of-day trade cash. - `trade_cash: string` Trade-date effective cash. - `unsettled_credits: string` Trade-date unsettled cash credits. - `unsettled_debits: string` Trade-date unsettled cash debits. - `withdrawable_cash: string` The amount of cash currently available to withdraw. - `margin_details: optional MarginDetails` Margin-account-only details. - `day_trade_count: number` The number of day trades executed over the 5 most recent trading days. - `initial_margin_excess: string` Initial margin excess for trade-date balances. - `initial_margin_requirement: string` Initial margin requirement for trade-date balances. - `maintenance_margin_excess: string` Maintenance margin excess for trade-date balances. - `maintenance_margin_requirement: string` Maintenance margin requirement for trade-date balances. - `pattern_day_trader: boolean` `true` if the account is currently flagged as a PDT, otherwise `false`. - `day_trade_buying_power_usage: optional string` The amount of day-trade buying power used during the current trading day. - `top_contributors: optional array of MarginTopContributor` Optional top margin contributors, returned only when explicitly requested. - `day_trade_buying_power_usage: string` Day-trade buying power consumed by fills against this underlying on the current trade date. Populated only for pattern day trader accounts. - `initial_margin_requirement: string` Initial margin requirement attributable to this underlying. - `maintenance_margin_requirement: string` Maintenance margin requirement attributable to this underlying. - `market_value: string` Net market value attributable to this underlying. - `underlying_instrument_id: string` UUID of the underlying security contributing to margin requirement. - `usage: optional MarginDetailsUsage` Current usage totals. - `total: string` The total margin available in the current model. - `used: string` The amount of margin that is currently being utilized. - `multiplier: optional string` Applied multiplier for margin calculations. - `short_market_value: optional string` The total market value of all short positions. ### Account Get Portfolio History Response - `AccountGetPortfolioHistoryResponse = BaseResponse` - `data: PortfolioHistoryResponse` - `segments: array of PortfolioHistorySegment` - `date: string` The date for this segment - `eod_equity: string` The equity at the end of the trading day. - `realized_pnl: string` Sum of the profit and loss realized from position closing trading activity. - `sod_equity: string` The equity at the start of the trading day. - `unrealized_pnl: string` Sum of the profit and loss from market changes. - `bought_notional: optional string` Amount bought MTM - `day_pnl: optional string` Sum of the profit and loss from intraday trading activities for the trading day. - `net_pnl: optional string` P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses - `position_pnl: optional string` P&L attributable to start-of-day (carried) positions from market movement during this trading day. - `sold_notional: optional string` Amount sold MTM # API Version ## Get the API version. **get** `/v1/version` Returns the current version string for this API endpoint. ### Returns - `data: Version` API version information - `version: string` API version string ### Example ```http curl https://api.clearstreet.com/v1/version \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "version": "2025-10-31" }, "error": null, "metadata": { "request_id": "2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f" } } ``` ## Domain Types ### Version - `Version object { version }` API version information - `version: string` API version string ### API Version Get Version Response - `APIVersionGetVersionResponse = BaseResponse` - `data: Version` API version information - `version: string` API version string # Calendar ## Get Clock **get** `/v1/clock` Returns the current server time in UTC. ### Returns - `data: ClockDetail` Current server time and market clock information - `clock: string` Current server time in UTC ### Example ```http curl https://api.clearstreet.com/v1/clock \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "clock": "2025-03-01T03:35:00.000000000Z" }, "error": null, "metadata": { "request_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e" } } ``` ## Get Market Hours Calendar. **get** `/v1/calendars/market-hours` Retrieves comprehensive trading hours including pre-market, regular, and after-hours sessions. Returns market status, session times, and next session schedules. ### Query Parameters - `date: string` The date to query market hours for (YYYY-MM-DD). Defaults to today. - `market: optional MarketType` Market type to query (us_equities, us_options). If omitted, returns all markets. - `"us_equities"` - `"us_options"` ### Returns - `data: MarketHoursDetailList` - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: optional SessionSchedule` After-hours session schedule, null if not available - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: optional SessionSchedule` Pre-market session schedule, null if not available - `regular: optional SessionSchedule` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: boolean` Whether the market is currently open (real-time) - `current_session: optional MarketSessionType` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: string` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Example ```http curl https://api.clearstreet.com/v1/calendars/market-hours \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "current_time": "2025-11-28T11:00:00-05:00", "date": "2025-11-28", "market": "us_equities", "market_name": "US Equities", "next_sessions": { "after_hours": { "close": "2025-12-01T20:00:00-05:00", "open": "2025-12-01T16:00:00-05:00" }, "pre_market": { "close": "2025-12-01T09:30:00-05:00", "open": "2025-12-01T04:00:00-05:00" }, "regular": { "close": "2025-12-01T16:00:00-05:00", "open": "2025-12-01T09:30:00-05:00" } }, "status": { "current_session": "regular", "day_type": "EARLY_CLOSE", "is_open": true }, "timezone": "America/New_York", "today_sessions": { "pre_market": { "close": "2025-11-28T09:30:00-05:00", "open": "2025-11-28T04:00:00-05:00" }, "regular": { "close": "2025-11-28T13:00:00-05:00", "open": "2025-11-28T09:30:00-05:00", "time_until_close": "PT2H" } } } ], "error": null, "metadata": { "request_id": "3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a" } } ``` ## Domain Types ### Clock Detail - `ClockDetail object { clock }` Current server time and market clock information - `clock: string` Current server time in UTC ### Day Type - `DayType = "TRADING_DAY" or "EARLY_CLOSE" or "HOLIDAY" or "WEEKEND"` Day type for market hours - indicates the type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` ### Market Hours Detail - `MarketHoursDetail object { current_time, date, market, 5 more }` Comprehensive market hours information for a specific market and date - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: optional SessionSchedule` After-hours session schedule, null if not available - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: optional SessionSchedule` Pre-market session schedule, null if not available - `regular: optional SessionSchedule` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: boolean` Whether the market is currently open (real-time) - `current_session: optional MarketSessionType` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: string` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Market Hours Detail List - `MarketHoursDetailList = array of MarketHoursDetail` - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: optional SessionSchedule` After-hours session schedule, null if not available - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: optional SessionSchedule` Pre-market session schedule, null if not available - `regular: optional SessionSchedule` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: boolean` Whether the market is currently open (real-time) - `current_session: optional MarketSessionType` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: string` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields ### Market Session Type - `MarketSessionType = "pre_market" or "regular" or "after_hours"` Session type for market hours - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Status - `MarketStatus object { day_type, is_open, current_session }` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: boolean` Whether the market is currently open (real-time) - `current_session: optional MarketSessionType` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Type - `MarketType = "us_equities" or "us_options"` Market type for market hours calendar endpoint - `"us_equities"` - `"us_options"` ### Session Schedule - `SessionSchedule object { close, open, time_until_close, time_until_open }` Session schedule with open and close timestamps - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. ### Trading Sessions - `TradingSessions object { after_hours, pre_market, regular }` Trading sessions for a market day with full timestamps - `after_hours: optional SessionSchedule` After-hours session schedule, null if not available - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: optional SessionSchedule` Pre-market session schedule, null if not available - `regular: optional SessionSchedule` Regular trading session schedule, null if holiday/weekend ### Calendar Get Clock Response - `CalendarGetClockResponse = BaseResponse` - `data: ClockDetail` Current server time and market clock information - `clock: string` Current server time in UTC ### Calendar Get Market Hours Calendar Response - `CalendarGetMarketHoursCalendarResponse = BaseResponse` - `data: MarketHoursDetailList` - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: MarketType` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: TradingSessions` Next trading day's session schedules (without time_until fields) - `after_hours: optional SessionSchedule` After-hours session schedule, null if not available - `close: string` Session close timestamp with timezone offset - `open: string` Session open timestamp with timezone offset - `time_until_close: optional string` ISO 8601 duration until session closes. Null if session is not currently open. - `time_until_open: optional string` ISO 8601 duration until session opens. Null if session has already started or closed. - `pre_market: optional SessionSchedule` Pre-market session schedule, null if not available - `regular: optional SessionSchedule` Regular trading session schedule, null if holiday/weekend - `status: MarketStatus` Market status information - `day_type: DayType` The type of trading day - `"TRADING_DAY"` - `"EARLY_CLOSE"` - `"HOLIDAY"` - `"WEEKEND"` - `is_open: boolean` Whether the market is currently open (real-time) - `current_session: optional MarketSessionType` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` - `timezone: string` IANA timezone identifier for the market - `today_sessions: TradingSessions` Trading session schedules for the requested date with time_until fields # Instrument Data ## Get All Instrument Events **get** `/v1/instruments/events` List instrument events across all securities. Retrieves all instrument events grouped by date. ### Query Parameters - `event_types: optional array of AllEventsEventType` Filter by event type(s). Comma-delimited list. Example: `event_types=EARNINGS,IPO`. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `from_date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `instrument_ids: optional array of string` Filter by OEMS instrument ID(s). Comma-delimited list of UUIDs. Example: `instrument_ids=550e8400-e29b-41d4-a716-446655440000`. - `to_date: optional string` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `data: InstrumentAllEventsData` All-events payload grouped by date. - `event_dates: array of InstrumentEventsByDate` Events grouped by date in descending order. - `date: string` Event date. - `events: array of InstrumentEventEnvelope` Flat event envelopes for this date. - `symbol: string` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional InstrumentDividendEvent` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: optional InstrumentEarnings` Earnings payload when type is EARNINGS. - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: optional string` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: optional InstrumentEventIpoItem` IPO payload when type is IPO. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. - `name: optional string` Instrument name associated with the event, when available. - `reporting_currency: optional string` The currency used for reporting financial data. - `stock_split_event_data: optional InstrumentSplitEvent` Stock split payload when type is STOCK_SPLIT. - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Example ```http curl https://api.clearstreet.com/v1/instruments/events \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "event_dates": [ { "date": "2026-04-23", "events": [ { "dividend_event_data": { "adjusted_dividend_amount": "0.5236", "declaration_date": "2026-04-22", "dividend_amount": "0.5236", "dividend_yield": "43.82881469863321", "ex_date": "2026-04-23", "frequency": "Weekly", "payment_date": "2026-04-24", "record_date": "2026-04-23" }, "instrument_id": "2281b543-7136-4008-aa0a-a402bf9d9f90", "name": "YieldMax ABNB Option Income Strategy ETF", "reporting_currency": "USD", "symbol": "ABNY", "type": "DIVIDEND" }, { "dividend_event_data": { "adjusted_dividend_amount": "0.1432", "declaration_date": "2026-04-22", "dividend_amount": "0.1432", "dividend_yield": "181.7918287937743", "ex_date": "2026-04-23", "frequency": "Weekly", "payment_date": "2026-04-24", "record_date": "2026-04-23" }, "instrument_id": "4b33fa52-8ab6-43f5-a8df-042e0c63d20e", "name": "YieldMax AI Option Income Strategy ETF", "reporting_currency": "USD", "symbol": "AIYY", "type": "DIVIDEND" } ] } ] }, "metadata": { "request_id": "5efbf08a-9067-4491-9f29-cf0b233507ef" } } ``` ## Get Instrument Events **get** `/v1/instruments/{instrument_id}/events` Retrieves corporate events (dividends, splits, etc.) for an instrument, grouped by event type. Date range defaults: - `from_date`: today - 365 days - `to_date`: today + 60 days ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `from_date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `to_date: optional string` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `data: InstrumentEventsData` Grouped instrument events by type - `dividends: array of InstrumentDividendEvent` Dividend distribution events - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: array of InstrumentEarnings` Earnings announcement events - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: string` OEMS instrument UUID from the request - `splits: array of InstrumentSplitEvent` Stock split events - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: optional string` The currency used for reporting financial data ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/events \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "dividends": [ { "adjusted_dividend_amount": "0.25", "declaration_date": "2024-10-31", "dividend_amount": "0.25", "dividend_yield": "0.44", "ex_date": "2024-11-08", "frequency": "Quarterly", "payment_date": "2024-11-14", "record_date": "2024-11-11" } ], "earnings": [ { "date": "2024-10-31", "eps_actual": "1.64", "eps_estimate": "1.60", "eps_surprise_percent": "2.5", "revenue_actual": "94930000000", "revenue_estimate": "94500000000", "revenue_surprise_percent": "0.45" } ], "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "reporting_currency": "USD", "splits": [ { "date": "2020-08-31", "denominator": "1", "numerator": "4", "split_type": "stock-split" } ] }, "error": null, "metadata": { "request_id": "0f1a2b3c-4d5e-6789-8a7b-6c5d4e3f2a1b" } } ``` ## Get Instrument Fundamentals **get** `/v1/instruments/{instrument_id}/fundamentals` Retrieves supplemental fundamentals and company profile data for an instrument. ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `data: InstrumentFundamentals` Supplemental fundamentals and company profile data for an instrument. - `average_volume: optional number` The average daily trading volume over the past 30 days - `beta: optional string` The beta value, measuring the instrument's volatility relative to the overall market - `description: optional string` A detailed description of the instrument or company - `dividend_yield: optional string` The trailing twelve months (TTM) dividend yield - `earnings_per_share: optional string` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: optional string` The highest price over the last 52 weeks - `fifty_two_week_low: optional string` The lowest price over the last 52 weeks - `industry: optional string` The specific industry of the instrument's issuer - `list_date: optional string` The date the instrument was first listed - `logo_url: optional string` URL to a representative logo image for the instrument or issuer - `market_cap: optional string` The total market capitalization - `previous_close: optional string` The closing price from the previous trading day - `price_to_earnings: optional string` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: optional string` The currency used for reporting financial data - `sector: optional string` The business sector of the instrument's issuer ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/fundamentals \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "average_volume": 76000000, "beta": "1.20", "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.", "dividend_yield": "0.005", "earnings_per_share": "5.61", "fifty_two_week_high": "230.00", "fifty_two_week_low": "165.00", "industry": "Consumer Electronics", "list_date": "1980-12-12", "logo_url": "https://example.com/logos/aapl.png", "market_cap": "2800000000000", "previous_close": "210.87", "price_to_earnings": "30.5", "reporting_currency": "USD", "sector": "Technology" }, "error": null, "metadata": { "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" } } ``` ## Get Instrument Balance Sheet Statements **get** `/v1/instruments/{instrument_id}/balance-sheets` Get balance sheet statements for an instrument. Retrieves quarterly balance sheet statements for a specific instrument, sorted by fiscal period (most recent first). Date range defaults: - `from_date`: None (no lower bound) - `to_date`: None (no upper bound) ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `from_date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `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. - `to_date: optional string` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `data: InstrumentBalanceSheetStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `account_payables: optional string` Account payables - `accounts_receivables: optional string` Accounts receivables - `accrued_expenses: optional string` Accrued expenses - `accumulated_other_comprehensive_income_loss: optional string` Accumulated other comprehensive income/loss - `additional_paid_in_capital: optional string` Additional paid-in capital - `capital_lease_obligations: optional string` Capital lease obligations (total) - `capital_lease_obligations_current: optional string` Capital lease obligations (current portion) - `cash_and_cash_equivalents: optional string` Cash and cash equivalents - `cash_and_short_term_investments: optional string` Cash and short-term investments combined - `common_stock: optional string` Common stock - `deferred_revenue: optional string` Deferred revenue - `deferred_revenue_non_current: optional string` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: optional string` Deferred tax liabilities (non-current) - `goodwill: optional string` Goodwill - `goodwill_and_intangible_assets: optional string` Goodwill and intangible assets combined - `intangible_assets: optional string` Intangible assets - `inventory: optional string` Inventory - `long_term_debt: optional string` Long-term debt - `long_term_investments: optional string` Long-term investments - `minority_interest: optional string` Minority interest - `net_debt: optional string` Net debt (total debt minus cash) - `net_receivables: optional string` Net receivables - `other_assets: optional string` Other assets - `other_current_assets: optional string` Other current assets - `other_current_liabilities: optional string` Other current liabilities - `other_liabilities: optional string` Other liabilities - `other_non_current_assets: optional string` Other non-current assets - `other_non_current_liabilities: optional string` Other non-current liabilities - `other_payables: optional string` Other payables - `other_receivables: optional string` Other receivables - `other_total_stockholders_equity: optional string` Other total stockholders equity - `preferred_stock: optional string` Preferred stock - `prepaids: optional string` Prepaids - `property_plant_and_equipment_net: optional string` Property, plant and equipment net of depreciation - `retained_earnings: optional string` Retained earnings - `short_term_debt: optional string` Short-term debt - `short_term_investments: optional string` Short-term investments - `tax_assets: optional string` Tax assets - `tax_payables: optional string` Tax payables - `total_assets: optional string` Total assets - `total_current_assets: optional string` Total current assets - `total_current_liabilities: optional string` Total current liabilities - `total_debt: optional string` Total debt - `total_equity: optional string` Total equity - `total_investments: optional string` Total investments - `total_liabilities: optional string` Total liabilities - `total_liabilities_and_total_equity: optional string` Total liabilities and total equity - `total_non_current_assets: optional string` Total non-current assets - `total_non_current_liabilities: optional string` Total non-current liabilities - `total_payables: optional string` Total payables - `total_stockholders_equity: optional string` Total stockholders equity - `treasury_stock: optional string` Treasury stock ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/balance-sheets \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "cash_and_cash_equivalents": "29943000000", "filing_date": "2025-05-01", "net_debt": "76323000000", "period": "Q1", "period_type": "QUARTERLY", "reported_currency": "USD", "total_assets": "352583000000", "total_debt": "106266000000", "total_liabilities": "308258000000", "total_stockholders_equity": "56727000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Get Instrument Income Statements **get** `/v1/instruments/{instrument_id}/income-statements` Retrieves quarterly income statements for a specific instrument, sorted by fiscal period (most recent first). Date range defaults: - `from_date`: None (no lower bound) - `to_date`: None (no upper bound) ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `from_date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `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. - `to_date: optional string` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `data: InstrumentIncomeStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `bottom_line_net_income: optional string` Bottom line net income after all adjustments - `cost_and_expenses: optional string` Total costs and expenses - `cost_of_revenue: optional string` Direct costs attributable to producing goods sold - `depreciation_and_amortization: optional string` Depreciation and amortization expenses - `ebit: optional string` Earnings before interest and taxes - `ebitda: optional string` Earnings before interest, taxes, depreciation, and amortization - `eps: optional string` Basic earnings per share - `eps_diluted: optional string` Diluted earnings per share - `general_and_administrative_expenses: optional string` General administrative overhead expenses - `gross_profit: optional string` Revenue minus cost of revenue - `income_before_tax: optional string` Income before income tax expense - `income_tax_expense: optional string` Income tax expense for the period - `interest_expense: optional string` Interest paid on debt - `interest_income: optional string` Interest earned on investments and cash - `net_income: optional string` Total net income for the period - `net_income_deductions: optional string` Deductions from net income - `net_income_from_continuing_operations: optional string` Net income from continuing operations - `net_income_from_discontinued_operations: optional string` Net income from discontinued operations - `net_interest_income: optional string` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: optional string` Non-operating income excluding interest - `operating_expenses: optional string` Total operating expenses - `operating_income: optional string` Income from core business operations - `other_adjustments_to_net_income: optional string` Other adjustments to net income - `other_expenses: optional string` Other miscellaneous expenses - `research_and_development_expenses: optional string` Expenditure on research and development activities - `revenue: optional string` Total revenue from sales of goods and services - `selling_and_marketing_expenses: optional string` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: optional string` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: optional string` Net of other income and expenses - `weighted_average_shs_out: optional string` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: optional string` Weighted average shares outstanding (diluted) ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/income-statements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "cost_of_revenue": "52080000000", "eps": "1.40", "eps_diluted": "1.38", "filing_date": "2025-05-01", "gross_profit": "42850000000", "net_income": "22200000000", "operating_income": "26550000000", "period": "Q1", "period_type": "QUARTERLY", "reported_currency": "USD", "revenue": "94930000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Get Instrument Analyst Consensus **get** `/v1/instruments/{instrument_id}/analyst-reporting` Retrieves analyst ratings and price targets for an instrument. ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `from: optional string` The start date for the query range, inclusive (YYYY-MM-DD) - `to: optional string` The end date for the query range, inclusive (YYYY-MM-DD) ### Returns - `data: InstrumentAnalystConsensus` Aggregated analyst consensus metrics - `date: string` The date the consensus snapshot was generated - `distribution: optional AnalystDistribution` Count of individual analyst recommendations by category - `buy: number` Number of buy recommendations - `hold: number` Number of hold recommendations - `sell: number` Number of sell recommendations - `strong_buy: number` Number of strong buy recommendations - `strong_sell: number` Number of strong sell recommendations - `price_target: optional PriceTarget` Aggregated analyst price target statistics - `average: string` Average analyst price target - `currency: string` ISO 4217 currency code of the price targets - `high: string` Highest analyst price target - `low: string` Lowest analyst price target - `rating: optional AnalystRating` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/analyst-reporting \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "date": "2025-10-01", "distribution": { "buy": 20, "hold": 3, "sell": 1, "strong_buy": 18, "strong_sell": 0 }, "price_target": { "average": "240.00", "currency": "USD", "high": "275.00", "low": "190.00" }, "rating": "BUY" }, "error": null, "metadata": { "request_id": "9e0f1a2b-3c4d-5e6f-7890-1a2b3c4d5e6f" } } ``` ## Get Instrument Cash Flow Statements **get** `/v1/instruments/{instrument_id}/cash-flow-statements` Get cash flow statements for an instrument. Retrieves historical cash flow statements for the specified instrument. Cash flow statements show cash inflows and outflows from operating, investing, and financing activities. ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `from_date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `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. - `to_date: optional string` The end date for the query range, inclusive (YYYY-MM-DD). ### Returns - `data: InstrumentCashFlowStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `accounts_payables: optional string` Change in accounts payables - `accounts_receivables: optional string` Change in accounts receivables - `acquisitions_net: optional string` Net acquisitions - `capital_expenditure: optional string` Capital expenditure - `cash_at_beginning_of_period: optional string` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: optional string` Cash and cash equivalents at end of period - `change_in_working_capital: optional string` Change in working capital - `common_dividends_paid: optional string` Common dividends paid - `common_stock_issuance: optional string` Common stock issuance - `common_stock_repurchased: optional string` Common stock repurchased (buybacks) - `deferred_income_tax: optional string` Deferred income tax expense - `depreciation_and_amortization: optional string` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: optional string` Effect of foreign exchange changes on cash - `free_cash_flow: optional string` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: optional string` Income taxes paid - `interest_paid: optional string` Interest paid - `inventory: optional string` Change in inventory - `investments_in_property_plant_and_equipment: optional string` Investments in property, plant, and equipment - `long_term_net_debt_issuance: optional string` Long-term net debt issuance - `net_cash_provided_by_financing_activities: optional string` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: optional string` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: optional string` Net cash provided by operating activities - `net_change_in_cash: optional string` Net change in cash during the period - `net_common_stock_issuance: optional string` Net common stock issuance - `net_debt_issuance: optional string` Net debt issuance (long-term + short-term) - `net_dividends_paid: optional string` Net dividends paid (common + preferred) - `net_income: optional string` Net income for the period - `net_preferred_stock_issuance: optional string` Net preferred stock issuance - `net_stock_issuance: optional string` Net stock issuance (common + preferred) - `operating_cash_flow: optional string` Operating cash flow (alternative calculation) - `other_financing_activities: optional string` Other financing activities - `other_investing_activities: optional string` Other investing activities - `other_non_cash_items: optional string` Other non-cash items - `other_working_capital: optional string` Change in other working capital - `preferred_dividends_paid: optional string` Preferred dividends paid - `purchases_of_investments: optional string` Purchases of investments - `sales_maturities_of_investments: optional string` Sales and maturities of investments - `short_term_net_debt_issuance: optional string` Short-term net debt issuance - `stock_based_compensation: optional string` Stock-based compensation expense ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID/cash-flow-statements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "accepted_date": "2025-05-02T14:30:00Z", "capital_expenditure": "-2600000000", "cash_at_beginning_of_period": "33743000000", "cash_at_end_of_period": "29943000000", "change_in_working_capital": "-3200000000", "common_stock_repurchased": "-23000000000", "depreciation_and_amortization": "2900000000", "filing_date": "2025-05-01", "free_cash_flow": "25800000000", "investments_in_property_plant_and_equipment": "-2600000000", "net_cash_provided_by_financing_activities": "-28300000000", "net_cash_provided_by_investing_activities": "-3900000000", "net_cash_provided_by_operating_activities": "28400000000", "net_change_in_cash": "-3800000000", "net_debt_issuance": "-1500000000", "net_dividends_paid": "-3800000000", "net_income": "22200000000", "operating_cash_flow": "28400000000", "period": "Q1", "period_type": "QUARTERLY", "purchases_of_investments": "-9500000000", "reported_currency": "USD", "sales_maturities_of_investments": "8200000000", "stock_based_compensation": "2500000000", "year": 2025 } ], "error": null, "metadata": { "next_page_token": "AAAAAAAAAGQAAAAAAAAAZQ==", "page_number": 1, "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "total_items": 20, "total_pages": 2 } } ``` ## Domain Types ### All Events Event Type - `AllEventsEventType = "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event types supported by the all-events endpoint. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` ### Analyst Distribution - `AnalystDistribution object { buy, hold, sell, 2 more }` Analyst recommendation distribution - `buy: number` Number of buy recommendations - `hold: number` Number of hold recommendations - `sell: number` Number of sell recommendations - `strong_buy: number` Number of strong buy recommendations - `strong_sell: number` Number of strong sell recommendations ### Analyst Rating - `AnalystRating = "STRONG_BUY" or "BUY" or "HOLD" or 2 more` Analyst rating category - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Fiscal Period Type - `FiscalPeriodType = "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` Fiscal period type for earnings reports - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` ### Instrument All Events Data - `InstrumentAllEventsData object { event_dates }` All-events payload grouped by date. - `event_dates: array of InstrumentEventsByDate` Events grouped by date in descending order. - `date: string` Event date. - `events: array of InstrumentEventEnvelope` Flat event envelopes for this date. - `symbol: string` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional InstrumentDividendEvent` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: optional InstrumentEarnings` Earnings payload when type is EARNINGS. - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: optional string` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: optional InstrumentEventIpoItem` IPO payload when type is IPO. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. - `name: optional string` Instrument name associated with the event, when available. - `reporting_currency: optional string` The currency used for reporting financial data. - `stock_split_event_data: optional InstrumentSplitEvent` Stock split payload when type is STOCK_SPLIT. - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Analyst Consensus - `InstrumentAnalystConsensus object { date, distribution, price_target, rating }` Aggregated analyst consensus metrics - `date: string` The date the consensus snapshot was generated - `distribution: optional AnalystDistribution` Count of individual analyst recommendations by category - `buy: number` Number of buy recommendations - `hold: number` Number of hold recommendations - `sell: number` Number of sell recommendations - `strong_buy: number` Number of strong buy recommendations - `strong_sell: number` Number of strong sell recommendations - `price_target: optional PriceTarget` Aggregated analyst price target statistics - `average: string` Average analyst price target - `currency: string` ISO 4217 currency code of the price targets - `high: string` Highest analyst price target - `low: string` Lowest analyst price target - `rating: optional AnalystRating` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Instrument Balance Sheet Statement - `InstrumentBalanceSheetStatement object { accepted_date, filing_date, period, 55 more }` A quarterly balance sheet statement for an instrument. - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `account_payables: optional string` Account payables - `accounts_receivables: optional string` Accounts receivables - `accrued_expenses: optional string` Accrued expenses - `accumulated_other_comprehensive_income_loss: optional string` Accumulated other comprehensive income/loss - `additional_paid_in_capital: optional string` Additional paid-in capital - `capital_lease_obligations: optional string` Capital lease obligations (total) - `capital_lease_obligations_current: optional string` Capital lease obligations (current portion) - `cash_and_cash_equivalents: optional string` Cash and cash equivalents - `cash_and_short_term_investments: optional string` Cash and short-term investments combined - `common_stock: optional string` Common stock - `deferred_revenue: optional string` Deferred revenue - `deferred_revenue_non_current: optional string` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: optional string` Deferred tax liabilities (non-current) - `goodwill: optional string` Goodwill - `goodwill_and_intangible_assets: optional string` Goodwill and intangible assets combined - `intangible_assets: optional string` Intangible assets - `inventory: optional string` Inventory - `long_term_debt: optional string` Long-term debt - `long_term_investments: optional string` Long-term investments - `minority_interest: optional string` Minority interest - `net_debt: optional string` Net debt (total debt minus cash) - `net_receivables: optional string` Net receivables - `other_assets: optional string` Other assets - `other_current_assets: optional string` Other current assets - `other_current_liabilities: optional string` Other current liabilities - `other_liabilities: optional string` Other liabilities - `other_non_current_assets: optional string` Other non-current assets - `other_non_current_liabilities: optional string` Other non-current liabilities - `other_payables: optional string` Other payables - `other_receivables: optional string` Other receivables - `other_total_stockholders_equity: optional string` Other total stockholders equity - `preferred_stock: optional string` Preferred stock - `prepaids: optional string` Prepaids - `property_plant_and_equipment_net: optional string` Property, plant and equipment net of depreciation - `retained_earnings: optional string` Retained earnings - `short_term_debt: optional string` Short-term debt - `short_term_investments: optional string` Short-term investments - `tax_assets: optional string` Tax assets - `tax_payables: optional string` Tax payables - `total_assets: optional string` Total assets - `total_current_assets: optional string` Total current assets - `total_current_liabilities: optional string` Total current liabilities - `total_debt: optional string` Total debt - `total_equity: optional string` Total equity - `total_investments: optional string` Total investments - `total_liabilities: optional string` Total liabilities - `total_liabilities_and_total_equity: optional string` Total liabilities and total equity - `total_non_current_assets: optional string` Total non-current assets - `total_non_current_liabilities: optional string` Total non-current liabilities - `total_payables: optional string` Total payables - `total_stockholders_equity: optional string` Total stockholders equity - `treasury_stock: optional string` Treasury stock ### Instrument Balance Sheet Statement List - `InstrumentBalanceSheetStatementList = array of InstrumentBalanceSheetStatement` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `account_payables: optional string` Account payables - `accounts_receivables: optional string` Accounts receivables - `accrued_expenses: optional string` Accrued expenses - `accumulated_other_comprehensive_income_loss: optional string` Accumulated other comprehensive income/loss - `additional_paid_in_capital: optional string` Additional paid-in capital - `capital_lease_obligations: optional string` Capital lease obligations (total) - `capital_lease_obligations_current: optional string` Capital lease obligations (current portion) - `cash_and_cash_equivalents: optional string` Cash and cash equivalents - `cash_and_short_term_investments: optional string` Cash and short-term investments combined - `common_stock: optional string` Common stock - `deferred_revenue: optional string` Deferred revenue - `deferred_revenue_non_current: optional string` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: optional string` Deferred tax liabilities (non-current) - `goodwill: optional string` Goodwill - `goodwill_and_intangible_assets: optional string` Goodwill and intangible assets combined - `intangible_assets: optional string` Intangible assets - `inventory: optional string` Inventory - `long_term_debt: optional string` Long-term debt - `long_term_investments: optional string` Long-term investments - `minority_interest: optional string` Minority interest - `net_debt: optional string` Net debt (total debt minus cash) - `net_receivables: optional string` Net receivables - `other_assets: optional string` Other assets - `other_current_assets: optional string` Other current assets - `other_current_liabilities: optional string` Other current liabilities - `other_liabilities: optional string` Other liabilities - `other_non_current_assets: optional string` Other non-current assets - `other_non_current_liabilities: optional string` Other non-current liabilities - `other_payables: optional string` Other payables - `other_receivables: optional string` Other receivables - `other_total_stockholders_equity: optional string` Other total stockholders equity - `preferred_stock: optional string` Preferred stock - `prepaids: optional string` Prepaids - `property_plant_and_equipment_net: optional string` Property, plant and equipment net of depreciation - `retained_earnings: optional string` Retained earnings - `short_term_debt: optional string` Short-term debt - `short_term_investments: optional string` Short-term investments - `tax_assets: optional string` Tax assets - `tax_payables: optional string` Tax payables - `total_assets: optional string` Total assets - `total_current_assets: optional string` Total current assets - `total_current_liabilities: optional string` Total current liabilities - `total_debt: optional string` Total debt - `total_equity: optional string` Total equity - `total_investments: optional string` Total investments - `total_liabilities: optional string` Total liabilities - `total_liabilities_and_total_equity: optional string` Total liabilities and total equity - `total_non_current_assets: optional string` Total non-current assets - `total_non_current_liabilities: optional string` Total non-current liabilities - `total_payables: optional string` Total payables - `total_stockholders_equity: optional string` Total stockholders equity - `treasury_stock: optional string` Treasury stock ### Instrument Cash Flow Statement - `InstrumentCashFlowStatement object { accepted_date, filing_date, period, 42 more }` A quarterly cash flow statement for an instrument. - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `accounts_payables: optional string` Change in accounts payables - `accounts_receivables: optional string` Change in accounts receivables - `acquisitions_net: optional string` Net acquisitions - `capital_expenditure: optional string` Capital expenditure - `cash_at_beginning_of_period: optional string` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: optional string` Cash and cash equivalents at end of period - `change_in_working_capital: optional string` Change in working capital - `common_dividends_paid: optional string` Common dividends paid - `common_stock_issuance: optional string` Common stock issuance - `common_stock_repurchased: optional string` Common stock repurchased (buybacks) - `deferred_income_tax: optional string` Deferred income tax expense - `depreciation_and_amortization: optional string` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: optional string` Effect of foreign exchange changes on cash - `free_cash_flow: optional string` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: optional string` Income taxes paid - `interest_paid: optional string` Interest paid - `inventory: optional string` Change in inventory - `investments_in_property_plant_and_equipment: optional string` Investments in property, plant, and equipment - `long_term_net_debt_issuance: optional string` Long-term net debt issuance - `net_cash_provided_by_financing_activities: optional string` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: optional string` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: optional string` Net cash provided by operating activities - `net_change_in_cash: optional string` Net change in cash during the period - `net_common_stock_issuance: optional string` Net common stock issuance - `net_debt_issuance: optional string` Net debt issuance (long-term + short-term) - `net_dividends_paid: optional string` Net dividends paid (common + preferred) - `net_income: optional string` Net income for the period - `net_preferred_stock_issuance: optional string` Net preferred stock issuance - `net_stock_issuance: optional string` Net stock issuance (common + preferred) - `operating_cash_flow: optional string` Operating cash flow (alternative calculation) - `other_financing_activities: optional string` Other financing activities - `other_investing_activities: optional string` Other investing activities - `other_non_cash_items: optional string` Other non-cash items - `other_working_capital: optional string` Change in other working capital - `preferred_dividends_paid: optional string` Preferred dividends paid - `purchases_of_investments: optional string` Purchases of investments - `sales_maturities_of_investments: optional string` Sales and maturities of investments - `short_term_net_debt_issuance: optional string` Short-term net debt issuance - `stock_based_compensation: optional string` Stock-based compensation expense ### Instrument Cash Flow Statement List - `InstrumentCashFlowStatementList = array of InstrumentCashFlowStatement` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `accounts_payables: optional string` Change in accounts payables - `accounts_receivables: optional string` Change in accounts receivables - `acquisitions_net: optional string` Net acquisitions - `capital_expenditure: optional string` Capital expenditure - `cash_at_beginning_of_period: optional string` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: optional string` Cash and cash equivalents at end of period - `change_in_working_capital: optional string` Change in working capital - `common_dividends_paid: optional string` Common dividends paid - `common_stock_issuance: optional string` Common stock issuance - `common_stock_repurchased: optional string` Common stock repurchased (buybacks) - `deferred_income_tax: optional string` Deferred income tax expense - `depreciation_and_amortization: optional string` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: optional string` Effect of foreign exchange changes on cash - `free_cash_flow: optional string` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: optional string` Income taxes paid - `interest_paid: optional string` Interest paid - `inventory: optional string` Change in inventory - `investments_in_property_plant_and_equipment: optional string` Investments in property, plant, and equipment - `long_term_net_debt_issuance: optional string` Long-term net debt issuance - `net_cash_provided_by_financing_activities: optional string` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: optional string` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: optional string` Net cash provided by operating activities - `net_change_in_cash: optional string` Net change in cash during the period - `net_common_stock_issuance: optional string` Net common stock issuance - `net_debt_issuance: optional string` Net debt issuance (long-term + short-term) - `net_dividends_paid: optional string` Net dividends paid (common + preferred) - `net_income: optional string` Net income for the period - `net_preferred_stock_issuance: optional string` Net preferred stock issuance - `net_stock_issuance: optional string` Net stock issuance (common + preferred) - `operating_cash_flow: optional string` Operating cash flow (alternative calculation) - `other_financing_activities: optional string` Other financing activities - `other_investing_activities: optional string` Other investing activities - `other_non_cash_items: optional string` Other non-cash items - `other_working_capital: optional string` Change in other working capital - `preferred_dividends_paid: optional string` Preferred dividends paid - `purchases_of_investments: optional string` Purchases of investments - `sales_maturities_of_investments: optional string` Sales and maturities of investments - `short_term_net_debt_issuance: optional string` Short-term net debt issuance - `stock_based_compensation: optional string` Stock-based compensation expense ### Instrument Dividend Event - `InstrumentDividendEvent object { adjusted_dividend_amount, ex_date, declaration_date, 5 more }` Represents a dividend event for an instrument - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. ### Instrument Earnings - `InstrumentEarnings object { date, eps_actual, eps_estimate, 4 more }` Represents instrument earnings data - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue ### Instrument Event Envelope - `InstrumentEventEnvelope object { symbol, type, dividend_event_data, 6 more }` Unified envelope for the all-events response. - `symbol: string` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional InstrumentDividendEvent` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: optional InstrumentEarnings` Earnings payload when type is EARNINGS. - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: optional string` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: optional InstrumentEventIpoItem` IPO payload when type is IPO. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. - `name: optional string` Instrument name associated with the event, when available. - `reporting_currency: optional string` The currency used for reporting financial data. - `stock_split_event_data: optional InstrumentSplitEvent` Stock split payload when type is STOCK_SPLIT. - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Event Ipo Item - `InstrumentEventIpoItem object { actions, announced_at, company, 4 more }` IPO event in the all-events date grouping response. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. ### Instrument Events By Date - `InstrumentEventsByDate object { date, events }` Instrument events for a single date. - `date: string` Event date. - `events: array of InstrumentEventEnvelope` Flat event envelopes for this date. - `symbol: string` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional InstrumentDividendEvent` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: optional InstrumentEarnings` Earnings payload when type is EARNINGS. - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: optional string` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: optional InstrumentEventIpoItem` IPO payload when type is IPO. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. - `name: optional string` Instrument name associated with the event, when available. - `reporting_currency: optional string` The currency used for reporting financial data. - `stock_split_event_data: optional InstrumentSplitEvent` Stock split payload when type is STOCK_SPLIT. - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Events Data - `InstrumentEventsData object { dividends, earnings, instrument_id, 2 more }` Grouped instrument events by type - `dividends: array of InstrumentDividendEvent` Dividend distribution events - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: array of InstrumentEarnings` Earnings announcement events - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: string` OEMS instrument UUID from the request - `splits: array of InstrumentSplitEvent` Stock split events - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: optional string` The currency used for reporting financial data ### Instrument Fundamentals - `InstrumentFundamentals object { average_volume, beta, description, 12 more }` Supplemental fundamentals and company profile data for an instrument. - `average_volume: optional number` The average daily trading volume over the past 30 days - `beta: optional string` The beta value, measuring the instrument's volatility relative to the overall market - `description: optional string` A detailed description of the instrument or company - `dividend_yield: optional string` The trailing twelve months (TTM) dividend yield - `earnings_per_share: optional string` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: optional string` The highest price over the last 52 weeks - `fifty_two_week_low: optional string` The lowest price over the last 52 weeks - `industry: optional string` The specific industry of the instrument's issuer - `list_date: optional string` The date the instrument was first listed - `logo_url: optional string` URL to a representative logo image for the instrument or issuer - `market_cap: optional string` The total market capitalization - `previous_close: optional string` The closing price from the previous trading day - `price_to_earnings: optional string` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: optional string` The currency used for reporting financial data - `sector: optional string` The business sector of the instrument's issuer ### Instrument Income Statement - `InstrumentIncomeStatement object { accepted_date, filing_date, period, 34 more }` A quarterly income statement for an instrument. - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `bottom_line_net_income: optional string` Bottom line net income after all adjustments - `cost_and_expenses: optional string` Total costs and expenses - `cost_of_revenue: optional string` Direct costs attributable to producing goods sold - `depreciation_and_amortization: optional string` Depreciation and amortization expenses - `ebit: optional string` Earnings before interest and taxes - `ebitda: optional string` Earnings before interest, taxes, depreciation, and amortization - `eps: optional string` Basic earnings per share - `eps_diluted: optional string` Diluted earnings per share - `general_and_administrative_expenses: optional string` General administrative overhead expenses - `gross_profit: optional string` Revenue minus cost of revenue - `income_before_tax: optional string` Income before income tax expense - `income_tax_expense: optional string` Income tax expense for the period - `interest_expense: optional string` Interest paid on debt - `interest_income: optional string` Interest earned on investments and cash - `net_income: optional string` Total net income for the period - `net_income_deductions: optional string` Deductions from net income - `net_income_from_continuing_operations: optional string` Net income from continuing operations - `net_income_from_discontinued_operations: optional string` Net income from discontinued operations - `net_interest_income: optional string` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: optional string` Non-operating income excluding interest - `operating_expenses: optional string` Total operating expenses - `operating_income: optional string` Income from core business operations - `other_adjustments_to_net_income: optional string` Other adjustments to net income - `other_expenses: optional string` Other miscellaneous expenses - `research_and_development_expenses: optional string` Expenditure on research and development activities - `revenue: optional string` Total revenue from sales of goods and services - `selling_and_marketing_expenses: optional string` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: optional string` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: optional string` Net of other income and expenses - `weighted_average_shs_out: optional string` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: optional string` Weighted average shares outstanding (diluted) ### Instrument Income Statement List - `InstrumentIncomeStatementList = array of InstrumentIncomeStatement` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `bottom_line_net_income: optional string` Bottom line net income after all adjustments - `cost_and_expenses: optional string` Total costs and expenses - `cost_of_revenue: optional string` Direct costs attributable to producing goods sold - `depreciation_and_amortization: optional string` Depreciation and amortization expenses - `ebit: optional string` Earnings before interest and taxes - `ebitda: optional string` Earnings before interest, taxes, depreciation, and amortization - `eps: optional string` Basic earnings per share - `eps_diluted: optional string` Diluted earnings per share - `general_and_administrative_expenses: optional string` General administrative overhead expenses - `gross_profit: optional string` Revenue minus cost of revenue - `income_before_tax: optional string` Income before income tax expense - `income_tax_expense: optional string` Income tax expense for the period - `interest_expense: optional string` Interest paid on debt - `interest_income: optional string` Interest earned on investments and cash - `net_income: optional string` Total net income for the period - `net_income_deductions: optional string` Deductions from net income - `net_income_from_continuing_operations: optional string` Net income from continuing operations - `net_income_from_discontinued_operations: optional string` Net income from discontinued operations - `net_interest_income: optional string` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: optional string` Non-operating income excluding interest - `operating_expenses: optional string` Total operating expenses - `operating_income: optional string` Income from core business operations - `other_adjustments_to_net_income: optional string` Other adjustments to net income - `other_expenses: optional string` Other miscellaneous expenses - `research_and_development_expenses: optional string` Expenditure on research and development activities - `revenue: optional string` Total revenue from sales of goods and services - `selling_and_marketing_expenses: optional string` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: optional string` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: optional string` Net of other income and expenses - `weighted_average_shs_out: optional string` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: optional string` Weighted average shares outstanding (diluted) ### Instrument Split Event - `InstrumentSplitEvent object { date, denominator, numerator, split_type }` Represents a stock split event for an instrument - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Price Target - `PriceTarget object { average, currency, high, low }` Analyst price target statistics - `average: string` Average analyst price target - `currency: string` ISO 4217 currency code of the price targets - `high: string` Highest analyst price target - `low: string` Lowest analyst price target ### Instrument Data Get All Instrument Events Response - `InstrumentDataGetAllInstrumentEventsResponse = BaseResponse` - `data: InstrumentAllEventsData` All-events payload grouped by date. - `event_dates: array of InstrumentEventsByDate` Events grouped by date in descending order. - `date: string` Event date. - `events: array of InstrumentEventEnvelope` Flat event envelopes for this date. - `symbol: string` Symbol associated with the event. - `type: AllEventsEventType` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional InstrumentDividendEvent` Dividend payload when type is DIVIDEND. - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings_event_data: optional InstrumentEarnings` Earnings payload when type is EARNINGS. - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: optional string` OEMS instrument identifier, when the instrument is found in the instrument cache. - `ipo_event_data: optional InstrumentEventIpoItem` IPO payload when type is IPO. - `actions: optional string` IPO action. - `announced_at: optional string` IPO announced timestamp. - `company: optional string` IPO company name. - `exchange: optional string` IPO exchange. - `market_cap: optional string` IPO market cap. - `price_range: optional string` IPO price range. - `shares: optional string` IPO shares offered. - `name: optional string` Instrument name associated with the event, when available. - `reporting_currency: optional string` The currency used for reporting financial data. - `stock_split_event_data: optional InstrumentSplitEvent` Stock split payload when type is STOCK_SPLIT. - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ### Instrument Data Get Instrument Events Response - `InstrumentDataGetInstrumentEventsResponse = BaseResponse` - `data: InstrumentEventsData` Grouped instrument events by type - `dividends: array of InstrumentDividendEvent` Dividend distribution events - `adjusted_dividend_amount: string` The adjusted dividend amount accounting for any splits. - `ex_date: string` The day the stock starts trading without the right to receive that dividend. - `declaration_date: optional string` The declaration date of the dividend - `dividend_amount: optional string` The dividend amount per share. - `dividend_yield: optional string` The dividend yield as a percentage of the stock price. - `frequency: optional string` The frequency of the dividend payments (e.g., "Quarterly", "Annual"). - `payment_date: optional string` The payment date is the date on which a declared stock dividend is scheduled to be paid. - `record_date: optional string` The record date, set by a company's board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend. - `earnings: array of InstrumentEarnings` Earnings announcement events - `date: string` The date when the earnings report was published - `eps_actual: optional string` The actual earnings per share (EPS) for the period - `eps_estimate: optional string` The estimated earnings per share (EPS) for the period - `eps_surprise_percent: optional string` The percentage difference between actual and estimated EPS - `revenue_actual: optional string` The actual total revenue for the period - `revenue_estimate: optional string` The estimated total revenue for the period - `revenue_surprise_percent: optional string` The percentage difference between actual and estimated revenue - `instrument_id: string` OEMS instrument UUID from the request - `splits: array of InstrumentSplitEvent` Stock split events - `date: string` The date of the stock split - `denominator: string` The denominator of the split ratio - `numerator: string` The numerator of the split ratio - `split_type: string` The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") - `reporting_currency: optional string` The currency used for reporting financial data ### Instrument Data Get Instrument Fundamentals Response - `InstrumentDataGetInstrumentFundamentalsResponse = BaseResponse` - `data: InstrumentFundamentals` Supplemental fundamentals and company profile data for an instrument. - `average_volume: optional number` The average daily trading volume over the past 30 days - `beta: optional string` The beta value, measuring the instrument's volatility relative to the overall market - `description: optional string` A detailed description of the instrument or company - `dividend_yield: optional string` The trailing twelve months (TTM) dividend yield - `earnings_per_share: optional string` The trailing twelve months (TTM) earnings per share - `fifty_two_week_high: optional string` The highest price over the last 52 weeks - `fifty_two_week_low: optional string` The lowest price over the last 52 weeks - `industry: optional string` The specific industry of the instrument's issuer - `list_date: optional string` The date the instrument was first listed - `logo_url: optional string` URL to a representative logo image for the instrument or issuer - `market_cap: optional string` The total market capitalization - `previous_close: optional string` The closing price from the previous trading day - `price_to_earnings: optional string` The price-to-earnings (P/E) ratio for the trailing twelve months (TTM) - `reporting_currency: optional string` The currency used for reporting financial data - `sector: optional string` The business sector of the instrument's issuer ### Instrument Data Get Instrument Balance Sheet Statements Response - `InstrumentDataGetInstrumentBalanceSheetStatementsResponse = BaseResponse` - `data: InstrumentBalanceSheetStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `account_payables: optional string` Account payables - `accounts_receivables: optional string` Accounts receivables - `accrued_expenses: optional string` Accrued expenses - `accumulated_other_comprehensive_income_loss: optional string` Accumulated other comprehensive income/loss - `additional_paid_in_capital: optional string` Additional paid-in capital - `capital_lease_obligations: optional string` Capital lease obligations (total) - `capital_lease_obligations_current: optional string` Capital lease obligations (current portion) - `cash_and_cash_equivalents: optional string` Cash and cash equivalents - `cash_and_short_term_investments: optional string` Cash and short-term investments combined - `common_stock: optional string` Common stock - `deferred_revenue: optional string` Deferred revenue - `deferred_revenue_non_current: optional string` Deferred revenue (non-current) - `deferred_tax_liabilities_non_current: optional string` Deferred tax liabilities (non-current) - `goodwill: optional string` Goodwill - `goodwill_and_intangible_assets: optional string` Goodwill and intangible assets combined - `intangible_assets: optional string` Intangible assets - `inventory: optional string` Inventory - `long_term_debt: optional string` Long-term debt - `long_term_investments: optional string` Long-term investments - `minority_interest: optional string` Minority interest - `net_debt: optional string` Net debt (total debt minus cash) - `net_receivables: optional string` Net receivables - `other_assets: optional string` Other assets - `other_current_assets: optional string` Other current assets - `other_current_liabilities: optional string` Other current liabilities - `other_liabilities: optional string` Other liabilities - `other_non_current_assets: optional string` Other non-current assets - `other_non_current_liabilities: optional string` Other non-current liabilities - `other_payables: optional string` Other payables - `other_receivables: optional string` Other receivables - `other_total_stockholders_equity: optional string` Other total stockholders equity - `preferred_stock: optional string` Preferred stock - `prepaids: optional string` Prepaids - `property_plant_and_equipment_net: optional string` Property, plant and equipment net of depreciation - `retained_earnings: optional string` Retained earnings - `short_term_debt: optional string` Short-term debt - `short_term_investments: optional string` Short-term investments - `tax_assets: optional string` Tax assets - `tax_payables: optional string` Tax payables - `total_assets: optional string` Total assets - `total_current_assets: optional string` Total current assets - `total_current_liabilities: optional string` Total current liabilities - `total_debt: optional string` Total debt - `total_equity: optional string` Total equity - `total_investments: optional string` Total investments - `total_liabilities: optional string` Total liabilities - `total_liabilities_and_total_equity: optional string` Total liabilities and total equity - `total_non_current_assets: optional string` Total non-current assets - `total_non_current_liabilities: optional string` Total non-current liabilities - `total_payables: optional string` Total payables - `total_stockholders_equity: optional string` Total stockholders equity - `treasury_stock: optional string` Treasury stock ### Instrument Data Get Instrument Income Statements Response - `InstrumentDataGetInstrumentIncomeStatementsResponse = BaseResponse` - `data: InstrumentIncomeStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `bottom_line_net_income: optional string` Bottom line net income after all adjustments - `cost_and_expenses: optional string` Total costs and expenses - `cost_of_revenue: optional string` Direct costs attributable to producing goods sold - `depreciation_and_amortization: optional string` Depreciation and amortization expenses - `ebit: optional string` Earnings before interest and taxes - `ebitda: optional string` Earnings before interest, taxes, depreciation, and amortization - `eps: optional string` Basic earnings per share - `eps_diluted: optional string` Diluted earnings per share - `general_and_administrative_expenses: optional string` General administrative overhead expenses - `gross_profit: optional string` Revenue minus cost of revenue - `income_before_tax: optional string` Income before income tax expense - `income_tax_expense: optional string` Income tax expense for the period - `interest_expense: optional string` Interest paid on debt - `interest_income: optional string` Interest earned on investments and cash - `net_income: optional string` Total net income for the period - `net_income_deductions: optional string` Deductions from net income - `net_income_from_continuing_operations: optional string` Net income from continuing operations - `net_income_from_discontinued_operations: optional string` Net income from discontinued operations - `net_interest_income: optional string` Net interest income (interest income minus interest expense) - `non_operating_income_excluding_interest: optional string` Non-operating income excluding interest - `operating_expenses: optional string` Total operating expenses - `operating_income: optional string` Income from core business operations - `other_adjustments_to_net_income: optional string` Other adjustments to net income - `other_expenses: optional string` Other miscellaneous expenses - `research_and_development_expenses: optional string` Expenditure on research and development activities - `revenue: optional string` Total revenue from sales of goods and services - `selling_and_marketing_expenses: optional string` Expenditure on marketing and sales activities - `selling_general_and_administrative_expenses: optional string` Combined selling, general, and administrative expenses - `total_other_income_expenses_net: optional string` Net of other income and expenses - `weighted_average_shs_out: optional string` Weighted average shares outstanding (basic) - `weighted_average_shs_out_dil: optional string` Weighted average shares outstanding (diluted) ### Instrument Data Get Instrument Analyst Consensus Response - `InstrumentDataGetInstrumentAnalystConsensusResponse = BaseResponse` - `data: InstrumentAnalystConsensus` Aggregated analyst consensus metrics - `date: string` The date the consensus snapshot was generated - `distribution: optional AnalystDistribution` Count of individual analyst recommendations by category - `buy: number` Number of buy recommendations - `hold: number` Number of hold recommendations - `sell: number` Number of sell recommendations - `strong_buy: number` Number of strong buy recommendations - `strong_sell: number` Number of strong sell recommendations - `price_target: optional PriceTarget` Aggregated analyst price target statistics - `average: string` Average analyst price target - `currency: string` ISO 4217 currency code of the price targets - `high: string` Highest analyst price target - `low: string` Lowest analyst price target - `rating: optional AnalystRating` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Instrument Data Get Instrument Cash Flow Statements Response - `InstrumentDataGetInstrumentCashFlowStatementsResponse = BaseResponse` - `data: InstrumentCashFlowStatementList` - `accepted_date: string` The date and time when the filing was accepted by the SEC - `filing_date: string` The date the financial statement was filed - `period: string` The fiscal period identifier (e.g., "Q1", "Q2", "Q3", "Q4") - `period_type: FiscalPeriodType` The type of fiscal period - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` - `reported_currency: string` The currency in which the statement is reported (ISO 4217) - `year: number` The fiscal year of the statement - `accounts_payables: optional string` Change in accounts payables - `accounts_receivables: optional string` Change in accounts receivables - `acquisitions_net: optional string` Net acquisitions - `capital_expenditure: optional string` Capital expenditure - `cash_at_beginning_of_period: optional string` Cash and cash equivalents at beginning of period - `cash_at_end_of_period: optional string` Cash and cash equivalents at end of period - `change_in_working_capital: optional string` Change in working capital - `common_dividends_paid: optional string` Common dividends paid - `common_stock_issuance: optional string` Common stock issuance - `common_stock_repurchased: optional string` Common stock repurchased (buybacks) - `deferred_income_tax: optional string` Deferred income tax expense - `depreciation_and_amortization: optional string` Depreciation and amortization expense - `effect_of_forex_changes_on_cash: optional string` Effect of foreign exchange changes on cash - `free_cash_flow: optional string` Free cash flow (operating cash flow minus capital expenditure) - `income_taxes_paid: optional string` Income taxes paid - `interest_paid: optional string` Interest paid - `inventory: optional string` Change in inventory - `investments_in_property_plant_and_equipment: optional string` Investments in property, plant, and equipment - `long_term_net_debt_issuance: optional string` Long-term net debt issuance - `net_cash_provided_by_financing_activities: optional string` Net cash provided by financing activities - `net_cash_provided_by_investing_activities: optional string` Net cash provided by investing activities - `net_cash_provided_by_operating_activities: optional string` Net cash provided by operating activities - `net_change_in_cash: optional string` Net change in cash during the period - `net_common_stock_issuance: optional string` Net common stock issuance - `net_debt_issuance: optional string` Net debt issuance (long-term + short-term) - `net_dividends_paid: optional string` Net dividends paid (common + preferred) - `net_income: optional string` Net income for the period - `net_preferred_stock_issuance: optional string` Net preferred stock issuance - `net_stock_issuance: optional string` Net stock issuance (common + preferred) - `operating_cash_flow: optional string` Operating cash flow (alternative calculation) - `other_financing_activities: optional string` Other financing activities - `other_investing_activities: optional string` Other investing activities - `other_non_cash_items: optional string` Other non-cash items - `other_working_capital: optional string` Change in other working capital - `preferred_dividends_paid: optional string` Preferred dividends paid - `purchases_of_investments: optional string` Purchases of investments - `sales_maturities_of_investments: optional string` Sales and maturities of investments - `short_term_net_debt_issuance: optional string` Short-term net debt issuance - `stock_based_compensation: optional string` Stock-based compensation expense # Market Data ## Get Snapshots **get** `/v1/market-data/snapshot` Get market data snapshots for one or more securities. ### Query Parameters - `instrument_ids: optional array of string` Comma-separated OEMS instrument UUIDs. ### Returns - `data: MarketDataSnapshotList` - `instrument_id: string` OEMS instrument identifier. - `symbol: string` Display symbol for the security. - `cumulative_volume: optional number` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: optional SnapshotQuote` Most recent quote if available. - `ask: string` Current best ask. - `bid: string` Current best bid. - `midpoint: string` Midpoint of bid and ask. - `ask_size: optional number` Size at the best ask, in shares. - `bid_size: optional number` Size at the best bid, in shares. - `last_trade: optional SnapshotLastTrade` Most recent last-sale trade if available. - `price: string` Most recent last-sale eligible trade price. - `name: optional string` Security name if available. - `session: optional SnapshotSession` Session metrics computed from previous close and last trade, if available. - `change: string` Absolute change from previous close to last trade. - `change_percent: string` Percent change from previous close to last trade. - `previous_close: string` Previous session close price. ### Example ```http curl https://api.clearstreet.com/v1/market-data/snapshot \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "cumulative_volume": 12345678, "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "last_quote": { "ask": "210.14", "ask_size": 120, "bid": "210.10", "bid_size": 100, "midpoint": "210.12" }, "last_trade": { "price": "210.12" }, "name": "Apple Inc.", "session": { "change": "1.82", "change_percent": "0.8737", "previous_close": "208.30" }, "symbol": "AAPL" } ], "error": null, "metadata": { "request_id": "2d0c9159-8f5d-49ca-a861-0d8346fd11da" } } ``` ## Get Daily Aggregate Summaries **get** `/v1/market-data/daily-summary` Returns the most recent OHLV and current price for the requested OEMS instruments. Backed by the in-memory Polygon snapshot cache. Response contract: every request returns one row per **unique** `instrument_id`, in first-seen request order. Unresolvable IDs come back with `symbol = null` and every market-data field `null`; resolvable IDs with no cache entry come back with `symbol` populated but market-data fields `null`. **Note (temporary):** ID resolution currently goes through the supplemental screener (OEMS instrument_id → FMP fmp_symbol → metadata_id → realtime cache). Removed when the market-data service serves daily aggregates directly, or when Polygon symbology is loaded into the instrument cache. ### Query Parameters - `instrument_ids: string` Comma-separated OEMS instrument UUIDs (required, 1..=100) ### Returns - `data: DailySummaryList` - `instrument_id: string` OEMS instrument identifier. Always populated; echoes the request ID. - `high: optional string` Session high. - `low: optional string` Session low. - `open: optional string` Opening price for the session. - `symbol: optional string` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: optional string` Session date the OHLV represents, US/Eastern. - `volume: optional number` Session cumulative trading volume. ### Example ```http curl https://api.clearstreet.com/v1/market-data/daily-summary \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "high": "215.20", "low": "210.10", "open": "211.00", "symbol": "AAPL", "trade_date": "2026-04-23", "volume": 88000000 } ] } ``` ## Domain Types ### Daily Summary - `DailySummary object { instrument_id, high, low, 4 more }` Daily aggregate (OHLV) summary for a single instrument. Returned by `GET /market-data/daily-summary`. Every field except `instrument_id` is `Option`: - Unresolvable `instrument_id` → all other fields `None` (including `symbol`). - Resolvable `instrument_id` with no realtime cache entry → `symbol` populated, OHLV/`trade_date` `None`. - `trade_date` reflects the session the OHLV represents (today during trading hours, the last trading date during weekends/holidays). - `instrument_id: string` OEMS instrument identifier. Always populated; echoes the request ID. - `high: optional string` Session high. - `low: optional string` Session low. - `open: optional string` Opening price for the session. - `symbol: optional string` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: optional string` Session date the OHLV represents, US/Eastern. - `volume: optional number` Session cumulative trading volume. ### Daily Summary List - `DailySummaryList = array of DailySummary` - `instrument_id: string` OEMS instrument identifier. Always populated; echoes the request ID. - `high: optional string` Session high. - `low: optional string` Session low. - `open: optional string` Opening price for the session. - `symbol: optional string` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: optional string` Session date the OHLV represents, US/Eastern. - `volume: optional number` Session cumulative trading volume. ### Market Data Snapshot - `MarketDataSnapshot object { instrument_id, symbol, cumulative_volume, 4 more }` Market data snapshot for a single security. - `instrument_id: string` OEMS instrument identifier. - `symbol: string` Display symbol for the security. - `cumulative_volume: optional number` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: optional SnapshotQuote` Most recent quote if available. - `ask: string` Current best ask. - `bid: string` Current best bid. - `midpoint: string` Midpoint of bid and ask. - `ask_size: optional number` Size at the best ask, in shares. - `bid_size: optional number` Size at the best bid, in shares. - `last_trade: optional SnapshotLastTrade` Most recent last-sale trade if available. - `price: string` Most recent last-sale eligible trade price. - `name: optional string` Security name if available. - `session: optional SnapshotSession` Session metrics computed from previous close and last trade, if available. - `change: string` Absolute change from previous close to last trade. - `change_percent: string` Percent change from previous close to last trade. - `previous_close: string` Previous session close price. ### Market Data Snapshot List - `MarketDataSnapshotList = array of MarketDataSnapshot` - `instrument_id: string` OEMS instrument identifier. - `symbol: string` Display symbol for the security. - `cumulative_volume: optional number` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: optional SnapshotQuote` Most recent quote if available. - `ask: string` Current best ask. - `bid: string` Current best bid. - `midpoint: string` Midpoint of bid and ask. - `ask_size: optional number` Size at the best ask, in shares. - `bid_size: optional number` Size at the best bid, in shares. - `last_trade: optional SnapshotLastTrade` Most recent last-sale trade if available. - `price: string` Most recent last-sale eligible trade price. - `name: optional string` Security name if available. - `session: optional SnapshotSession` Session metrics computed from previous close and last trade, if available. - `change: string` Absolute change from previous close to last trade. - `change_percent: string` Percent change from previous close to last trade. - `previous_close: string` Previous session close price. ### Snapshot Last Trade - `SnapshotLastTrade object { price }` Last-trade fields for a market data snapshot. - `price: string` Most recent last-sale eligible trade price. ### Snapshot Quote - `SnapshotQuote object { ask, bid, midpoint, 2 more }` L1 quote fields for a market data snapshot. - `ask: string` Current best ask. - `bid: string` Current best bid. - `midpoint: string` Midpoint of bid and ask. - `ask_size: optional number` Size at the best ask, in shares. - `bid_size: optional number` Size at the best bid, in shares. ### Snapshot Session - `SnapshotSession object { change, change_percent, previous_close }` Session-level pricing metrics for a market data snapshot. - `change: string` Absolute change from previous close to last trade. - `change_percent: string` Percent change from previous close to last trade. - `previous_close: string` Previous session close price. ### Market Data Get Snapshots Response - `MarketDataGetSnapshotsResponse = BaseResponse` - `data: MarketDataSnapshotList` - `instrument_id: string` OEMS instrument identifier. - `symbol: string` Display symbol for the security. - `cumulative_volume: optional number` Cumulative traded volume reported on the most recent trade, in shares for equities or contracts for options. Absent when no trade is available. - `last_quote: optional SnapshotQuote` Most recent quote if available. - `ask: string` Current best ask. - `bid: string` Current best bid. - `midpoint: string` Midpoint of bid and ask. - `ask_size: optional number` Size at the best ask, in shares. - `bid_size: optional number` Size at the best bid, in shares. - `last_trade: optional SnapshotLastTrade` Most recent last-sale trade if available. - `price: string` Most recent last-sale eligible trade price. - `name: optional string` Security name if available. - `session: optional SnapshotSession` Session metrics computed from previous close and last trade, if available. - `change: string` Absolute change from previous close to last trade. - `change_percent: string` Percent change from previous close to last trade. - `previous_close: string` Previous session close price. ### Market Data Get Daily Summaries Response - `MarketDataGetDailySummariesResponse = BaseResponse` - `data: DailySummaryList` - `instrument_id: string` OEMS instrument identifier. Always populated; echoes the request ID. - `high: optional string` Session high. - `low: optional string` Session low. - `open: optional string` Opening price for the session. - `symbol: optional string` Display symbol for the security. `None` for unresolvable IDs. - `trade_date: optional string` Session date the OHLV represents, US/Eastern. - `volume: optional number` Session cumulative trading volume. # News ## Get News **get** `/v1/news` Retrieves news items with optional filtering by security IDs, time range, publisher, type, and text query. ### Query Parameters - `exclude_publishers: optional string` Comma-separated list of publishers to exclude (mutually exclusive with include_publishers). - `from: optional string` Inclusive start timestamp. Accepts `YYYY-MM-DD` or RFC3339 datetime. - `include_publishers: optional string` Comma-separated list of publishers to include (mutually exclusive with exclude_publishers). - `instrument_ids: optional array of string` Comma-delimited OEMS instrument UUIDs to filter by. - `news_type: optional "NEWS" or "PRESS_RELEASE"` Filter by news type. - `"NEWS"` - `"PRESS_RELEASE"` - `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. - `search_query: optional string` Free-text query matched against title/text and associated security IDs. - `sectors: optional array of "BASIC_MATERIALS" or "COMMUNICATION_SERVICES" or "CONSUMER_CYCLICAL" or 8 more` Comma-separated sector values to filter by. - `"BASIC_MATERIALS"` - `"COMMUNICATION_SERVICES"` - `"CONSUMER_CYCLICAL"` - `"CONSUMER_DEFENSIVE"` - `"ENERGY"` - `"FINANCIAL_SERVICES"` - `"HEALTHCARE"` - `"INDUSTRIALS"` - `"REAL_ESTATE"` - `"TECHNOLOGY"` - `"UTILITIES"` - `to: optional string` Inclusive end timestamp. Accepts `YYYY-MM-DD` or RFC3339 datetime. ### Returns - `data: NewsItemList` - `instruments: array of NewsInstrument` Instruments associated with this news item. - `instrument_id: string` OEMS instrument UUID. - `name: optional string` Instrument name/description, if available from instrument cache enrichment. - `symbol: optional string` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: string` The published date/time of the article in UTC. - `publisher: string` The publisher or newswire source. - `title: string` The headline/title of the article. - `url: string` Canonical URL to the full article. - `image_url: optional string` URL of an associated image if provided by the source. - `site: optional string` The primary domain/site of the publisher. - `text: optional string` The full or excerpted article body. ### Example ```http curl https://api.clearstreet.com/v1/news \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "instruments": [ { "instrument_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Apple Inc.", "symbol": "AAPL" } ], "news_type": "NEWS", "published_at": "2025-10-31T14:30:00.000000000Z", "publisher": "Reuters", "site": "reuters.com", "title": "Apple announces new hardware lineup", "url": "https://example.com/news/1" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E", "page_number": 1, "request_id": "0f1a2b3c-4d5e-6f78-9012-3a4b5c6d7e8f", "total_items": 25, "total_pages": 3 } } ``` ## Domain Types ### News Instrument - `NewsInstrument object { instrument_id, name, symbol }` Instrument associated with a news item. - `instrument_id: string` OEMS instrument UUID. - `name: optional string` Instrument name/description, if available from instrument cache enrichment. - `symbol: optional string` Trading symbol, if available from instrument cache enrichment. ### News Item - `NewsItem object { instruments, news_type, published_at, 6 more }` A single news item and its associated instruments. - `instruments: array of NewsInstrument` Instruments associated with this news item. - `instrument_id: string` OEMS instrument UUID. - `name: optional string` Instrument name/description, if available from instrument cache enrichment. - `symbol: optional string` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: string` The published date/time of the article in UTC. - `publisher: string` The publisher or newswire source. - `title: string` The headline/title of the article. - `url: string` Canonical URL to the full article. - `image_url: optional string` URL of an associated image if provided by the source. - `site: optional string` The primary domain/site of the publisher. - `text: optional string` The full or excerpted article body. ### News Item List - `NewsItemList = array of NewsItem` - `instruments: array of NewsInstrument` Instruments associated with this news item. - `instrument_id: string` OEMS instrument UUID. - `name: optional string` Instrument name/description, if available from instrument cache enrichment. - `symbol: optional string` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: string` The published date/time of the article in UTC. - `publisher: string` The publisher or newswire source. - `title: string` The headline/title of the article. - `url: string` Canonical URL to the full article. - `image_url: optional string` URL of an associated image if provided by the source. - `site: optional string` The primary domain/site of the publisher. - `text: optional string` The full or excerpted article body. ### News Type - `NewsType = "NEWS" or "PRESS_RELEASE"` News item classification. - `"NEWS"` - `"PRESS_RELEASE"` ### News Get News Response - `NewsGetNewsResponse = BaseResponse` - `data: NewsItemList` - `instruments: array of NewsInstrument` Instruments associated with this news item. - `instrument_id: string` OEMS instrument UUID. - `name: optional string` Instrument name/description, if available from instrument cache enrichment. - `symbol: optional string` Trading symbol, if available from instrument cache enrichment. - `news_type: NewsType` Classification of the item. - `"NEWS"` - `"PRESS_RELEASE"` - `published_at: string` The published date/time of the article in UTC. - `publisher: string` The publisher or newswire source. - `title: string` The headline/title of the article. - `url: string` Canonical URL to the full article. - `image_url: optional string` URL of an associated image if provided by the source. - `site: optional string` The primary domain/site of the publisher. - `text: optional string` The full or excerpted article body. # Instruments ## Get Instruments **get** `/v1/instruments` Retrieves a list of tradeable instruments. ### Query Parameters - `easy_to_borrow: optional boolean` Filter by easy to borrow status - `instrument_ids: optional array of string` Comma-separated OEMS instrument UUIDs - `instrument_type: optional "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Filter by instrument type. OPTION is not supported on this endpoint; use GET /instruments/options/contracts to list option contracts. If omitted, returns all supported instrument types except options. - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `is_liquidation_only: optional boolean` Filter by liquidation only status - `is_marginable: optional boolean` Filter by marginable status - `is_restricted: optional boolean` Filter by restricted status - `is_short_prohibited: optional boolean` Filter by short prohibited status - `is_threshold_security: optional boolean` Filter by threshold security status - `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 - `data: InstrumentCoreList` - `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 SecurityType` 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. - `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 ### Example ```http curl https://api.clearstreet.com/v1/instruments \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "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" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPUdNRQ==", "page_number": 1, "request_id": "4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d", "total_items": 10, "total_pages": 5 } } ``` ## Get Instrument By ID **get** `/v1/instruments/{instrument_id}` Retrieves detailed information for a specific instrument. ### Path Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Query Parameters - `include_options_expiry_dates: optional boolean` When true, include unique options expiry dates for this instrument ### Returns - `data: Instrument` Represents a tradable financial instrument. - `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 SecurityType` 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 ### Example ```http curl https://api.clearstreet.com/v1/instruments/$INSTRUMENT_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "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, "long_margin_rate": "0.25", "name": "Apple Inc.", "short_margin_rate": "0.25", "symbol": "AAPL", "venue": "XNMS" }, "error": null, "metadata": { "request_id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" } } ``` ## Search Instruments **get** `/v1/instruments/search` Search instruments by symbol, alternate identifier, or company name. The `q` parameter is case-insensitive and supports ticker symbols, alternate identifiers such as CUSIP, ISIN, OPRA root, and CMS identifiers, and company names for non-option instruments. Results are ranked by match quality plus instrument quality signals including log-scaled ADV, listing status, marginability, easy-to-borrow status, and OTC, restricted, and liquidation-only penalties. Defaults to the `EQUITY` asset class (common stocks, preferred shares, ADRs, ETFs, and exchange-traded mutual funds). Pass `asset_class=OPTION` to search option contracts by symbol or alternate identifier. ### Query Parameters - `q: string` Search term applied case-insensitively to ticker symbols, alternate identifiers (CUSIP, ISIN, OPRA root, CMS), and company names for non-option instruments. Option searches match symbols and alternate identifiers. - `asset_class: optional string` Comma-separated asset classes (EQUITY|OPTION|WARRANT|BOND|FX|OTHER). Defaults to EQUITY. - `country: optional string` Optional listing-country filter (e.g., US). - `currency: optional string` Optional ISO currency filter (e.g., USD). - `include_inactive: optional boolean` Include inactive instruments. Default false. - `include_restricted: optional boolean` Include restricted instruments. Default true (penalized in ranking). - `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 - `data: InstrumentCoreList` - `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 SecurityType` 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. - `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 ### Example ```http curl https://api.clearstreet.com/v1/instruments/search \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "currency": "USD", "id": "0f5a1a4e-5b3e-4d8f-9b7a-2b1d0e3f4a5b", "instrument_type": "COMMON_STOCK", "is_marginable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "..." } } ``` ## Get Option Contracts **get** `/v1/instruments/options/contracts` List options contracts. Returns options contracts for a given underlier with options-specific metadata. Exactly one underlier identifier must be provided. ### Query Parameters - `contract_type: optional ContractType` Filter by contract type: CALL or PUT - `"CALL"` - `"PUT"` - `expiry: optional string` Filter to contracts expiring on this date (YYYY-MM-DD) - `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. - `underlier: optional string` Underlier symbol (e.g., AAPL, SPX) - `underlying_instrument_id: optional InstrumentIDOrSymbol` OEMS instrument UUID or symbol of the underlying equity/index ### Returns - `data: OptionsContractList` - `id: string` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: string` ISO currency code - `exchange: string` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: string` Expiration date - `is_liquidation_only: boolean` Whether the contract is liquidation-only - `is_marginable: boolean` Whether the contract is marginable - `is_restricted: boolean` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: string` Contract multiplier (100 for standard options) - `strike_price: string` Strike price - `symbol: string` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: optional number` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: optional string` OEMS instrument ID of the underlying instrument, if resolvable ### Example ```http curl https://api.clearstreet.com/v1/instruments/options/contracts \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "contract_type": "CALL", "currency": "USD", "exchange": "BATO", "exercise_style": "AMERICAN", "expiry": "2026-03-20", "id": "b6f4b5e2-94a8-4fe4-9a85-2b4a81d30cc5", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_tradable": true, "listing_type": "STANDARD", "multiplier": "100", "strike_price": "180", "symbol": "AAPL 260320C00180000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8" }, { "contract_type": "PUT", "currency": "USD", "exchange": "BATO", "exercise_style": "AMERICAN", "expiry": "2026-03-20", "id": "c7e5c6f3-a5b9-5gf5-0b96-3c5b92e41dd6", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_tradable": true, "listing_type": "STANDARD", "multiplier": "100", "strike_price": "180", "symbol": "AAPL 260320P00180000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8" } ], "metadata": { "page_number": 1, "request_id": "c2d0429d-c629-4ee1-b719-df007157f3bb", "total_items": 2, "total_pages": 1 } } ``` ## Domain Types ### Contract Type - `ContractType = "CALL" or "PUT"` The type of options contract - `"CALL"` - `"PUT"` ### Exercise Style - `ExerciseStyle = "AMERICAN" or "EUROPEAN"` The exercise style of an options contract - `"AMERICAN"` - `"EUROPEAN"` ### Instrument - `Instrument object { id, country_of_issue, currency, 19 more }` Represents a tradable financial instrument. - `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 SecurityType` 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 ### Instrument Core - `InstrumentCore object { id, country_of_issue, currency, 18 more }` - `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 SecurityType` 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. - `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 ### Instrument Core List - `InstrumentCoreList = array of InstrumentCore` - `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 SecurityType` 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. - `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 ### Listing Type - `ListingType = "STANDARD" or "FLEX" or "OTC"` The listing type of an options contract - `"STANDARD"` - `"FLEX"` - `"OTC"` ### Options Contract - `OptionsContract object { id, contract_type, currency, 12 more }` An options contract with options-specific metadata - `id: string` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: string` ISO currency code - `exchange: string` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: string` Expiration date - `is_liquidation_only: boolean` Whether the contract is liquidation-only - `is_marginable: boolean` Whether the contract is marginable - `is_restricted: boolean` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: string` Contract multiplier (100 for standard options) - `strike_price: string` Strike price - `symbol: string` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: optional number` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: optional string` OEMS instrument ID of the underlying instrument, if resolvable ### Options Contract List - `OptionsContractList = array of OptionsContract` - `id: string` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: string` ISO currency code - `exchange: string` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: string` Expiration date - `is_liquidation_only: boolean` Whether the contract is liquidation-only - `is_marginable: boolean` Whether the contract is marginable - `is_restricted: boolean` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: string` Contract multiplier (100 for standard options) - `strike_price: string` Strike price - `symbol: string` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: optional number` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: optional string` OEMS instrument ID of the underlying instrument, if resolvable ### Instrument Get Instruments Response - `InstrumentGetInstrumentsResponse = BaseResponse` - `data: InstrumentCoreList` - `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 SecurityType` 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. - `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 ### Instrument Get Instrument By ID Response - `InstrumentGetInstrumentByIDResponse = BaseResponse` - `data: Instrument` Represents a tradable financial instrument. - `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 SecurityType` 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 ### Instrument Search Instruments Response - `InstrumentSearchInstrumentsResponse = BaseResponse` - `data: InstrumentCoreList` - `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 SecurityType` 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. - `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 ### Instrument Get Option Contracts Response - `InstrumentGetOptionContractsResponse = BaseResponse` - `data: OptionsContractList` - `id: string` OEMS instrument identifier - `contract_type: ContractType` Whether this is a CALL or PUT - `"CALL"` - `"PUT"` - `currency: string` ISO currency code - `exchange: string` MIC code of the primary listing venue - `exercise_style: ExerciseStyle` Exercise style - `"AMERICAN"` - `"EUROPEAN"` - `expiry: string` Expiration date - `is_liquidation_only: boolean` Whether the contract is liquidation-only - `is_marginable: boolean` Whether the contract is marginable - `is_restricted: boolean` Whether the contract is restricted from trading - `listing_type: ListingType` Listing type - `"STANDARD"` - `"FLEX"` - `"OTC"` - `multiplier: string` Contract multiplier (100 for standard options) - `strike_price: string` Strike price - `symbol: string` OSI symbol (e.g. "AAPL 251219C00150000") - `open_interest: optional number` Open interest (number of outstanding contracts), if available - `underlying_instrument_id: optional string` OEMS instrument ID of the underlying instrument, if resolvable # Omni AI ## Domain Types ### Action Button - `ActionButton object { buttonId, label, prompt, structuredAction }` Button metadata shared by chart and suggested-actions payloads. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Chart Payload - `ChartPayload object { chartId, actionButtons, dataChart, symbolChart }` Typed chart payload rendered inline in assistant content. - `chartId: string` Stable chart identifier scoped to the content part. - `actionButtons: optional array of ActionButton` Buttons associated with this chart. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. - `dataChart: optional DataChart` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional SymbolChart` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Chart Point - `ChartPoint object { x, y }` Single chart coordinate. - `x: string` - `y: number` ### Chart Series - `ChartSeries object { name, points }` Named data series within a chart. - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` ### Content Part Chart Payload - `ContentPartChartPayload object { payload }` Chart payload content part. - `payload: ChartPayload` Typed chart payload rendered inline in assistant content. - `chartId: string` Stable chart identifier scoped to the content part. - `actionButtons: optional array of ActionButton` Buttons associated with this chart. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. - `dataChart: optional DataChart` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional SymbolChart` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Content Part Custom Payload - `ContentPartCustomPayload object { payload }` Escape-hatch custom payload content part. - `payload: unknown` ### Content Part Structured Action Payload - `ContentPartStructuredActionPayload object { action, action_id }` Structured action content part. - `action: StructuredAction` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `PrefillOrder object { prefill_order }` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` - `OpenChart object { open_chart }` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `OpenScreener object { open_screener }` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). - `OpenEntitlementConsent object { open_entitlement_consent }` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` - `action_id: string` ### Content Part Suggested Actions Payload - `ContentPartSuggestedActionsPayload object { payload }` Suggested actions payload content part. - `payload: SuggestedActionsPayload` Suggested follow-up buttons rendered at the end of an assistant message. - `actionButtons: optional array of ActionButton` Ordered message-level buttons. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Content Part Text Payload - `ContentPartTextPayload object { text }` Text content part. - `text: string` ### Content Part Thinking Payload - `ContentPartThinkingPayload object { thoughts }` Thinking content part shown on dynamic response polling. - `thoughts: array of string` ### Data Chart - `DataChart object { series }` Chart represented by explicit data series. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` ### Open Chart Action - `OpenChartAction object { symbol, extras, timeframe }` Action to open a chart for a symbol. - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") ### Open Entitlement Consent Action - `OpenEntitlementConsentAction object { agreement_key, reason, requested_entitlement_codes, trading_account_ids }` Action to open entitlement consent flow for one or more accounts. - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Open Screener Action - `OpenScreenerAction object { filters, field_filter, page_size, 2 more }` Action to open a stock screener with filters. - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). ### Prefill Cancel Order Action - `PrefillCancelOrderAction object { orders }` Cancel-order prefill action. - `orders: array of CancelOrderRequest` Orders to cancel using the same identifiers required by the cancel-order API. - `account_id: number` Account ID (from path parameter) - `order_id: string` Order ID to cancel (from path parameter) ### Prefill New Order Action - `PrefillNewOrderAction object { orders }` New-order prefill action. - `orders: array of NewOrderRequest` Orders to prefill using the same shape accepted by the orders API. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: string` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: optional string` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: optional InstrumentIDOrSymbol` OEMS instrument UUID - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: optional PositionEffect` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `"OPEN"` - `"CLOSE"` - `stop_price: optional string` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: optional string` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: optional string` Trailing offset amount (required for trailing orders) - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Prefill Order Action - `PrefillOrderAction = PrefillNewOrderAction or PrefillCancelOrderAction` Action to prefill order details for user confirmation. The user must review and authorize the order before submission to the trading API. This action provides parsed order data that can be used to prefill an order ticket UI or submitted directly via the orders API after user confirmation. - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` ### Prompt Button Action - `PromptButtonAction object { prompt }` Prompt-style button behavior. - `prompt: string` Prompt text to submit as the next user turn. ### Screener Filter - `ScreenerFilter object { field, operator, value }` A single filter criterion for the screener. - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value ### Structured Action - `StructuredAction = object { prefill_order } or object { open_chart } or object { open_screener } or object { open_entitlement_consent }` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `PrefillOrder object { prefill_order }` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` - `OpenChart object { open_chart }` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `OpenScreener object { open_screener }` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). - `OpenEntitlementConsent object { open_entitlement_consent }` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Structured Action Button Action - `StructuredActionButtonAction object { actionId }` Structured-action button behavior. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Suggested Actions Payload - `SuggestedActionsPayload object { actionButtons }` Suggested follow-up buttons rendered at the end of an assistant message. - `actionButtons: optional array of ActionButton` Ordered message-level buttons. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Symbol Chart - `SymbolChart object { symbol, timeframe }` Chart for a single symbol and timeframe. - `symbol: string` - `timeframe: optional string` # Entitlements ## Get Entitlements **get** `/v1/omni-ai/entitlements` List caller's active entitlement grants. ### Query Parameters - `trading_account_id: optional number` ### Returns - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Create Entitlements **post** `/v1/omni-ai/entitlements` Record consent and upsert one-or-more active grants. ### Body Parameters - `agreement_id: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Returns - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "agreement_id": "01JZ0000000000000000000000", "requested_entitlement_codes": [ "omni.account_data" ], "trading_account_ids": [ 100019, 100021 ] }' ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Delete Entitlement **delete** `/v1/omni-ai/entitlements/{entitlement_id}` Revoke one entitlement grant by id. ### Path Parameters - `entitlement_id: string` ### Returns - `data: DeleteEntitlementResponse` - `entitlement_id: string` - `revoked: boolean` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements/$ENTITLEMENT_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "entitlement_id": "entitlement_id", "revoked": true } } ``` ## Get Entitlement Agreements **get** `/v1/omni-ai/entitlement-agreements` List current signable entitlement agreements for consent UX. ### Returns - `data: EntitlementAgreementResourceList` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlement-agreements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "agreement_key": "omni_account_data_access", "document_content": "document_content", "document_sha256": "document_sha256", "entitlement_codes": [ "omni.account_data" ], "title": "title", "version": 0 } ] } ``` ## Domain Types ### Delete Entitlement Response - `DeleteEntitlementResponse object { entitlement_id, revoked }` - `entitlement_id: string` - `revoked: boolean` ### Entitlement Agreement Key - `EntitlementAgreementKey = "omni_account_data_access"` Stable entitlement agreement family key. - `"omni_account_data_access"` ### Entitlement Agreement Resource - `EntitlementAgreementResource object { agreement_id, agreement_key, document_content, 4 more }` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Entitlement Agreement Resource List - `EntitlementAgreementResourceList = array of EntitlementAgreementResource` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Entitlement Code - `EntitlementCode = "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` ### Entitlement Resource - `EntitlementResource object { agreement_id, entitlement_code, entitlement_id, 2 more }` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Resource List - `EntitlementResourceList = array of EntitlementResource` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Get Entitlements Response - `EntitlementGetEntitlementsResponse = BaseResponse` - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Create Entitlements Response - `EntitlementCreateEntitlementsResponse = BaseResponse` - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Delete Entitlement Response - `EntitlementDeleteEntitlementResponse = BaseResponse` - `data: DeleteEntitlementResponse` - `entitlement_id: string` - `revoked: boolean` ### Entitlement Get Entitlement Agreements Response - `EntitlementGetEntitlementAgreementsResponse = BaseResponse` - `data: EntitlementAgreementResourceList` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` # Messages ## Get Message By ID **get** `/v1/omni-ai/messages/{message_id}` Get a finalized message by ID. Returns a single finalized message. Returns **404** if the message belongs to an in-progress assistant turn (use the response endpoint for live output). Once the turn completes, the message becomes available here. ### Path Parameters - `message_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Message` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/messages/$MESSAGE_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, "metadata": { "request_id": "0f991501-757d-4051-bf00-6d7f452d6fcf" } } ``` ## Submit Feedback **post** `/v1/omni-ai/messages/{message_id}/feedback` Submit feedback on a finalized assistant message. Attaches a score and optional comment to a finalized assistant message. Feedback is only valid for messages with role `ASSISTANT` that have reached a terminal outcome. ### Path Parameters - `message_id: string` ### Body Parameters - `account_id: number` Account ID for the request - `score: number` Feedback score (-1, 0, +1 or 1-5) - `comment: optional string` Optional feedback comment - `metadata: optional unknown` Optional metadata ### Returns - `data: CreateFeedbackResponse` - `created_at: string` - `feedback_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/messages/$MESSAGE_ID/feedback \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 0, "score": 0 }' ``` #### Response ```json { "data": { "created_at": "2026-04-23T16:09:51.746912+00:00", "feedback_id": "019dbb1a-d782-7f42-8dd8-a1a7ca5d48e3" }, "metadata": { "request_id": "372a359a-fd4f-4c69-8f11-d80831aa5f23" } } ``` ## Domain Types ### Create Feedback Response - `CreateFeedbackResponse object { created_at, feedback_id }` - `created_at: string` - `feedback_id: optional string` ### Message Get Message By ID Response - `MessageGetMessageByIDResponse = BaseResponse` - `data: Message` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Submit Feedback Response - `MessageSubmitFeedbackResponse = BaseResponse` - `data: CreateFeedbackResponse` - `created_at: string` - `feedback_id: optional string` # Responses ## Get Response By ID **get** `/v1/omni-ai/responses/{response_id}` Poll a response for assistant output. Returns the current snapshot of an in-progress or completed response. While the status is `queued` or `running`, the content may be partial and may include `thinking` parts. Poll this endpoint periodically until the status reaches a terminal value (`succeeded`, `failed`, or `canceled`). Once terminal, the finalized assistant message is available in thread history via `GET /omni-ai/threads/{thread_id}/messages`. ### Path Parameters - `response_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "AAPL is currently trading at ...", "type": "text" }, { "thoughts": [ "Fetching current market data for AAPL..." ], "type": "thinking" } ] }, "id": "019dbafd-db54-7523-a412-ec9195cc5d99", "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81", "status": "succeeded", "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad", "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174" }, "metadata": { "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb" } } ``` ## Cancel Response **delete** `/v1/omni-ai/responses/{response_id}` Cancel a response. Requests cancellation of a queued or running response. If the response has already reached a terminal status, this is an idempotent success. A canceled turn still produces a final assistant message with outcome `canceled` in the thread history. ### Path Parameters - `response_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: CancelResponsePayload` - `canceled: boolean` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "canceled": false }, "metadata": { "request_id": "fa26a786-f5d3-48b0-80eb-778e17af4964" } } ``` ## Domain Types ### Cancel Response Payload - `CancelResponsePayload object { canceled }` - `canceled: boolean` ### Error Status - `ErrorStatus object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Response - `Response object { id, status, thread_id, 4 more }` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Response Content - `ResponseContent object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Content Part - `ResponseContentPart = ContentPartTextPayload or ContentPartThinkingPayload or ContentPartStructuredActionPayload or 3 more` Dynamic content part visible on a pollable response. - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Status - `ResponseStatus = "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` ### Response Get Response By ID Response - `ResponseGetResponseByIDResponse = BaseResponse` - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Response Cancel Response Response - `ResponseCancelResponseResponse = BaseResponse` - `data: CancelResponsePayload` - `canceled: boolean` # Threads ## Get Threads **get** `/v1/omni-ai/threads` List conversation threads. Returns thread metadata ordered by most recently created first. Use `page_size` and `page_token` for pagination. Thread objects contain only metadata (title, timestamps) — use the messages endpoint for conversation history. ### Query Parameters - `account_id: number` Account ID for the request - `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 - `data: ThreadList` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" } ], "metadata": { "request_id": "eb95e1b8-d245-41b1-bbd0-cc1073e68bfd" } } ``` ## Get Thread By ID **get** `/v1/omni-ai/threads/{thread_id}` Get a specific thread. Returns metadata (title, timestamps) for a single thread. Does not include messages — use `GET /omni-ai/threads/{thread_id}/messages` for conversation history. ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" }, "metadata": { "request_id": "5683a394-6dd1-4843-8591-f102ced2e636" } } ``` ## Create Thread **post** `/v1/omni-ai/threads` Create a new conversation thread. Atomically creates a new thread and submits the first user turn. The response contains a `response_id` that should be polled via `GET /omni-ai/responses/{response_id}` for assistant output. Two creation modes are supported: - **instant** — provide `text` with a natural-language prompt. - **deep\_insights** — provide a `target` ticker and optional `thesis` for long-form research. ### Body Parameters - `account_id: number` - `type: "instant" or "deep_insights"` Thread creation mode. - `"instant"` - `"deep_insights"` - `capabilities: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` - `target: optional object { ticker, type }` Deep-insights target payload. - `ticker: string` - `type: "ticker"` Deep-insights target type. Launch supports ticker-only. - `"ticker"` - `text: optional string` - `thesis: optional string` ### Returns - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 19816, "type": "instant" }' ``` #### Response ```json { "data": { "response_id": "019dbae9-73b4-7760-a947-8b4bcab57c49", "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "user_message_id": "019dbae9-73b8-75b2-9c06-ac348927696d" }, "metadata": { "request_id": "f7a9ad4d-753a-403e-aa0e-ca151f991a81" } } ``` ## Get Thread Response **get** `/v1/omni-ai/threads/{thread_id}/response` Get the active response for a thread. Convenience endpoint to look up the currently active response for a thread without knowing the `response_id`. Useful when reloading a thread whose last finalized message is a `USER` message — this indicates an assistant turn is likely in progress. Returns **404** if no active response exists (the thread is idle). ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/response \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "", "type": "text" }, { "thoughts": [ "[1/4] Running parallel analysis on AAPL -- fundamentals, technicals, sentiment, and macro..." ], "type": "thinking" } ] }, "id": "019dbb03-cf23-74e1-9c31-ef0136ff7fed", "output_message_id": "019dbb03-cf32-74d1-906b-a148d4be3da9", "status": "running", "thread_id": "019dbb03-cf22-7da0-a663-f51c756efa07", "user_message_id": "019dbb03-cf24-7b03-8286-5bfc2411b052" }, "metadata": { "request_id": "927a85a6-b11b-4cc5-a2cd-3f46ae64e85d" } } ``` ## Get Messages **get** `/v1/omni-ai/threads/{thread_id}/messages` List finalized messages in a thread. Returns **finalized** messages in chronological order. Messages from in-progress assistant turns are excluded — use `GET /omni-ai/threads/{thread_id}/response` or `GET /omni-ai/responses/{response_id}` for live output. If the last finalized message has role `USER`, an active response likely exists and should be polled separately. ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request - `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 - `data: MessageList` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/messages \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "content": { "parts": [ { "text": "How are the markets doing today?", "type": "text" } ] }, "created_at": "2026-04-16T09:20:17.274943+00:00", "id": "019d9597-5983-7691-8281-7ce264127740", "outcome": "completed", "role": "USER", "seq": 1, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" } ], "metadata": { "request_id": "664c0f85-cdab-4fac-afe3-8ecc0148cd4a" } } ``` ## Create Message **post** `/v1/omni-ai/threads/{thread_id}/messages` Continue an existing conversation thread. Appends a new user message to the thread and starts an assistant response. Only one response may be active per thread at a time — if the previous turn is still in progress, this endpoint returns **409 Conflict**. Wait for the active response to reach a terminal status before submitting the next turn. Poll the returned `response_id` via `GET /omni-ai/responses/{response_id}` for assistant output. ### Path Parameters - `thread_id: string` ### Body Parameters - `account_id: number` - `text: string` - `capabilities: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` ### Returns - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/messages \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 19816, "text": "Compare that to AMD." }' ``` #### Response ```json { "data": { "response_id": "019dbaec-8dd3-7fa3-89d0-5303609f125f", "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "user_message_id": "019dbaec-8dd4-7f91-bce2-3ec8fba79eb7" }, "metadata": { "request_id": "48775400-61f4-4c6c-bc6d-8f4996c571c7" } } ``` ## Domain Types ### Create Message Response - `CreateMessageResponse object { response_id, thread_id, user_message_id }` Response payload for continuing a thread with a new message. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Create Thread Response - `CreateThreadResponse object { response_id, thread_id, user_message_id }` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Message - `Message object { id, content, created_at, 5 more }` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Content - `MessageContent object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message Content Part - `MessageContentPart = ContentPartTextPayload or ContentPartStructuredActionPayload or ContentPartChartPayload or 2 more` Final immutable content part visible on persisted messages. - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message List - `MessageList = array of Message` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Outcome - `MessageOutcome = "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` ### Message Role - `MessageRole = "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` ### Thread - `Thread object { id, created_at, title, updated_at }` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread List - `ThreadList = array of Thread` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Get Threads Response - `ThreadGetThreadsResponse = BaseResponse` - `data: ThreadList` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Get Thread By ID Response - `ThreadGetThreadByIDResponse = BaseResponse` - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Create Thread Response - `ThreadCreateThreadResponse = BaseResponse` - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Thread Get Thread Response Response - `ThreadGetThreadResponseResponse = BaseResponse` - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Thread Get Messages Response - `ThreadGetMessagesResponse = BaseResponse` - `data: MessageList` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Thread Create Message Response - `ThreadCreateMessageResponse = BaseResponse` - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: string` - `thread_id: string` - `user_message_id: string` # Orders ## Get Orders **get** `/v1/accounts/{account_id}/orders` List orders for an account with optional filtering ### Path Parameters - `account_id: number` ### Query Parameters - `from: optional string` The start date and time for the query range, inclusive (ISO 8601 format) - `instrument_ids: optional array of string` Comma-separated OEMS instrument UUIDs - `instrument_type: optional "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Instrument type filter (e.g., COMMON_STOCK, OPTION) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `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. - `status: optional array of "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` Comma-separated order statuses to filter by - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: optional string` Filter by symbol - `to: optional string` The end date and time for the query range, inclusive (ISO 8601 format) - `underlying_instrument_ids: optional string` Comma-separated OEMS instrument UUIDs. Matches options orders whose resolved underlier is any of the given IDs. ### Returns - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": "149.95", "client_order_id": "my-ref-id-20251001-001", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "0195f6c7-4f64-7e3c-8b0a-1d8e4f5e6a7b", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PARTIALLY_FILLED", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T13:35:10.000000000Z" }, { "account_id": 19816, "average_fill_price": "450.75", "client_order_id": "my-ref-id-20251001-002", "created_at": "2025-10-31T14:00:00.000000000Z", "filled_quantity": "200", "id": "0195f6c8-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "instrument_id": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9", "instrument_type": "COMMON_STOCK", "leaves_quantity": "0", "limit_price": null, "order_type": "MARKET", "quantity": "200", "side": "SELL", "status": "FILLED", "stop_price": null, "symbol": "MSFT", "time_in_force": "DAY", "updated_at": "2025-10-31T14:00:05.000000000Z" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3RfaWQ9b3JkXzRjRDVlNkY3ZzhIOWkwSjE=", "page_number": 1, "request_id": "d9a4f5b6-c3d4-6e5f-0a1b-7c8d9e0f1a2b", "total_items": 25, "total_pages": 3 } } ``` ## Get Order By ID **get** `/v1/accounts/{account_id}/orders/{order_id}` Get Order By ID ### Path Parameters - `account_id: number` - `order_id: string` ### Returns - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PARTIALLY_FILLED", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T13:35:10.000000000Z" }, "error": null, "metadata": { "request_id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } ``` ## Submit Orders **post** `/v1/accounts/{account_id}/orders` Submit new orders ### Path Parameters - `account_id: number` ### Body Parameters - `orders: array of object { legs, order_type, time_in_force, 3 more } or NewOrderRequest` - `NewOrderMultilegRequest object { legs, order_type, time_in_force, 3 more }` Multileg strategy order request - `legs: array of object { instrument_type, ratio, security, 3 more }` Legs that compose the strategy. - `instrument_type: SecurityType` Security type for the leg. - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `ratio: string` Ratio for the leg. - `security: string` Trading symbol (e.g. "AAPL" or OSI symbol for options) - `side: Side` Leg side. - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `id: optional string` Optional leg reference identifier. - `position_effect: optional PositionEffect` Optional leg position effect. - `"OPEN"` - `"CLOSE"` - `order_type: RequestOrderType` Type of order (currently MARKET or LIMIT for multileg strategy submission) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `limit_price: optional string` Strategy price, required for LIMIT orders. - `quantity: optional string` Optional strategy-level quantity. Multiplies leg quantities. Defaults to 1. - `NewOrderRequest object { instrument_type, order_type, quantity, 13 more }` Request to submit a new order (PlaceOrderRequest from spec) - `instrument_type: SecurityType` Type of security - `order_type: RequestOrderType` Type of order - `quantity: string` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `time_in_force: RequestTimeInForce` Time in force - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: optional string` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: optional InstrumentIDOrSymbol` OEMS instrument UUID - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: optional PositionEffect` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `stop_price: optional string` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: optional string` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: optional string` Trailing offset amount (required for trailing orders) - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Returns - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '[ { "legs": [ { "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-447a-706f-996f-097254663f02", "side": "BUY", "id": "1", "position_effect": "OPEN" }, { "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-4db4-78ec-b4fd-cba8be61cf8a", "side": "SELL", "id": "2", "position_effect": "OPEN" }, { "instrument_type": "OPTION", "ratio": "ratio", "security": "0193bb84-5264-7f20-8fd3-35df82cd6ef0", "side": "BUY", "id": "3", "position_effect": "OPEN" } ], "order_type": "LIMIT", "time_in_force": "DAY", "id": "my-mleg-ref-20251001-001", "limit_price": "0.50", "quantity": "1" } ]' ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "client_order_id": "my-ref-id-20251003-001", "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNAS" }, { "account_id": 19816, "average_fill_price": null, "client_order_id": "my-ref-id-20251003-002", "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "180.00", "order_type": "LIMIT", "quantity": "50", "side": "BUY", "status": "PENDING_NEW", "stop_price": null, "symbol": "TSLA", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNAS" } ], "error": null, "metadata": { "request_id": "ea0b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d" } } ``` ## Replace Order **patch** `/v1/accounts/{account_id}/orders/{order_id}` Replace an order with new parameters ### Path Parameters - `account_id: number` - `order_id: string` ### Body Parameters - `limit_price: optional string` New limit price for the order - `quantity: optional string` New quantity for the order - `stop_price: optional string` New stop price for the order - `time_in_force: optional RequestTimeInForce` New time in force for the order - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` ### Returns - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "limit_price": "150.50", "quantity": "125", "stop_price": "148.00" }' ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.50", "order_type": "LIMIT", "quantity": "125", "side": "BUY", "status": "PENDING_REPLACE", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:10:00.000000000Z" }, "error": null, "metadata": { "request_id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a" } } ``` ## Cancel Open Order **delete** `/v1/accounts/{account_id}/orders/{order_id}` Cancel a specific order ### Path Parameters - `account_id: number` - `order_id: string` ### Returns - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "my-ref-id-20251001-001", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.50", "order_type": "LIMIT", "quantity": "125", "side": "BUY", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" }, "error": null, "metadata": { "request_id": "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b" } } ``` ## Cancel All Open Orders **delete** `/v1/accounts/{account_id}/orders` Cancel all orders for an account ### Path Parameters - `account_id: number` ### Query Parameters - `instrument_ids: optional array of string` Comma-separated OEMS instrument UUIDs - `instrument_type: optional "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Filter by instrument type (e.g., COMMON_STOCK, OPTION) - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `side: optional "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Filter by order side (BUY or SELL) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `type: optional "MARKET" or "LIMIT" or "STOP" or 4 more` Filter by order type (e.g., MARKET, LIMIT) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` ### Returns - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/orders \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": "149.95", "created_at": "2025-10-31T13:30:00.000000000Z", "filled_quantity": "50", "id": "019c0b48-b8fb-700d-8c5e-931d54555f54", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "leaves_quantity": "50", "limit_price": "150.00", "order_type": "LIMIT", "quantity": "100", "side": "BUY", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "AAPL", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" }, { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-31T14:00:00.000000000Z", "filled_quantity": "0", "id": "019c0b49-03af-70d1-8eeb-d69836c9840b", "instrument_id": "b2b3b4b5-c2c3-d2d3-e2e3-e4e5e6e7e8e9", "instrument_type": "COMMON_STOCK", "leaves_quantity": "200", "limit_price": "450.00", "order_type": "LIMIT", "quantity": "200", "side": "SELL", "status": "PENDING_CANCEL", "stop_price": null, "symbol": "MSFT", "time_in_force": "DAY", "updated_at": "2025-10-31T14:15:00.000000000Z" } ], "error": null, "metadata": { "request_id": "fb1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" } } ``` ## Domain Types ### Cancel Order Request - `CancelOrderRequest object { account_id, order_id }` Request to cancel an existing order Note: In the API, order cancellation is done via DELETE request without a body. The order_id and account_id come from the URL path parameters. - `account_id: number` Account ID (from path parameter) - `order_id: string` Order ID to cancel (from path parameter) ### Instrument ID Or Symbol - `InstrumentIDOrSymbol = string` OEMS instrument UUID ### New Order Request - `NewOrderRequest object { instrument_type, order_type, quantity, 13 more }` Request to submit a new order (PlaceOrderRequest from spec) - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: string` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: optional string` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: optional InstrumentIDOrSymbol` OEMS instrument UUID - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: optional PositionEffect` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `"OPEN"` - `"CLOSE"` - `stop_price: optional string` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: optional string` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: optional string` Trailing offset amount (required for trailing orders) - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Order - `Order object { id, account_id, client_order_id, 29 more }` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order List - `OrderList = array of Order` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Status - `OrderStatus = "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` Order status - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` ### Order Type - `OrderType = "MARKET" or "LIMIT" or "STOP" or 4 more` Order type - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` ### Position Effect - `PositionEffect = "OPEN" or "CLOSE"` Position effect for options orders - `"OPEN"` - `"CLOSE"` ### Queue State - `QueueState = "AWAITING_RELEASE" or "RELEASED"` Parent order queue or hold state. - `"AWAITING_RELEASE"` - `"RELEASED"` ### Request Order Type - `RequestOrderType = "MARKET" or "LIMIT" or "STOP" or 3 more` Strict order-type enum for order submission/replacement requests. - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` ### Request Time In Force - `RequestTimeInForce = "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 7 more` Strict time-in-force enum for order submission/replacement requests. - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` ### Side - `Side = "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of an order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` ### Time In Force - `TimeInForce = "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` ### Trailing Offset Type - `TrailingOffsetType = "PRICE" or "BPS"` Trailing offset type for trailing stop orders. - `"PRICE"` - `"BPS"` ### Order Get Orders Response - `OrderGetOrdersResponse = BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Get Order By ID Response - `OrderGetOrderByIDResponse = BaseResponse` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Submit Orders Response - `OrderSubmitOrdersResponse = BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Replace Order Response - `OrderReplaceOrderResponse = BaseResponse` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Cancel Open Order Response - `OrderCancelOpenOrderResponse = BaseResponse` - `data: Order` A trading order with its current state and execution details. This is the unified API representation of an order across its lifecycle, combining data from execution reports, order status queries, and parent/child tracking. - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Order Cancel All Open Orders Response - `OrderCancelAllOpenOrdersResponse = BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. # Positions ## Get Positions **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Path Parameters - `account_id: number` ### Query Parameters - `instrument_ids: optional array of string` Comma-separated OEMS instrument UUIDs - `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. - `sort_by: optional "SYMBOL" or "INSTRUMENT_TYPE" or "QUANTITY" or 4 more` Field to sort by - `"SYMBOL"` - `"INSTRUMENT_TYPE"` - `"QUANTITY"` - `"MARKET_VALUE"` - `"POSITION_TYPE"` - `"UNREALIZED_PNL"` - `"DAILY_UNREALIZED_PNL"` - `sort_direction: optional "ASC" or "DESC"` Sort direction - `"ASC"` - `"DESC"` ### Returns - `data: PositionList` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_id": 19816, "available_quantity": "100", "avg_price": "145.00", "closing_price": "150.50", "closing_price_date": "2025-10-31", "cost_basis": "14500.00", "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_price": "151.00", "instrument_type": "COMMON_STOCK", "market_value": "15050.00", "position_type": "LONG", "quantity": "100", "symbol": "AAPL", "unrealized_pnl": "550.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "180.00", "closing_price": "180.00", "closing_price_date": "2025-10-30", "cost_basis": "-9000.00", "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab", "instrument_price": "178.50", "instrument_type": "COMMON_STOCK", "market_value": "-9000.00", "position_type": "SHORT", "quantity": "-50", "symbol": "TSLA", "unrealized_pnl": "75.00" }, { "account_id": 19816, "available_quantity": "100", "avg_price": "2.50", "closing_price": "2.70", "closing_price_date": "2025-10-30", "cost_basis": "2500.00", "instrument_id": "e5e6e7e8-f5f6-a5a6-b5b6-b7b8b9babcbe", "instrument_price": "2.72", "instrument_type": "OPTION", "market_value": "2700.00", "position_type": "LONG_CALL", "quantity": "10", "symbol": "AAPL250117C00190000", "underlying_instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "unrealized_pnl": "200.00" } ], "error": null, "metadata": { "next_page_token": "cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E=", "page_number": 1, "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c", "total_items": 25, "total_pages": 3 } } ``` ## Close Positions **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Path Parameters - `account_id: number` ### Body Parameters - `cancel_orders: optional boolean` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b57-0850-7b0b-8a2c-5ee3fb5a5876", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## Close Position **delete** `/v1/accounts/{account_id}/positions/{instrument_id}` Delete a position within an account for an instrument. Retrieves orders generated to close the position. ### Path Parameters - `account_id: number` - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Body Parameters - `cancel_orders: optional boolean` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions/$INSTRUMENT_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "account_id": 19816, "average_fill_price": null, "created_at": "2025-10-03T14:01:15.000000000Z", "filled_quantity": "0", "id": "019c0b56-2119-7482-a80f-5a2a316524d9", "instrument_id": "c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa", "instrument_type": "COMMON_STOCK", "leaves_quantity": "25", "limit_price": null, "order_type": "MARKET", "quantity": "25", "side": "SELL", "status": "PENDING_NEW", "stop_price": null, "symbol": "GOOG", "time_in_force": "DAY", "updated_at": "2025-10-03T14:01:15.000000000Z", "venue": "XNMS" } ], "error": null, "metadata": { "request_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c" } } ``` ## List Position Instructions **get** `/v1/accounts/{account_id}/positions/instructions` Returns the current lifecycle state of the account's position instructions. Optionally filter by a specific contract. ### Path Parameters - `account_id: number` ### Query Parameters - `instrument_id: optional InstrumentIDOrSymbol` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions/instructions \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } ] } ``` ## Submit Position Instructions **post** `/v1/accounts/{account_id}/positions/instructions` Submit one or more position instructions (Exercise, Do-Not-Exercise, Contrary Exercise Advice) against the account. Batch semantics: - **All rows accepted** → `200 OK`. Every row is in `data` with `status = SENT`. - **Partial success** → `207 Multi-Status`. `data` contains every row; rejected rows carry `status = ENGINE_REJECTED` (or `REJECTED`) and `rejection_reason`. The top-level `error` summarizes the batch failure. - **All rows rejected** → `4xx`/`5xx` error response. The HTTP status reflects the underlying cause: `409` for duplicate `instruction_id`, `400` for validation failures such as DNE/CEA on a non-expiry day, `503` if the clearing service is unavailable. No `data` is returned. Pre-flight validation (unknown `instrument_id`, unencodable `quantity`) short-circuits the whole batch with a `4xx` before any row is submitted. ### Path Parameters - `account_id: number` ### Body Parameters - `instructions: array of object { instruction_type, instrument_id, quantity, instruction_id }` - `instruction_type: PositionInstructionType` The action to take. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract to act on. Unknown ids return 404. - `quantity: string` Number of contracts to include in the instruction. - `instruction_id: optional string` Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted. ### Returns - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions/instructions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '[ { "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "instruction_id": "ui-20260424-001" } ]' ``` #### Response ```json { "data": [ { "account_id": 122503, "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000" } ], "metadata": { "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01" } } ``` ## Cancel Position Instruction **delete** `/v1/accounts/{account_id}/positions/instructions/{instruction_id}` Cancel an outstanding position instruction by its server-assigned `id`. Returns the updated instruction with status `CANCEL_REQUESTED`. The terminal `CANCELLED` or `CANCEL_FAILED` state arrives asynchronously and is observable via subsequent GETs. ### Path Parameters - `account_id: number` - `instruction_id: string` ### Returns - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Example ```http curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/positions/instructions/$INSTRUCTION_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "account_id": 122503, "instruction_id": "ui-20260424-001", "instruction_type": "EXERCISE", "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02", "quantity": "1", "status": "SENT", "symbol": "AAPL 280121C00195000", "accepted_quantity": null, "created_at": "2026-04-24T14:30:00Z", "rejection_reason": null, "updated_at": "2026-04-24T14:30:00Z" } } ``` ## Domain Types ### Position - `Position object { account_id, available_quantity, instrument_id, 15 more }` Represents a holding of a particular instrument in an account - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Instruction - `PositionInstruction object { id, account_id, instruction_id, 9 more }` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Position Instruction List - `PositionInstructionList = array of PositionInstruction` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Position Instruction Status - `PositionInstructionStatus = "SENT" or "ACCEPTED" or "REJECTED" or 5 more` Lifecycle status of a position instruction. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` ### Position Instruction Type - `PositionInstructionType = "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` The action to take against an options position. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` ### Position List - `PositionList = array of Position` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Type - `PositionType = "LONG" or "SHORT" or "LONG_CALL" or 3 more` Position type classification - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` ### Position Get Positions Response - `PositionGetPositionsResponse = BaseResponse` - `data: PositionList` - `account_id: number` The account this position belongs to - `available_quantity: string` The quantity of a position that is free to be operated on. - `instrument_id: string` OEMS instrument UUID - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: PositionType` The type of position - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` - `quantity: string` The number of shares or contracts. Can be positive (long) or negative (short) - `symbol: string` The trading symbol for the instrument - `avg_price: optional string` The average price paid per share or contract for this position - `closing_price: optional string` The closing price used to value the position for the last trading day - `closing_price_date: optional string` The market date associated with `closing_price` - `cost_basis: optional string` The total cost basis for this position - `daily_unrealized_pnl: optional string` The unrealized profit or loss for this position relative to the previous close - `daily_unrealized_pnl_pct: optional string` The unrealized profit/loss for the position for the current day, expressed as a percentage of the baseline value (range: 0-100). - `instrument_price: optional string` The current market price of the instrument - `underlying_instrument_id: optional string` OEMS instrument identifier of the underlying instrument, if resolvable - `unrealized_pnl: optional string` The total unrealized profit or loss for this position based on current market value - `unrealized_pnl_pct: optional string` The unrealized profit/loss for the position, expressed as a percentage of the position's cost basis (range: 0-100). ### Position Close Positions Response - `PositionClosePositionsResponse = BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Position Close Position Response - `PositionClosePositionResponse = BaseResponse` - `data: OrderList` - `id: string` Engine-assigned unique identifier for this order (UUID). - `account_id: number` Account placing the order - `client_order_id: string` Client-provided identifier echoed back (FIX tag 11). - `created_at: string` Timestamp when order was created (UTC) - `filled_quantity: string` Cumulative filled quantity - `instrument_id: string` OEMS instrument UUID for the traded instrument. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: OrderType` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: Side` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: OrderStatus` Current status of the order - `"PENDING_NEW"` - `"NEW"` - `"PARTIALLY_FILLED"` - `"FILLED"` - `"CANCELED"` - `"REJECTED"` - `"EXPIRED"` - `"PENDING_CANCEL"` - `"PENDING_REPLACE"` - `"REPLACED"` - `"DONE_FOR_DAY"` - `"STOPPED"` - `"SUSPENDED"` - `"CALCULATED"` - `"OTHER"` - `symbol: string` Trading symbol - `time_in_force: TimeInForce` Time in force instruction - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `"OTHER"` - `updated_at: string` Timestamp of the most recent update (UTC) - `venue: string` MIC code of the venue where the order is routed - `average_fill_price: optional string` Average fill price across all executions - `details: optional array of string` Contains execution, rejection or cancellation details, if any - `expires_at: optional string` Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Whether the order is eligible for extended-hours trading. - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (for LIMIT and STOP_LIMIT orders) - `queue_state: optional QueueState` Parent order queue state, present when the order is awaiting release or released. - `"AWAITING_RELEASE"` - `"RELEASED"` - `releases_at: optional string` Scheduled release time for orders awaiting release. - `stop_price: optional string` Stop price (for STOP and STOP_LIMIT orders) - `trailing_limit_px: optional string` Current trailing limit price computed by the trailing strategy - `trailing_offset: optional string` Trailing offset amount for trailing orders - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type for trailing orders - `"PRICE"` - `"BPS"` - `trailing_stop_px: optional string` Current trailing stop price computed by the trailing strategy - `trailing_watermark_px: optional string` Trailing watermark price for trailing orders - `trailing_watermark_ts: optional string` Trailing watermark timestamp for trailing orders - `underlying_instrument_id: optional string` OEMS instrument ID of the option's underlying instrument. Populated only for OPTIONS orders; `null` for non-options and for options whose underlier cannot be resolved from the instrument cache. ### Position Get Position Instructions Response - `PositionGetPositionInstructionsResponse = BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Position Submit Position Instructions Response - `PositionSubmitPositionInstructionsResponse = BaseResponse` - `data: PositionInstructionList` - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. ### Position Cancel Position Instruction Response - `PositionCancelPositionInstructionResponse = BaseResponse` - `data: PositionInstruction` A position instruction and its current lifecycle state. - `id: string` Server-assigned id. Used as the path parameter on cancel. - `account_id: number` Account the instruction belongs to. - `instruction_id: string` Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied. - `instruction_type: PositionInstructionType` The action this instruction requests. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` - `instrument_id: string` Identifier of the options contract this instruction acts on. - `quantity: string` Number of contracts included in the instruction. - `status: PositionInstructionStatus` Current lifecycle status. - `"SENT"` - `"ACCEPTED"` - `"REJECTED"` - `"ENGINE_REJECTED"` - `"CANCEL_REQUESTED"` - `"CANCELLED"` - `"CANCEL_FAILED"` - `"UNKNOWN"` - `symbol: string` Options symbol (OSI) for display. - `accepted_quantity: optional string` Number of contracts accepted by the clearing venue. Populated once the instruction reaches `ACCEPTED`. - `created_at: optional string` When the instruction was first accepted by the service. - `rejection_reason: optional string` Human-readable explanation populated on any non-success terminal status — `REJECTED`, `ENGINE_REJECTED`, or `CANCEL_FAILED`. On a `207 Multi-Status` batch submit the top-level `error` field summarizes the batch; per-row detail continues to live here. - `updated_at: optional string` When the instruction's lifecycle state last changed. # Watchlist ## Get Watchlists **get** `/v1/watchlists` List watchlists for the authenticated user ### Query 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 - `data: WatchlistEntryList` - `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 ```http curl https://api.clearstreet.com/v1/watchlists \ -H "Authorization: Bearer $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 **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Path Parameters - `watchlist_id: string` ### Returns - `data: WatchlistDetail` 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 Instrument` 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 SecurityType` 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 ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID \ -H "Authorization: Bearer $API_KEY" ``` #### 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 **post** `/v1/watchlists` Create Watchlist ### Body Parameters - `name: string` The desired watchlist name. ### Returns - `data: WatchlistEntry` 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 ```http curl https://api.clearstreet.com/v1/watchlists \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "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 **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Path Parameters - `watchlist_id: string` ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Path Parameters - `watchlist_id: string` ### Body Parameters - `instrument_id: InstrumentIDOrSymbol` OEMS instrument UUID ### Returns - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID/items \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "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 **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Path Parameters - `watchlist_id: string` - `item_id: string` ### Example ```http curl https://api.clearstreet.com/v1/watchlists/$WATCHLIST_ID/items/$ITEM_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `AddWatchlistItemData object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Detail - `WatchlistDetail 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 Instrument` 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 SecurityType` 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 - `WatchlistEntry 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 - `WatchlistEntryList = 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 - `WatchlistItemEntry 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 Instrument` 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 SecurityType` 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 ### Watchlist Get Watchlists Response - `WatchlistGetWatchlistsResponse = BaseResponse` - `data: WatchlistEntryList` - `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 Get Watchlist By ID Response - `WatchlistGetWatchlistByIDResponse = BaseResponse` - `data: WatchlistDetail` 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 Instrument` 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 SecurityType` 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 Create Watchlist Response - `WatchlistCreateWatchlistResponse = BaseResponse` - `data: WatchlistEntry` 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 Delete Watchlist Response - `WatchlistDeleteWatchlistResponse = unknown` ### Watchlist Add Watchlist Item Response - `WatchlistAddWatchlistItemResponse = BaseResponse` - `data: AddWatchlistItemData` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Delete Watchlist Item Response - `WatchlistDeleteWatchlistItemResponse = unknown` # Websocket ## Websocket Handler **get** `/v1/ws` Upgrade the HTTP connection to a WebSocket and echo incoming messages. ### Example ```http curl https://api.clearstreet.com/v1/ws \ -H "Authorization: Bearer $API_KEY" ```