GitHub - alpha-xone/xbbg: An intuitive Bloomberg API

xbbg: The intuitive Bloomberg API for Python, JavaScript and Rust

Quick Links: Discord • Documentation • Installation • Quickstart • Examples • Contributing • Changelog

Latest release: xbbg==1.1.2 (release: notes)

This main branch is the Rust-powered v1 release, a significant upgrade over 0.x in performance and architecture. Need the legacy pure-Python behavior? Use release/0.x.

Overview

xbbg is the modern standard Bloomberg API across Python, JavaScript, and Rust: broad Bloomberg coverage, an enterprise-grade native runtime, and clean language-native interfaces without legacy wrapper bloat. This main branch is the v1 release: Bloomberg request execution is Rust-powered for performance and reliability while preserving the familiar Python xbbg API and exposing the same engine to JavaScript and Rust workflows.

Key Features

Complete API Coverage

Reference data (BDP/BDS)
Historical time series (BDH)
Intraday bars and tick data
Real-time subscriptions
BQL, BEQS, and BSRCH queries
Technical analysis (BTA)

Enterprise-Grade Features

ZFP over leased lines with TLS credentials
B-PIPE auth, failover servers, SOCKS5, and SDK logging
Async/await support for non-blocking operations
Narwhals default with legacy PyArrow backing when installed (plus explicit native, PyArrow, pandas, Polars, and DuckDB backends)
Full type hints, structured errors, and diagnostics
Exchange-aware market hours

Excel Compatibility

Familiar Bloomberg Excel syntax
Same field names and date formats
Minimal learning curve for Excel users
Direct migration path from Excel workflows

Developer Experience

Consistent, intuitive API design
Extensive documentation and examples
Active community support (Discord)
Regular updates and maintenance
Semantic versioning

Quick Example

from xbbg import blp

# Reference data
prices = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], 'PX_LAST')

# Historical data
hist = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31')

# Intraday bars with sub-minute precision
intraday = blp.bdib('TSLA US Equity', dt='2024-01-15', interval=10, intervalHasSeconds=True)

See py-xbbg/examples/xbbg_jupyter_examples.ipynb for comprehensive tutorials and examples.

Why Choose xbbg?

xbbg is the standard, most modern, highest-performance Bloomberg API wrapper for Python. It is built for enterprise use: ZFP over leased lines, B-PIPE authentication, TLS, failover servers, SOCKS5, SDK logging, Rust-powered execution, Arrow-native data movement, typed Python ergonomics, and comprehensive Bloomberg coverage without the boilerplate or one-off wrappers that make smaller libraries feel simple until your workflow grows.

🎯 Unmatched Feature Coverage

xbbg is designed to replace direct blpapi usage for almost every normal Bloomberg workflow: high-level helpers cover the common APIs, while the generic request layer gives access to arbitrary Bloomberg services and operations when you need to go lower level.

Near-complete blpapi coverage: Reference, Historical, Bulk, Intraday, Tick, Streaming, BQL, BEQS, BSRCH, BQR, BTA, YAS, fields, portfolios, curves, government lookup, and raw/generic service requests
Direct replacement for raw blpapi in applications: session setup, auth, request dispatch, event parsing, Arrow output, async execution, logging, errors, and retries are handled by xbbg instead of hand-written SDK loops
Sub-second precision: Down to 10-second intraday bars (unique to xbbg)
Real-time streaming: Live market data with async support
Advanced utilities: Futures/CDX contract resolution, currency conversion, market hours

📊 Enterprise-Grade Without Bloat

ZFP over leased lines: First-class zfp_remote support using Bloomberg's ZFP leased-line session setup with client credentials and trust material
B-PIPE and SAPI-ready authentication: User, application, user+application, directory, manual, and token auth modes for real enterprise identity flows
Transport control for managed networks: Direct hosts, ordered failover servers, TLS, SOCKS5 proxying, startup attempts, auto-restart, and retry policy are all explicit configuration, not ad hoc connection strings
Operational observability: xbbg tracing, Bloomberg SDK log bridging, SDK runtime detection, worker health, and request environment snapshots make failures inspectable instead of opaque
Concurrency and isolation: Independent request worker pools and isolated subscription sessions keep batch requests, live streams, and scoped engines from stepping on each other
Enterprise middleware hooks: Request middleware gives platform teams a supported place for audit logging, entitlement checks, request labeling, metrics, tracing, policy enforcement, and standardized error handling across every Bloomberg request
Validation and governance hooks: Field validation modes, persistent field caches, middleware context, and stable output contracts give teams enforceable request behavior
Advanced zero-copy architecture: Rust decodes Bloomberg payloads into typed Arrow builders, releases the GIL around native work, wraps native ArrowTable results in a Narwhals DataFrame by default for dataframe ergonomics, and exposes explicit native/PyArrow/pandas/Polars/DuckDB conversions when requested
Benchmarking across changes: Dedicated live and offline benchmark harnesses track request latency, allocation behavior, cache contention, subscription replay throughput, and competitor equivalence so performance regressions are visible instead of guessed
Rust-powered hot path: Bloomberg sessions, request execution, parsing, and Arrow handoff run in the shared native engine instead of slow Python event-loop glue
No bloat: every core dependency is part of the enterprise data path — Bloomberg SDK access, typed tabular interchange, backend conversion, benchmarking, diagnostics, or runtime packaging

💡 Developer Experience

Excel-compatible: Use familiar Bloomberg Excel syntax - zero learning curve
Pythonic API: Consistent, intuitive function names (bdp, bdh, bdib)
Rich documentation: 100+ examples, Jupyter notebooks, comprehensive guides
Active community: Discord support, regular updates, responsive maintainers

🚀 Performance & Reliability

Nothing else in the Python Bloomberg ecosystem is this complete: xbbg covers simple BDP/BDH/BDS and scales to intraday bars, ticks, subscriptions, BQL, BEQS, BSRCH, BTA, YAS, ZFP, B-PIPE auth, TLS, failover, SOCKS5, and more
Highest-performance architecture: Rust worker pools, typed Arrow builders, async execution, GIL-free native work, zero-copy columnar handoff, and reusable Bloomberg sessions replace the repeated Python session boilerplate used by older wrappers
Benchmark-driven engineering: xbbg tracks performance across changes with live Bloomberg benchmarks, offline replay harnesses, allocation profiling, cache-contention measurements, subscription replay tests, and competitor equivalence checks
No bloat: every core dependency is part of the enterprise data path — Bloomberg SDK access, typed tabular interchange, backend conversion, benchmarking, diagnostics, or runtime packaging
Battle-tested: Used in production by hedge funds, asset managers, and research teams
Modern Python: Supports Python 3.10-3.14 with latest language features
CI/CD pipeline: Automated testing across multiple Python versions and platforms
Semantic versioning: Predictable releases with clear upgrade paths

Comparison with Alternatives

The gap is not cosmetic. The other Python Bloomberg packages are either narrow homegrown wrappers around BDP/BDH/BDS, seldom-updated legacy pandas-era clients, or partial modern experiments. They can be useful for tiny scripts, but they are not comprehensive Bloomberg platforms: they miss major services, lack enterprise transports, do not provide the same async/session architecture, and do not carry the same benchmark-driven Rust/Arrow runtime. xbbg is the standard because it is the only package that covers the simple path and the institutional path in one stack.

Detailed competitor notes

vs. raw blpapi

Official SDK surface, but intentionally low-level: every app must rebuild session setup, service opening, request construction, correlation IDs, event-loop parsing, retries, logging, and dataframe conversion.
xbbg keeps the SDK power underneath through Bloomberg's C/C++ SDK while replacing hand-written event loops with a typed Rust engine, async worker pools, structured exceptions, Arrow output, and generic requests.
For almost every normal application, xbbg is the professional replacement for direct blpapi, not just a convenience wrapper.

vs. bbg-fetch / BloombergFetch

Small, homegrown pandas helper package for prices/fundamentals/curves/analytics; targets Python 3.9–3.12 and is not a modern Python 3.13+ option.
Hard-depends on numpy>=2.0 and pandas>=2.2.0 (plus optional pyarrow, Jupyter, and dev extras), so it is not meaningfully simpler than xbbg's core dependency surface.
Missing the institutional surface: intraday bars, ticks, streaming, BQL/BEQS/BSRCH/BQR/BTA, ZFP, B-PIPE/SAPI auth, SDK logging, multi-backend output, typed Arrow transport, async execution, and generic Bloomberg service requests.

vs. pdblp

Legacy pandas-era wrapper; its own README says it has been superseded by blp and is no longer under active development.
No modern Requires-Python floor; only declares pandas>=0.18.0, exactly the old pandas-wrapper model xbbg replaces.
Covers a small subset of Bloomberg data and leaves async, streaming, enterprise transports, Rust/Arrow performance, typed errors, diagnostics, multi-backend output, and broad service coverage outside the package.

vs. blp

Cleaner than pdblp, but still a Python-level interface around Bloomberg Open API concepts.
Declares Python >=3.6 and mandatory pandas, keeping it in the classic Python/pandas wrapper category.
xbbg goes further with native Rust execution, reusable worker pools, Arrow-native output, near-complete blpapi workflow coverage, enterprise connection modes, high-level analytics, and benchmark coverage across changes.

vs. polars-bloomberg

Locks the whole workflow into Polars; xbbg gives you Polars as an optional conversion alongside pandas, DuckDB, Narwhals, and raw xbbg native Arrow paths.
Partial Bloomberg surface: useful BQL/search-style coverage, but not full API coverage across BDP/BDS/BDH/BDIB/BDTICK/streaming, enterprise transports, middleware, diagnostics, or generic service requests.
xbbg is the broader platform: same modern Polars-friendly output when you want it, without giving up the rest of Bloomberg or forcing every team onto one dataframe library.

