NautilusTrader
Integrations

Nightly docs

These docs track unreleased changes and may change without notice. Their code examples can use APIs that the latest release lacks, so run them with a development wheel or switch to the latest release docs.

Databento

NautilusTrader includes an adapter for the Databento API and for data in Databento Binary Encoding (DBN). Databento is a market data provider only, so the adapter does not include an execution client. For execution or signal use, you can:

  • Pair it with a sandbox for simulated execution.
  • Route execution through another adapter, such as Interactive Brokers.
  • Use it to calculate traditional asset class signals for crypto trading.

The adapter supports:

  • Loading historical data from DBN files and decoding to Nautilus objects for backtesting or catalog storage.
  • Requesting historical data decoded to Nautilus objects for live trading and backtesting.
  • Subscribing to real-time data feeds decoded to Nautilus objects for live trading and sandbox environments.

Databento offers $125 in free data credits for new sign-ups. Apply the credits to historical data requests, or offset them against a subscription plan. Credits are shared across a team and expire six months after signup.

With careful requests, this covers testing and evaluation. Check the metadata.get_cost endpoint before requesting data.

Overview

The adapter uses the databento-rs crate, Databento's official Rust client library.

You do not need to install databento separately. The adapter compiles as a static library and links automatically during the build.

The following adapter classes are available:

  • DatabentoDataLoader: Loads DBN data from files.
  • DatabentoHistoricalClient: Fetches historical market data and instrument definitions via the Databento HTTP API.
  • DatabentoLiveClient: Subscribes to real-time data feeds via Databento's raw TCP API.
  • DatabentoDataClient: Data client for live trading nodes, wrapping the historical and live clients.
  • DatabentoDataClientFactory: Builds the data client from a DatabentoDataClientConfig for LiveNode.

Most users configure a live trading node (covered below) and do not work with these components directly.

Examples

Rust examples live under crates/adapters/databento/examples/. The data tester subscribes to live quotes and trades for the configured instrument when run:

cargo run --example databento-data-tester --package nautilus-databento

Databento documentation

See the Databento new users guide. Refer to it alongside this integration guide.

Databento Binary Encoding (DBN)

Databento Binary Encoding (DBN) is a fast message encoding and storage format for normalized market data. The DBN spec includes a self-describing metadata header and a fixed set of struct definitions that standardize how market data is normalized.

The adapter decodes DBN data to Nautilus objects. The same Rust decoder handles:

  • Loading and decoding DBN files from disk.
  • Decoding historical and live data in real time.

Supported schemas

The following Databento schemas are supported by NautilusTrader:

Databento schemaNautilus data typeDescription
MBOOrderBookDelta | TradeTickMarket by order (L3).
MBP_1(QuoteTick, TradeTick | None)Market by price (L1).
MBP_10OrderBookDepthMarket depth (L2).
BBO_1SQuoteTick1-second best bid/offer.
BBO_1MQuoteTick1-minute best bid/offer.
CMBP_1(QuoteTick, TradeTick | None)Consolidated MBP across venues.
CBBO_1SQuoteTickConsolidated 1-second BBO.
CBBO_1MQuoteTickConsolidated 1-minute BBO.
TCBBO(QuoteTick, TradeTick)Trade-sampled consolidated BBO.
TBBO(QuoteTick, TradeTick)Trade-sampled best bid/offer.
TRADESTradeTickTrade ticks.
OHLCV_1SBar1-second bars.
OHLCV_1MBar1-minute bars.
OHLCV_1HBar1-hour bars.
OHLCV_1DBarDaily bars.
DEFINITIONInstrument (various types)Instrument definitions.
IMBALANCEDatabentoImbalanceAuction imbalance data.
STATISTICSDatabentoStatisticsMarket statistics.
STATUSInstrumentStatusMarket status updates.

Databento also documents reference schemas, including corporate actions, adjustment factors, and security master data. This adapter maps only the schemas listed above to Nautilus data types. Daily Databento OHLCV uses ohlcv-1d, and ohlcv-eod records also decode to daily bars. Official settlement prices and open interest come from the statistics schema, not OHLCV bars.

Instrument definitions for unsupported instrument_class values ('I' Index, 'B' Bond) are skipped with a warning rather than aborting the batch. FX spot definitions with currencies that Nautilus cannot map are also skipped. Index definitions come mainly from the Cboe Global Indices Feed (MAIN.CGIF) and the OPRA options publishers. publishers.json lists every publisher ID with its dataset and venue. Open an issue if you need Nautilus modeling for these.

Statistics messages with stat_type values outside the modeled range (1-20) are also skipped with a warning. This includes the venue-specific values VenueSpecificVolume1 (10001) and VenueSpecificPrice1 (10002), which exceed the u8 Arrow column width used for persistence.

