# V1 ## Domain Types ### Security Type - `security_type: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Security type - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` # Accounts ## Get Accounts `$ clear-street v1:accounts get-accounts` **get** `/v1/accounts` List accounts the authenticated user has permission to access ### 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 - `V1AccountGetAccountsResponse: BaseResponse` - `data: 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: "ACTIVE" or "INACTIVE" or "CLOSED"` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: "CASH" or "MARGIN" or "OTHER"` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: "CUSTOMER" or "OTHER"` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Example ```cli clear-street v1:accounts get-accounts \ --api-key 'My 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 `$ clear-street v1:accounts get-account-by-id` **get** `/v1/accounts/{account_id}` Fetch account details by ID ### Parameters - `--account-id: number` Account identifier ### Returns - `V1AccountGetAccountByIDResponse: BaseResponse` - `data: 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: "ACTIVE" or "INACTIVE" or "CLOSED"` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: "CASH" or "MARGIN" or "OTHER"` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: "CUSTOMER" or "OTHER"` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Example ```cli clear-street v1:accounts get-account-by-id \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:accounts patch-account-by-id` **patch** `/v1/accounts/{account_id}` Update account risk settings ### Parameters - `--account-id: number` Account identifier - `--risk: optional object { max_notional }` Risk settings for the account ### Returns - `V1AccountPatchAccountByIDResponse: BaseResponse` - `data: object { risk }` - `risk: optional object { max_notional }` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Example ```cli clear-street v1:accounts patch-account-by-id \ --api-key 'My API Key' \ --account-id 0 ``` #### Response ```json { "data": { "risk": { "max_notional": "5000000.00" } }, "error": null, "metadata": { "request_id": "c8f3e4a5-b2c3-5d4e-9f0a-6b7c8d9e0f1a" } } ``` ## Get Account Balances `$ clear-street v1:accounts get-account-balances` **get** `/v1/accounts/{account_id}/balances` Fetch account balance information ### Parameters - `--account-id: number` Account identifier - `--top-margin-contributors-limit: optional number` Limit the number of top margin contributors returned by the engine. ### Returns - `V1AccountGetAccountBalancesResponse: BaseResponse` - `data: 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: "OTHER" or "NONE" or "PORTFOLIO_MARGIN" or 6 more` 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: object { buying_power, equity, long_market_value, 6 more }` 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 object { day_trade_count, initial_margin_excess, initial_margin_requirement, 6 more }` 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 object { total, used }` 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 ```cli clear-street v1:accounts get-account-balances \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:accounts get-portfolio-history` **get** `/v1/accounts/{account_id}/portfolio-history` Retrieves daily portfolio history for the specified account. ### Parameters - `--account-id: number` Account identifier - `--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 - `V1AccountGetPortfolioHistoryResponse: BaseResponse` - `data: 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 ### Example ```cli clear-street v1:accounts get-portfolio-history \ --api-key 'My API Key' \ --account-id 0 \ --start-date "'2019-12-27'" ``` #### 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: "ACTIVE" or "INACTIVE" or "CLOSED"` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: "CASH" or "MARGIN" or "OTHER"` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: "CUSTOMER" or "OTHER"` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Balances - `account_balances: 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: "OTHER" or "NONE" or "PORTFOLIO_MARGIN" or 6 more` 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: object { buying_power, equity, long_market_value, 6 more }` 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 object { day_trade_count, initial_margin_excess, initial_margin_requirement, 6 more }` 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 object { total, used }` 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 - `account_balances_sod: 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 - `account_list: 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: "ACTIVE" or "INACTIVE" or "CLOSED"` The current status of the account - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` - `subtype: "CASH" or "MARGIN" or "OTHER"` The sub-type of account - `"CASH"` - `"MARGIN"` - `"OTHER"` - `type: "CUSTOMER" or "OTHER"` The type of account - `"CUSTOMER"` - `"OTHER"` - `close_date: optional string` The date the account was closed, if applicable ### Account Settings - `account_settings: object { risk }` - `risk: optional object { max_notional }` Risk settings for the account - `max_notional: optional string` The maximum notional value available to the account ### Account Status - `account_status: "ACTIVE" or "INACTIVE" or "CLOSED"` Account status - `"ACTIVE"` - `"INACTIVE"` - `"CLOSED"` ### Account Subtype - `account_subtype: "CASH" or "MARGIN" or "OTHER"` Account subtype classification providing more granular categorization - `"CASH"` - `"MARGIN"` - `"OTHER"` ### Account Type - `account_type: "CUSTOMER" or "OTHER"` Account type classification - `"CUSTOMER"` - `"OTHER"` ### Margin Details - `margin_details: 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 object { total, used }` 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 - `margin_details_usage: 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 - `margin_top_contributor: 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 - `margin_type: "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 - `portfolio_history_response: 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 - `portfolio_history_segment: 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 - `risk_settings: object { max_notional }` Risk settings for an account - `max_notional: optional string` The maximum notional value available to the account # API Version ## Get the API version. `$ clear-street v1:api-version get-version` **get** `/v1/version` Returns the current version string for this API endpoint. ### Returns - `V1APIVersionGetVersionResponse: BaseResponse` - `data: object { version }` API version information - `version: string` API version string ### Example ```cli clear-street v1:api-version get-version \ --api-key 'My 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 # Calendar ## Get Clock `$ clear-street v1:calendar get-clock` **get** `/v1/clock` Returns the current server time in UTC. ### Returns - `V1CalendarGetClockResponse: BaseResponse` - `data: object { clock }` Current server time and market clock information - `clock: string` Current server time in UTC ### Example ```cli clear-street v1:calendar get-clock \ --api-key 'My 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. `$ clear-street v1:calendar 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. ### Parameters - `--date: string` The date to query market hours for (YYYY-MM-DD). Defaults to today. - `--market: optional "us_equities" or "us_options"` Market type to query (us_equities, us_options). If omitted, returns all markets. ### Returns - `V1CalendarGetMarketHoursCalendarResponse: BaseResponse` - `data: array of MarketHoursDetail` - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: "us_equities" or "us_options"` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: object { after_hours, pre_market, regular }` Next trading day's session schedules (without time_until fields) - `after_hours: optional object { close, open, time_until_close, time_until_open }` 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 object { close, open, time_until_close, time_until_open }` Pre-market 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. - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend - `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. - `status: object { day_type, is_open, current_session }` Market status information - `day_type: "TRADING_DAY" or "EARLY_CLOSE" or "HOLIDAY" or "WEEKEND"` 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 "pre_market" or "regular" or "after_hours"` 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: object { after_hours, pre_market, regular }` Trading session schedules for the requested date with time_until fields - `after_hours: optional object { close, open, time_until_close, time_until_open }` After-hours session schedule, null if not available - `pre_market: optional object { close, open, time_until_close, time_until_open }` Pre-market session schedule, null if not available - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend ### Example ```cli clear-street v1:calendar get-market-hours-calendar \ --api-key 'My API Key' \ --date date ``` #### 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 - `clock_detail: object { clock }` Current server time and market clock information - `clock: string` Current server time in UTC ### Day Type - `day_type: "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 - `market_hours_detail: 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: "us_equities" or "us_options"` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: object { after_hours, pre_market, regular }` Next trading day's session schedules (without time_until fields) - `after_hours: optional object { close, open, time_until_close, time_until_open }` 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 object { close, open, time_until_close, time_until_open }` Pre-market 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. - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend - `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. - `status: object { day_type, is_open, current_session }` Market status information - `day_type: "TRADING_DAY" or "EARLY_CLOSE" or "HOLIDAY" or "WEEKEND"` 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 "pre_market" or "regular" or "after_hours"` 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: object { after_hours, pre_market, regular }` Trading session schedules for the requested date with time_until fields - `after_hours: optional object { close, open, time_until_close, time_until_open }` After-hours session schedule, null if not available - `pre_market: optional object { close, open, time_until_close, time_until_open }` Pre-market session schedule, null if not available - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend ### Market Hours Detail List - `market_hours_detail_list: array of MarketHoursDetail` - `current_time: string` Current time in market timezone with offset - `date: string` The date for which market hours are provided - `market: "us_equities" or "us_options"` Market type identifier - `"us_equities"` - `"us_options"` - `market_name: string` Human-readable market name - `next_sessions: object { after_hours, pre_market, regular }` Next trading day's session schedules (without time_until fields) - `after_hours: optional object { close, open, time_until_close, time_until_open }` 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 object { close, open, time_until_close, time_until_open }` Pre-market 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. - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend - `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. - `status: object { day_type, is_open, current_session }` Market status information - `day_type: "TRADING_DAY" or "EARLY_CLOSE" or "HOLIDAY" or "WEEKEND"` 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 "pre_market" or "regular" or "after_hours"` 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: object { after_hours, pre_market, regular }` Trading session schedules for the requested date with time_until fields - `after_hours: optional object { close, open, time_until_close, time_until_open }` After-hours session schedule, null if not available - `pre_market: optional object { close, open, time_until_close, time_until_open }` Pre-market session schedule, null if not available - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend ### Market Session Type - `market_session_type: "pre_market" or "regular" or "after_hours"` Session type for market hours - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Status - `market_status: object { day_type, is_open, current_session }` Market status information - `day_type: "TRADING_DAY" or "EARLY_CLOSE" or "HOLIDAY" or "WEEKEND"` 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 "pre_market" or "regular" or "after_hours"` Current session type if market is open, null if closed - `"pre_market"` - `"regular"` - `"after_hours"` ### Market Type - `market_type: "us_equities" or "us_options"` Market type for market hours calendar endpoint - `"us_equities"` - `"us_options"` ### Session Schedule - `session_schedule: 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 - `trading_sessions: object { after_hours, pre_market, regular }` Trading sessions for a market day with full timestamps - `after_hours: optional object { close, open, time_until_close, time_until_open }` 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 object { close, open, time_until_close, time_until_open }` Pre-market 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. - `regular: optional object { close, open, time_until_close, time_until_open }` Regular trading session schedule, null if holiday/weekend - `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. # Instrument Data ## Get All Instrument Events `$ clear-street v1:instrument-data get-all-instrument-events` **get** `/v1/instruments/events` List instrument events across all securities. Retrieves all instrument events grouped by date. ### Parameters - `--event-type: optional array of AllEventsEventType` Filter by event type(s). Comma-delimited list. Example: `event_types=EARNINGS,IPO`. - `--from-date: optional string` The start date for the query range, inclusive (YYYY-MM-DD). - `--instrument-id: 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 - `V1InstrumentDataGetAllInstrumentEventsResponse: BaseResponse` - `data: 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: "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional object { adjusted_dividend_amount, ex_date, declaration_date, 5 more }` 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 object { date, eps_actual, eps_estimate, 4 more }` 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 object { actions, announced_at, company, 4 more }` 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 object { date, denominator, numerator, split_type }` 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 ```cli clear-street v1:instrument-data get-all-instrument-events \ --api-key 'My 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 `$ clear-street v1:instrument-data 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 ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--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 - `V1InstrumentDataGetInstrumentEventsResponse: BaseResponse` - `data: 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 ### Example ```cli clear-street v1:instrument-data get-instrument-events \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instrument-data get-instrument-fundamentals` **get** `/v1/instruments/{instrument_id}/fundamentals` Retrieves supplemental fundamentals and company profile data for an instrument. ### Parameters - `--instrument-id: string` OEMS instrument UUID ### Returns - `V1InstrumentDataGetInstrumentFundamentalsResponse: BaseResponse` - `data: 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 ### Example ```cli clear-street v1:instrument-data get-instrument-fundamentals \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instrument-data 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) ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--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 - `V1InstrumentDataGetInstrumentBalanceSheetStatementsResponse: BaseResponse` - `data: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 ```cli clear-street v1:instrument-data get-instrument-balance-sheet-statements \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instrument-data 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) ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--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 - `V1InstrumentDataGetInstrumentIncomeStatementsResponse: BaseResponse` - `data: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 ```cli clear-street v1:instrument-data get-instrument-income-statements \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instrument-data get-instrument-analyst-consensus` **get** `/v1/instruments/{instrument_id}/analyst-reporting` Retrieves analyst ratings and price targets for an instrument. ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--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 - `V1InstrumentDataGetInstrumentAnalystConsensusResponse: BaseResponse` - `data: object { date, distribution, price_target, rating }` Aggregated analyst consensus metrics - `date: string` The date the consensus snapshot was generated - `distribution: optional object { buy, hold, sell, 2 more }` 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 object { average, currency, high, low }` 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 "STRONG_BUY" or "BUY" or "HOLD" or 2 more` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Example ```cli clear-street v1:instrument-data get-instrument-analyst-consensus \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instrument-data 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. ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--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 - `V1InstrumentDataGetInstrumentCashFlowStatementsResponse: BaseResponse` - `data: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 ```cli clear-street v1:instrument-data get-instrument-cash-flow-statements \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 - `all_events_event_type: "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event types supported by the all-events endpoint. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` ### Analyst Distribution - `analyst_distribution: 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 - `analyst_rating: "STRONG_BUY" or "BUY" or "HOLD" or 2 more` Analyst rating category - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Fiscal Period Type - `fiscal_period_type: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` Fiscal period type for earnings reports - `"QUARTERLY"` - `"ANNUAL"` - `"TTM"` - `"BIANNUAL"` ### Instrument All Events Data - `instrument_all_events_data: 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: "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional object { adjusted_dividend_amount, ex_date, declaration_date, 5 more }` 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 object { date, eps_actual, eps_estimate, 4 more }` 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 object { actions, announced_at, company, 4 more }` 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 object { date, denominator, numerator, split_type }` 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 - `instrument_analyst_consensus: object { date, distribution, price_target, rating }` Aggregated analyst consensus metrics - `date: string` The date the consensus snapshot was generated - `distribution: optional object { buy, hold, sell, 2 more }` 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 object { average, currency, high, low }` 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 "STRONG_BUY" or "BUY" or "HOLD" or 2 more` Consensus analyst rating - `"STRONG_BUY"` - `"BUY"` - `"HOLD"` - `"SELL"` - `"STRONG_SELL"` ### Instrument Balance Sheet Statement - `instrument_balance_sheet_statement: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_balance_sheet_statement_list: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_cash_flow_statement: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_cash_flow_statement_list: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_dividend_event: 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 - `instrument_earnings: 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 - `instrument_event_envelope: object { symbol, type, dividend_event_data, 6 more }` Unified envelope for the all-events response. - `symbol: string` Symbol associated with the event. - `type: "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional object { adjusted_dividend_amount, ex_date, declaration_date, 5 more }` 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 object { date, eps_actual, eps_estimate, 4 more }` 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 object { actions, announced_at, company, 4 more }` 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 object { date, denominator, numerator, split_type }` 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 - `instrument_event_ipo_item: 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 - `instrument_events_by_date: 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: "EARNINGS" or "DIVIDEND" or "STOCK_SPLIT" or "IPO"` Event type discriminator. - `"EARNINGS"` - `"DIVIDEND"` - `"STOCK_SPLIT"` - `"IPO"` - `dividend_event_data: optional object { adjusted_dividend_amount, ex_date, declaration_date, 5 more }` 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 object { date, eps_actual, eps_estimate, 4 more }` 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 object { actions, announced_at, company, 4 more }` 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 object { date, denominator, numerator, split_type }` 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 - `instrument_events_data: 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 - `instrument_fundamentals: 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 - `instrument_income_statement: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_income_statement_list: 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: "QUARTERLY" or "ANNUAL" or "TTM" or "BIANNUAL"` 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 - `instrument_split_event: 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 - `price_target: 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 # Market Data ## Get Snapshots `$ clear-street v1:instrument-data:market-data get-snapshots` **get** `/v1/market-data/snapshot` Get market data snapshots for one or more securities. ### Parameters - `--instrument-id: optional array of string` Comma-separated OEMS instrument UUIDs. ### Returns - `V1InstrumentDataMarketDataGetSnapshotsResponse: BaseResponse` - `data: 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 object { ask, bid, midpoint, 2 more }` 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 object { price }` 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 object { change, change_percent, previous_close }` 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 ```cli clear-street v1:instrument-data:market-data get-snapshots \ --api-key 'My 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 `$ clear-street v1:instrument-data:market-data get-daily-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. ### Parameters - `--instrument-ids: string` Comma-separated OEMS instrument UUIDs (required, 1..=100) ### Returns - `V1InstrumentDataMarketDataGetDailySummariesResponse: BaseResponse` - `data: 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. ### Example ```cli clear-street v1:instrument-data:market-data get-daily-summaries \ --api-key 'My API Key' \ --instrument-ids instrument_ids ``` #### 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 - `daily_summary: 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 - `daily_summary_list: 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 - `market_data_snapshot: 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 object { ask, bid, midpoint, 2 more }` 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 object { price }` 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 object { change, change_percent, previous_close }` 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 - `market_data_snapshot_list: 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 object { ask, bid, midpoint, 2 more }` 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 object { price }` 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 object { change, change_percent, previous_close }` 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 - `snapshot_last_trade: object { price }` Last-trade fields for a market data snapshot. - `price: string` Most recent last-sale eligible trade price. ### Snapshot Quote - `snapshot_quote: 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 - `snapshot_session: 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. # News ## Get News `$ clear-street v1:instrument-data:news get-news` **get** `/v1/news` Retrieves news items with optional filtering by security IDs, time range, publisher, type, and text 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-id: optional array of string` Comma-delimited OEMS instrument UUIDs to filter by. - `--news-type: optional "NEWS" or "PRESS_RELEASE"` Filter by news type. - `--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. - `--sector: optional array of "BASIC_MATERIALS" or "COMMUNICATION_SERVICES" or "CONSUMER_CYCLICAL" or 8 more` Comma-separated sector values to filter by. - `--to: optional string` Inclusive end timestamp. Accepts `YYYY-MM-DD` or RFC3339 datetime. ### Returns - `V1InstrumentDataNewsGetNewsResponse: BaseResponse` - `data: 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: "NEWS" or "PRESS_RELEASE"` 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 ```cli clear-street v1:instrument-data:news get-news \ --api-key 'My 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 - `news_instrument: 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 - `news_item: 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: "NEWS" or "PRESS_RELEASE"` 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 - `news_item_list: 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: "NEWS" or "PRESS_RELEASE"` 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 - `news_type: "NEWS" or "PRESS_RELEASE"` News item classification. - `"NEWS"` - `"PRESS_RELEASE"` # Instruments ## Get Instruments `$ clear-street v1:instruments get-instruments` **get** `/v1/instruments` Retrieves a list of tradeable instruments. ### Parameters - `--easy-to-borrow: optional boolean` Filter by easy to borrow status - `--instrument-id: 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. - `--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 - `V1InstrumentGetInstrumentsResponse: BaseResponse` - `data: 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 ```cli clear-street v1:instruments get-instruments \ --api-key 'My 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 `$ clear-street v1:instruments get-instrument-by-id` **get** `/v1/instruments/{instrument_id}` Retrieves detailed information for a specific instrument. ### Parameters - `--instrument-id: string` OEMS instrument UUID - `--include-options-expiry-dates: optional boolean` When true, include unique options expiry dates for this instrument ### Returns - `V1InstrumentGetInstrumentByIDResponse: BaseResponse` - `data: 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 ```cli clear-street v1:instruments get-instrument-by-id \ --api-key 'My API Key' \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:instruments 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. ### 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 - `V1InstrumentSearchInstrumentsResponse: BaseResponse` - `data: 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 ```cli clear-street v1:instruments search-instruments \ --api-key 'My API Key' \ --q q ``` #### 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 `$ clear-street v1:instruments 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. ### Parameters - `--contract-type: optional "CALL" or "PUT"` Filter by contract type: CALL or 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 string` OEMS instrument UUID or symbol of the underlying equity/index ### Returns - `V1InstrumentGetOptionContractsResponse: BaseResponse` - `data: array of OptionsContract` - `id: string` OEMS instrument identifier - `contract_type: "CALL" or "PUT"` 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: "AMERICAN" or "EUROPEAN"` 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: "STANDARD" or "FLEX" or "OTC"` 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 ```cli clear-street v1:instruments get-option-contracts \ --api-key 'My 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 - `contract_type: "CALL" or "PUT"` The type of options contract - `"CALL"` - `"PUT"` ### Exercise Style - `exercise_style: "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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 - `instrument_core: 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 - `instrument_core_list: 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 - `listing_type: "STANDARD" or "FLEX" or "OTC"` The listing type of an options contract - `"STANDARD"` - `"FLEX"` - `"OTC"` ### Options Contract - `options_contract: object { id, contract_type, currency, 12 more }` An options contract with options-specific metadata - `id: string` OEMS instrument identifier - `contract_type: "CALL" or "PUT"` 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: "AMERICAN" or "EUROPEAN"` 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: "STANDARD" or "FLEX" or "OTC"` 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 - `options_contract_list: array of OptionsContract` - `id: string` OEMS instrument identifier - `contract_type: "CALL" or "PUT"` 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: "AMERICAN" or "EUROPEAN"` 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: "STANDARD" or "FLEX" or "OTC"` 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 - `action_button: 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 object { prompt }` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional object { actionId }` 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 - `chart_payload: 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 object { prompt }` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional object { actionId }` 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 object { series }` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional object { symbol, timeframe }` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Chart Point - `chart_point: object { x, y }` Single chart coordinate. - `x: string` - `y: number` ### Chart Series - `chart_series: object { name, points }` Named data series within a chart. - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` ### Content Part Chart Payload - `content_part_chart_payload: object { payload }` Chart payload content part. - `payload: 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 object { prompt }` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional object { actionId }` 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 object { series }` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional object { symbol, timeframe }` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Content Part Custom Payload - `content_part_custom_payload: object { payload }` Escape-hatch custom payload content part. - `payload: unknown` ### Content Part Structured Action Payload - `content_part_structured_action_payload: object { action, action_id }` Structured action content part. - `action: 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: PrefillNewOrderAction or PrefillCancelOrderAction` 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: object { symbol, extras, timeframe }` 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: object { filters, field_filter, page_size, 2 more }` 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: object { agreement_key, reason, requested_entitlement_codes, trading_account_ids }` Open entitlement consent flow - `agreement_key: "omni_account_data_access"` 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 - `content_part_suggested_actions_payload: object { payload }` Suggested actions payload content part. - `payload: 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 object { prompt }` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional object { actionId }` 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 - `content_part_text_payload: object { text }` Text content part. - `text: string` ### Content Part Thinking Payload - `content_part_thinking_payload: object { thoughts }` Thinking content part shown on dynamic response polling. - `thoughts: array of string` ### Data Chart - `data_chart: 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 - `open_chart_action: 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 - `open_entitlement_consent_action: object { agreement_key, reason, requested_entitlement_codes, trading_account_ids }` Action to open entitlement consent flow for one or more accounts. - `agreement_key: "omni_account_data_access"` 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 - `open_screener_action: 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 - `prefill_cancel_order_action: 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 - `prefill_new_order_action: object { orders }` New-order prefill action. - `orders: array of NewOrderRequest` Orders to prefill using the same shape accepted by the orders API. - `instrument_type: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: "MARKET" or "LIMIT" or "STOP" or 3 more` 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: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 7 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"` - `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 string` 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 "OPEN" or "CLOSE"` 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 "PRICE" or "BPS"` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Prefill Order Action - `prefill_order_action: 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 - `prompt_button_action: object { prompt }` Prompt-style button behavior. - `prompt: string` Prompt text to submit as the next user turn. ### Screener Filter - `screener_filter: 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 - `structured_action: 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: PrefillNewOrderAction or PrefillCancelOrderAction` 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: object { symbol, extras, timeframe }` 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: object { filters, field_filter, page_size, 2 more }` 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: object { agreement_key, reason, requested_entitlement_codes, trading_account_ids }` Open entitlement consent flow - `agreement_key: "omni_account_data_access"` 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 - `structured_action_button_action: object { actionId }` Structured-action button behavior. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Suggested Actions Payload - `suggested_actions_payload: 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 object { prompt }` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional object { actionId }` 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 - `symbol_chart: object { symbol, timeframe }` Chart for a single symbol and timeframe. - `symbol: string` - `timeframe: optional string` # Entitlements ## Get Entitlements `$ clear-street v1:omni-ai:entitlements get-entitlements` **get** `/v1/omni-ai/entitlements` List caller's active entitlement grants. ### Parameters - `--trading-account-id: optional number` ### Returns - `V1OmniAIEntitlementGetEntitlementsResponse: BaseResponse` - `data: array of EntitlementResource` - `agreement_id: string` - `entitlement_code: "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```cli clear-street v1:omni-ai:entitlements get-entitlements \ --api-key 'My 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 `$ clear-street v1:omni-ai:entitlements create-entitlements` **post** `/v1/omni-ai/entitlements` Record consent and upsert one-or-more active grants. ### Parameters - `--agreement-id: string` - `--requested-entitlement-code: array of EntitlementCode` - `--trading-account-id: array of number` ### Returns - `V1OmniAIEntitlementNewEntitlementsResponse: BaseResponse` - `data: array of EntitlementResource` - `agreement_id: string` - `entitlement_code: "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```cli clear-street v1:omni-ai:entitlements create-entitlements \ --api-key 'My API Key' \ --agreement-id 01JZ0000000000000000000000 \ --requested-entitlement-code omni.account_data \ --trading-account-id 100019 \ --trading-account-id 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 `$ clear-street v1:omni-ai:entitlements delete-entitlement` **delete** `/v1/omni-ai/entitlements/{entitlement_id}` Revoke one entitlement grant by id. ### Parameters - `--entitlement-id: string` Entitlement grant id ### Returns - `V1OmniAIEntitlementDeleteEntitlementResponse: BaseResponse` - `data: object { entitlement_id, revoked }` - `entitlement_id: string` - `revoked: boolean` ### Example ```cli clear-street v1:omni-ai:entitlements delete-entitlement \ --api-key 'My API Key' \ --entitlement-id entitlement_id ``` #### 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 `$ clear-street v1:omni-ai:entitlements get-entitlement-agreements` **get** `/v1/omni-ai/entitlement-agreements` List current signable entitlement agreements for consent UX. ### Returns - `V1OmniAIEntitlementGetEntitlementAgreementsResponse: BaseResponse` - `data: array of EntitlementAgreementResource` - `agreement_id: string` - `agreement_key: "omni_account_data_access"` 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 ```cli clear-street v1:omni-ai:entitlements get-entitlement-agreements \ --api-key 'My 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 - `delete_entitlement_response: object { entitlement_id, revoked }` - `entitlement_id: string` - `revoked: boolean` ### Entitlement Agreement Key - `entitlement_agreement_key: "omni_account_data_access"` Stable entitlement agreement family key. - `"omni_account_data_access"` ### Entitlement Agreement Resource - `entitlement_agreement_resource: object { agreement_id, agreement_key, document_content, 4 more }` - `agreement_id: string` - `agreement_key: "omni_account_data_access"` 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 - `entitlement_agreement_resource_list: array of EntitlementAgreementResource` - `agreement_id: string` - `agreement_key: "omni_account_data_access"` 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 - `entitlement_code: "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` ### Entitlement Resource - `entitlement_resource: object { agreement_id, entitlement_code, entitlement_id, 2 more }` - `agreement_id: string` - `entitlement_code: "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Resource List - `entitlement_resource_list: array of EntitlementResource` - `agreement_id: string` - `entitlement_code: "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` # Messages ## Get Message By ID `$ clear-street v1:omni-ai: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. ### Parameters - `--message-id: string` Message identifier - `--account-id: number` Account ID for the request ### Returns - `V1OmniAIMessageGetMessageByIDResponse: BaseResponse` - `data: object { id, content, created_at, 5 more }` Final immutable message. - `id: string` - `content: object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```cli clear-street v1:omni-ai:messages get-message-by-id \ --api-key 'My API Key' \ --message-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:messages 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. ### Parameters - `--message-id: string` Finalized assistant message to rate - `--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 - `V1OmniAIMessageSubmitFeedbackResponse: BaseResponse` - `data: object { created_at, feedback_id }` - `created_at: string` - `feedback_id: optional string` ### Example ```cli clear-street v1:omni-ai:messages submit-feedback \ --api-key 'My API Key' \ --message-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --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 - `create_feedback_response: object { created_at, feedback_id }` - `created_at: string` - `feedback_id: optional string` # Responses ## Get Response By ID `$ clear-street v1:omni-ai: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`. ### Parameters - `--response-id: string` Response identifier (returned by create thread/message) - `--account-id: number` Account ID for the request ### Returns - `V1OmniAIResponseGetResponseByIDResponse: BaseResponse` - `data: object { id, status, thread_id, 4 more }` Dynamic pollable response. - `id: string` - `status: "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `union_member_2: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_3: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_4: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_5: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```cli clear-street v1:omni-ai:responses get-response-by-id \ --api-key 'My API Key' \ --response-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:responses 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. ### Parameters - `--response-id: string` Response identifier to cancel - `--account-id: number` Account ID for the request ### Returns - `V1OmniAIResponseCancelResponseResponse: BaseResponse` - `data: object { canceled }` - `canceled: boolean` ### Example ```cli clear-street v1:omni-ai:responses cancel-response \ --api-key 'My API Key' \ --response-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### Response ```json { "data": { "canceled": false }, "metadata": { "request_id": "fa26a786-f5d3-48b0-80eb-778e17af4964" } } ``` ## Domain Types ### Cancel Response Payload - `cancel_response_payload: object { canceled }` - `canceled: boolean` ### Error Status - `error_status: 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: "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `union_member_2: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_3: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_4: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_5: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Response Content - `response_content: object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `union_member_2: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_3: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_4: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_5: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Content Part - `response_content_part: ContentPartTextPayload or ContentPartThinkingPayload or ContentPartStructuredActionPayload or 3 more` Dynamic content part visible on a pollable response. - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `union_member_2: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_3: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_4: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_5: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Status - `response_status: "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` # Threads ## Get Threads `$ clear-street v1:omni-ai: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. ### 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 - `V1OmniAIThreadGetThreadsResponse: BaseResponse` - `data: array of Thread` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Example ```cli clear-street v1:omni-ai:threads get-threads \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:threads 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. ### Parameters - `--thread-id: string` Thread identifier - `--account-id: number` Account ID for the request ### Returns - `V1OmniAIThreadGetThreadByIDResponse: BaseResponse` - `data: 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` ### Example ```cli clear-street v1:omni-ai:threads get-thread-by-id \ --api-key 'My API Key' \ --thread-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:threads 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. ### Parameters - `--account-id: number` - `--type: "instant" or "deep_insights"` Thread creation mode. - `--capability: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` - `--target: optional object { ticker, type }` Deep-insights target payload. - `--text: optional string` - `--thesis: optional string` ### Returns - `V1OmniAIThreadNewThreadResponse: BaseResponse` - `data: object { response_id, thread_id, user_message_id }` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Example ```cli clear-street v1:omni-ai:threads create-thread \ --api-key 'My API Key' \ --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 `$ clear-street v1:omni-ai:threads 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). ### Parameters - `--thread-id: string` Thread to check for active response - `--account-id: number` Account ID for the request ### Returns - `V1OmniAIThreadGetThreadResponseResponse: BaseResponse` - `data: object { id, status, thread_id, 4 more }` Dynamic pollable response. - `id: string` - `status: "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `union_member_2: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_3: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_4: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_5: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```cli clear-street v1:omni-ai:threads get-thread-response \ --api-key 'My API Key' \ --thread-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:threads 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. ### Parameters - `--thread-id: string` Thread to list messages for - `--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 - `V1OmniAIThreadGetMessagesResponse: BaseResponse` - `data: array of Message` - `id: string` - `content: object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```cli clear-street v1:omni-ai:threads get-messages \ --api-key 'My API Key' \ --thread-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --account-id 0 ``` #### 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 `$ clear-street v1:omni-ai:threads 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. ### Parameters - `--thread-id: string` Thread to continue - `--account-id: number` - `--text: string` - `--capability: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` ### Returns - `V1OmniAIThreadNewMessageResponse: BaseResponse` - `data: 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` ### Example ```cli clear-street v1:omni-ai:threads create-message \ --api-key 'My API Key' \ --thread-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --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 - `create_message_response: 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 - `create_thread_response: 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: object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Content - `message_content: object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message Content Part - `message_content_part: ContentPartTextPayload or ContentPartStructuredActionPayload or ContentPartChartPayload or 2 more` Final immutable content part visible on persisted messages. - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message List - `message_list: array of Message` - `id: string` - `content: object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `union_member_0: ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `union_member_1: ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `union_member_2: ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `union_member_3: ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `union_member_4: ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Outcome - `message_outcome: "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` ### Message Role - `message_role: "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 - `thread_list: array of Thread` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` # Orders ## Get Orders `$ clear-street v1:orders get-orders` **get** `/v1/accounts/{account_id}/orders` List orders for an account with optional filtering ### Parameters - `--account-id: number` Account identifier - `--from: optional string` The start date and time for the query range, inclusive (ISO 8601 format) - `--instrument-id: 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) - `--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 - `--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 - `V1OrderGetOrdersResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders get-orders \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:orders get-order-by-id` **get** `/v1/accounts/{account_id}/orders/{order_id}` Get Order By ID ### Parameters - `--account-id: number` Account identifier - `--order-id: string` Order identifier ### Returns - `V1OrderGetOrderByIDResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders get-order-by-id \ --api-key 'My API Key' \ --account-id 0 \ --order-id order_id ``` #### 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 `$ clear-street v1:orders submit-orders` **post** `/v1/accounts/{account_id}/orders` Submit new orders ### Parameters - `--account-id: number` Account identifier - `--order: array of object { legs, order_type, time_in_force, 3 more } or NewOrderRequest` ### Returns - `V1OrderSubmitOrdersResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders submit-orders \ --api-key 'My API Key' \ --account-id 0 \ --order '{legs: [{instrument_type: OPTION, ratio: ratio, security: 0193bb84-447a-706f-996f-097254663f02, side: BUY}, {instrument_type: OPTION, ratio: ratio, security: 0193bb84-4db4-78ec-b4fd-cba8be61cf8a, side: SELL}, {instrument_type: OPTION, ratio: ratio, security: 0193bb84-5264-7f20-8fd3-35df82cd6ef0, side: BUY}], order_type: LIMIT, time_in_force: DAY}' ``` #### 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 `$ clear-street v1:orders replace-order` **patch** `/v1/accounts/{account_id}/orders/{order_id}` Replace an order with new parameters ### Parameters - `--account-id: number` Path param: Account identifier - `--order-id: string` Path param: Order identifier - `--limit-price: optional string` Body param: New limit price for the order - `--quantity: optional string` Body param: New quantity for the order - `--stop-price: optional string` Body param: New stop price for the order - `--time-in-force: optional "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 7 more` Body param: New time in force for the order ### Returns - `V1OrderReplaceOrderResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders replace-order \ --api-key 'My API Key' \ --account-id 0 \ --order-id order_id ``` #### 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 `$ clear-street v1:orders cancel-open-order` **delete** `/v1/accounts/{account_id}/orders/{order_id}` Cancel a specific order ### Parameters - `--account-id: number` Account identifier - `--order-id: string` Order identifier ### Returns - `V1OrderCancelOpenOrderResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders cancel-open-order \ --api-key 'My API Key' \ --account-id 0 \ --order-id order_id ``` #### 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 `$ clear-street v1:orders cancel-all-open-orders` **delete** `/v1/accounts/{account_id}/orders` Cancel all orders for an account ### Parameters - `--account-id: number` Account identifier - `--instrument-id: 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) - `--side: optional "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Filter by order side (BUY or SELL) - `--type: optional "MARKET" or "LIMIT" or "STOP" or 4 more` Filter by order type (e.g., MARKET, LIMIT) ### Returns - `V1OrderCancelAllOpenOrdersResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:orders cancel-all-open-orders \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 - `cancel_order_request: 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 - `instrument_id_or_symbol: string` OEMS instrument UUID ### New Order Request - `new_order_request: object { instrument_type, order_type, quantity, 13 more }` Request to submit a new order (PlaceOrderRequest from spec) - `instrument_type: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: "MARKET" or "LIMIT" or "STOP" or 3 more` 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: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 7 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"` - `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 string` 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 "OPEN" or "CLOSE"` 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 "PRICE" or "BPS"` 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 - `order_list: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 - `order_status: "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 - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Order type - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` ### Position Effect - `position_effect: "OPEN" or "CLOSE"` Position effect for options orders - `"OPEN"` - `"CLOSE"` ### Queue State - `queue_state: "AWAITING_RELEASE" or "RELEASED"` Parent order queue or hold state. - `"AWAITING_RELEASE"` - `"RELEASED"` ### Request Order Type - `request_order_type: "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 - `request_time_in_force: "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 - `time_in_force: "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 - `trailing_offset_type: "PRICE" or "BPS"` Trailing offset type for trailing stop orders. - `"PRICE"` - `"BPS"` # Positions ## Get Positions `$ clear-street v1:positions get-positions` **get** `/v1/accounts/{account_id}/positions` Retrieves all positions for the specified trading account. ### Parameters - `--account-id: number` Account identifier - `--instrument-id: 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 - `--sort-direction: optional "ASC" or "DESC"` Sort direction ### Returns - `V1PositionGetPositionsResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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 ```cli clear-street v1:positions get-positions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions close-positions` **delete** `/v1/accounts/{account_id}/positions` Delete all positions within an account. Closes all positions for the specified trading account. ### Parameters - `--account-id: number` Account identifier - `--cancel-orders: optional boolean` Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `V1PositionClosePositionsResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:positions close-positions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions 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. ### Parameters - `--account-id: number` Path param: Account identifier - `--instrument-id: string` Path param: OEMS instrument UUID - `--cancel-orders: optional boolean` Body param: Whether to cancel existing open orders for the position before submitting closing orders. ### Returns - `V1PositionClosePositionResponse: BaseResponse` - `data: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `leaves_quantity: string` Remaining unfilled quantity - `order_type: "MARKET" or "LIMIT" or "STOP" or 4 more` Type of order (MARKET, LIMIT, etc.) - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `"OTHER"` - `quantity: string` Total order quantity - `side: "BUY" or "SELL" or "SELL_SHORT" or "OTHER"` Side of the order (BUY, SELL, SELL_SHORT) - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `status: "PENDING_NEW" or "NEW" or "PARTIALLY_FILLED" or 12 more` 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: "DAY" or "GOOD_TILL_CANCEL" or "IMMEDIATE_OR_CANCEL" or 8 more` 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 "AWAITING_RELEASE" or "RELEASED"` 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 "PRICE" or "BPS"` 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 ```cli clear-street v1:positions close-position \ --api-key 'My API Key' \ --account-id 0 \ --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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 `$ clear-street v1:positions get-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. ### Parameters - `--account-id: number` Account identifier - `--instrument-id: optional string` Limit results to a single contract. Accepts the instrument id or the OSI symbol. ### Returns - `V1PositionGetPositionInstructionsResponse: BaseResponse` - `data: 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` 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 ```cli clear-street v1:positions get-position-instructions \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clear-street v1:positions 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. ### Parameters - `--account-id: number` Account identifier - `--instruction: array of object { instruction_type, instrument_id, quantity, instruction_id }` ### Returns - `V1PositionSubmitPositionInstructionsResponse: BaseResponse` - `data: 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` 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 ```cli clear-street v1:positions submit-position-instructions \ --api-key 'My API Key' \ --account-id 0 \ --instruction "{instruction_type: EXERCISE, instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02, quantity: '1'}" ``` #### 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 `$ clear-street v1:positions 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. ### Parameters - `--account-id: number` Account identifier - `--instruction-id: string` Server-assigned instruction id ### Returns - `V1PositionCancelPositionInstructionResponse: BaseResponse` - `data: 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` 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 ```cli clear-street v1:positions cancel-position-instruction \ --api-key 'My API Key' \ --account-id 0 \ --instruction-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e ``` #### 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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 - `position_instruction: 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` 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 - `position_instruction_list: 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: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` 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: "SENT" or "ACCEPTED" or "REJECTED" or 5 more` 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 - `position_instruction_status: "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 - `position_instruction_type: "EXERCISE" or "DO_NOT_EXERCISE" or "CONTRARY_EXERCISE"` The action to take against an options position. - `"EXERCISE"` - `"DO_NOT_EXERCISE"` - `"CONTRARY_EXERCISE"` ### Position List - `position_list: 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: "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `market_value: string` The current market value of the position - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` 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 - `position_type: "LONG" or "SHORT" or "LONG_CALL" or 3 more` Position type classification - `"LONG"` - `"SHORT"` - `"LONG_CALL"` - `"SHORT_CALL"` - `"LONG_PUT"` - `"SHORT_PUT"` # Watchlist ## Get Watchlists `$ clear-street v1:watchlist get-watchlists` **get** `/v1/watchlists` List watchlists for the authenticated user ### 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 - `V1WatchlistGetWatchlistsResponse: BaseResponse` - `data: 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. ### Example ```cli clear-street v1:watchlist get-watchlists \ --api-key 'My 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 `$ clear-street v1:watchlist get-watchlist-by-id` **get** `/v1/watchlists/{watchlist_id}` Get a watchlist by ID with all its items ### Parameters - `--watchlist-id: string` Watchlist ID ### Returns - `V1WatchlistGetWatchlistByIDResponse: BaseResponse` - `data: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 ```cli clear-street v1:watchlist get-watchlist-by-id \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 ``` #### Response ```json { "data": { "created_at": "2025-01-15T10:00:00.000000000Z", "id": "550e8400-e29b-41d4-a716-446655440000", "items": [ { "added_at": "2025-01-16T09:30:00.000000000Z", "added_price": "150.25", "id": "660e8400-e29b-41d4-a716-446655440001", "instrument": { "country_of_issue": "US", "currency": "USD", "easy_to_borrow": true, "id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", "instrument_type": "COMMON_STOCK", "is_liquidation_only": false, "is_marginable": true, "is_restricted": false, "is_short_prohibited": false, "is_threshold_security": false, "is_tradable": true, "name": "Apple Inc.", "symbol": "AAPL", "venue": "XNMS" } } ], "name": "Tech Stocks" }, "error": null, "metadata": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } } ``` ## Create Watchlist `$ clear-street v1:watchlist create-watchlist` **post** `/v1/watchlists` Create Watchlist ### Parameters - `--name: string` The desired watchlist name. ### Returns - `V1WatchlistNewWatchlistResponse: BaseResponse` - `data: 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. ### Example ```cli clear-street v1:watchlist create-watchlist \ --api-key 'My API Key' \ --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 `$ clear-street v1:watchlist delete-watchlist` **delete** `/v1/watchlists/{watchlist_id}` Delete a watchlist and all its items ### Parameters - `--watchlist-id: string` Watchlist ID ### Returns - `V1WatchlistDeleteWatchlistResponse: unknown` ### Example ```cli clear-street v1:watchlist delete-watchlist \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 ``` #### Response ```json { "data": null, "metadata": { "request_id": "cb824f1b-ea6e-4045-8169-9503be2b24d7" } } ``` ## Add Watchlist Item `$ clear-street v1:watchlist add-watchlist-item` **post** `/v1/watchlists/{watchlist_id}/items` Add an instrument to a watchlist ### Parameters - `--watchlist-id: string` Watchlist ID - `--instrument-id: string` OEMS instrument UUID ### Returns - `V1WatchlistAddWatchlistItemResponse: BaseResponse` - `data: object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Example ```cli clear-street v1:watchlist add-watchlist-item \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 \ --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 `$ clear-street v1:watchlist delete-watchlist-item` **delete** `/v1/watchlists/{watchlist_id}/items/{item_id}` Delete an instrument from a watchlist ### Parameters - `--watchlist-id: string` Watchlist ID - `--item-id: string` Item ID ### Returns - `V1WatchlistDeleteWatchlistItemResponse: unknown` ### Example ```cli clear-street v1:watchlist delete-watchlist-item \ --api-key 'My API Key' \ --watchlist-id 550e8400-e29b-41d4-a716-446655440000 \ --item-id 660e8400-e29b-41d4-a716-446655440001 ``` #### Response ```json { "data": null, "metadata": { "request_id": "5b0709e3-5868-4116-9a84-26f1b8c30503" } } ``` ## Domain Types ### Add Watchlist Item Data - `add_watchlist_item_data: object { item_id }` Response data for adding a watchlist item - `item_id: string` ID of the created item ### Watchlist Detail - `watchlist_detail: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 - `watchlist_entry: 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 - `watchlist_entry_list: 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 - `watchlist_item_entry: 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 object { id, country_of_issue, currency, 19 more }` 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 "COMMON_STOCK" or "PREFERRED_STOCK" or "OPTION" or 2 more` 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 # Websocket ## Websocket Handler `$ clear-street v1:websocket websocket-handler` **get** `/v1/ws` Upgrade the HTTP connection to a WebSocket and echo incoming messages. ### Example ```cli clear-street v1:websocket websocket-handler \ --api-key 'My API Key' ```