Feature	xbbg	bbg-fetch (BloombergFetch)	pdblp	blp	polars-bloomberg
Data Services
Reference Data (BDP/BDS)	✅	✅	✅	✅	✅
Historical Data (BDH)	✅	✅	✅	✅	✅
Intraday Bars (BDIB)	✅	❌	❌	❌	✅
Tick-by-Tick Data	✅	❌	❌	❌	❌
Real-time Subscriptions	✅	❌	❌	❌	❌
Advanced Features
Equity Screening (BEQS)	✅	❌	❌	❌	❌
Query Language (BQL)	✅	❌	❌	❌	✅
Quote Request (BQR)	✅	❌	❌	❌	❌
Search (BSRCH)	✅	❌	❌	❌	✅
Technical Analysis (BTA)	✅	❌	❌	❌	❌
Yield & Spread Analysis (YAS)	✅	❌¹	❌	❌	❌
Developer Features
Excel-compatible syntax	✅	❌	❌	❌	❌
Sub-minute intervals (10s bars)	✅	❌	❌	❌	❌
Async/await support	✅	❌	❌	❌	❌
Multi-backend output	✅	❌	❌	❌	❌
Utilities
Currency conversion	✅	❌	❌	❌	❌
Futures contract resolution	✅	✅²	❌	❌	❌
CDX index resolution	✅	❌	❌	❌	❌
Exchange market hours	✅	❌	❌	❌	❌
Project Health
Active development	✅	✅	❌³	✅	✅
Python version support	3.10-3.14⁴	3.9-3.12⁵	legacy 3.x⁶	3.6+⁷	3.12+
Live last commit⁸
DataFrame library	Multi-backend	pandas	pandas	pandas	Polars
Type hints	✅ Full	❌	❌	Partial	✅ Full
Real CI matrix across all supported Python versions⁹	✅	❌	❌	❌	❌

Bottom line: Use xbbg. The alternatives are narrower, older, slower, seldom updated, or incomplete: they stop at basic pandas workflows, miss major Bloomberg services, lack enterprise connectivity, or rely on repeated Python session boilerplate. xbbg is the standard Bloomberg Python stack and can replace direct blpapi for almost every normal application workflow: broader coverage, modern Rust/Arrow internals, benchmarked performance across changes, enterprise transports, async execution, configurable sessions, generic service requests, and non-pandas backends without switching libraries.

Common objections, answered

“Rust and Narwhals are dependency bloat.” False. xbbg has a deliberately small core dependency surface: narwhals plus the native engine. The Rust engine emits xbbg native Arrow objects (ArrowTable / ArrowRecordBatch) directly, and Narwhals provides the lightweight plugin interface that lets one engine serve pandas, Polars, DuckDB, and other dataframe consumers when you explicitly request conversion. By contrast, bbg-fetch installs numpy>=2.0 and pandas>=2.2.0 as hard dependencies, with optional pyarrow, Jupyter, and dev extras. Pandas-based wrappers are not dependency-free; they just make pandas mandatory and still leave you with Python event-loop parsing, one-off dataframe shaping, and a narrow API. xbbg is leaner where it matters: fewer core concepts, fewer repeated parsing paths, fewer mandatory dataframe assumptions, and one native engine for the whole Bloomberg surface.
“Use a lighter package for simple bdp() calls.” No. xbbg is still simple at the call site (xbbg.bdp(...)), but it does not trap you in a toy architecture when that same notebook grows into B-PIPE auth, async batch jobs, intraday bars, BQL, streaming, typed outputs, or non-pandas pipelines.
“Fixed income and government bonds are gaps.” No. xbbg has explicit fixed-income coverage: ISIN/CUSIP/SEDOL support, BDS cash-flow style data, BSRCH fixed-income searches, BQR dealer quotes, YAS helpers, bond analytics, curves, and CDX analytics. When Bloomberg returns no data for a security/field/date combination, xbbg surfaces the request result instead of pretending unavailable Bloomberg data exists.
“You need raw blpapi for SAPI or B-PIPE session control.” No. xbbg exposes first-class session configuration: direct hosts, ordered failover servers, ZFP over leased lines, TLS credentials, SOCKS5, SAPI/B-PIPE auth modes (user, app, userapp, dir, manual, token), startup attempts, auto-restart, retry policy, SDK logging, scoped Engine(...) instances, and request/subscription worker pools. For unusual Bloomberg operations, the generic request layer lets xbbg replace hand-written blpapi request/event-loop code without dropping to the raw SDK.
“xbbg creates Bloomberg data compliance risk by saving data locally.” No. xbbg does not require a BBG_ROOT market-data cache or auto-save Bloomberg responses as local Parquet files. Core requests return typed tables/dataframes to the caller. Metadata caches used for field/schema/type resolution are not Bloomberg market-data archives.
“High-level means black-box troubleshooting.” No. xbbg is high-level at the Python API and low-level where debugging matters: structured exception classes, SDK detection via get_sdk_info(), xbbg tracing, Bloomberg SDK log bridging with enable_sdk_logging(), request IDs, worker health, middleware context, request environment snapshots, raw request access, and JSON output modes for inspecting Bloomberg payloads.

Complete API Reference

Unless noted otherwise, the typed request helpers below have async a... counterparts (bdp → abdp, bcurves → abcurves, etc.).

Reference Data - Point-in-Time Snapshots

Function	Description	Key Features
`bdp()`	Get current/reference data	Multiple tickers & fields Excel-style overrides ISIN/CUSIP/SEDOL support
`bds()`	Bulk/multi-row data	Portfolio holdings Fixed income cash flows Corporate actions
`abdp()`	Async reference data	Non-blocking operations Concurrent requests Web application friendly
`abds()`	Async bulk data	Parallel bulk queries Same API as `bds()`
`bflds()`	Unified field metadata	Get field info or search by keyword Single function for both use cases
`fieldInfo()`	Field metadata lookup (alias for `bflds`)	Data types & descriptions Discover available fields
`fieldSearch()`	Search Bloomberg fields (alias for `bflds`)	Find fields by keyword Explore data catalog
`blkp()`	Find tickers by name	Company name search Asset class filtering
`bport()`	Portfolio data queries	Dedicated portfolio API Holdings & weights

Fixed Income Analytics

Function	Description	Key Features
`yas()`	Yield & Spread Analysis	YAS calculator wrapper YTM/YTC yield types Price↔yield conversion Spread calculations
`preferreds()`	Preferred security screening	Issuer-centric lookup BQL-backed preferred universe
`corporate_bonds()`	Corporate bond screening	Cross-market debt lookup Issuer-to-bond discovery

xbbg.ext follows the same async naming convention as the core API: extension helpers generally expose a... variants without needing separate conceptual documentation for each async name.

Bond Analytics (via `xbbg.ext`)

Function	Description	Key Features
`bond_info()`	Bond reference metadata	Ratings, maturity, coupon
`bond_risk()`	Duration and risk metrics	Modified/Macaulay duration, convexity, DV01
`bond_spreads()`	Spread analytics	OAS, Z-spread, I-spread, ASW
`bond_cashflows()`	Cash flow schedule	Coupon and principal payments
`bond_key_rates()`	Key rate durations	Key rate DV01s and risks
`bond_curve()`	Relative value comparison	Multi-bond analytics

Options Analytics (via `xbbg.ext`)

Function	Description	Key Features
`option_info()`	Contract metadata	Strike, expiry, exercise type
`option_greeks()`	Greeks and implied vol	Delta, gamma, theta, vega, IV
`option_pricing()`	Value decomposition	Intrinsic/time value, activity
`option_chain()`	Chain via overrides	`CHAIN_TICKERS` with filtering
`option_chain_bql()`	Chain via BQL	Rich filtering, expiry/strike ranges
`option_screen()`	Multi-option comparison	Side-by-side analytics

Options helper enums exported by xbbg.ext:

PutCall — put/call selector
ChainPeriodicity — chain interval / expiry grouping
StrikeRef — strike-reference mode
ExerciseType — American/European exercise metadata
ExpiryMatch — expiry matching strategy

CDX Analytics (via `xbbg.ext`)

Function	Description	Key Features
`cdx_info()`	CDX reference metadata	Series, version, constituents
`cdx_defaults()`	Default history	Settled defaults in index
`cdx_pricing()`	Market pricing	Spread, price, recovery rate
`cdx_risk()`	Risk metrics	DV01, duration, spread sensitivity
`cdx_basis()`	Basis analytics	CDX vs intrinsics spread
`cdx_default_prob()`	Default probability	Implied default rates
`cdx_cashflows()`	Cash flow schedule	Premium and protection legs
`cdx_curve()`	Term structure	Multi-tenor curve analytics

Historical Data - Time Series Analysis

Function	Description	Key Features
`bdh()`	End-of-day historical data	Flexible date ranges Excel-compatible aliases (`Per`, `Fill`, `Points`, etc.) Local presentation aliases (`Dts`, `DtFmt`, `Sort`, `Direction`) Dividend/split adjustments
`abdh()`	Async historical data	Non-blocking time series Batch historical queries Same alias support as `bdh()`
`dividend()`	Dividend & split history	All dividend types Projected dividends Date range filtering
`earnings()`	Corporate earnings	Geographic breakdowns Product segments Fiscal period analysis
`turnover()`	Trading volume & turnover	Multi-currency support Automatic FX conversion

Intraday Data - High-Frequency Analysis

Function	Description	Key Features
`bdib()`	Intraday bar data	Sub-minute bars (10s intervals) Session filtering (open/close) Exchange-aware timing Timezone control (`tz` parameter)
`bdtick()`	Tick-by-tick data	Trade & quote events Condition codes Exchange/broker details

Screening & Advanced Queries

Function	Description	Key Features
`beqs()`	Bloomberg Equity Screening	Custom screening criteria Private & public screens
`bql()`	Bloomberg Query Language	SQL-like syntax Complex transformations Options chain analysis
`bqr()`	Bloomberg Quote Request	Tick-level dealer quotes Broker attribution codes Spread price & yield data Date offset support (-2d, -1w)
`bsrch()`	SRCH (Search) queries	Fixed income searches Commodity screens Weather data
`bcurves()`	Yield-curve discovery	Country/currency filters Curve ID lookup
`bgovts()`	Government security search	Treasury/sovereign lookup Partial or exact matching
`bta()`	Technical Analysis	50+ technical indicators Custom studies
`ta_studies()`	Technical analysis catalog	Discover available studies
`ta_study_params()`	TA parameter inspection	Study inputs, defaults, and metadata
`etf_holdings()`	ETF holdings via BQL	Complete holdings list Weights & positions

Real-Time - Live Market Data

Function	Description	Key Features
`subscribe()`	Real-time subscriptions	Async iteration Topic failure isolation `status` / `events` / `stats` observability
`stream()`	Simplified streaming	Context manager Non-blocking updates
`vwap()`	Real-time VWAP	Streaming volume-weighted average price
`mktbar()`	Real-time market bars	Streaming OHLCV bars
`depth()`	Market depth	Streaming order book levels B-PIPE required
`chains()`	Option/futures chains	Real-time chain data B-PIPE required

Utilities

Function	Description	Key Features
`convert_ccy()`	Currency conversion	Multi-currency DataFrames Historical FX rates Automatic alignment
`fut_ticker()`	Futures contract resolution	Generic to specific mapping Date-aware selection
`active_futures()`	Active futures selection	Volume-based logic Roll date handling
`cdx_ticker()`	CDX index resolution	Series mapping Index family support
`active_cdx()`	Active CDX selection	On-the-run detection Lookback windows

