gh-nice-wolf-studio-wolf-skills-marketplace-integrations/skills/databento/references/symbology.md

Databento Symbology Reference

Comprehensive guide to Databento's symbology system including continuous contracts, symbol types, and resolution strategies.

Symbol Types (stypes)

Databento supports multiple symbology naming conventions. Use mcp__databento__symbology_resolve to convert between types.

raw_symbol

Native exchange symbols as provided by the venue.

Examples:

• ESH5 - ES March 2025 contract
• NQM5 - NQ June 2025 contract
• AAPL - Apple Inc. stock
• SPY - SPDR S&P 500 ETF

When to use:

• Working with specific contract months
• Exact symbol from exchange documentation
• Historical analysis of specific expirations

Limitations:

• Requires knowing exact contract codes
• Different venues use different conventions
• Doesn't handle roll automatically

instrument_id

Databento's internal numeric identifier for each instrument.

Examples:

• 123456789 - Unique ID for ESH5
• 987654321 - Unique ID for NQM5

When to use:

• After symbol resolution
• Internally within Databento system
• When guaranteed uniqueness is required

Benefits:

• Globally unique across all venues
• Never changes for a given instrument
• Most efficient for API requests

Limitations:

• Not human-readable
• Requires resolution step to obtain

continuous

Continuous contract notation with automatic rolling for futures.

Format: {ROOT}.{STRATEGY}.{OFFSET}

Examples:

• ES.c.0 - ES front month, calendar roll
• NQ.n.0 - NQ front month, open interest roll
• ES.v.1 - ES second month, volume roll
• GC.c.0 - Gold front month, calendar roll

When to use:

• Backtesting across multiple expirations
• Avoiding roll gaps in analysis
• Long-term continuous price series

Benefits:

• Automatic roll handling
• Consistent symbology across time
• Ideal for backtesting

parent

Parent contract symbols for options or complex instruments.

Examples:

• ES - Parent for all ES contracts
• NQ - Parent for all NQ contracts

When to use:

• Options underlying symbols
• Querying all contracts in a family
• Getting contract family metadata

Continuous Contract Deep Dive

Continuous contracts are the most powerful feature for futures analysis. They automatically handle contract rolls using different strategies.

Roll Strategies

Calendar Roll (.c.X)

Rolls on fixed calendar dates regardless of market activity.

Notation: ES.c.0, NQ.c.1

Roll Timing:

• ES: Rolls 8 days before contract expiration
• NQ: Rolls 8 days before contract expiration

When to use:

• Standard backtesting
• Most predictable roll schedule
• When roll timing is less critical

Pros:

• Predictable roll dates
• Consistent across instruments
• Simple to understand

Cons:

• May roll during low liquidity
• Doesn't consider market dynamics

Open Interest Roll (.n.X)

Rolls when open interest moves to the next contract.

Notation: ES.n.0, NQ.n.1

Roll Timing:

• Switches when next contract's OI > current contract's OI

When to use:

• Avoiding early rolls
• Following market participants
• When market dynamics matter

Pros:

• Follows market behavior
• Natural transition point
• Avoids artificial timing

Cons:

• Less predictable timing
• Can be delayed during low volume
• Different instruments roll at different times

Volume Roll (.v.X)

Rolls when trading volume moves to the next contract.

Notation: ES.v.0, NQ.v.1

Roll Timing:

• Switches when next contract's volume > current contract's volume

When to use:

• Following most liquid contract
• High-frequency analysis
• When execution quality matters

Pros:

• Always in most liquid contract
• Best for execution
• Real-time liquidity tracking

Cons:

• Most variable timing
• Can switch back and forth
• Requires careful validation

Offset Parameter (.X)

The offset determines which contract month in the series.

Offset	Description	Example Usage
.0	Front month	Primary trading contract
.1	Second month	Spread analysis vs front
.2	Third month	Deferred spread analysis
.3+	Further months	Calendar spread strategies

Common Patterns:

