Instrument definitions
Instrument definitions provide point-in-time reference information about each instrument, which includes properties like symbol, instrument name, expiration date, listing date, tick size, and strike price.
Fields (definition
)
Field |
Type |
Description |
---|---|---|
ts_recv |
uint64_t | The capture-server-received timestamp expressed as the number of nanoseconds since the UNIX epoch. |
ts_event |
uint64_t | The matching-engine-received timestamp expressed as the number of nanoseconds since the UNIX epoch. |
rtype |
uint8_t | A sentinel value indicating the record type. Always 19 in the definition schema. See Rtype. |
publisher_id |
uint16_t | The publisher ID assigned by Databento, which denotes the dataset and venue. |
instrument_id |
uint32_t | The numeric instrument ID. |
raw_symbol |
char[symbol_cstr_len] | The instrument name (symbol) provided by the publisher, where symbol_cstr_len is specified in the Metadata. |
security_update_action |
char | Indicates if the instrument definition has been Added, Modified, or Deleted. |
instrument_class |
char | The classification of the instrument. See Instrument class. |
min_price_increment |
int64_t | The minimum constant tick for the instrument in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
display_factor |
int64_t | The multiplier to convert the venue’s display price to the conventional price in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
expiration |
uint64_t | The last eligible trade time expressed as a number of nanoseconds since the UNIX epoch. May only have date precision depending on the publisher. |
activation |
uint64_t | The time of instrument activation expressed as a number of nanoseconds since the UNIX epoch. May only have date precision depending on the publisher. |
high_limit_price |
int64_t | The allowable high limit price for the trading day in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
low_limit_price |
int64_t | The allowable low limit price for the trading day in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
max_price_variation |
int64_t | The differential value for price banding in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
unit_of_measure_qty |
int64_t | The contract size for each instrument, in combination with unit_of_measure , in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
min_price_increment_amount |
int64_t | The value currently under development by the venue. Converted to units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
price_ratio |
int64_t | The value used for price calculation in spread and leg pricing in units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
inst_attrib_value |
int32_t | A bitmap of instrument eligibility attributes. |
underlying_id |
uint32_t | The instrument_id of the first underlying instrument. |
raw_instrument_id |
uint64_t | The instrument ID assigned by the publisher. May be the same as instrument_id . |
market_depth_implied |
int32_t | The implied book depth on the price level data feed. |
market_depth |
int32_t | The (outright) book depth on the price level data feed. |
market_segment_id |
uint32_t | The market segment of the instrument. |
max_trade_vol |
uint32_t | The maximum trading volume for the instrument. |
min_lot_size |
int32_t | The minimum order entry quantity for the instrument. |
min_lot_size_block |
int32_t | The minimum quantity required for a block trade of the instrument. |
min_lot_size_round_lot |
int32_t | The minimum quantity required for a round lot of the instrument. Multiples of this quantity are also round lots. |
min_trade_vol |
uint32_t | The minimum trading volume for the instrument. |
contract_multiplier |
int32_t | The number of deliverables per instrument, i.e. peak days. |
decay_quantity |
int32_t | The quantity that a contract will decay daily, after decay_start_date has been reached. |
original_contract_size |
int32_t | The fixed contract value assigned to each instrument. |
appl_id |
int16_t | The channel ID assigned at the venue. |
maturity_year |
uint16_t | The calendar year reflected in the instrument symbol. |
decay_start_date |
uint16_t | The date at which a contract will begin to decay. |
channel_id |
uint16_t | The channel ID assigned by Databento as an incrementing integer starting at zero. |
currency |
char[4] | The currency used for price fields. |
settl_currency |
char[4] | The currency used for settlement, if different from currency . |
secsubtype |
char[6] | The strategy type of the spread. |
group |
char[21] | The security group code of the instrument. |
exchange |
char[5] | The exchange used to identify the instrument. |
asset |
char[11] | The underlying asset code (product code) of the instrument. |
cfi |
char[7] | The ISO standard instrument categorization code. |
security_type |
char[7] | The type of the instrument, e.g. FUT for future or future spread. |
unit_of_measure |
char[31] | The unit of measure for the instrument’s original contract size, e.g. USD or LBS. |
underlying |
char[21] | The symbol of the first underlying instrument. |
strike_price_currency |
char[4] | The currency used for strike_price . |
strike_price |
int64_t | The exercise price if the instrument is an option. Converted to units of 1e-9, i.e. 1/1,000,000,000 or 0.000000001. |
match_algorithm |
char | The matching algorithm used for the instrument, typically FIFO. See Matching algorithm. |
main_fraction |
uint8_t | The price denominator of the main fraction. |
price_display_format |
uint8_t | The number of digits to the right of the tick mark, to display fractional prices. |
sub_fraction |
uint8_t | The price denominator of the sub fraction. |
underlying_product |
uint8_t | The product complex of the instrument. |
maturity_month |
uint8_t | The calendar month reflected in the instrument symbol. |
maturity_day |
uint8_t | The calendar day reflected in the instrument symbol, or 0. |
maturity_week |
uint8_t | The calendar week reflected in the instrument symbol, or 0. |
user_defined_instrument |
char | Indicates if the instrument is user defined: Yes or No. |
contract_multiplier_unit |
int8_t | The type of contract_multiplier . Either 1 for hours, or 2 for days. |
flow_schedule_type |
int8_t | The schedule for delivering electricity. |
tick_rule |
uint8_t | The tick rule of the spread. |
leg_count |
uint16_t | The number of legs in the strategy or spread. Will be 0 for outrights. |
leg_index |
uint16_t | The 0-based index of the leg (if any). |
leg_instrument_id |
uint32_t | The numeric ID assigned to the leg instrument. |
leg_raw_symbol |
char[symbol_cstr_len] | The leg instrument's raw symbol assigned by the publisher, where symbol_cstr_len is specified in the Metadata. |
leg_instrument_class |
char | The leg instrument's classification. See Instrument class. |
leg_side |
char | The side taken for the leg when buying the spread or strategy. |
leg_price |
int64_t | The tied price (if any) of the leg. Used for hedged strategies. |
leg_delta |
int64_t | The associated delta (if any) of the leg. Used for hedged strategies. |
leg_ratio_price_numerator |
int32_t | The numerator of the price ratio of the leg within the spread. |
leg_ratio_price_denominator |
int32_t | The denominator of the price ratio of the leg within the spread. |
leg_ratio_qty_numerator |
int32_t | The numerator of the quantity ratio of the leg within the spread. |
leg_ratio_qty_denominator |
int32_t | The denominator of the quantity ratio of the leg within the spread. |
leg_underlying_id |
uint32_t | The numeric ID of the leg instrument's underlying instrument. |
Instrument class
The instrument_class
field groups instruments into different classes of securities and derivatives.
Name | Value | Description |
---|---|---|
Bond | B |
A bond. |
Call | C |
A call option. |
Future | F |
A future. |
Stock | K |
A stock. |
Mixed spread | M |
A spread with legs of multiple instrument classes. |
Put | P |
A put option. |
Future spread | S |
A spread with future legs. |
Option spread | T |
A spread with options. |
FX spot | X |
A foreign exchange spot. |
Commodity spot | Y |
A commodity being traded for immediate delivery. |
Security type
The security_type
field classifies the type of instrument.
Name | Value | Description |
---|---|---|
Option on equity | OPT |
An option on equity or a spread with options on equities. |
Option on future | OOF |
An option on future or a spread with options on futures. |
Future | FUT |
A future or a spread on futures. |
Spreads | MLEG |
A spread with legs of multiple instrument classes. |
Interest rate swap | IRS |
An interest rate swap security. |
Matching algorithm
The matching_algorithm
field defines the type of matching algorithm used for the instrument.
Name | Value | Description |
---|---|---|
Undefined | |
A matching algorithm was not specified. |
FIFO | F |
First-in-first-out matching. |
Configurable | K |
A configurable match algorithm. |
Pro-Rata | C |
Trade quantity is allocated to resting orders based on a pro-rata percentage: resting order quantity divided by total quantity. |
FIFO with LMM | T |
Like FIFO, but with LMM allocations prior to FIFO allocations. |
Threshold Pro-Rata | O |
Like Pro-Rata, but includes a configurable allocation to the first order that improves the market. |
FIFO with Top Order and LMM | S |
Like FIFO with LMM, but includes a configurable allocation to the first order that improves the market. |
Threshold Pro-Rata with LMM | Q |
Like Threshold Pro-Rata, but includes a special priority to LMMs. |
Eurodollar Futures | Y |
Special variant used only for Eurodollar futures on CME. |
Time Pro-Rata | P |
A commodity being traded for immediate delivery. |
Institutional Prioritization | V |
A two-pass FIFO algorithm. The first pass fills the Institutional Group the aggressing order is associated with. The second pass matches orders without an Institutional Group association. |
Point-in-time instrument definitions
An important distinction of Databento's instrument definition data is that we usually provide it in point-in-time format like the rest of our market data.
In other words, the instrument definitions are timestamped to the nanosecond and treated as a time series, allowing you to simulate the sequence in which they arrived in real time. This is useful as it avoids lookahead and survivorship bias, and also allows you to backtest any strategy that trades instruments immediately as they become available intraday, such as new options strikes and new listings from IPOs.
If you're switching to Databento from another data provider, you may find this behavior different, as many data providers only give you a cumulative list of all instruments or daily updates on instrument definitions.
Snapshots
For publishers that do not provide a full list of instrument definitions at least daily, the historical API provides a snapshot of all active definitions at UTC midnight Monday through Friday. Therefore, any request for definitions for a 24-hour period beginning at UTC midnight is guaranteed to include definitions for all instruments active during that time period.
Instrument definitions on time series endpoints vs. reference data endpoints
Databento also provides other forms of reference information and static data, such as corporate actions, cross-symbology mappings, and security master data. However, these additional forms of reference data may be found on API endpoints other than our time series endpoints.
The reason that these are separated into different endpoints is that instrument definitions on our time series endpoints are those included with the primary source of data, which is usually a direct feed from a trading venue. On the other hand, other forms of reference data may originate from different secondary sources or need to be licensed separately from such direct feeds.
Databento generally provides ways for you to join and merge instrument definitions and other forms of reference data.
Strategies
One definition record is created for each leg of a strategy or spread.
The primary fields will be the same for each of these records, while the fields beginning with leg_
will have information about the particular leg.