Schema Introspection

Function	Description	Key Features
`bops()`	List service operations	Discover available request types
`bschema()`	Get operation schema	Field definitions, types, enums
`list_valid_elements()`	Valid request elements	Check parameter names before sending
`get_enum_values()`	Enum values for a field	Discover valid override values
`generate_stubs()`	IDE stub generation	Auto-complete for request parameters

Engine Lifecycle

Function	Description	Key Features
`configure()`	Engine and session setup	Server host/port, auth, options Replaces `connect()` / `disconnect()`
`shutdown()`	Stop engine and sessions	Graceful cleanup
`reset()`	Reset engine state	Clear sessions and caches
`is_connected()`	Check connection status	Boolean connectivity check

Request Middleware

Function	Description	Key Features
`add_middleware()`	Register request middleware	Enterprise audit logging, entitlement checks, metrics, tracing, policy enforcement, request labeling
`set_middleware()`	Replace middleware chain	Install a known platform pipeline in one call
`get_middleware()`	Inspect middleware chain	Useful in apps/tests before mutation or compliance checks
`remove_middleware()`	Unregister middleware	Clean removal for scoped tests or application shutdown
`clear_middleware()`	Clear middleware chain	Reset to a pristine request path
`RequestContext`	Request metadata	Request ID, request payload, timing, results, errors
`RequestEnvironment`	Engine/auth snapshot	Host, auth method, validation mode, server list, transport context

Additional Features

Timezone Support: Exchange-aware market hours for 50+ global exchanges; bdib() / bdtick() support request_tz and output_tz (interpretation and time-column relabeling in the Rust engine; Bloomberg wire format remains UTC)
Per-request field validation: validate_fields= can override engine-level validation on bdp() / bds() / bdh()
Scoped engines: Engine(...) lets you route a block of requests to a dedicated connection without mutating global state
Configurable Logging: Debug mode for troubleshooting
Batch Processing: Efficient multi-ticker queries
Explicit output contracts: Core metadata columns are stable; generic BDS preserves Bloomberg bulk subfield labels exactly
Non-live test helpers: xbbg.testing exposes mock_engine() and TestUtil-backed helpers for unit testing Bloomberg flows without a live terminal
Bloomberg ZFP over leased lines: blp.configure(zfp_remote='8194' | '8196', tls_client_credentials=..., tls_trust_material=...) uses Bloomberg's ZFP leased-line session setup directly. ZFP is a distinct enterprise transport mode from direct host/port/servers/SOCKS5 configuration.

Requirements

Bloomberg C++ SDK version 3.12.1 or higher:
- Visit Bloomberg API Library and download C++ Supported Release
- For local source builds in this repo, install it with bash ./scripts/sdktool.sh on macOS/Linux or .\scripts\sdktool.ps1 on Windows PowerShell
- If you manage the SDK yourself, set BLPAPI_ROOT to the extracted SDK root
Bloomberg official Python API:

pip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/

Python dependencies (core): narwhals>=2.0 plus the native xbbg._core extension. PyArrow is optional; when installed, it backs the default Narwhals DataFrame for legacy-compatible behavior.
Optional conversion backends (install separately if needed):
- pyarrow - For actual pyarrow.Table conversion (pip install xbbg[pyarrow] or pip install pyarrow)
- pandas - For pandas DataFrame conversion (pip install xbbg[pandas] or pip install pandas)
- polars - For Polars DataFrame / LazyFrame conversion (pip install xbbg[polars] or pip install polars)
- duckdb - For DuckDB relation conversion (pip install xbbg[duckdb] or pip install duckdb)
- Native Narwhals plugin - Included with xbbg as the minimal fallback when no PyArrow/pandas/Polars backend is installed; emits a one-time warning because it intentionally has a smaller dataframe surface

Installation

pip install xbbg

For most users, also install Bloomberg's official Python package so xbbg can auto-detect the SDK runtime:

pip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/

Supported Python versions: 3.10 – 3.14 (universal wheel).

Quick verification:

import xbbg

print(xbbg.__version__)
print(xbbg.get_sdk_info())

# Optional: if you manage the SDK yourself instead of using blpapi/DAPI
# xbbg.set_sdk_path('/path/to/blpapi_cpp')
# xbbg.clear_sdk_path()  # remove a manual override

MCP Server for Claude Code / OpenCode

Need xbbg inside a coding agent instead of Python code? Install the local MCP wrapper + binary from GitHub Releases:

curl -fsSL https://raw.githubusercontent.com/alpha-xone/xbbg/main/scripts/install-xbbg-mcp.sh | sh

The installer currently targets macOS arm64 and Linux amd64. Windows .zip assets are attached to GitHub releases for manual installation.

GitHub release assets include only the xbbg wrapper/binary pair. They do not bundle Bloomberg SDK files or the Bloomberg runtime; you must supply those locally via blpapi, BLPAPI_ROOT, or another supported runtime source.

Claude Code:

claude mcp add --transport stdio xbbg -- ~/.local/bin/xbbg-mcp

OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xbbg": {
      "type": "local",
      "command": ["/Users/you/.local/bin/xbbg-mcp"],
      "enabled": true
    }
  }
}

The launcher searches for the Bloomberg runtime via XBBG_MCP_LIB_DIR, BLPAPI_LIB_DIR, BLPAPI_ROOT, a vendored SDK under vendor/blpapi-sdk/, or the official blpapi Python package. See apps/xbbg-mcp/README.md for the full env surface.

Quickstart

Basic Usage

from xbbg import blp

# Get current stock prices
prices = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], 'PX_LAST')
print(prices)

Common Workflows

📊 Get Reference Data (Current Snapshot)

# Single ticker, multiple fields
info = blp.bdp('NVDA US Equity', ['Security_Name', 'GICS_Sector_Name', 'PX_LAST'])

# Multiple tickers, single field
prices = blp.bdp(['AAPL US Equity', 'MSFT US Equity', 'GOOGL US Equity'], 'PX_LAST')

# With overrides (e.g., VWAP for specific date)
vwap = blp.bdp('AAPL US Equity', 'Eqy_Weighted_Avg_Px', VWAP_Dt='20240115')

📈 Get Historical Data (Time Series)

# Simple historical query
hist = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31')

# Multiple fields
ohlc = blp.bdh('AAPL US Equity', ['open', 'high', 'low', 'close'], '2024-01-01', '2024-01-31')

# With dividend/split adjustments
adjusted = blp.bdh('AAPL US Equity', 'px_last', '2024-01-01', '2024-12-31', adjust='all')

# Weekly data with forward fill
weekly = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31', Per='W', Fill='P')

# Excel-style request aliases and presentation controls
weekly = blp.bdh(
    'SPX Index',
    'PX_LAST',
    '2024-01-01',
    '2024-12-31',
    Per='W',        # periodicitySelection='WEEKLY'
    Fill='P',       # nonTradingDayFillMethod='PREVIOUS_VALUE'
    Points=10,      # maxDataPoints=10
    Dts='Show',     # keep date column
    DtFmt='Both',   # add period labels alongside dates
    Sort='Reverse', # newest rows first
    Direction='V',  # vertical/long output shape
)

⏱️ Get Intraday Data (High Frequency)

# 5-minute bars
bars_5m = blp.bdib('SPY US Equity', dt='2024-01-15', interval=5)

# 1-minute bars (default)
bars_1m = blp.bdib('TSLA US Equity', dt='2024-01-15')

# Sub-minute bars (10-second intervals) - UNIQUE TO XBBG!
bars_10s = blp.bdib('AAPL US Equity', dt='2024-01-15', interval=10, intervalHasSeconds=True)

# Session filtering (e.g., first 30 minutes)
opening = blp.bdib('SPY US Equity', dt='2024-01-15', session='day_open_30')

# Get data in UTC instead of exchange local time
bars_utc = blp.bdib('SPY US Equity', dt='2024-01-15', tz='UTC')

🔍 Advanced Queries (BQL, Screening)

# Bloomberg Query Language
result = blp.bql("get(px_last) for('AAPL US Equity')")

# Equity screening
screen_results = blp.beqs(screen='MyScreen', asof='2024-01-01')

# ETF holdings
holdings = blp.etf_holdings('SPY US Equity')

# Search queries
bonds = blp.bsrch("FI:MYSEARCH")

# Dealer quotes with broker codes (BQR)
quotes = blp.bqr("XYZ 4.5 01/15/30@MSG1 Corp", date_offset="-2d")

🔧 Utilities (Futures, Currency, etc.)

# Resolve futures contract
contract = blp.fut_ticker('ES1 Index', '2024-01-15', freq='ME')  # → 'ESH24 Index'

# Get active futures
active = blp.active_futures('ESA Index', '2024-01-15')

# Currency conversion
hist_usd = blp.bdh('BMW GR Equity', 'PX_LAST', '2024-01-01', '2024-01-31')
hist_eur = blp.convert_ccy(hist_usd, ccy='EUR')

# Dividend history
divs = blp.dividend('AAPL US Equity', start_date='2024-01-01', end_date='2024-12-31')

Fixed Income Analytics (Bond, CDX)

from xbbg.ext import bond_info, bond_risk, bond_spreads, cdx_info, cdx_pricing

# Bond reference data
info = bond_info('T 4.5 05/15/38 Govt')

# Bond risk metrics (duration, convexity, DV01)
risk = bond_risk('T 4.5 05/15/38 Govt')

# Bond spreads (OAS, Z-spread, ASW)
spreads = bond_spreads('T 4.5 05/15/38 Govt')

# CDX index info
cdx = cdx_info('CDX IG CDSI GEN 5Y Corp')

# CDX pricing
px = cdx_pricing('CDX IG CDSI GEN 5Y Corp')

Options Analytics

from xbbg.ext import option_info, option_greeks, option_chain_bql

# Option contract metadata
info = option_info('AAPL US 01/17/25 C200 Equity')

# Greeks and implied volatility
greeks = option_greeks('AAPL US 01/17/25 C200 Equity')

# Option chain via BQL (rich filtering)
chain = option_chain_bql('AAPL US Equity', expiry='2025-01-17')

Best Practices

Excel users: Use the same field names and date formats as Bloomberg Excel
Performance: Rust-powered request execution and Arrow-native output reduce Python overhead for large Bloomberg responses
Async operations: Use abdp(), abdh(), abds() for non-blocking requests
Debugging: Set logging.getLogger('xbbg').setLevel(logging.DEBUG) for detailed logs

Connection Options

By default, xbbg connects to localhost on port 8194. To connect to a remote Bloomberg server or configure authentication, use configure():

from xbbg import blp

