> For the complete documentation index, see [llms.txt](https://developer.barchart.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.barchart.com/architecture/openfeed-instrument-proto.md). # instrument.proto ### openfeed\_instrument.proto #### InstrumentDefinition | Field | Type | Label | Description | | --------------------------------- | ------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | marketId | [sint64](#sint64) | | Unique ID used in the data feed. | | instrumentType | [InstrumentDefinition.InstrumentType](#InstrumentDefinitionInstrumentType) | | Instrument type as enum... | | supportBookTypes | [InstrumentDefinition.BookType](#InstrumentDefinitionBookType) | repeated | Supported Book Types | | bookDepth | [sint32](#sint32) | | Maximum depth of market-by-price order book | | vendorId | [string](#string) | | The name of the market data vendor | | symbol | [string](#string) | | Human readable market symbol, assigned by the exchange or venue. Not necessarily unique as the exchange or vendor could assign the same symbol to different instruments, for example if the instruments trade on different exchanges. | | description | [string](#string) | | Human readable market description. | | cfiCode | [string](#string) | | Market CFI code: | | currencyCode | [string](#string) | | Market currency code: | | exchangeCode | [string](#string) | | Market exchange code: For inter-exchange spreads, use the leg MICs separated by a hyphen | | minimumPriceIncrement | [float](#float) | | Minimum price increment in market currency. | | contractPointValue | [float](#float) | | Contract point value in market currency. | | schedule | [InstrumentDefinition.Schedule](#InstrumentDefinitionSchedule) | | Trading schedule for a typical week | | calendar | [InstrumentDefinition.Calendar](#InstrumentDefinitionCalendar) | | Trading calendar (expiration, notice days, holidays?, etc) | | recordCreateTime | [sint64](#sint64) | | UTC Timestamp of creation, nano seconds since Unix epoch | | recordUpdateTime | [sint64](#sint64) | | UTC Timestamp of update, nano seconds since Unix epoch | | timeZoneName | [string](#string) | | Market time zone TZ database name. Permanent. Can be resolved into timeZoneOffset for given date/time. See See | | instrumentGroup | [string](#string) | | Identifies a logical grouping of instruments. By product, for example. | | symbolExpiration | [InstrumentDefinition.MaturityDate](#InstrumentDefinitionMaturityDate) | | The Date of expiration for futures and options. | | state | [InstrumentDefinition.State](#InstrumentDefinitionState) | | active: can have market state updates, can have historical data passive: can NOT have market state updates, but can have historical data normally "active" means newly listed or currently non expired markets normally "passive" means expired options, de-listed equities, etc. | | channel | [sint32](#sint32) | | The channel that updates for this instrument will appear on. | | underlyingMarketId | [sint64](#sint64) | | The marketId of the underlying asset. Used by Futures and Options when the underlying instrument is defined by the vendor | | priceFormat | [InstrumentDefinition.PriceFormat](#InstrumentDefinitionPriceFormat) | | Display format | | optionStrikePriceFormat | [InstrumentDefinition.PriceFormat](#InstrumentDefinitionPriceFormat) | | Strike price display format | | priceDenominator | [sint32](#sint32) | | Divide prices by this value to get real price values | | quantityDenominator | [sint32](#sint32) | | Divide trade quantities by this value to get real quantities | | isTradable | [bool](#bool) | | true if this is a tradable instrument | | transactionTime | [sint64](#sint64) | | UTC timestamp of transaction, nano seconds since Unix epoch | | auxiliaryData | [bytes](#bytes) | | For internal use only. Ignore | | symbols | [InstrumentDefinition.Symbol](#InstrumentDefinitionSymbol) | repeated | List of alternate symbols for this instrument. A single instrument may be provided by many different market data vendors, each with their own unique symbology. Allows this instrument to be tagged with as many vendor symbols as necessary. | | optionStrike | [sint64](#sint64) | | Option strike price in market currency. Multiply by / factorOptionsStrike to get actual strike | | optionType | [InstrumentDefinition.OptionType](#InstrumentDefinitionOptionType) | | Option type: call vs put. | | optionStyle | [InstrumentDefinition.OptionStyle](#InstrumentDefinitionOptionStyle) | | Option style : American vs European. | | optionStrikeDenominator | [sint32](#sint32) | | Divide optionStrike by this value to get real strike price | | spreadCode | [string](#string) | | Spread type, can be vendor specific | | spreadLeg | [InstrumentDefinition.SpreadLeg](#InstrumentDefinitionSpreadLeg) | repeated | Ordered list of underlying legs in a spread. | | userDefinedSpread | [bool](#bool) | | true if user defined spread | | marketTier | [string](#string) | | Listing market classification | | financialStatusIndicator | [string](#string) | | Current financial status of the issuer | | isin | [string](#string) | | ISIN: | | currencyPair | [InstrumentDefinition.CurrencyPair](#InstrumentDefinitionCurrencyPair) | | Break out of currency pair | | exchangeSendsVolume | [bool](#bool) | | true if exchange sends volume. | | exchangeSendsHigh | [bool](#bool) | | true if exchange sends high. | | exchangeSendsLow | [bool](#bool) | | true if exchange sends low. | | exchangeSendsOpen | [bool](#bool) | | true if exchange sends open. | | consolidatedFeedInstrument | [bool](#bool) | | true if this instrument represents consolidated NBBO. | | openOutcryInstrument | [bool](#bool) | | true if this instrument represents Pit symbol. | | syntheticAmericanOptionInstrument | [bool](#bool) | | true if this instrument generated FX option. | | barchartExchangeCode | [string](#string) | | | | barchartBaseCode | [string](#string) | | | | volumeDenominator | [sint32](#sint32) | | | | bidOfferQuantityDenominator | [sint32](#sint32) | | | | primaryListingMarketParticipantId | [string](#string) | | | | subscriptionSymbol | [string](#string) | | | | contractMaturity | [InstrumentDefinition.MaturityDate](#InstrumentDefinitionMaturityDate) | | The Month/ Day of expiration for futures and options. Corresponds to the expiration month. | | underlying | [string](#string) | | Barchart Underlying Symbol | | commodity | [string](#string) | | | | exchangeId | [sint32](#sint32) | | Barchart Exchange Id | | priceScalingExponent | [sint32](#sint32) | | Barchart Price Scaling Exponent | | underlyingOpenfeedMarketId | [sint64](#sint64) | | The Openfeed marketId of the underlying asset. | | barchartExchange | [string](#string) | | Barchart Exchange Name | | contractSize | [sint64](#sint64) | | | | contractSizeDescription | [string](#string) | | | | exchangeMetadata | [InstrumentDefinition.ExchangeMetadata](#InstrumentDefinitionExchangeMetadata) | | | | roundLotSize | [sint32](#sint32) | | | | quantityFractionalDenominator | [sint32](#sint32) | | Divide fractional quantities by this value to get real quantities | | volumeFractionalDenominator | [sint32](#sint32) | | Divide fractional volumes by this value to get real volumes | | contractMetadata | [InstrumentDefinition.ContractMetadata](#InstrumentDefinitionContractMetadata) | | | #### InstrumentDefinition.Calendar | Field | Type | Label | Description | | ------ | -------------------------------------------------------- | -------- | ----------- | | events | [InstrumentDefinition.Event](#InstrumentDefinitionEvent) | repeated | | #### InstrumentDefinition.ContractMetadata Contract Metadata | Field | Type | Label | Description | | --------------- | ----------------- | ----- | ----------- | | productCategory | [string](#string) | | | | marketCode | [string](#string) | | | | name | [string](#string) | | | | term | [string](#string) | | | | beginDate | [sint32](#sint32) | | | | endDate | [sint32](#sint32) | | | | deliveryPeriod | [string](#string) | | | | priceType | [string](#string) | | | #### InstrumentDefinition.CurrencyPair Currency Pair | Field | Type | Label | Description | | --------- | ----------------- | ----- | ----------- | | currency1 | [string](#string) | | | | currency2 | [string](#string) | | | #### InstrumentDefinition.Event | Field | Type | Label | Description | | ----- | ---------------------------------------------------------------- | ----- | ---------------- | | type | [InstrumentDefinition.EventType](#InstrumentDefinitionEventType) | | | | date | [sint64](#sint64) | | Epoch time in ms | #### InstrumentDefinition.ExchangeMetadata Exchange Metadata | Field | Type | Label | Description | | -------------------- | ----------------- | ----- | ----------- | | securityId | [sint64](#sint64) | | | | channelId | [string](#string) | | | | sbeId | [sint32](#sint32) | | | | underlyingSecurityId | [sint64](#sint64) | | | | securitySymbol | [string](#string) | | | | underlyingSymbol | [string](#string) | | | #### InstrumentDefinition.MaturityDate Date and time with time zone. | Field | Type | Label | Description | | ----- | ----------------- | ----- | ---------------- | | year | [sint32](#sint32) | | Year of century. | | month | [sint32](#sint32) | | Month of year. | | day | [sint32](#sint32) | | Day of month. | #### InstrumentDefinition.PriceFormat Recommended display format for prices. | Field | Type | Label | Description | | -------------- | --------------------------------------------------------------------------------------- | ----- | ----------- | | isFractional | [bool](#bool) | | | | denominator | [sint32](#sint32) | | | | subDenominator | [sint32](#sint32) | | | | subFormat | [InstrumentDefinition.PriceFormat.SubFormat](#InstrumentDefinitionPriceFormatSubFormat) | | | #### InstrumentDefinition.Schedule Typical trading week schedule | Field | Type | Label | Description | | -------- | -------------------------------------------------------------- | -------- | ----------- | | sessions | [InstrumentDefinition.TimeSpan](#InstrumentDefinitionTimeSpan) | repeated | | #### InstrumentDefinition.SpreadLeg | Field | Type | Label | Description | | -------------- | ----------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | marketId | [sint64](#sint64) | | The marketId of the leg | | ratio | [sint32](#sint32) | | The ratio of the this leg with respect to the spread. Negative means short the absolute value, positive means long the absolute value. FIXME? Alternatively, we could have separate LONG/SHORT indicator in the message and use this field as only the absolute value | | symbol | [string](#string) | | | | longSymbol | [string](#string) | | | | legOptionDelta | [float](#float) | | | | legPrice | [float](#float) | | Additional information about the leg will be found in the instrument definition for the leg. It is not included here to reduce duplication. | #### InstrumentDefinition.Symbol A vendor's symbol for an instrument | Field | Type | Label | Description | | ---------- | ----------------- | ----- | ------------------------------------------------------------------------- | | vendor | [string](#string) | | The vendor that provides this symbol. | | symbol | [string](#string) | | The symbol assigned by the vendor. | | longSymbol | [string](#string) | | The long symbol assigned by the vendor. Includes 2 char year for futures. | #### InstrumentDefinition.TimeSpan Trading session Times are in nanos since midnight UTC on the Sunday starting a given trading week | Field | Type | Label | Description | | ---------- | ----------------- | ----- | ----------- | | timeStart | [sint64](#sint64) | | | | timeFinish | [sint64](#sint64) | | | #### InstrumentDefinition.BookType Market depth implementation type | Name | Number | Description | | ------------------- | ------ | --------------------- | | UNKNOWN\_BOOK\_TYPE | 0 | | | TOP\_OF\_BOOK | 1 | BBO | | PRICE\_LEVEL\_DEPTH | 2 | Book uses price level | | ORDER\_DEPTH | 3 | Book uses order-id | #### InstrumentDefinition.EventType | Name | Number | Description | | --------------------- | ------ | --------------- | | UNKNOWN\_EVENT\_TYPE | 0 | | | FIRST\_TRADE\_DATE | 1 | All instruments | | LAST\_TRADE\_DATE | 2 | | | MATURITY\_DATE | 10 | Futures only | | FIRST\_DELIVERY\_DATE | 11 | | | LAST\_DELIVERY\_DATE | 12 | | | FIRST\_NOTICE\_DATE | 13 | | | LAST\_NOTICE\_DATE | 14 | | | FIRST\_HOLDING\_DATE | 15 | | | LAST\_HOLDING\_DATE | 16 | | | FIRST\_POSITION\_DATE | 17 | | | LAST\_POSITION\_DATE | 18 | | | DELIVERY\_START\_DATE | 30 | Grain Bids | | DELIVERY\_END\_DATE | 31 | | #### InstrumentDefinition.InstrumentType \############################################# | Name | Number | Description | | ------------------------- | ------ | ----------- | | UNKNOWN\_INSTRUMENT\_TYPE | 0 | | | FOREX | 1 | | | INDEX | 2 | | | EQUITY | 3 | | | FUTURE | 4 | | | OPTION | 5 | | | SPREAD | 6 | | | MUTUAL\_FUND | 7 | | | MONEY\_MARKET\_FUND | 8 | | | USER\_DEFINED\_SPREAD | 9 | | | EQUITY\_OPTION | 10 | | | OTHER | 99 | | #### InstrumentDefinition.OptionStyle Option style. | Name | Number | Description | | ----------------------- | ------ | ----------- | | UNKNOWN\_OPTIONS\_STYLE | 0 | | | DEFAULT | 1 | | | AMERICAN | 2 | | | EUROPEAN | 3 | | #### InstrumentDefinition.OptionType Option type. | Name | Number | Description | | --------------------- | ------ | ----------- | | UNKNOWN\_OPTION\_TYPE | 0 | | | CALL | 1 | | | PUT | 2 | | #### InstrumentDefinition.PriceFormat.SubFormat | Name | Number | Description | | ---------- | ------ | ----------- | | FLAT | 0 | | | FRACTIONAL | 1 | | | DECIMAL | 2 | | #### InstrumentDefinition.State | Name | Number | Description | | -------------- | ------ | ----------- | | UNKNOWN\_STATE | 0 | | | ACTIVE | 1 | | | PASSIVE | 2 | | ### Scalar Value Types | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------- | ----------- | ------- | ---------- | -------------- | ------------------------------ | | double | | double | double | float | float64 | double | float | Float | | float | | float | float | float | float32 | float | float | Float | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | | sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | | bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | \[]byte | ByteString | string | String (ASCII-8BIT) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.barchart.com/architecture/openfeed-instrument-proto.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.