Schema considerations

  • TBBO and TCBBO: Trade-sampled feeds that pair every trade with the BBO immediately before the trade's effect. Use them for trades aligned with contemporaneous quotes without managing two streams.
  • MBP-1 and CMBP-1 (L1): Event-level updates that emit trades only on trade events. Choose them for a complete top-of-book event tape. For quote and trade alignment, prefer TBBO or TCBBO.
  • MBP-10 (L2): Top 10 levels with trades. Use it for depth-aware strategies that do not need full MBO data. Includes orders per level. Databento serves this schema at 10 levels only, so depth requests must use depth=10.
  • MBO (L3): Per-order events for queue position modeling and exact book reconstruction. subscribe_book_deltas() requests no snapshot, so a node subscription streams from the point of subscription with no initial book state. A strategy that needs a complete book must start before the trading session, seed the book from a historical request, or drive DatabentoLiveClient.subscribe directly with snapshot=True.
  • BBO_1S/BBO_1M and CBBO_1S/CBBO_1M: Sampled top-of-book updates at fixed intervals (1s or 1m). The adapter emits QuoteTick only for these schemas. Use them for monitoring, spreads, and low-cost signals. They are not suited for microstructure work.
  • TRADES: Trades only. For quote context alongside trades, subscribe with MBP-1, which emits a TradeTick on every trade event, or use TBBO or TCBBO.
  • OHLCV: Aggregated bars from trades. Use them for higher-timeframe analytics. Bars carry close timestamps by default. Set bars_timestamp_on_close=False to timestamp on the interval open. Daily bars use ohlcv-1d. Use statistics for official settlements and open interest.
  • Imbalance and statistics: Venue operational data with no built-in Nautilus equivalent. Subscribe through subscribe_data(), or reach them through the historical client, the data loader, or the direct live client (see Imbalance and statistics).
  • Status: Venue trading-state updates. Subscribe via subscribe_instrument_status.

Consolidated schemas (CMBP_1, CBBO_1S, CBBO_1M, TCBBO) aggregate data across multiple venues. Useful for cross-venue analysis.

See also the Databento Schemas and data formats guide.

Dataset availability and selection

Databento dataset IDs are separate from Nautilus venue identifiers. The adapter supports the schemas listed above, but each Databento dataset exposes its own subset. Check the metadata endpoints before adding a new dataset or schema to a live configuration:

databento_auth="$(printf '%s:' "$DATABENTO_API_KEY" | base64 | tr -d '\n')"

curl --header "Authorization: Basic ${databento_auth}" \
  "https://hist.databento.com/v0/metadata.list_schemas?dataset=EQUS.MINI"

curl --header "Authorization: Basic ${databento_auth}" \
  "https://hist.databento.com/v0/metadata.list_unit_prices?dataset=EQUS.MINI"

curl --header "Authorization: Basic ${databento_auth}" \
  "https://hist.databento.com/v0/metadata.get_cost" \
  --data-urlencode "dataset=EQUS.MINI" \
  --data-urlencode "symbols=AAPL" \
  --data-urlencode "stype_in=raw_symbol" \
  --data-urlencode "schema=bbo-1s" \
  --data-urlencode "start=2026-06-24T14:30:00Z" \
  --data-urlencode "end=2026-06-24T14:31:00Z"

For the two common evaluation datasets:

  • GLBX.MDP3 is the CME Globex MDP 3.0 dataset for CME, CBOT, NYMEX, and COMEX futures, options on futures, and spreads. It supports MBO, MBP-1, MBP-10, TBBO, trades, BBO intervals, OHLCV, definitions, statistics, and status. It does not expose the consolidated equity schemas (cmbp-1, cbbo-*, or tcbbo).
  • EQUS.MINI is Databento US Equities Mini. It is a derived aggregated top-of-book dataset with anonymized component venues. It supports MBP-1, TBBO, trades, BBO intervals, OHLCV, and definitions. It does not support MBO, MBP-10, imbalance, statistics, status, or consolidated schemas.

Use EQUS as the Nautilus venue for US Equities Mini instruments: AAPL.EQUS, MSFT.EQUS, and so on. The built-in venue-to-dataset map routes EQUS to EQUS.MINI. Venue codes such as XNAS and XNYS refer to venue-specific datasets unless you override them with venue_dataset_map.

If you override a venue such as XNAS to EQUS.MINI, keep downstream instrument IDs consistent. Mini records carry the consolidated EQUS publisher, and file or historical decoding without an explicit instrument_id emits *.EQUS identifiers.

Cost depends on the schema, symbols, and time range. For exploration, start with tight ranges, definition, bbo-1s, bbo-1m, or trades, and call metadata.get_cost before pulling historical time series data. Avoid duplicate quote and trade subscriptions when a combined schema such as mbp-1 or tbbo already carries the data needed by the strategy.

Subscriptions and requests

Nautilus subscription methods map to Databento schemas as follows:

Nautilus subscription methodDefault schemaAvailable Databento schemasNautilus data type
subscribe_instrument()definitiondefinitionInstrument
subscribe_quotes()mbp-1mbp-1, bbo-1s, bbo-1m, cmbp-1, cbbo-1s, cbbo-1m, tbbo, tcbboQuoteTick
subscribe_trades()tradestrades, tbbo, tcbbo, mbp-1, cmbp-1TradeTick
subscribe_book_deltas()mbomboOrderBookDeltas
subscribe_book_depth()mbp-10mbp-10OrderBookDepth
subscribe_bars()noneohlcv-1s, ohlcv-1m, ohlcv-1h, ohlcv-1dBar
subscribe_data()nonestatistics, imbalanceDatabentoStatistics, DatabentoImbalance
subscribe_instrument_status()statusstatusInstrumentStatus

Pass a non-default schema through the schema subscription parameter, as shown in the examples below. Only subscribe_quotes() and subscribe_trades() accept a choice. subscribe_bars() takes its schema from the bar aggregation, and subscribe_data() from the data type name (DatabentoStatistics or DatabentoImbalance). The other methods always use the single schema listed. The matching historical requests, request_quotes() and request_trades(), take the same schema values and defaults.