# Connect to a remote Bloomberg server
blp.configure(server_host='192.168.1.100', server_port=18194)

# With SAPI authentication
blp.configure(
    server_host='192.168.1.100',
    server_port=18194,
    auth_method='app',
    app_name='myapp:SAPI',
)

# All subsequent calls use the configured connection
blp.bdp(tickers='NVDA US Equity', flds=['Security_Name'])

You can also pass server and port as kwargs to individual function calls for ad-hoc connections.

Engine Architecture

xbbg v1 is powered by a Rust async engine with pre-warmed worker pools:

┌─────────────────────────────────────────────────┐
│                   xbbg Engine                   │
│                                                 │
│  ┌──────────────────────┐  ┌─────────────────┐  │
│  │  Request Worker Pool │  │ Subscription    │  │
│  │  (request_pool_size) │  │ Session Pool    │  │
│  │                      │  │ (sub_pool_size) │  │
│  │  Worker 1 ──session  │  │                 │  │
│  │  Worker 2 ──session  │  │  Session 1      │  │
│  │  ...                 │  │  ...            │  │
│  └──────────────────────┘  └─────────────────┘  │
│           │ round-robin          │ isolated      │
│           ▼                      ▼               │
│    bdp/bdh/bds/bdib       subscribe/stream       │
│    bql/bsrch/beqs         vwap/mktbar/depth      │
└─────────────────────────────────────────────────┘

Request workers each hold an independent Bloomberg session. Concurrent bdp/bdh/bds calls are dispatched round-robin across workers, so request_pool_size=4 allows 4 parallel Bloomberg requests.
Subscription sessions are isolated per session to avoid cross-contamination between topic streams. Each subscribe() call gets its own Bloomberg session from the pool.
Workers are pre-warmed at first use — sessions are started and services opened before your first request, eliminating cold-start latency.

EngineConfig Reference

Call configure() before any Bloomberg request to tune the engine. All fields have sensible defaults:

from xbbg import configure, EngineConfig

# Keyword arguments (most common)
configure(request_pool_size=4, subscription_pool_size=2)

# Or use an EngineConfig object
configure(EngineConfig(request_pool_size=4, subscription_pool_size=2))

Connection & Session

Parameter	Default	Description
`host`	`'localhost'`	Bloomberg server host. Aliases: `server_host`, `server`
`port`	`8194`	Bloomberg server port. Alias: `server_port`
`num_start_attempts`	`3`	Retries before giving up on session start. Alias: `max_attempt`
`auto_restart_on_disconnection`	`True`	Auto-reconnect on session disconnect. Alias: `auto_restart`

Worker Pools

Parameter	Default	Description
`request_pool_size`	`2`	Number of pre-warmed request workers (parallel Bloomberg sessions for bdp/bdh/bds/etc.)
`subscription_pool_size`	`1`	Number of pre-warmed subscription sessions (isolated sessions for subscribe/stream)
`warmup_services`	`['//blp/refdata', '//blp/apiflds']`	Services to pre-open on startup

Subscription Tuning

Parameter	Default	Description
`subscription_flush_threshold`	`1`	Ticks buffered before flushing to Python (increase for throughput, decrease for latency)
`subscription_stream_capacity`	`256`	Backpressure buffer size per subscription stream
`overflow_policy`	`'drop_newest'`	Slow consumer policy: `'drop_newest'` or `'block'`

Internal Buffers

Parameter	Default	Description
`max_event_queue_size`	`10000`	Bloomberg SDK event queue depth
`command_queue_size`	`256`	Internal command channel capacity

Validation

Parameter	Default	Description
`validation_mode`	`'disabled'`	Field validation: `'disabled'`, `'strict'` (reject unknown fields), or `'lenient'` (warn)
`field_cache_path`	`~/.xbbg/field_cache.json`	Path for persistent field type cache. Set to customize location

Authentication (SAPI / B-PIPE)

Parameter	Default	Description
`auth_method`	`None`	Auth mode: `'user'`, `'app'`, `'userapp'`, `'dir'`, `'manual'`, or `'token'`
`app_name`	`None`	Application name (required for `app`, `userapp`, `manual`)
`user_id`	`None`	Bloomberg user ID (required for `manual`)
`ip_address`	`None`	Bloomberg IP address (required for `manual`)
`dir_property`	`None`	Active Directory property (required for `dir`)
`token`	`None`	Auth token (required for `token`)

Auth mode examples:

# B-PIPE application auth
configure(auth_method='app', app_name='myapp:8888', host='bpipe-host')

# Manual auth (SAPI)
configure(auth_method='manual', app_name='myapp', user_id='12345', ip_address='10.0.0.1')

# Active Directory auth
configure(auth_method='dir', dir_property='mail')

Async Functions

Every sync function has an async counterpart prefixed with a — for example bdp() → abdp(), bdh() → abdh(), bdib() → abdib(). In the v1 architecture, async implementations are the canonical source of truth and sync functions delegate via _run_sync().

Common async families:

Sync	Async
`bdp`, `bds`, `bdh`, `bdib`, `bdtick`	`abdp`, `abds`, `abdh`, `abdib`, `abdtick`
`bql`, `bsrch`, `bqr`, `beqs`	`abql`, `absrch`, `abqr`, `abeqs`
`blkp`, `bport`, `bcurves`, `bgovts`	`ablkp`, `abport`, `abcurves`, `abgovts`
`subscribe`, `stream`, `vwap`, `mktbar`, `depth`, `chains`	`asubscribe`, `astream`, `avwap`, `amktbar`, `adepth`, `achains`
`bta`, `bflds`, `fieldInfo`, `fieldSearch`	`abta`, `abflds`, `afieldInfo`, `afieldSearch`

In scripts (no existing event loop)

import asyncio
from xbbg import blp

async def get_data():
    df = await blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])
    return df

async def get_multiple():
    # Concurrent requests — runs in parallel on a single thread
    results = await asyncio.gather(
        blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST']),
        blp.abdp(tickers='MSFT US Equity', flds=['PX_LAST']),
        blp.abdh(tickers='GOOGL US Equity', start_date='2024-01-01'),
    )
    return results

data = asyncio.run(get_data())
multiple = asyncio.run(get_multiple())

In Jupyter notebooks

Jupyter and VS Code Interactive already run an event loop. For one-shot request/response calls, you can keep using the familiar sync API:

from xbbg import blp

df = blp.bdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])
hist = blp.bdh(tickers='AAPL US Equity', flds='PX_LAST', start_date='2024-01-01')

bdp, bdh, bds, bdib, bdtick, and request use a notebook-only background event-loop bridge when IPykernel already has a loop running.

If your notebook cell is already async, use the async APIs directly:

from xbbg import blp

df = await blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])

Important: Generic async applications such as FastAPI or ASGI services should still use await blp.abdp(...) / await blp.abdh(...). The sync bridge is only for IPykernel notebook environments and does not apply to streaming or long-lived async APIs.

Benefits:

Non-blocking: async APIs don't block the event loop
Concurrent: use asyncio.gather() for parallel requests
Compatible: async APIs work with web frameworks; one-shot sync APIs work in notebooks
Same API: identical parameters between sync and async versions (bdp / abdp, bdh / abdh)

Multi-Backend Support

Starting with v1, xbbg defaults to a Narwhals DataFrame. When PyArrow is installed, that Narwhals frame is backed by a real pyarrow.Table, preserving the pre-native-backend behavior and full Narwhals expression support. Minimal installs fall back through installed dataframe libraries and finally xbbg's native Arrow carrier; that final native-plugin fallback emits a one-time RuntimeWarning because it intentionally does not implement the full PyArrow/Narwhals expression surface. Request backend="native" / Backend.NATIVE when you want the raw xbbg._core.ArrowTable; request backend="pyarrow" / Backend.PYARROW when you want PyArrow's full table API.

Conversion backends are explicit opt-ins. Install only the libraries you actually use.

Supported Backends

Backend	Type	Output	Best For
default / `narwhals`	Core wrapper	Narwhals DataFrame over PyArrow when installed, otherwise installed dataframe backends or `xbbg._core.ArrowTable` fallback	Backwards-compatible dataframe ergonomics without pandas/PyArrow as hard deps
`native`	Native eager	`xbbg._core.ArrowTable`	Zero-copy xbbg-native workflows, Arrow PyCapsule interop
`pyarrow`	Optional conversion	`pyarrow.Table`	Full PyArrow table functionality and Arrow ecosystem integrations
`pandas`	Optional conversion	`pd.DataFrame`	Traditional dataframe workflows, compatibility
`polars`	Optional conversion	`pl.DataFrame`	High-performance eager analytics
`polars_lazy`	Optional conversion	`pl.LazyFrame`	Deferred Polars execution
`duckdb`	Optional conversion	DuckDB relation	SQL analytics and OLAP queries
`narwhals_lazy`	Native plugin	Narwhals LazyFrame over xbbg Arrow objects	Library-agnostic lazy evaluation
`modin`, `cudf`, `dask`, `ibis`, `pyspark`, `sqlframe`	Optional Narwhals-backed conversions	Native objects for installed libraries	Specialized distributed/GPU/SQL workflows

Note: wide / Format.WIDE was removed in v1.0.0rc4. Use semi_long for one row per security, or pivot a long result explicitly in your downstream DataFrame library.

Check Backend Availability

from xbbg import get_available_backends, print_backend_status, is_backend_available

# Narwhals/default and native carrier are always available
print(is_backend_available("narwhals"))  # True
print(is_backend_available("native"))    # True

# Lists Backend.NARWHALS, Backend.NATIVE, plus installed optional conversion backends
print(get_available_backends())

# Check if a specific optional conversion backend is available
if is_backend_available("polars"):
    print("Polars is installed!")

# Print detailed status of all backends
print_backend_status()

Usage

from xbbg import blp, Backend

# Default Narwhals DataFrame; PyArrow-backed when PyArrow is installed
df = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")
print(df.columns, len(df))

# Explicit native carrier
table = blp.bdp("AAPL US Equity", "PX_LAST", backend="native")

# Optional conversions
table_pyarrow = blp.bdp("IBM US Equity", "PX_LAST", backend=Backend.PYARROW)
df_pandas = blp.bdp("MSFT US Equity", "PX_LAST", backend=Backend.PANDAS)
df_polars = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.POLARS)
duckdb_rel = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", backend=Backend.DUCKDB)
nw_df = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.NARWHALS)

Narwhals can also consume native xbbg Arrow objects directly through the included plugin:

import narwhals as nw
from xbbg import blp

table = blp.bdp("AAPL US Equity", "PX_LAST", backend="native")
nw_df = nw.from_native(table)

Output Formats