• ES.c.0 - Standard ES continuous (front month)
• ES.c.0,ES.c.1 - ES calendar spread (front vs back)
• ES.c.0,NQ.c.0 - ES/NQ pair analysis

ES/NQ Specific Symbology

ES (E-mini S&P 500)

Contract Months: H (Mar), M (Jun), U (Sep), Z (Dec)

Raw Symbol Format: ES{MONTH}{YEAR}

• ESH5 = March 2025
• ESM5 = June 2025
• ESU5 = September 2025
• ESZ5 = December 2025

Continuous Contracts:

• ES.c.0 - Front month (most common)
• ES.n.0 - OI-based front month
• ES.v.0 - Volume-based front month

Tick Size: 0.25 points ($12.50 per tick) Contract Multiplier: $50 per point Trading Hours: Nearly 24 hours (Sunday 6pm - Friday 5pm ET)

NQ (E-mini Nasdaq-100)

Contract Months: H (Mar), M (Jun), U (Sep), Z (Dec)

Raw Symbol Format: NQ{MONTH}{YEAR}

• NQH5 = March 2025
• NQM5 = June 2025
• NQU5 = September 2025
• NQZ5 = December 2025

Continuous Contracts:

• NQ.c.0 - Front month (most common)
• NQ.n.0 - OI-based front month
• NQ.v.0 - Volume-based front month

Tick Size: 0.25 points ($5.00 per tick) Contract Multiplier: $20 per point Trading Hours: Nearly 24 hours (Sunday 6pm - Friday 5pm ET)

Month Codes Reference

Code	Month	Typical Expiration
F	January	3rd Friday
G	February	3rd Friday
H	March	3rd Friday
J	April	3rd Friday
K	May	3rd Friday
M	June	3rd Friday
N	July	3rd Friday
Q	August	3rd Friday
U	September	3rd Friday
V	October	3rd Friday
X	November	3rd Friday
Z	December	3rd Friday

Note: ES/NQ only trade quarterly contracts (H, M, U, Z).

Symbol Resolution

Use mcp__databento__symbology_resolve to convert between symbol types.

Common Resolution Patterns

Continuous to Instrument ID:

Input: ES.c.0
stype_in: continuous
stype_out: instrument_id
Result: Maps to current front month's instrument_id

Raw Symbol to Instrument ID:

Input: ESH5
stype_in: raw_symbol
stype_out: instrument_id
Result: Specific instrument_id for ESH5

Continuous to Raw Symbol:

Input: ES.c.0
stype_in: continuous
stype_out: raw_symbol
Result: Current front month symbol (e.g., ESH5)

Time-Based Resolution

Symbol resolution is date-dependent. The same continuous contract resolves to different instruments across time.

Example:

• ES.c.0 on 2024-01-15 → ESH4 (March 2024)
• ES.c.0 on 2024-04-15 → ESM4 (June 2024)
• ES.c.0 on 2024-07-15 → ESU4 (September 2024)

Important: Always specify start_date and end_date when resolving symbols for historical analysis.

Resolution Parameters

mcp__databento__symbology_resolve
- dataset: "GLBX.MDP3"
- symbols: ["ES.c.0", "NQ.c.0"]
- stype_in: "continuous"
- stype_out: "instrument_id"
- start_date: "2024-01-01"
- end_date: "2024-12-31"

Returns mapping of continuous symbols to instrument IDs for each day in the range.

Expiration Handling

Roll Dates

ES/NQ contracts expire on the 3rd Friday of the contract month at 9:30 AM ET.

Calendar Roll (.c.0) Schedule:

• Rolls 8 days before expiration
• Always rolls on the same relative day
• Predictable for backtesting

Example for ESH5 (March 2025):

• Expiration: Friday, March 21, 2025
• Calendar roll: March 13, 2025 (8 days before)

Roll Detection

To detect when a continuous contract rolled, compare instrument_id or raw_symbol across consecutive timestamps.

Example:

2024-03-12: ES.c.0 → ESH4
2024-03-13: ES.c.0 → ESM4 (rolled!)

Handling Roll Gaps

Price discontinuities often occur at roll:

Gap Detection:

if abs(close_before_roll - open_after_roll) > threshold:
    # Roll gap detected

Adjustment Strategies:

1. Ratio Adjustment: Multiply historical prices by ratio
2. Difference Adjustment: Add/subtract difference
3. No Adjustment: Keep raw prices (most common for futures)

For ES/NQ futures, no adjustment is standard since contracts are similar.

Symbol Validation

Valid Symbol Patterns

Continuous:

• Must match: {ROOT}.{c|n|v}.{0-9+}
• Examples: ES.c.0, NQ.n.1, GC.v.0

Raw Symbols (Futures):

• Must match: {ROOT}{MONTH_CODE}{YEAR}
• Examples: ESH5, NQZ4, GCM6

Equity Symbols:

• 1-5 uppercase letters
• Examples: AAPL, MSFT, SPY, GOOGL

Symbol Existence Validation

Before using a symbol, validate it exists in the dataset:

1. Use mcp__databento__symbology_resolve to resolve
2. Use mcp__databento__reference_search_securities for metadata
3. Check definition schema for instrument details

Common Symbol Pitfalls

1. Wrong stype_in for Continuous Contracts

Wrong:

symbols: "ES.c.0"
stype_in: "raw_symbol"  # WRONG!

Correct:

symbols: "ES.c.0"
stype_in: "continuous"  # CORRECT

2. Forgetting Date Range for Resolution

Wrong:

symbology_resolve(symbols=["ES.c.0"], start_date="2024-01-01")
# Missing end_date - only resolves for one day

Correct:

symbology_resolve(symbols=["ES.c.0"], start_date="2024-01-01", end_date="2024-12-31")
# Resolves for entire year

3. Using Expired Contracts

Wrong:

# ESH4 expired in March 2024
symbols: "ESH4"
start_date: "2024-06-01"  # After expiration!

Correct:

# Use continuous contract
symbols: "ES.c.0"
start_date: "2024-06-01"  # Automatically maps to ESM4

4. Mixing Symbol Types

Wrong:

symbols: "ES.c.0,ESH5,123456"  # Mixed types!

Correct:

# Resolve separately or use same type
symbols: "ES.c.0,NQ.c.0"  # All continuous

Symbol Best Practices

1. Use continuous contracts for backtesting - Avoids manual roll management
2. Prefer calendar rolls (.c.X) unless specific reason - Most predictable
3. Always validate symbols exist - Use symbology_resolve before fetching data
4. Specify date ranges for resolution - Symbol meanings change over time
5. Use instrument_id after resolution - Most efficient for API calls
6. Document roll strategy - Know which roll type (.c/.n/.v) you're using
7. Test around roll dates - Verify behavior during contract transitions
8. Cache symbol mappings - Don't re-resolve repeatedly

Quick Reference: Common Symbols

ES/NQ Continuous (Most Common)

ES.c.0  # ES front month, calendar roll
NQ.c.0  # NQ front month, calendar roll
ES.c.1  # ES second month
NQ.c.1  # NQ second month

ES/NQ Specific Contracts (2025)

ESH5  # ES March 2025
ESM5  # ES June 2025
ESU5  # ES September 2025
ESZ5  # ES December 2025

NQH5  # NQ March 2025
NQM5  # NQ June 2025
NQU5  # NQ September 2025
NQZ5  # NQ December 2025

Equity Market Breadth (Supporting ES/NQ Analysis)

SPY   # SPDR S&P 500 ETF
QQQ   # Invesco QQQ (Nasdaq-100 ETF)
VIX   # CBOE Volatility Index
TICK  # NYSE TICK
VOLD  # NYSE Volume Delta

For equity symbols, use dataset XNAS.ITCH (Nasdaq) or other appropriate equity dataset.