request_instrument(), request_quotes(), and request_trades() accept identifier lists. The adapter groups identifiers by dataset and preserves successful groups if another group fails. Check on_data_response() for the completion state and failure reason. Quote and trade requests with multiple IDs do not accept a record limit.

Book and bar requests require one list member. A parent-symbol request_book_deltas() can return several book payloads under the same correlation ID; completion follows the last payload.

Actor and Strategy historical requests include both bounds on ts_init. Bar requests select bars by close time even when bars_timestamp_on_close=False.

The "Available Databento schemas" column lists adapter-supported choices for that Nautilus subscription method. The selected dataset must also support the schema. For example, EQUS.MINI cannot serve mbo, mbp-10, statistics, or status.

The examples below assume a Strategy or DataActor context where self has subscription methods. Import the required types:

from nautilus_trader.model import BarType
from nautilus_trader.model import BookType
from nautilus_trader.model import ClientId
from nautilus_trader.model import DataType
from nautilus_trader.model import InstrumentId


DATABENTO_CLIENT_ID = ClientId.from_str("DATABENTO")
instrument_id = InstrumentId.from_str("ES.c.0.GLBX")

Instrument definition subscriptions

# Stream definition messages, which also populate the live price precision map
self.subscribe_instrument(
    instrument_id=instrument_id,
    client_id=DATABENTO_CLIENT_ID,
)

Subscription lists

Implemented instrument subscriptions accept one ID or a non-empty list through instrument_id. External bar subscriptions accept full bar types through bar_type.

Quote and trade batching

Quotes and trades use one subscription per dataset. The adapter validates every ID before dispatch and applies price_precision to each symbol.

  • A dataset enqueue failure is logged and does not stop later datasets.
  • Accepted datasets are not rolled back. The client reports exactly their accepted IDs.
  • The client adapter tracks accepted members and sends only missing IDs when another subscribe command reaches it. Retry is not automatic.

Repeating a subscribe call on the same actor sends no command while that actor retains its local subscription. To retry, release that local subscription first, or subscribe from another owner.

Other subscriptions

Other implemented instrument hooks and external bar hooks iterate members locally:

  • Existing dataset and schema rules apply to each member.
  • A member failure reports the exact synchronous accepted subset.
  • Full bar types on the same instrument remain distinct.

Granular unsubscribe is a documented no-op for every member. Stop the live session to remove its subscriptions.

Quote subscriptions (MBP and L1)

# Default MBP-1 quotes (also emits trades on trade events)
self.subscribe_quotes(instrument_id, client_id=DATABENTO_CLIENT_ID)

# One subscription for both contract IDs in GLBX.MDP3
self.subscribe_quotes(
    instrument_id=[InstrumentId.from_str("ESZ26.GLBX"), InstrumentId.from_str("NQZ26.GLBX")],
    params={"price_precision": 2},
    client_id=DATABENTO_CLIENT_ID,
)

# Explicit MBP-1 schema
self.subscribe_quotes(
    instrument_id=instrument_id,
    params={"schema": "mbp-1"},
    client_id=DATABENTO_CLIENT_ID,
)

# 1-second BBO snapshots (adapter emits QuoteTick only)
self.subscribe_quotes(
    instrument_id=instrument_id,
    params={"schema": "bbo-1s"},
    client_id=DATABENTO_CLIENT_ID,
)

# Consolidated quotes across venues
self.subscribe_quotes(
    instrument_id=instrument_id,
    params={"schema": "cbbo-1s"},  # or "cmbp-1" for consolidated MBP
    client_id=DATABENTO_CLIENT_ID,
)

# Trade-sampled BBO (includes quotes and trades)
self.subscribe_quotes(
    instrument_id=instrument_id,
    params={"schema": "tbbo"},  # Receives QuoteTick and TradeTick on the message bus
    client_id=DATABENTO_CLIENT_ID,
)

Trade subscriptions

Trade calls accept an instrument list as described in Quote and trade batching.

# Trade ticks only
self.subscribe_trades(instrument_id, client_id=DATABENTO_CLIENT_ID)

# Trades from MBP-1 feed (only when trade events occur)
self.subscribe_trades(
    instrument_id=instrument_id,
    params={"schema": "mbp-1"},
    client_id=DATABENTO_CLIENT_ID,
)

# Trade-sampled data (includes quotes at trade time)
self.subscribe_trades(
    instrument_id=instrument_id,
    params={"schema": "tbbo"},  # Also provides quotes at trade events
    client_id=DATABENTO_CLIENT_ID,
)

Order book deltas subscriptions (MBO and L3)

# Subscribe to full order book updates (market by order)
self.subscribe_book_deltas(
    instrument_id=instrument_id,
    book_type=BookType.L3_MBO,  # Uses MBO schema
    client_id=DATABENTO_CLIENT_ID,
)

# Deltas stream from the point of subscription with no initial book snapshot

Instrument status subscriptions

# Subscribe to venue trading-state updates
self.subscribe_instrument_status(
    instrument_id=instrument_id,
    client_id=DATABENTO_CLIENT_ID,
)

Depth, bar, and custom data subscriptions