Control the shape of your data with the format parameter:

Format	Description	Use Case
`long`	Tidy format with ticker, field, value columns	Analysis, joins, aggregations
`long_typed`	Typed value columns per data type	Type-safe analysis, no casting needed
`long_metadata`	String values with dtype metadata column	Serialization, debugging, data catalogs
`semi_long`	One row per security/date, fields as columns	Quick inspection, Excel-style output, replacement for removed `wide`

from xbbg import blp

# Long format (tidy data, default)
df_long = blp.bdp(["AAPL US Equity", "MSFT US Equity"], ["PX_LAST", "VOLUME"], format="long")

# Semi-long format (one row per ticker, fields as columns)
df_semi = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", format="semi_long")

Global Configuration

Set defaults for your entire session:

from xbbg import set_backend, Backend
from xbbg import blp, get_backend

# Without configuration, calls use Backend.NARWHALS
print(get_backend())  # None means the default public backend is Backend.NARWHALS

# Set Polars as default backend
set_backend(Backend.POLARS)
print(get_backend())  # Backend.POLARS

# All subsequent calls use this default
df = blp.bdp("AAPL US Equity", "PX_LAST")  # Returns Polars DataFrame

Why native Arrow + optional conversions?

Default compatibility: the public default is a Narwhals DataFrame so existing dataframe-style code keeps len(df), df.columns, and explicit conversions
Explicit native carrier: backend="native" returns the raw xbbg ArrowTable
Explicit PyArrow: backend="pyarrow" returns a real pyarrow.Table when PyArrow is installed
Interoperability: Arrow PyCapsule methods let Arrow-aware libraries consume xbbg data while keeping PyArrow optional

Power User and Infrastructure APIs

The core blp.bdp() / blp.bdh() workflow covers most day-to-day usage, but the current package exposes several advanced surfaces that are easy to miss if you only skim the quickstart. This section summarizes the non-obvious parts of the public API so the README tracks the package more faithfully.

Generic Requests and Raw JSON

For uncommon Bloomberg operations, raw service access, or debugging request payloads, use the generic request layer:

Surface	Purpose	Notes
`request()` / `arequest()`	Low-level request entrypoint	Works with arbitrary Bloomberg services and operations
`Service` / `Operation`	Enum wrappers for service URIs and request types	Safer than hand-typed strings
`RequestParams`	Dataclass for validated request payloads	Useful in middleware or reusable request builders
`OutputMode`	Output transport (`ARROW` or `JSON`)	`JSON` is useful for debugging Bloomberg payloads
`ExtractorHint`	Override extraction strategy	Advanced escape hatch for bulk/custom responses

from xbbg import Operation, OutputMode, Service, request

# Generic refdata request
df = request(
    Service.REFDATA,
    Operation.REFERENCE_DATA,
    securities=['AAPL US Equity'],
    fields=['PX_LAST', 'VOLUME'],
)

# Raw JSON transport for debugging/custom parsing
raw = request(
    Service.REFDATA,
    Operation.REFERENCE_DATA,
    securities=['AAPL US Equity'],
    fields=['PX_LAST'],
    output=OutputMode.JSON,
)

Schema, Operations, and IDE Stubs

xbbg ships two schema surfaces:

blp.bops() / blp.bschema() for quick interactive discovery
xbbg.schema for typed schema objects and stub-generation utilities

Surface	Purpose
`bops()` / `abops()`	List operations available on a Bloomberg service
`bschema()` / `abschema()`	Return service/operation schema as plain dictionaries
`xbbg.schema.get_schema()` / `aget_schema()`	Return typed `ServiceSchema` objects
`xbbg.schema.get_operation()` / `aget_operation()`	Return typed `OperationSchema` objects backed by `ElementInfo` trees
`xbbg.schema.list_operations()` / `alist_operations()`	Enumerate operations for a service
`xbbg.schema.get_enum_values()` / `aget_enum_values()`	Discover valid enum values for an element
`xbbg.schema.list_valid_elements()` / `alist_valid_elements()`	Inspect valid request element names before sending
`generate_stubs()` / `configure_ide_stubs()`	Generate IDE-friendly stubs from cached Bloomberg schema
`generate_ta_stubs()`	Generate TA helper stubs for study-specific autocomplete

from xbbg import blp
from xbbg.schema import get_operation, list_operations

print(blp.bops())  # quick list for //blp/refdata
print(list_operations('//blp/instruments'))

hist_schema = get_operation('//blp/refdata', 'HistoricalDataRequest')
print(hist_schema.request.children[0].name)

Field Metadata, Cache, and Type Resolution

There are three related layers here:

bflds() / fieldInfo() / fieldSearch() for Bloomberg field catalog discovery
xbbg.field_cache for Arrow type resolution and cache management
field_types= request overrides for per-call control

Surface	Purpose
`bflds()` / `abflds()`	Unified field-info and field-search entrypoint
`bfld()` / `abfld()`	Alias for `bflds()`
`fieldInfo()` / `afieldInfo()`	Alias for `bflds(fields=...)`
`fieldSearch()` / `afieldSearch()`	Alias for `bflds(search_spec=...)`
`resolve_field_types()` / `aresolve_field_types()`	Resolve Bloomberg fields to Arrow types
`cache_field_types()`	Pre-warm the field cache
`get_field_info()`	Return structured `FieldInfo` objects
`get_field_cache_stats()`	Inspect cache path and entry count
`clear_field_cache()`	Clear in-memory and on-disk field cache
`FieldTypeCache`	Compatibility facade over the Rust resolver

from xbbg import blp
from xbbg.field_cache import (
    get_field_cache_stats,
    resolve_field_types,
)

catalog = blp.fieldSearch('vwap')
details = blp.fieldInfo(['PX_LAST', 'VOLUME'])
types = resolve_field_types(['PX_LAST', 'NAME', 'DVD_EX_DT'])
stats = get_field_cache_stats()

Important current behavior:

Field type resolution is Rust-backed and persistent
field_cache_path= can be set via configure(...) before the engine starts
long_typed and long_metadata formats are driven by these resolved field types

Market Metadata and Session Overrides

The xbbg.markets module exposes exchange/session helpers that complement request APIs:

Surface	Purpose
`ExchangeInfo`	Structured exchange metadata record returned by Bloomberg-backed helpers
`SessionWindows`	Dataclass representing derived market sessions (`day`, `pre`, `post`, etc.)
`market_info()`	Lightweight market metadata for a security
`market_timing()`	Session timing lookup for a ticker/session combination
`ccy_pair()`	FX conversion metadata for currency pair normalization
`exch_info()`	Exchange/session metadata lookup
`get_session_windows()` / `derive_sessions()`	Derive named session windows without a data request
`fetch_exchange_info()` / `afetch_exchange_info()`	Bloomberg-backed exchange metadata fetch
`set_exchange_override()` / `get_exchange_override()` / `clear_exchange_override()`	Runtime override lifecycle for timezone/session metadata
`list_exchange_overrides()` / `has_override()`	Inspect override state
`convert_session_times_to_utc()`	Convert local market sessions to UTC

from xbbg.markets import get_session_windows, market_info, set_exchange_override

print(market_info('ES1 Index'))
print(get_session_windows('AAPL US Equity', mic='XNAS', regular_hours=('09:30', '16:00')))

set_exchange_override(
    'MY_PRIVATE_TICKER Equity',
    timezone='America/New_York',
    sessions={'regular': ('09:30', '16:00')},
)

SDK Detection, Logging, and Diagnostics

Beyond configure(), the package exposes helpers for SDK discovery, backend validation, and engine diagnostics:

Surface	Purpose
`get_sdk_info()`	Show detected Bloomberg SDK sources and active runtime
`set_sdk_path()` / `clear_sdk_path()`	Manually override SDK discovery
`set_log_level()` / `get_log_level()`	Control Rust-side logging verbosity
`enable_sdk_logging()`	Surface underlying Bloomberg SDK logs
`get_available_backends()` / `is_backend_available()`	Inspect installed dataframe backends
`check_backend()`	Validate backend availability/version and get install guidance
`get_supported_formats()` / `is_format_supported()`	Inspect backend/format compatibility
`check_format_compatibility()` / `validate_backend_format()`	Guard backend + format combinations programmatically

from xbbg import Backend, check_backend, get_sdk_info, print_backend_status, validate_backend_format

print(get_sdk_info())
check_backend('polars')
validate_backend_format(Backend.PANDAS, 'semi_long')
print_backend_status()

Testing Utilities

xbbg.testing is part of the supported public surface for non-live tests:

Helper	Purpose
`MockResponse`	Structured canned-response container used by `mock_engine()`
`create_mock_response()`	Build canned request responses without a live terminal
`mock_engine()`	Context manager that intercepts xbbg calls and returns canned responses
`create_mock_event()`	Build Bloomberg `blpapi.test` events when `blpapi` is installed
`get_admin_message_definition()`	Fetch TestUtil admin-message definitions for mocked admin events
`deserialize_service()`	Deserialize service XML for TestUtil-backed mocks
`append_message_dict()`	Populate mock Bloomberg messages from Python dictionaries

from xbbg import blp
from xbbg.testing import create_mock_response, mock_engine

response = create_mock_response(
    service='//blp/refdata',
    operation='ReferenceDataRequest',
    data={'AAPL US Equity': {'PX_LAST': 210.5}},
)

with mock_engine([response]):
    df = blp.bdp('AAPL US Equity', 'PX_LAST')

Exception Types

The current exception surface is intentionally typed and worth calling out in the README because many workflows want to catch Bloomberg failures explicitly:

Exception	Typical use
`BlpError`	Base class for Bloomberg-related failures
`BlpSessionError`	Session startup/connectivity/auth failures
`BlpRequestError`	Request-level failure with service/operation context
`BlpSecurityError`	Security-specific request failure
`BlpFieldError`	Field-specific request failure
`BlpValidationError`	Invalid request shape, bad elements, bad enum values
`BlpTimeoutError`	Request timed out
`BlpInternalError`	Internal engine/runtime failure
`BlpBPipeError`	B-PIPE-only feature used without B-PIPE access (`depth`, `chains`)

from xbbg import blp
from xbbg.exceptions import BlpBPipeError, BlpValidationError

try:
    blp.depth('AAPL US Equity')
except BlpBPipeError:
    ...
except BlpValidationError as exc:
    print(exc.element, exc.suggestion)

Examples

📊 Reference Data

Equity and Index Securities

from xbbg import blp

# Single point-in-time data (BDP)
blp.bdp(tickers='NVDA US Equity', flds=['Security_Name', 'GICS_Sector_Name'])

Out[2]:
               security_name        gics_sector_name
