# Instruments ## Get Instruments `InstrumentGetInstrumentsResponse v1().instruments().getInstruments(InstrumentGetInstrumentsParamsparams = InstrumentGetInstrumentsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/instruments` Retrieves a list of tradeable instruments. ### Parameters - `InstrumentGetInstrumentsParams params` - `Optional easyToBorrow` Filter by easy to borrow status - `Optional> instrumentIds` Comma-separated OEMS instrument UUIDs - `Optional instrumentType` Filter by instrument type. OPTION is not supported on this endpoint; use GET /instruments/options/contracts to list option contracts. If omitted, returns all supported instrument types except options. - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional isLiquidationOnly` Filter by liquidation only status - `Optional isMarginable` Filter by marginable status - `Optional isRestricted` Filter by restricted status - `Optional isShortProhibited` Filter by short prohibited status - `Optional isThresholdSecurity` Filter by threshold security status - `Optional pageSize` The number of items to return per page. Only used when page_token is not provided. - `Optional pageToken` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class InstrumentGetInstrumentsResponse:` - `List data` - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.instruments.InstrumentGetInstrumentsParams; import com.clear_street.api.models.v1.instruments.InstrumentGetInstrumentsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); InstrumentGetInstrumentsResponse response = client.v1().instruments().getInstruments(); } } ``` #### 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 `InstrumentGetInstrumentByIdResponse v1().instruments().getInstrumentById(InstrumentGetInstrumentByIdParamsparams = InstrumentGetInstrumentByIdParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/v1/instruments/{instrument_id}` Retrieves detailed information for a specific instrument. ### Parameters - `InstrumentGetInstrumentByIdParams params` - `Optional instrumentId` OEMS instrument UUID - `Optional includeOptionsExpiryDates` When true, include unique options expiry dates for this instrument ### Returns - `class InstrumentGetInstrumentByIdResponse:` - `Instrument data` Represents a tradable financial instrument. - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional> optionsExpiryDates` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.instruments.InstrumentGetInstrumentByIdParams; import com.clear_street.api.models.v1.instruments.InstrumentGetInstrumentByIdResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); InstrumentGetInstrumentByIdResponse response = client.v1().instruments().getInstrumentById("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 `InstrumentSearchInstrumentsResponse v1().instruments().searchInstruments(InstrumentSearchInstrumentsParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **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 - `InstrumentSearchInstrumentsParams params` - `String q` 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. - `Optional assetClass` Comma-separated asset classes (EQUITY|OPTION|WARRANT|BOND|FX|OTHER). Defaults to EQUITY. - `Optional country` Optional listing-country filter (e.g., US). - `Optional currency` Optional ISO currency filter (e.g., USD). - `Optional includeInactive` Include inactive instruments. Default false. - `Optional includeRestricted` Include restricted instruments. Default true (penalized in ranking). - `Optional pageSize` The number of items to return per page. Only used when page_token is not provided. - `Optional pageToken` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `class InstrumentSearchInstrumentsResponse:` - `List data` - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.instruments.InstrumentSearchInstrumentsParams; import com.clear_street.api.models.v1.instruments.InstrumentSearchInstrumentsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); InstrumentSearchInstrumentsParams params = InstrumentSearchInstrumentsParams.builder() .q("q") .build(); InstrumentSearchInstrumentsResponse response = client.v1().instruments().searchInstruments(params); } } ``` #### 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 `InstrumentGetOptionContractsResponse v1().instruments().getOptionContracts(InstrumentGetOptionContractsParamsparams = InstrumentGetOptionContractsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **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 - `InstrumentGetOptionContractsParams params` - `Optional contractType` Filter by contract type: CALL or PUT - `Optional expiry` Filter to contracts expiring on this date (YYYY-MM-DD) - `Optional pageSize` The number of items to return per page. Only used when page_token is not provided. - `Optional pageToken` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. - `Optional underlier` Underlier symbol (e.g., AAPL, SPX) - `Optional underlyingInstrumentId` OEMS instrument UUID or symbol of the underlying equity/index ### Returns - `class InstrumentGetOptionContractsResponse:` - `List data` - `String id` OEMS instrument identifier - `ContractType contractType` Whether this is a CALL or PUT - `CALL("CALL")` - `PUT("PUT")` - `String currency` ISO currency code - `String exchange` MIC code of the primary listing venue - `ExerciseStyle exerciseStyle` Exercise style - `AMERICAN("AMERICAN")` - `EUROPEAN("EUROPEAN")` - `LocalDate expiry` Expiration date - `boolean isLiquidationOnly` Whether the contract is liquidation-only - `boolean isMarginable` Whether the contract is marginable - `boolean isRestricted` Whether the contract is restricted from trading - `ListingType listingType` Listing type - `STANDARD("STANDARD")` - `FLEX("FLEX")` - `OTC("OTC")` - `String multiplier` Contract multiplier (100 for standard options) - `String strikePrice` Strike price - `String symbol` OSI symbol (e.g. "AAPL 251219C00150000") - `Optional openInterest` Open interest (number of outstanding contracts), if available - `Optional underlyingInstrumentId` OEMS instrument ID of the underlying instrument, if resolvable ### Example ```java package com.clear_street.api.example; import com.clear_street.api.client.ClearStreetClient; import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient; import com.clear_street.api.models.v1.instruments.InstrumentGetOptionContractsParams; import com.clear_street.api.models.v1.instruments.InstrumentGetOptionContractsResponse; public final class Main { private Main() {} public static void main(String[] args) { ClearStreetClient client = ClearStreetOkHttpClient.builder() .fromEnv() .apiKey("My API Key") .build(); InstrumentGetOptionContractsResponse response = client.v1().instruments().getOptionContracts(); } } ``` #### 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 - `enum ContractType:` The type of options contract - `CALL("CALL")` - `PUT("PUT")` ### Exercise Style - `enum ExerciseStyle:` The exercise style of an options contract - `AMERICAN("AMERICAN")` - `EUROPEAN("EUROPEAN")` ### Instrument - `class Instrument:` Represents a tradable financial instrument. - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional> optionsExpiryDates` Available options expiration dates for this instrument. Present only when `include_options_expiry_dates=true` in the request. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments ### Instrument Core - `class InstrumentCore:` - `String id` Unique OEMS instrument identifier (UUID) - `String countryOfIssue` The ISO country code of the instrument's issue - `String currency` The ISO currency code in which the instrument is traded - `boolean easyToBorrow` Indicates if the instrument is classified as Easy-To-Borrow - `boolean isLiquidationOnly` Indicates if the instrument is liquidation only and cannot be bought - `boolean isMarginable` Indicates if the instrument is marginable - `boolean isRestricted` Indicates if the instrument is restricted from trading - `boolean isShortProhibited` Indicates if short selling is prohibited for the instrument - `boolean isThresholdSecurity` Indicates if the instrument is on the Regulation SHO Threshold Security List - `boolean isTradable` Indicates if the instrument is tradable - `String symbol` The trading symbol for the instrument - `String venue` The MIC code of the primary listing venue - `Optional adv` Average daily share volume from the security definition. - `Optional expiry` The expiration date for options instruments - `Optional instrumentType` The type of security (e.g., Common Stock, ETF) - `COMMON_STOCK("COMMON_STOCK")` - `PREFERRED_STOCK("PREFERRED_STOCK")` - `OPTION("OPTION")` - `CASH("CASH")` - `OTHER("OTHER")` - `Optional longMarginRate` The percent of a long position's value you must post as margin - `Optional name` The full name of the instrument or its issuer - `Optional notionalAdv` 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. - `Optional previousClose` Last close price from the security definition. - `Optional shortMarginRate` The percent of a short position's value you must post as margin - `Optional strikePrice` The strike price for options instruments ### Listing Type - `enum ListingType:` The listing type of an options contract - `STANDARD("STANDARD")` - `FLEX("FLEX")` - `OTC("OTC")` ### Options Contract - `class OptionsContract:` An options contract with options-specific metadata - `String id` OEMS instrument identifier - `ContractType contractType` Whether this is a CALL or PUT - `CALL("CALL")` - `PUT("PUT")` - `String currency` ISO currency code - `String exchange` MIC code of the primary listing venue - `ExerciseStyle exerciseStyle` Exercise style - `AMERICAN("AMERICAN")` - `EUROPEAN("EUROPEAN")` - `LocalDate expiry` Expiration date - `boolean isLiquidationOnly` Whether the contract is liquidation-only - `boolean isMarginable` Whether the contract is marginable - `boolean isRestricted` Whether the contract is restricted from trading - `ListingType listingType` Listing type - `STANDARD("STANDARD")` - `FLEX("FLEX")` - `OTC("OTC")` - `String multiplier` Contract multiplier (100 for standard options) - `String strikePrice` Strike price - `String symbol` OSI symbol (e.g. "AAPL 251219C00150000") - `Optional openInterest` Open interest (number of outstanding contracts), if available - `Optional underlyingInstrumentId` OEMS instrument ID of the underlying instrument, if resolvable