subscribe_book_depth() streams mbp-10 depth snapshots for one instrument. Databento serves a depth of 10 only, so an explicit depth other than 10 is rejected. The bar aggregation in the BarType selects the OHLCV schema for subscribe_bars() (ohlcv-1s, ohlcv-1m, ohlcv-1h, or ohlcv-1d). The step must be 1 and the price type must be LAST, the only price type the decoder emits. subscribe_data() streams DatabentoStatistics or DatabentoImbalance records for the instrument ID given as the data type identifier, and rejects a data type with metadata. Records are published with that identifier, so a subscriber receives only the records of its own instrument.

These three subscriptions accept contract IDs such as ESZ26.GLBX only. Records resolve to the underlying contract, so continuous (ES.c.0) and parent (ES.FUT) symbols are rejected rather than published on topics the subscriber does not listen on. The examples use a contract ID:

instrument_id = InstrumentId.from_str("ESZ26.GLBX")

self.subscribe_book_depth(
    instrument_id=instrument_id,
    book_type=BookType.L2_MBP,
    client_id=DATABENTO_CLIENT_ID,
)

self.subscribe_bars(
    BarType.from_str(f"{instrument_id}-1-MINUTE-LAST-EXTERNAL"),
    client_id=DATABENTO_CLIENT_ID,
)

self.subscribe_data(
    DataType("DatabentoStatistics", identifier=str(instrument_id)),
    client_id=DATABENTO_CLIENT_ID,
)

Databento live subscriptions cannot be removed one at a time, so the matching unsubscribe_* commands are ignored.

Historical requests for depth and bars

MBP-10 depth and OHLCV bars are available as historical requests. The bar aggregation in the BarType selects the OHLCV schema (ohlcv-1s, ohlcv-1m, ohlcv-1h, or ohlcv-1d), and depth requests use mbp-10:

import pandas as pd


# Request 1-minute bars (uses the ohlcv-1m schema)
self.request_bars(
    bar_type=BarType.from_str(f"{instrument_id}-1-MINUTE-LAST-EXTERNAL"),
    start=pd.Timestamp("2024-03-06", tz="UTC"),
    end=pd.Timestamp("2024-03-07", tz="UTC"),
    client_id=DATABENTO_CLIENT_ID,
)

# Request top 10 levels of market depth (Databento serves depth=10 only)
self.request_book_depth(
    instrument_id=instrument_id,
    depth=10,
    start=pd.Timestamp("2024-03-06T14:30", tz="UTC"),
    end=pd.Timestamp("2024-03-06T14:31", tz="UTC"),
    client_id=DATABENTO_CLIENT_ID,
)

Instrument IDs and symbology

Databento market data includes a numeric instrument_id field. The publisher usually assigns this ID. Databento synthesizes one if the publisher does not provide it. Databento only guarantees this ID is unique within a given day. This differs from the Nautilus InstrumentId, a string of symbol + venue separated by a period: "{symbol}.{venue}".

The decoder derives the Nautilus symbol from the Databento raw_symbol, normalizing supported futures year suffixes as described below. Publisher IDs map to the default Nautilus venue through publishers.json. Subscription InstrumentId metadata can also seed the symbol-to-venue map before market data arrives.

Dataset IDs follow Databento's dataset naming conventions, which are distinct from the venue code in a Nautilus InstrumentId.

For historical requests and live subscriptions, the adapter converts supported futures codes to native year digits and infers stype_in from the symbol:

  • Symbols ending in .FUT or .OPT use Databento parent symbology, for example ES.FUT.XCME.
  • Three-part symbols whose last part is numeric use continuous symbology, for example ES.c.0.GLBX.
  • All-numeric symbols use Databento instrument_id symbology.
  • All other symbols use raw symbol symbology, for example ESZ26.XCME or AAPL.EQUS.

Supported futures and futures-option IDs use two-digit years by default, such as ESZ26.XCME and ESZ26 P5000.XCME. This applies to GLBX.MDP3, IFEU.IMPACT, NDEX.IMPACT, IFUS.IMPACT, IFLL.IMPACT, XEUR.EOBI, XEEE.EOBI, XCBF.PITCH, and XOSE.ITCH. The instrument's raw_symbol keeps the native symbol; futures-option underlying symbols use the same year digits as instrument IDs.

Rust APIs use nautilus_model::identifiers::futures::FuturesYearDigits::{One, Two}, with Two as the default. Python configuration keeps the integer values 1 and 2.

When using Databento data with Interactive Brokers execution, set futures_year_digits to the same value in both adapters so their instrument IDs match.

Requests send native symbols: ESU26-ESM27 is sent as ESU6-ESM7. Set futures_year_digits=1 on the data client config, data loader, historical client, or live client to retain existing IDs.

The factory convenience method DatabentoDataClientFactory.create_live_data_client() uses the default. To retain old IDs, construct DatabentoDataClient directly with futures_year_digits=1.

To use XOSE.ITCH, supply a publisher metadata file with its publisher entry; the bundled file does not include it.

Load definitions for the data's dates through the same loader or historical client instance before loading market data to use their contract-year context. Without a definition, canonical IDs in the current historical request also identify contracts that trade into the following year. Earlier historical requests do not supply year hints. Otherwise, one-digit years resolve to the next matching year at or after the record's ts_recv year (ts_event for OHLCV). Live records received before a definition retain their resolved IDs; later records use the definition's year and venue. Repeated mappings preserve definition-derived years and exchange venues. Inferred IDs refresh from subscription hints; changed native symbols clear cached identity.