NVDA US Equity   NVIDIA Corp  Information Technology

# With field overrides
blp.bdp('AAPL US Equity', 'Eqy_Weighted_Avg_Px', VWAP_Dt='20181224')

Out[3]:
                eqy_weighted_avg_px
AAPL US Equity               148.75

# Multiple tickers and fields
blp.bdp(
    tickers=['AAPL US Equity', 'MSFT US Equity', 'GOOGL US Equity'],
    flds=['Security_Name', 'GICS_Sector_Name', 'PX_LAST']
)

Out[3a]:
                  security_name        gics_sector_name px_last
AAPL US Equity        Company A  Information Technology  150.25
GOOGL US Equity    Company B  Communication Services  165.30
MSFT US Equity   Company C  Information Technology  180.45

# Bulk/block data (BDS) - multi-row per ticker
blp.bds('AAPL US Equity', 'DVD_Hist_All', DVD_Start_Dt='20180101', DVD_End_Dt='20180531')

bds() and abds() preserve Bloomberg bulk subfield labels exactly as emitted. The only xbbg-added columns are ticker and field; field-specific columns may contain spaces, punctuation, and Bloomberg casing such as Future's Ticker or Last Trade Date. Normalize or rename these columns in your own code when you need a stable application schema.

Fixed Income Securities

xbbg supports fixed income securities using standard security identifiers (ISIN, CUSIP, SEDOL). Use the /isin/{isin}, /cusip/{cusip}, or /sedol/{sedol} format as the ticker:

# Reference data using ISIN
blp.bdp(tickers='/isin/US1234567890', flds=['SECURITY_NAME', 'MATURITY', 'COUPON', 'PX_LAST'])

Out[9]:
                       security_name    maturity coupon    px_last
/isin/US1234567890  US Treasury Note  2035-05-15   4.25  101.25

# Cash flow schedule using ISIN
blp.bds(tickers='/isin/US1234567890', flds='DES_CASH_FLOW')

The cash-flow output follows the same BDS contract: ticker and field are xbbg metadata columns, and Bloomberg cash-flow subfield labels are preserved verbatim.

Note: Fixed income securities work with bdp(), bds(), and bdh() functions. The identifier format (/isin/, /cusip/, /sedol/) is automatically passed to blpapi.

Yield & Spread Analysis (YAS)

The yas() function provides a convenient wrapper for Bloomberg's YAS calculator:

from xbbg import blp
from xbbg.api.fixed_income import YieldType

# Get yield to maturity
blp.yas('T 4.5 05/15/38 Govt')

Out[11]:
                     YAS_BOND_YLD
ticker
T 4.5 05/15/38 Govt         4.348

# Calculate yield from price
blp.yas('T 4.5 05/15/38 Govt', price=95.0)

Out[12]:
                     YAS_BOND_YLD
ticker
T 4.5 05/15/38 Govt          5.05

# Calculate price from yield
blp.yas('T 4.5 05/15/38 Govt', flds='YAS_BOND_PX', yield_=4.8)

Out[13]:
                     YAS_BOND_PX
ticker
T 4.5 05/15/38 Govt    97.229553

# Yield to call for callable bonds
blp.yas('AAPL 2.65 05/11/50 Corp', yield_type=YieldType.YTC)

Out[14]:
                          YAS_BOND_YLD
ticker
AAPL 2.65 05/11/50 Corp          5.431

# Multiple YAS analytics
blp.yas('T 4.5 05/15/38 Govt', ['YAS_BOND_YLD', 'YAS_MOD_DUR', 'YAS_ASW_SPREAD'])

Out[15]:
                     YAS_ASW_SPREAD  YAS_BOND_YLD  YAS_MOD_DUR
ticker
T 4.5 05/15/38 Govt       33.093531         4.348     9.324928

Available parameters:

settle_dt: Settlement date (YYYYMMDD or datetime)
yield_type: YieldType.YTM (default) or YieldType.YTC
price: Input price to calculate yield
yield_: Input yield to calculate price
spread: Spread to benchmark in basis points
benchmark: Benchmark bond ticker for spread calculations

Field Information and Search

# Unified field lookup (recommended)
blp.bflds(fields=['PX_LAST', 'VOLUME'])  # Get metadata for specific fields
blp.bflds(search_spec='vwap')            # Search for fields by keyword

# Convenience aliases
blp.fieldInfo(['PX_LAST', 'VOLUME'])     # Same as bflds(fields=...)
blp.fieldSearch('vwap')                  # Same as bflds(search_spec=...)

Security Lookup

# Look up securities by company name
blp.blkp('IBM', max_results=10)

# Lookup with asset class filter
blp.blkp('Apple', yellowkey='eqty', max_results=20)

Portfolio Data

# Get portfolio data (dedicated function)
blp.bport('PORTFOLIO_NAME', 'PORTFOLIO_MWEIGHT')

📈 Historical Data

# End-of-day historical data (BDH)
blp.bdh(
    tickers='SPX Index', flds=['high', 'low', 'last_price'],
    start_date='2018-10-10', end_date='2018-10-20',
)

Out[4]:
           SPX Index
                high      low last_price
2018-10-10  2,874.02 2,784.86   2,785.68
2018-10-11  2,795.14 2,710.51   2,728.37
2018-10-12  2,775.77 2,729.44   2,767.13
2018-10-15  2,775.99 2,749.03   2,750.79
2018-10-16  2,813.46 2,766.91   2,809.92
2018-10-17  2,816.94 2,781.81   2,809.21
2018-10-18  2,806.04 2,755.18   2,768.78
2018-10-19  2,797.77 2,760.27   2,767.78

# Multiple tickers and fields
blp.bdh(
    tickers=['AAPL US Equity', 'MSFT US Equity'],
    flds=['px_last', 'volume'],
    start_date='2024-01-01', end_date='2024-01-10',
)

Out[4a]:
           AAPL US Equity             MSFT US Equity            
                  px_last      volume        px_last      volume
2024-01-02         150.25  45000000.0         180.45  25000000.0
2024-01-03         151.30  42000000.0         181.20  23000000.0
2024-01-04         149.80  48000000.0         179.90  24000000.0
2024-01-05         150.10  44000000.0         180.15  22000000.0
2024-01-08         151.50  46000000.0         181.80  26000000.0

# Excel-compatible inputs with periodicity
blp.bdh(
    tickers='SHCOMP Index', flds=['high', 'low', 'last_price'],
    start_date='2018-09-26', end_date='2018-10-20',
    Per='W', Fill='P', Days='A',
)

Out[5]:
           SHCOMP Index
                   high      low last_price
2018-09-28     2,827.34 2,771.16   2,821.35
2018-10-05     2,827.34 2,771.16   2,821.35
2018-10-12     2,771.94 2,536.66   2,606.91
2018-10-19     2,611.97 2,449.20   2,550.47

# Dividend/split adjustments
blp.bdh('AAPL US Equity', 'px_last', '20140606', '20140609', adjust='all')

Out[15]:
           AAPL US Equity
                  px_last
2014-06-06          85.22
2014-06-09          86.58

# Dividend history
blp.dividend(['C US Equity', 'MS US Equity'], start_date='2018-01-01', end_date='2018-05-01')

Out[13]:
                dec_date     ex_date    rec_date    pay_date  dvd_amt dvd_freq      dvd_type
C US Equity   2018-01-18  2018-02-02  2018-02-05  2018-02-23     0.32  Quarter  Regular Cash
MS US Equity  2018-04-18  2018-04-27  2018-04-30  2018-05-15     0.25  Quarter  Regular Cash
MS US Equity  2018-01-18  2018-01-30  2018-01-31  2018-02-15     0.25  Quarter  Regular Cash

# Earnings breakdowns
blp.earnings('AMD US Equity', by='Geo', Eqy_Fund_Year=2017, Number_Of_Periods=1)

Out[12]:
                 level    fy2017  fy2017_pct
Asia-Pacific      1.00  3,540.00       66.43
    China         2.00  1,747.00       49.35
    Japan         2.00  1,242.00       35.08
    Singapore     2.00    551.00       15.56
United States     1.00  1,364.00       25.60
Europe            1.00    263.00        4.94
Other Countries   1.00    162.00        3.04

⏱️ Intraday Data

# Intraday bars (1-minute default)
blp.bdib(ticker='BHP AU Equity', dt='2018-10-17').tail()

Out[9]:
                          BHP AU Equity
                                   open  high   low close   volume num_trds
2018-10-17 15:56:00+11:00         33.62 33.65 33.62 33.64    16660      126
2018-10-17 15:57:00+11:00         33.65 33.65 33.63 33.64    13875      156
2018-10-17 15:58:00+11:00         33.64 33.65 33.62 33.63    16244      159
2018-10-17 15:59:00+11:00         33.63 33.63 33.61 33.62    16507      167
2018-10-17 16:10:00+11:00         33.66 33.66 33.66 33.66  1115523      216

Selecting bar intervals:

Minute-based intervals (default): Use the interval parameter to specify minutes. By default, interval=1 (1-minute bars). Common intervals:
- interval=5 → 5-minute bars
- interval=15 → 15-minute bars
- interval=30 → 30-minute bars
- interval=60 → 1-hour bars

# 5-minute bars
blp.bdib(ticker='AAPL US Equity', dt='2025-11-12', interval=5).head()

# 15-minute bars
blp.bdib(ticker='AAPL US Equity', dt='2025-11-12', interval=15).head()

Sub-minute intervals (seconds): Set intervalHasSeconds=True and specify seconds:

# 10-second bars
blp.bdib(ticker='AAPL US Equity', dt='2025-11-12', interval=10, intervalHasSeconds=True).head()

Out[9a]:
                          AAPL US Equity
                                   open    high     low   close volume num_trds
2025-11-12 09:31:00-05:00        150.25  150.35  150.20  150.30  25000      150
2025-11-12 09:31:10-05:00        150.30  150.40  150.25  150.35  18000      120
2025-11-12 09:31:20-05:00        150.35  150.45  150.30  150.40  22000      135

Note: By default, interval is interpreted as minutes. Set intervalHasSeconds=True to use seconds-based intervals.

# Market session filtering
blp.bdib(ticker='7974 JT Equity', dt='2018-10-17', session='am_open_30').tail()

Out[11]:
                          7974 JT Equity
                                    open      high       low     close volume num_trds
2018-10-17 09:27:00+09:00      39,970.00 40,020.00 39,970.00 39,990.00  10800       44
2018-10-17 09:28:00+09:00      39,990.00 40,020.00 39,980.00 39,980.00   6300       33
2018-10-17 09:29:00+09:00      39,970.00 40,000.00 39,960.00 39,970.00   3300       21
2018-10-17 09:30:00+09:00      39,960.00 40,010.00 39,950.00 40,000.00   3100       19
2018-10-17 09:31:00+09:00      39,990.00 40,000.00 39,980.00 39,990.00   2000       15

