Instrument

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/clearstreet8e71/main/json-schema/clearstreet8e71-instrument-schema.json",
  "title": "Instrument",
  "description": "Represents a tradable financial instrument.",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/clearstreet8e71-openapi.yaml#/components/schemas/Instrument",
  "allOf": [
    {
      "type": "object",
      "required": [
        "id",
        "symbol",
        "venue",
        "country_of_issue",
        "currency",
        "is_marginable",
        "easy_to_borrow",
        "is_short_prohibited",
        "is_threshold_security",
        "is_liquidation_only",
        "is_tradable",
        "is_fractionable",
        "is_ptp"
      ],
      "properties": {
        "adv": {
          "type": [
            "string",
            "null"
          ],
          "description": "Average daily share volume from the security definition.\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "cax_adjusted_previous_close": {
          "type": [
            "string",
            "null"
          ],
          "description": "Corporate-action-adjusted last close; present only when an adjustment\nexists for the previous_close date.\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "country_of_issue": {
          "type": "string",
          "description": "The ISO country code of the instrument's issue"
        },
        "currency": {
          "type": "string",
          "description": "The ISO currency code in which the instrument is traded"
        },
        "easy_to_borrow": {
          "type": "boolean",
          "description": "Indicates if the instrument is classified as Easy-To-Borrow"
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique instrument identifier (UUID)"
        },
        "instrument_type": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/SecurityType",
              "description": "The type of security (e.g., Common Stock, ETF)\nWhen a null/undefined value is observed, it indicates that there is no available data."
            }
          ]
        },
        "is_fractionable": {
          "type": "boolean",
          "description": "Indicates if the instrument supports fractional-quantity orders"
        },
        "is_liquidation_only": {
          "type": "boolean",
          "description": "Indicates if the instrument is liquidation only and cannot be bought"
        },
        "is_marginable": {
          "type": "boolean",
          "description": "Indicates if the instrument is marginable"
        },
        "is_ptp": {
          "type": "boolean",
          "description": "Indicates if the instrument is a publicly traded partnership (PTP).\nPTP sales are subject to a 10% withholding tax for non-US tax residents."
        },
        "is_short_prohibited": {
          "type": "boolean",
          "description": "Indicates if short selling is prohibited for the instrument. This is a\nstanding property of the security. For the live Rule 201 circuit\nbreaker, see `short_sale_restricted` on the market-data snapshot."
        },
        "is_threshold_security": {
          "type": "boolean",
          "description": "Indicates if the instrument is on the Regulation SHO Threshold Security List"
        },
        "is_tradable": {
          "type": "boolean",
          "description": "Indicates if the instrument is tradable"
        },
        "long_margin_rate": {
          "type": [
            "string",
            "null"
          ],
          "description": "The percent of a long position's value you must post as margin\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The full name of the instrument or its issuer\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "notional_adv": {
          "type": [
            "string",
            "null"
          ],
          "description": "Notional average daily volume (ADV multiplied by the cax-adjusted close\nwhen present, the raw previous close otherwise).\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "previous_close": {
          "type": [
            "string",
            "null"
          ],
          "description": "Last close price from the security definition.\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "short_margin_rate": {
          "type": [
            "string",
            "null"
          ],
          "description": "The percent of a short position's value you must post as margin\nWhen a null/undefined value is observed, it indicates that there is no available data."
        },
        "symbol": {
          "type": "string",
          "description": "The trading symbol for the instrument"
        },
        "tick_rules": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/TickRule"
          },
          "description": "Price bands this instrument quotes on, ascending. Absent when we have no\nschedule for it, which includes an option whose penny-program status our\nreference data never supplied."
        },
        "venue": {
          "type": "string",
          "description": "The MIC code of the primary listing venue"
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "options_contract_expiry_dates": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/OptionExpiryDate"
          },
          "description": "Available options expiration dates for this instrument, each annotated\nwith which settlement cycles have listed contracts on it.\nPresent only when `include_options_expiry_dates=true` in the request.\nWhen a null/undefined value is observed, it indicates it does not apply."
        },
        "options_expiry_dates": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "format": "date"
          },
          "description": "Available options expiration dates for this instrument.\nPresent only when `include_options_expiry_dates=true` in the request.\n\nDeprecated: use `options_contract_expiry_dates`, which carries the same\ndates annotated with settlement-cycle information.\nWhen a null/undefined value is observed, it indicates it does not apply.",
          "deprecated": true
        }
      }
    }
  ],
  "$defs": {
    "OptionExpiryDate": {
      "type": "object",
      "description": "An options expiry date, annotated with which settlement cycles have\nlisted contracts on it.",
      "required": [
        "date",
        "has_settles_on_open",
        "has_settles_on_close"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "The expiration date."
        },
        "has_settles_on_close": {
          "type": "boolean",
          "description": "Whether this date has at least one listed contract that settles at\nthe close (PM settlement) -- the standard cycle."
        },
        "has_settles_on_open": {
          "type": "boolean",
          "description": "Whether this date has at least one contract that settles on the opening\nprint (AM settlement) and can still be traded. AM-settled contracts stop\ntrading at the close of the business day before settlement, so this turns\nfalse before the expiration date arrives. A date leaves the list once no\ncontract on it can be traded in either settlement cycle."
        }
      }
    },
    "SecurityType": {
      "type": "string",
      "description": "Security type",
      "enum": [
        "COMMON_STOCK",
        "INDEX",
        "OPTION",
        "CASH"
      ]
    },
    "TickRule": {
      "type": "object",
      "description": "One band of an instrument's tick schedule. A price in the band is valid only\nif it is a whole multiple of `tick_size`. Bands describe the instrument\nitself: on an equity they say nothing about that equity's option chain.",
      "required": [
        "start_price",
        "tick_size"
      ],
      "properties": {
        "end_price": {
          "type": [
            "string",
            "null"
          ],
          "description": "Upper bound of the band, exclusive. Absent on the last band, which runs\nto infinity.\nWhen a null/undefined value is observed, it indicates it does not apply."
        },
        "start_price": {
          "type": "string",
          "description": "Lowest price in the band, inclusive."
        },
        "tick_size": {
          "type": "string",
          "description": "Minimum price increment within the band."
        }
      }
    }
  }
}