After upgrading, either set futures_year_digits=1 or re-import existing data into a separate catalog, rebuild caches, and update configured instrument IDs. Renaming catalog files does not change IDs stored in records.

Share classes use a space in instrument IDs by default: Databento's BRK.B becomes BRK B.EQUS, since a dot separates symbol and venue. This matches Interactive Brokers, which writes the class with a space. Parent and continuous symbols such as ES.FUT and ES.c.0 keep their dots. Requests send the native dotted symbol. The instrument's raw_symbol keeps BRK.B. Set share_class_space=False on the data client config, data loader, historical client, or live client to retain existing IDs.

All symbols in one request or subscription must use the same symbology type. Batch AAPL.EQUS with MSFT.EQUS, or ES.FUT.XCME with NQ.FUT.XCME, but do not mix raw and parent symbols in one Databento request.

For CME Globex MDP 3.0 (GLBX.MDP3), publisher defaults map to the GLBX venue. When use_exchange_as_venue=True, definition messages can override GLBX with the instrument's exchange MIC:

  • CBCM: XCME-XCBT inter-exchange spread
  • NYUM: XNYM-DUMX inter-exchange spread
  • XCBT: Chicago Board of Trade (CBOT)
  • XCEC: Commodities Exchange Center (COMEX)
  • XCME: Chicago Mercantile Exchange (CME)
  • XFXS: CME FX Link spread
  • XNYM: New York Mercantile Exchange (NYMEX)

Other venue MICs are in the venue field of responses from the metadata.list_publishers endpoint.

Timestamps

Databento data includes these timestamp fields:

  • ts_event: Matching-engine-received timestamp in nanoseconds since the UNIX epoch.
  • ts_in_delta: Matching-engine-sending timestamp in nanoseconds before ts_recv.
  • ts_recv: Capture-server-received timestamp in nanoseconds since the UNIX epoch.
  • ts_out: Databento sending timestamp (live only).

Nautilus data requires at least two timestamps (per the Data contract):

  • ts_event: UNIX timestamp (nanoseconds) when the data event occurred.
  • ts_init: UNIX timestamp (nanoseconds) when the data instance was created.

Quote and trade-like schemas map Databento ts_recv to Nautilus ts_event because it is more reliable and monotonically increases per Databento symbol. Bars use the DBN bar interval timestamp. bars_timestamp_on_close controls whether Nautilus bars use the interval open or close timestamp. InstrumentStatus uses the DBN record header ts_event. DatabentoImbalance and DatabentoStatistics preserve Databento timestamp fields because they are adapter-specific types.

Data types

This section maps Databento schemas to Nautilus data types.

Instrument definitions

Databento uses a single schema for all instrument classes. The decoder maps each to the appropriate Nautilus Instrument type.

Databento instrument classCodeNautilus instrument type
StockKEquity
FutureFFuturesContract
CallCOptionContract
PutPOptionContract
Future spreadSFuturesSpread
Option spreadTOptionSpread
Mixed spreadMOptionSpread
FX spotXCurrencyPair
IndexINot yet available
BondBNot yet available

Option exercise style and settlement type

The decoder sets exercise_style and settlement_type on each OptionContract from the CFI code (ISO 10962) in the definition. A field stays None when the code leaves that attribute undefined.

OPRA.PILLAR definitions carry no CFI code. For this dataset, the decoder applies US listing convention by option root:

  • Cash-settled, European-style: a fixed list of index, currency, and index binary option roots, such as SPX, SPXW, XSP, VIX, NDX, RUT, and DJX.
  • Cash-settled, American-style: OEX and XAU.
  • Ambiguous roots: both fields stay None. A five-letter root that starts with K can be a binary option on a company metric or an equity option such as KELYA, and the definition does not tell them apart. A root with a digit before a letter, such as B1SPY, is treated the same way.
  • Any other root: American-style and physically settled, the convention for equity and ETF options.

The OPRA root lists are fixed in the adapter. A cash-settled root that the adapter does not list, such as one listed after the adapter release, decodes as American-style and physically settled unless it is an ambiguous root.

Option expiration correction

OPRA option definitions (dataset OPRA.PILLAR) carry the expiration with date-level precision: the time-of-day is zeroed to midnight UTC. Thus, an option expiring at 16

New York time arrives stamped on the prior evening in New York. The matching engine then treats the contract as expired before its final trading session. By default, the loader corrects such midnight-UTC OPRA expirations to 16
New York time. It leaves every other dataset untouched. It also leaves expirations with an intraday time, such as CME Globex, untouched.

Override the default, or set per-underlying times, with expiration_overrides. It maps a dataset to a mapping of underlying symbol to time, where the reserved key default sets the dataset-wide time:

loader.load_instruments(
    filepath=path,
    use_exchange_as_venue=False,
    expiration_overrides={
        "OPRA.PILLAR": {"default": "16:00", "SPX": "09:30"},
    },
)

Times use HH:MM or HH:MM:SS in the exchange-local timezone (New York for OPRA). Only a dataset with a built-in correction rule can be tuned, and OPRA.PILLAR is the only such dataset. An unknown or rule-less dataset such as GLBX.MDP3 raises a ValueError. The correction keys on the option's underlying, so it cannot distinguish series that share an underlying but settle at different times (for example AM-settled SPX versus PM-settled SPXW). Set the time that matches the contracts you are loading.