How the `session` parameter works

The session parameter is resolved by xbbg.core.config.intervals.get_interval() and xbbg.core.process.time_range() using exchange metadata from xbbg/markets/config/exch.yml:

Base sessions (no underscores) map directly to session windows defined for the ticker's exchange in exch.yml:
- allday - Full trading day including pre/post market (e.g., [400, 2000] for US equities)
- day - Regular trading hours (e.g., [0930, 1600] for US equities)
- am - Morning session (e.g., [901, 1130] for Japanese equities)
- pm - Afternoon session (e.g., [1230, 1458] for Japanese equities)
- pre - Pre-market session (e.g., [400, 0930] for US equities)
- post - Post-market session (e.g., [1601, 2000] for US equities)
- night - Night trading session (e.g., [1710, 700] for Australian futures)
Not all exchanges define all sessions. For example, GBP Curncy uses CurrencyGeneric which defines allday and day only.
Compound sessions (with underscores) allow finer control by combining a base session with modifiers (open, close, normal, exact):
- Open windows (first N minutes of a session):
  - day_open_30 → first 30 minutes of the day session
  - am_open_30 → first 30 minutes of the am session
  - Note: open is not a base session; use day_open_30, not open_30
- Close windows (last N minutes of a session):
  - day_close_20 → last 20 minutes of the day session
  - am_close_30 → last 30 minutes of the am session
  - Note: close is not a base session; use day_close_20, not close_20
- Normal windows (skip open/close buffers):
  - day_normal_30_20 → skips first 30 min and last 20 min of day
  - am_normal_30_30 → skips first 30 min and last 30 min of am
- Exact clock times (exchange-local HHMM format):
  - day_exact_2130_2230 → [21:30, 22:30] local time (marker session)
  - allday_exact_2130_2230 → [21:30, 22:30] local time (actual window)
  - allday_exact_2130_0230 → [21:30, 02:30 next day] local time
Resolution order and fallbacks:
- blp.bdib / blp.bdtick call time_range(), which:
  1. Uses exch.yml + get_interval() and const.exch_info() to resolve local session times and exchange timezone.
  2. Converts that window to UTC and then to your requested tz argument (e.g., 'UTC', 'NY', 'Europe/London').
  3. If exchange metadata is missing for session and the asset, it may fall back to pandas‑market‑calendars (PMC) for simple sessions ('day' / 'allday'), based on the exchange code.
Errors and diagnostics:
- If a session name is not defined for the ticker's exchange, get_interval() raises a ValueError listing the available sessions for that exchange and points to xbbg/markets/exch.yml.
- For compound sessions whose base session doesn't exist (e.g. mis-typed am_open_30 for an exchange that has no am section), get_interval() returns SessNA and time_range() will then try the PMC fallback or ultimately raise a clear ValueError.

In practice:

Use simple names like session='day' or session='allday' when you just want the main trading hours.
Use compound names like session='day_open_30' or session='am_normal_30_30' when you need to focus on opening/closing auctions or to exclude "micro" windows (e.g. the first X minutes).
If you add or customize sessions, update exch.yml and rely on get_interval() to pick them up automatically.

# Using reference exchange for market hours
blp.bdib(ticker='ESM0 Index', dt='2020-03-20', ref='ES1 Index').tail()

out[10]:
                          ESM0 Index
                                open     high      low    close volume num_trds        value
2020-03-20 16:55:00-04:00   2,260.75 2,262.25 2,260.50 2,262.00    412      157   931,767.00
2020-03-20 16:56:00-04:00   2,262.25 2,267.00 2,261.50 2,266.75    812      209 1,838,823.50
2020-03-20 16:57:00-04:00   2,266.75 2,270.00 2,264.50 2,269.00   1136      340 2,576,590.25
2020-03-20 16:58:00-04:00   2,269.25 2,269.50 2,261.25 2,265.75   1077      408 2,439,276.00
2020-03-20 16:59:00-04:00   2,265.25 2,272.00 2,265.00 2,266.50   1271      378 2,882,978.25

# Tick-by-tick data with event types and condition codes
blp.bdtick(ticker='XYZ US Equity', dt='2024-10-15', session='day', types=['TRADE']).head()

Out[12]:
                          XYZ US Equity
                                   volume    typ   cond exch            trd_time
2024-10-15 09:30:15-04:00           1500  TRADE     @  NYSE  2024-10-15 09:30:15
2024-10-15 09:30:23-04:00            800  TRADE     @  NYSE  2024-10-15 09:30:23
2024-10-15 09:30:31-04:00           2200  TRADE     @  NYSE  2024-10-15 09:30:31

# Tick data with timeout (useful for large requests)
blp.bdtick(ticker='XYZ US Equity', dt='2024-10-15', session='day', timeout=1000)

Note: bdtick requests can take longer to respond. Use timeout parameter (in milliseconds) if you encounter empty DataFrames due to timeout.

Timezone handling (`bdib` / `bdtick`)

Bloomberg intraday APIs use UTC on the wire. The Rust engine accepts two optional knobs:

request_tz: How naive start_datetime / end_datetime (and the implicit full-day window when using dt=) are interpreted before the request. Omit or use UTC to keep the previous behavior (naive times treated as UTC wall times, matching older examples that use e.g. 14:30 for US cash open).
output_tz: Relabel the Arrow/Pandas time column to an IANA zone (same instants; only the timestamp type metadata changes). Omit or UTC leaves UTC.

Supported labels (case-insensitive where noted): UTC, local (machine IANA zone), exchange (resolve via the request’s security and cached/Bloomberg metadata), short aliases NY, LN, TK, HK, a reference ticker string containing a space (same as exch_info), or any IANA name (e.g. Europe/Zurich).

# Naive times in America/New_York → converted to UTC in the engine before the API call
bars = await blp.abdib(
    "SPY US Equity",
    start_datetime="2024-01-15 09:30",
    end_datetime="2024-01-15 16:00",
    interval=5,
    request_tz="America/New_York",
)

# Present tick times in the listing’s exchange zone (resolved in Rust)
ticks = await blp.abdtick(
    "SPY US Equity",
    "2024-01-15 09:30",
    "2024-01-15 10:00",
    request_tz="exchange",
    output_tz="exchange",
)

# Native datetime objects are accepted everywhere a date or datetime is taken.
# Tz-aware values preserve their tz; tz-naive values use request_tz.
from datetime import datetime
from zoneinfo import ZoneInfo

bars = await blp.abdib(
    "SPY US Equity",
    start_datetime=datetime(2024, 1, 15, 9, 30, tzinfo=ZoneInfo("America/New_York")),
    end_datetime=datetime(2024, 1, 15, 16, 0, tzinfo=ZoneInfo("America/New_York")),
    interval=5,
)

See the Dates and Datetimes guide for the full accepted set across bdh / bdib / bdtick / overrides and the JS / Node bindings.

# Trading volume & turnover (currency-adjusted, in millions)
blp.turnover(['ABC US Equity', 'DEF US Equity'], start_date='2024-01-01', end_date='2024-01-10', ccy='USD')

Out[13]:
            ABC US Equity  DEF US Equity
2024-01-02        15,304        8,920
2024-01-03        18,450       12,340
2024-01-04        14,890        9,560
2024-01-05        16,720       11,230
2024-01-08        10,905        7,890

# Currency conversion for historical data
hist = blp.bdh(['GHI US Equity'], ['px_last'], '2024-01-01', '2024-01-10')
blp.convert_ccy(hist, ccy='EUR')

Out[14]:
            GHI US Equity
2024-01-02        169.66
2024-01-03        171.23
2024-01-04        170.45
2024-01-05        172.10
2024-01-08        169.46

🔍 Screening & Queries

# Bloomberg Query Language (BQL)
# IMPORTANT: The 'for' clause must be OUTSIDE get(), not inside
# Correct: get(px_last) for('AAPL US Equity')
# Incorrect: get(px_last for('AAPL US Equity'))
# blp.bql("get(px_last) for('AAPL US Equity')")  # doctest: +SKIP

# BQL Options query example - sum open interest
# blp.bql("get(sum(group(open_int))) for(filter(options('SPX Index'), expire_dt=='2025-11-21'))")  # doctest: +SKIP

# BQL Options metadata - get available expiries
# blp.bql("get(expire_dt) for(options('INDEX Ticker'))")  # doctest: +SKIP

# BQL Options metadata - get option tickers for an underlying
# blp.bql("get(id) for(options('INDEX Ticker'))")  # doctest: +SKIP

# BQL Options metadata - get option chain (expiry, strike, put/call)
# blp.bql("get(id, expire_dt, strike_px, PUT_CALL) for(filter(options('INDEX Ticker'), expire_dt=='YYYY-MM-DD'))")  # doctest: +SKIP

# ETF Holdings (BQL)
# blp.etf_holdings('SPY US Equity')  # doctest: +SKIP
# Returns:
#               holding       id_isin SOURCE POSITION_TYPE  weights  position
# 0     MSFT US Equity  US5949181045    ETF             L   0.0725   123456.0
# 1     AAPL US Equity  US0378331005    ETF             L   0.0685   112233.0
# 2     NVDA US Equity  US67066G1040    ETF             L   0.0450    88776.0

# Bloomberg Equity Screening (BEQS)
# blp.beqs(screen='MyScreen', asof='2023-01-01')  # doctest: +SKIP

# SRCH (Search) - Fixed Income example
# blp.bsrch("FI:YOURSRCH")  # doctest: +SKIP

Out[16]:
              id
0  !!ABC123 Mtge
1  !!DEF456 Mtge
2  !!GHI789 Mtge
3  !!JKL012 Mtge
4  !!MNO345 Mtge

# SRCH - Weather data with parameters
blp.bsrch(  # doctest: +SKIP
    "comdty:weather",
    overrides={
        "provider": "wsi",
        "location": "US_XX",
        "model": "ACTUALS",
        "frequency": "DAILY",
        "target_start_date": "2021-01-01",
        "target_end_date": "2021-01-05",
        "location_time": "false",
        "fields": "WIND_SPEED|TEMPERATURE|HDD_65F|CDD_65F|HDD_18C|CDD_18C|PRECIPITATION_24HR|CLOUD_COVER|FEELS_LIKE_TEMPERATURE|MSL_PRESSURE|TEMPERATURE_MAX_24HR|TEMPERATURE_MIN_24HR"
    }
)