Price precision

Databento raw prices are fixed-point integers scaled by 1e-9. Instrument definitions supply tick-size precision, which can be insufficient for reported prices.

  • Market prices: Must be exactly representable at the resolved precision; decoding never promotes precision.
  • Statistics: Use at least the native nine-decimal wire precision to preserve VWAP, volatility, and delta. Higher resolved precision remains in effect.
  • Option strikes: Use the precision needed for the wire value, with a floor at the strike currency's minor-unit precision. Ordinary USD strikes keep two decimal places; adjusted strikes retain finer digits.

Insufficient market precision causes a decoding error. Historical requests and file loading stop at the first rejected record. Live feeds log and skip affected market and imbalance records. Precision errors name the instrument, field, value, and required precision. Select sufficient price_precision explicitly to decode finer prices without rounding.

Sub-penny equity prices

An equity definition at precision 2 does not guarantee two-decimal prices. Strict decoding rejects finer trade prices and OHLCV values, including valid sub-penny prices.

  • Combined records: When trade decoding is enabled, an unrepresentable trade price rejects the whole quote/trade record. Historical and loader MBP-1/CMBP-1 quote-only paths omit trade decoding, so their quotes are unaffected by trade prices.
  • Live overrides: An explicit precision takes precedence over definitions and remains effective after they arrive. It controls decoding; published instrument definitions retain their exchange tick metadata.
  • Historical requests and files: Set sufficient price_precision, such as 4 for four-decimal equity prices.
  • Backtests: Match the instrument's precision to the decoded data. At precision 4, use 0.0100 for a cent tick. Higher decode precision alone does not change the instrument.

Live feeds

The feed handler populates a per-instrument precision map from InstrumentDefMsg records as they arrive. Market data handlers resolve precision in this order:

  1. Subscription-supplied precision matched to the record instrument_id through a symbol mapping message.
  2. Subscription-supplied precision matched directly on the native Databento symbol.
  3. Precision from an InstrumentDefMsg already seen for the Databento record instrument_id.
  4. The USD default precision of 2.

Pass price_precision to subscribe_quotes() or subscribe_trades(); other subscription methods ignore it. The direct live client accepts price_precisions. Steps 1 and 2 let parent, continuous, and other non-raw symbology subscriptions apply the same override before and after definitions arrive.

Definition timing: Without an explicit override, definitions must arrive before market data for instruments with non-standard tick sizes, such as treasury futures with 1/256 ticks. Subscribe to the definition schema before or alongside market data subscriptions.

At strategy start, call subscribe_instrument() for each instrument to populate the live precision map. A symbol's price_precision override lasts for the dataset session. An override on a quote or trade subscription also covers its order book deltas, depth, bars, statistics, and imbalance. Statistics keep their nine-decimal minimum; InstrumentStatus has no prices and needs no precision.

Historical requests and file loading

Precision is resolved per record in this order:

  1. An explicit price_precision argument on the call.
  2. A per-symbol cache populated by loading definitions (load_instruments on the file loader, get_range_instruments on the historical client) or by an explicit set_price_precision(symbol, precision) call using the Nautilus symbol, such as ESZ26.

If neither source supplies precision, the data client fetches the instrument's definition from UTC midnight on the request's start date to include midnight definition snapshots. The market data request keeps its original time range.

Unresolved precision never defaults to USD precision. Historical client and loader calls return an error; data client requests log it and return an empty response.

MBO (market by order)

MBO is the highest granularity data from Databento, representing full order book depth. Some messages include trade data. The decoder produces an OrderBookDelta and optionally a TradeTick. The live client emits a TradeTick only after the instrument has received its first delta.

The live client buffers MBO messages until a record's F_LAST flag closes the match event, then passes one OrderBookDeltas container to the handler. It honors the raw flag even on records that produce no delta (fill attribution, status actions, or trades) or fail decoding. This prevents partial events from being stranded and merged into the next event.

When MBO carries the instrument's trades (see Real-time client architecture), a trade that closes the event follows the flushed container.

Snapshot records (F_SNAPSHOT) accumulate into the same buffer and flush with the first non-snapshot event boundary. Thus, a snapshot reaches the handler as one OrderBookDeltas container rather than individual deltas. When a subscription carries a replay start anchor, the client keeps replayed history out of the live stream until an event timestamp passes the session start time. It holds replayed deltas and flushes them with that first live event, and drops replayed trades.

MBP-1 (market by price, top-of-book)

MBP-1 represents top-of-book quotes and trades. Some messages carry trade data. The decoder produces a QuoteTick and also a TradeTick when the message is a trade.

TBBO and TCBBO (top-of-book with trades)

TBBO and TCBBO provide both quote and trade data in each message. Both schemas emit a TradeTick per message plus a QuoteTick, more efficient than separate quote and trade subscriptions. The quote is skipped when either the bid or ask price is undefined. TCBBO provides consolidated data across venues.

Trade ID derivation (CMBP-1 and TCBBO)

The CMBP-1 and TCBBO schemas do not publish a native trade identifier. The decoder derives a deterministic TradeId by FNV-1a hashing the instrument ID, ts_event, ts_recv, price, size, and aggressor side of the trade. The same venue event yields the same trade ID across replays, so downstream dedup stays intact. Two logically distinct trades with identical fields collide. This matches the venue's inability to distinguish them.