Out[17]:
              Reported Time  Wind Speed (m/s)  Temperature (°C)  Heating Degree Days (°F)  Cooling Degree Days (°F)
0 2021-01-01 06:00:00+00:00              3.45              -2.15                   38.25                     0.0
1 2021-01-02 06:00:00+00:00              2.10              -1.85                   36.50                     0.0
2 2021-01-03 06:00:00+00:00              1.95              -2.30                   37.80                     0.0
3 2021-01-04 06:00:00+00:00              2.40              -2.65                   38.10                     0.0
4 2021-01-05 06:00:00+00:00              2.15              -1.20                   35.75                     0.0

Note: The bsrch() function uses the blpapi Excel service (//blp/exrsvc) and supports user-defined SRCH screens, commodity screens, and blpapi example screens. For weather data and other specialized searches, use the overrides parameter to pass search-specific parameters.

# Bloomberg Quote Request (BQR) - Dealer quotes with broker codes
# Emulates Excel =BQR() function for fixed income dealer quotes

# Get fixed-income dealer quotes from last 2 days; BQR requests broker codes by default
# blp.bqr('XYZ 4.5 01/15/30@MSG1 Corp', date_offset='-2d')  # doctest: +SKIP

# Using ISIN with MSG1 pricing source (recommended for dealer attribution)
# blp.bqr('/isin/US123456789@MSG1 Corp', date_offset='-2d')  # doctest: +SKIP

# With spread data
# blp.bqr(  # doctest: +SKIP
#     'XYZ 4.5 01/15/30@MSG1 Corp',
#     date_offset='-2d',
#     include_spread_price=True,
# )

# With explicit date range
# blp.bqr('XYZ 4.5 01/15/30@MSG1 Corp', start_date='2024-01-15', end_date='2024-01-17')  # doctest: +SKIP

# Get only trade events
# blp.bqr('XYZ 4.5 01/15/30@MSG1 Corp', date_offset='-1d', event_types=['TRADE'])  # doctest: +SKIP

```pydocstring
Out[18]:
                              ticker                 time event_type   price      size spread_price broker_buy broker_sell
0  XYZ 4.5 01/15/30@MSG1 Corp  2024-01-15 10:30:00        BID   98.75  10000000         29.0       DLRA         NaN
1  XYZ 4.5 01/15/30@MSG1 Corp  2024-01-15 10:30:05        ASK   99.00   5000000         24.1        NaN        DLRB
2  XYZ 4.5 01/15/30@MSG1 Corp  2024-01-15 11:45:00      TRADE   98.85   2500000          NaN       DLRC        DLRC

Note: The bqr() function emulates Bloomberg Excel's =BQR() formula for fixed-income dealer quotes. It requests broker attribution by default and returns 0.x-compatible BQR columns such as event_type, price, broker_buy, and broker_sell. Prefer an ISIN input with @MSG1 Corp, e.g. /isin/US037833FB15@MSG1 Corp, for broker-level attribution. bqr() warns when an attributed request does not use that shape; if Bloomberg still returns quote rows without broker codes, bqr() raises instead of silently returning unattributed ticks. Pass include_broker_codes=False only when raw quote ticks without dealer attribution are intentional. Optional parameters include include_spread_price, include_yield, include_condition_codes, and include_exchange_codes.

📡 Real-time

# Real-time market data streaming (async)
# async for tick in blp.astream(['AAPL US Equity'], ['LAST_PRICE']):  # doctest: +SKIP
#     print(tick)  # doctest: +SKIP

# Subscriptions with failure isolation and health metadata
# sub = await blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE'])  # doctest: +SKIP
# async for update in sub:  # doctest: +SKIP
#     print(update)  # doctest: +SKIP

# Full Bloomberg payload (e.g. INITPAINT summary fields beyond your request list):
# sub = await blp.asubscribe(['XBTUSD Curncy'], ['LAST_PRICE', 'BID', 'ASK'], all_fields=True)  # doctest: +SKIP

# Real-time VWAP streaming
# async for bar in blp.avwap(['AAPL US Equity']):  # doctest: +SKIP
#     print(bar)  # doctest: +SKIP

🔧 Utilities

# Futures ticker resolution (generic to specific contract)
blp.fut_ticker('ES1 Index', '2024-01-15', freq='ME')

Out[15]:
'ESH24 Index'

# Active futures contract selection (volume-based)
blp.active_futures('ESA Index', '2024-01-15')

Out[16]:
'ESH24 Index'

# CDX index ticker resolution (series mapping)
blp.cdx_ticker('CDX IG CDSI GEN 5Y Corp', '2024-01-15')

Out[17]:
'CDX IG CDSI S45 5Y Corp'

# Active CDX contract selection
blp.active_cdx('CDX IG CDSI GEN 5Y Corp', '2024-01-15', lookback_days=10)

Out[18]:
'CDX IG CDSI S45 5Y Corp'

🔧 Troubleshooting

❌ Empty DataFrame Returned

Possible causes:

✅ Bloomberg Terminal not running → Start Bloomberg Terminal
✅ Wrong ticker format → Use 'AAPL US Equity' not 'AAPL'
✅ Data not available for date/time → Check Bloomberg Terminal
✅ Timeout too short → Increase: blp.bdtick(..., timeout=1000)

Quick fix:

# Verify ticker exists
blp.blkp('Apple', yellowkey='eqty')

# Check field availability
blp.fieldSearch('price')

🔌 Connection Errors

Checklist:

✅ Bloomberg Terminal is running and logged in
✅ Default connection is localhost:8194
✅ For remote: blp.bdp(..., server='192.168.1.100', port=18194)
✅ Bloomberg API (blpapi) is installed

Test connection:

from xbbg import blp
blp.bdp('AAPL US Equity', 'PX_LAST')  # Should return data

⏱️ Timeout Errors

Solutions:

# Increase timeout (milliseconds)
blp.bdtick('AAPL US Equity', dt='2024-01-15', timeout=5000)

# Break large requests into chunks
dates = pd.date_range('2024-01-01', '2024-12-31', freq='MS')
chunks = [blp.bdh('SPX Index', 'PX_LAST', start, end) for start, end in zip(dates[:-1], dates[1:])]
result = pd.concat(chunks)

🔍 Field Not Found

Find the right field:

# Search for fields
blp.fieldSearch('vwap')  # Find VWAP-related fields

# Get field info
blp.fieldInfo(['PX_LAST', 'VOLUME'])  # See data types & descriptions

# Check in Bloomberg Terminal
# Type FLDS<GO> to browse all fields

🐛 Still Stuck?

Get help fast:

💬 Discord: Join our community - Usually get answers within hours
🐛 GitHub Issues: Report bugs - Include error messages & code
📚 Documentation: Docs - Comprehensive guides
📓 Examples: xbbg_jupyter_examples.ipynb - 100+ working examples

When reporting issues, include:

xbbg version: import xbbg; print(xbbg.__version__)
Python version: python --version
Error message (full traceback)
Minimal code to reproduce

Development

Setup

Set up the development environment with pixi:

# Install the Bloomberg SDK into vendor/blpapi-sdk/ and let xbbg discover it
bash ./scripts/sdktool.sh               # macOS/Linux
# .\scripts\sdktool.ps1                # Windows PowerShell

# Install environment and compile the Rust extension
pixi install
pixi run install

If you already manage the SDK yourself, you can still set BLPAPI_ROOT manually.

Running Tests and Linting

pixi run test                  # run tests
pixi run lint                  # lint Python + Rust
pixi run ci                    # full sweep: fmt-check + lint + typecheck + test

For non-live application tests, xbbg.testing can mock Bloomberg-style responses:

from xbbg import blp
from xbbg.testing import create_mock_response, mock_engine

response = create_mock_response(
    service="//blp/refdata",
    operation="ReferenceDataRequest",
    data={"AAPL US Equity": {"PX_LAST": 254.23}},
)

with mock_engine([response]):
    df = blp.bdp("AAPL US Equity", "PX_LAST")

Building

pixi run build

Publishing is handled via GitHub Actions using PyPI Trusted Publishing (OIDC).

Documentation

The docs site uses Astro:

pixi run -e docs docs-install  # install npm deps
pixi run -e docs docs-dev      # local dev server
pixi run -e docs docs-build    # production build

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

Setting up your development environment
Code style and standards
Testing requirements
Pull request process
Community guidelines

Quick start for contributors:

# Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/xbbg.git
cd xbbg

# Set up development environment
pixi install && pixi run install

# Run tests and linting
pixi run ci

Getting Help

Community Support

Discord: Join our community for discussions, questions, and help
GitHub Issues: Report bugs or request features
GitHub Discussions: Share ideas and ask questions

Resources

Documentation: alpha-xone.github.io/xbbg
Examples: py-xbbg/examples/xbbg_jupyter_examples.ipynb
Changelog: CHANGELOG.md
Security: SECURITY.md

Links

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Star History

Project Status

Category	Badge
Docs
Build
License

For detailed release history, see CHANGELOG.md.

BloombergFetch README advertises bond analytics by ISIN, but not Bloomberg YAS request coverage. ↩
BloombergFetch README advertises futures contract tables, active contract series, and roll handling rather than the broader xbbg futures helper surface. ↩
pdblp has been superseded by blp and is no longer under active development. ↩
xbbg supports and tests Python 3.10, 3.11, 3.12, 3.13, and 3.14. ↩
bbg-fetch targets Python 3.9–3.12; its installed hard dependencies currently include NumPy and pandas, with optional pyarrow, Jupyter, and dev extras. ↩
pdblp package metadata does not declare a modern Requires-Python; its README says Python 3.x and the package depends on pandas>=0.18.0. ↩
blp declares Python >=3.6 and a mandatory pandas dependency in its package metadata. ↩
Last-commit badges are live shields.io badges against each GitHub repository's default branch; click through for the commit history. pdblp is still marked inactive by its own README even if repository metadata changes. ↩
xbbg is the only package in this comparison with a real CI matrix that exercises every supported Python version. The competitors either lack active CI across their claimed range, are legacy/inactive, or test a narrower slice than their advertised compatibility. ↩

Name		Name	Last commit message	Last commit date
Latest commit History 1,525 Commits
.cargo		.cargo
.github		.github
apps		apps
bindings		bindings
crates		crates
defs		defs
docker		docker
docs		docs
js-xbbg		js-xbbg
py-xbbg		py-xbbg
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.pre-commit-config.yaml		.pre-commit-config.yaml
404.html		404.html
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
RELEASE_PROCESS.md		RELEASE_PROCESS.md
SECURITY.md		SECURITY.md
deny.toml		deny.toml
index.html		index.html
pixi.lock		pixi.lock
pixi.toml		pixi.toml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Table of Contents