OHLCV (bar aggregates)

Databento timestamps bar messages at the open of the interval. By default, the decoder normalizes bar ts_event to the bar close: the original ts_event plus the interval. ts_init uses the live receipt time, or the close time for historical and file-based loads when no explicit init timestamp is supplied. Set bars_timestamp_on_close=False to timestamp bar ts_event on the interval open.

Imbalance and statistics

The imbalance and statistics schemas have no built-in Nautilus equivalents. The adapter defines DatabentoImbalance and DatabentoStatistics in Rust, and Python bindings expose both types from nautilus_trader.adapters.databento.

Subscribe to live records with subscribe_data() and a DataType named DatabentoStatistics or DatabentoImbalance whose identifier is the instrument ID. Historical requests and files use:

  • DatabentoDataLoader.load_imbalance and load_statistics for DBN files.
  • DatabentoHistoricalClient.get_range_imbalance and get_range_statistics for historical ranges.

DatabentoLiveClient.subscribe with the imbalance or statistics schema also streams them outside a node.

Request a bounded range of statistics for the ES.FUT parent symbol (all active E-mini S&P 500 futures). Both get_range_* methods are asynchronous. Use Databento's Historical metadata.get_cost endpoint before real historical pulls:

import os

from nautilus_trader.adapters.databento import DatabentoHistoricalClient
from nautilus_trader.core import dt_to_unix_nanos
from nautilus_trader.model import InstrumentId


client = DatabentoHistoricalClient(
    key=os.environ["DATABENTO_API_KEY"],
    publishers_filepath="publishers.json",
    use_exchange_as_venue=False,
)

statistics = await client.get_range_statistics(
    dataset="GLBX.MDP3",
    instrument_ids=[InstrumentId.from_str("ES.FUT.GLBX")],
    start=dt_to_unix_nanos("2024-03-06T00:00:00Z"),
    end=dt_to_unix_nanos("2024-03-07T00:00:00Z"),
    price_precision=2,
)

The example uses price_precision=2 for lookup; returned statistic prices have nine decimal places. A fresh historical client has no cached precision:

  • Required setup: Supply price_precision or first call get_range_instruments for the same range. Otherwise, the first decoded record aborts the request.
  • Parent symbols: set_price_precision cannot seed ES.FUT; records resolve to individual contract symbols.

Arrow encoding for imbalance and statistics

Both types implement Arrow record batch encoding and decoding. The nautilus_databento::arrow module exposes it in Rust behind the arrow feature flag:

use nautilus_databento::arrow::imbalance::{
    decode_imbalance_batch,
    imbalance_to_arrow_record_batch,
};

let batch = imbalance_to_arrow_record_batch(&imbalances)?;

let metadata = batch.schema().metadata().clone();
let decoded = decode_imbalance_batch(&metadata, &batch)?;

The statistics module follows the same pattern with decode_statistics_batch and statistics_to_arrow_record_batch. Call get_databento_arrow_schema_map(DatabentoImbalance) from Python to inspect the Arrow field map for either type.

  • Batch consistency: statistics_to_arrow_record_batch and registered custom-data encoding reject mixed instruments, price precisions, or quantity precisions. Null fields do not constrain precision. Align precisions explicitly before batching.
  • Explicit metadata: In Rust, supply DatabentoStatistics::encode_batch with sufficient precision metadata. It must name the same instrument for every row and represent every value exactly. Decoded values use that precision.

Neither type is registered with the ParquetDataCatalog custom data encoders. Thus, write_custom_data and query_custom_data fail with an unregistered-type error. Neither type streams through BacktestNode or BacktestEngine. For research with imbalance or statistics data, load or request the records and process them directly.

Performance considerations

Two options for backtesting with DBN data:

  • Store data as DBN (.dbn.zst) files and decode to Nautilus objects every run.
  • Convert DBN files to Nautilus objects once and write to the data catalog (Nautilus Parquet format).

The DBN decoder is optimized Rust, but writing to the catalog once gives the best backtest performance.

DataFusion streams Nautilus Parquet data from disk at high throughput, at least an order of magnitude faster than decoding DBN per run.

Measured decode and client throughput for this adapter is recorded in crates/adapters/databento/benches/BENCHMARKS.md, along with the command that reproduces it. Absolute numbers vary by machine, so only same-machine deltas are meaningful.

For live data, decoded delivery from the feed handler to Nautilus is intentionally unbounded. This prevents slow consumers from stalling the feed path. A process under memory pressure should fail rather than block live decoding.

Loading DBN data

DatabentoDataLoader decodes DBN files directly into Nautilus objects. It exposes a method for each supported output type, including load_instruments, load_order_book_deltas, load_order_book_depth, load_quotes, load_trades, load_bars, load_status, load_imbalance, and load_statistics.

Pass the publisher metadata file when it is not available beside the running executable:

from nautilus_trader.adapters.databento import DatabentoDataLoader
from nautilus_trader.model import InstrumentId


loader = DatabentoDataLoader(publishers_filepath="publishers.json")

instruments = loader.load_instruments(
    filepath="equity-definitions.dbn.zst",
    use_exchange_as_venue=True,
)
trades = loader.load_trades(
    filepath="aapl-trades.dbn.zst",
    instrument_id=InstrumentId.from_str("AAPL.XNAS"),
)

Write definition data before market data when writing to a ParquetDataCatalog, because the catalog needs the instrument before it can write records for that instrument:

from nautilus_trader.persistence import ParquetDataCatalog


catalog = ParquetDataCatalog(base_path="catalog")
catalog.write_instruments(instruments)
catalog.write_trade_ticks(trades)

Use the schema-specific methods for files whose schema is not the default for that output type:

  • load_bbo_quotes for BBO interval quotes.
  • load_cmbp_quotes for CMBP-1 quotes.
  • load_cbbo_quotes for CBBO quotes.
  • load_tbbo_trades for TBBO trades.
  • load_tcbbo_trades for TCBBO trades.

Call schema_for_file to read a file's schema from its DBN metadata header when picking the loader method.

Optional instrument_id and price_precision arguments bypass symbology or precision lookup when those values are already known. An explicit instrument_id is used as given; match its year digits to the loader's futures_year_digits. The bar loader also accepts timestamp_on_close.

Real-time client architecture

The DatabentoDataClient wraps the other Databento adapter classes. It creates one live feed handler per dataset on the first subscription for that dataset, and every schema for that dataset shares the handler. The handler runs one async task that races the next gateway record against the next engine command. Thus, later subscriptions reach the running session without a reconnect.

The trades, mbp-1, tbbo, cmbp-1, tcbbo, and mbo schemas all carry an instrument's trades. When one instrument is subscribed on several of them, such as quotes on mbp-1 beside trades on trades, the handler sends each trade only once. The first schema to deliver a trade for the instrument carries its trades until the handler reconnects, and trades decoded from the other schemas are dropped. Quotes and book deltas from those schemas are still sent. Which schema delivers first can differ between sessions, so with mbo beside another trade schema, a trade does not always follow its event's book deltas. Limitations:

  • The mbp-1 and tbbo schemas share a record type, so subscribing to both for one instrument still delivers each trade, and the quote at each trade, twice.
  • A continuous symbol stops carrying a contract when it rolls. If a schema subscribed on a continuous symbol carries a contract's trades, the other schemas' trades for that contract stay dropped after the roll.

A single DatabentoHistoricalClient serves every historical request from the data client, including the instrument definitions fetched to seed price precision.

Databento drops a replay start anchor sent after a live session has started, so a subscription made mid-session streams from that point forward with no history. The feed handler logs an error for a late start. It strips start from stored subscriptions, so a reconnect never replays history a second time.

Configuration

Create DatabentoDataClientConfig from the adapter's public Python module. The API key and publishers.json path are required:

import os
from pathlib import Path

from nautilus_trader.adapters.databento import DatabentoDataClientConfig


config = DatabentoDataClientConfig(
    api_key=os.environ["DATABENTO_API_KEY"],
    publishers_filepath=Path("publishers.json"),
    use_exchange_as_venue=False,
)

Download the canonical publishers.json and point publishers_filepath at the local copy.

OptionDefaultDescription
api_keyRequiredDatabento API key.
publishers_filepathRequiredLocal path to Databento publisher metadata.
use_exchange_as_venueFalseUse exchange MIC venues for GLBX instruments.
futures_year_digits2Use two-digit years, or 1 for existing futures IDs.
share_class_spaceTrueSpell share classes with a space (BRK B).
bars_timestamp_on_closeTrueTimestamp bars on close instead of the interval open.
venue_dataset_mapNoneOverride venue-to-dataset mappings from publisher data.
historical_base_urlNoneOverride the Historical API base URL.
live_gateway_addrNoneOverride the live gateway socket address (host:port).

Use DatabentoDataClientConfig with DatabentoDataClientFactory. The current Python example shows the complete LiveNode.builder(...) configuration.

Connection stability

The live client reconnects automatically on:

  • Network interruptions: Temporary connectivity issues.
  • Gateway restarts: Databento scheduled live gateway restarts. See the maintenance schedule.
  • Market closures: Sessions ending during off-hours.

Reconnection strategy

The factory-backed live client uses an internal 10-minute reconnection window with exponential backoff from 1 second, capped at 60 seconds. The Python DatabentoDataClientConfig constructor does not expose a reconnection timeout. Once the window elapses without a successful session, the client gives up and reports an error rather than retrying indefinitely.

Stalled connections are detected by the upstream Databento client, which raises a heartbeat timeout when no data arrives within the heartbeat interval plus 5 seconds. The feed handler treats that as a connection error and enters the same backoff loop.

All reconnections include:

  • Jitter: Random delay (up to 1 second) to prevent simultaneous reconnection storms.
  • Automatic resubscription: Restores all active subscriptions after reconnecting.
  • Cycle reset: Each successful session (>60s) resets the timeout clock and the backoff delay.
  • Command buffering: Commands received during backoff are applied to the next session.

Individual unsubscribe requests log at debug level and are ignored because Databento live sessions do not support granular unsubscribe. Stop the session to remove a subscription from the live gateway.

Scheduled maintenance

Databento restarts live gateways on this schedule (all clients disconnect):

DatasetRestart time
CME GlobexSaturday 02
CT
All ICE venuesSunday 09
UTC
All other datasetsSunday 10
UTC

The internal 10-minute timeout covers typical restarts. See the Databento Maintenance Schedule for details.

Contributing

To contribute, see the contributing guide.

On this page