xbbg 1.8.1

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

This main branch is the Rust-powered v1 release. For the legacy pure-Python line, use release/0.x.

Important: xbbg is an independent open-source project. It is not affiliated with, endorsed by, sponsored by, or approved by Bloomberg Finance L.P. or its affiliates. Bloomberg, Bloomberg Terminal, B-PIPE, BQL, and related names are trademarks or service marks of their respective owners. xbbg does not grant access to Bloomberg services, data, software, licenses, credentials, or entitlements; users must obtain and use those separately under their own Bloomberg agreements and applicable policies.

Contents

• What is xbbg?
• Why xbbg?
• Installation
• Quickstart
• Exchange auctions and imbalance
• JavaScript and Node
• Java
• Configuration and engines
• Common API surface
• Entitlement IDs
• Delayed data
• Output backends
• Async usage
• Subscriptions: raw, tick mode, and all fields
• MCP server
• Troubleshooting
• Development
• Project links

What is xbbg?

xbbg is a Bloomberg client with Python as the primary surface and companion JavaScript/Node and Java bindings, all backed by a shared Rust engine for request execution, response parsing, Arrow-shaped data movement, async workers, typed errors, and diagnostics.

Use xbbg when you already have Bloomberg access and want higher-level helpers for common request patterns, plus an escape hatch for lower-level Bloomberg service requests.

Core scope:

• request helpers for BDP, BDS, BDH, intraday bars, ticks, BQL, BEQS, BSRCH, BQR, BTA, YAS, and related analytics
• local Bloomberg Desktop API / DAPI by default
• configuration for managed Bloomberg environments, including B-PIPE/SAPI, ZFP leased lines, TLS, failover hosts, SOCKS5, and SDK logging
• sync and async Python APIs backed by the same engine
• output as Narwhals, native xbbg Arrow carriers, PyArrow, pandas, Polars, DuckDB, and other optional Narwhals-backed libraries
• JavaScript/Node bindings in js-xbbg
• Java bindings (Java 8+, plus a Java 17+ add-on) in java-xbbg

Why xbbg?

xbbg's project goal is direct: be the most complete, technically advanced, and performance-focused open-source Bloomberg client for Python workflows, while staying independent of Bloomberg and requiring users to bring their own authorized Bloomberg access.

The short version: if all you need is a tiny one-off bdp() wrapper, several packages can work. xbbg is built for the path where that notebook later grows into intraday data, BQL, streaming, B-PIPE/SAPI, ZFP, async services, typed errors, diagnostics, and non-pandas data pipelines.

Installation

pip install xbbg

Conda users can install the conda-forge build:

conda install -c conda-forge xbbg

blpapi is not required as a Python dependency. xbbg only needs Bloomberg's shared runtime library (blpapi3_64.dll on Windows, libblpapi3_64.so on macOS/Linux), which can come from Bloomberg Terminal/DAPI, a managed Bloomberg C++ SDK install, or Bloomberg's official blpapi wheel. Installing the wheel is just the easiest discovery path for many users:

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

Supported Python versions: 3.11 through 3.15. Free-threaded CPython 3.14t/3.15t wheels are available in beta with the pyarrow and pandas extras; polars, duckdb and the LangGraph adapter are not supported there. See docs/free-threading.md.

Requirements and notes:

• You need an authorized Bloomberg environment: local Terminal/DAPI, SAPI/B-PIPE, or ZFP, depending on your setup.
• If you build from source, stage the Bloomberg C++ SDK with bash ./scripts/sdktool.sh on macOS/Linux or .\\scripts\\sdktool.ps1 on Windows PowerShell.
• If you manage the SDK yourself, set BLPAPI_ROOT or use xbbg.set_sdk_path(...).
• On Windows Terminal installs, xbbg automatically probes DAPI runtime roots such as C:\blp\DAPI and C:\Program Files (x86)\Bloomberg\Blp\DAPI before requiring manual configuration.
• Linux wheels are manylinux_2_28 (x86_64): any distro with glibc ≥ 2.28 works — RHEL/Alma/Rocky 8+, Debian 10+, Ubuntu 20.04+, Amazon Linux 2023.
• Optional dataframe conversions are installed separately: xbbg[pyarrow], xbbg[pandas], xbbg[polars], or xbbg[duckdb].

Verify the install:

import xbbg

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

Quickstart

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
bars = blp.bdib("TSLA US Equity", dt="2024-01-15", interval=5)

Common request patterns:

from xbbg import blp, ovr

# Multiple fields
info = blp.bdp("NVDA US Equity", ["Security_Name", "GICS_Sector_Name", "PX_LAST"])

# Bloomberg-style overrides
vwap = blp.bdp("AAPL US Equity", "Eqy_Weighted_Avg_Px", VWAP_Dt="20240115")
adj = blp.bdp("AAPL US Equity", "CRNCY_ADJ_PX_LAST", overrides=ovr(EQY_FUND_CRNCY="EUR"))
per_sec = blp.bdp(
    ["AAPL US Equity", "MSFT US Equity"],
    "CRNCY_ADJ_PX_LAST",
    overrides=ovr(
        {
            "EQY_FUND_CRNCY": "USD",
            "AAPL US Equity": ovr(EQY_FUND_CRNCY="EUR"),
            "MSFT US Equity": ovr(EQY_FUND_CRNCY="JPY"),
        }
    ),
)

# Bulk data
holders = blp.bds("AAPL US Equity", "DVD_Hist_All", DVD_Start_Dt="20240101")

# BQL omits clientContext.appName unless an engine default or per-call value is set.
result = blp.bql("get(px_last) for('AAPL US Equity')")

# Override the engine BQL application context for this request.
# The application name below is synthetic; replace it with one authorized for your environment.
authorized_result = blp.bql(
    "get(px_last) for('AAPL US Equity')",
    app_name="example-authorized-bql-app",
)

# Field lookup
fields = blp.bflds(search_spec="vwap")

# Equity screening and constituents
screen = blp.beqs(screen="MyScreen", asof="2024-01-01")
members = blp.index_members("SPX Index", asof="2024-01-02")

# Workflow helpers
active = blp.active_futures("ESA Index", "2024-01-15")
surface = blp.vol_surface("SPX Index", start_date="2024-01-02", end_date="2024-01-05")
resolved = blp.resolve_isins(["US0378331005", "INVALIDISIN000"])

ETF NAV / iNAV workflows live in xbbg.ext and resolve Bloomberg's authoritative ETF_NAV_TICKER / ETF_INAV_TICKER relationships instead of guessing ticker suffixes:

from xbbg import ext

# Relationship discovery: QQQ US Equity -> QQQNV Index / QXV Index,
# AT1 LN Equity -> null daily NAV / AT1IN Index (independently nullable)
rel = ext.etf_nav_relationships(["QQQ US Equity", "AT1 LN Equity"])

# Daily NAV/iNAV history: mapped Index targets price with PX_LAST; AT1's
# missing daily NAV falls back to the fund's FUND_NET_ASSET_VAL — see the
# nav_source_ticker / nav_source_field columns on every row
hist = ext.etf_nav_history(
    ["QQQ US Equity", "AT1 LN Equity"],
    start_date="2026-06-01",
    end_date="2026-07-01",
)

# Real-time iNAV: validates every mapping first, then subscribes to the
# resolved iNAV topics (here QXV Index) with LAST_PRICE by default
sub = await ext.asubscribe_etf_inav("QQQ US Equity")
async for table in sub:
    print(table.to_pylist())
    break
await sub.unsubscribe()

For longer walkthroughs and example output shapes, use the examples notebook or xbbg.org.

Exchange auctions and imbalance

Bloomberg publishes auction imbalance data (buy/sell imbalance, paired shares, indicative and theoretical prices, auction state) and auction results only on the listing where the auction runs. Composite tickers such as SPY US Equity return none of it from reference data and only part of it in streams, and a pricing-source suffix on an equity ISIN (/isin/<ISIN>@UP) is silently ignored. xbbg.ext routes each input to its auction venue and checks Bloomberg's answer before returning data:

from xbbg import ext

# SPY US Equity -> SPY UP Equity, IBM US Equity -> IBM UN Equity,
# US0378331005 (Apple's ISIN) -> AAPL UW Equity
venues = ext.resolve_venues(["SPY US Equity", "IBM US Equity", "US0378331005"])

# Default auction fields for each venue in one validated reference-data request
snap = ext.auction_snapshot(["SPY US Equity", "IBM US Equity"])

# Live: resolves every input first, then subscribes the venues;
# rows and status keep the identifiers you passed
sub = await ext.asubscribe_auction(["SPY US Equity", "IBM US Equity"])
async for table in sub:
    print(table.to_pylist())
    break
await sub.unsubscribe()

# A board you poll instead of iterating: rows=False keeps only current values
board = await ext.asubscribe_auction(["SPY US Equity", "IBM US Equity"], rows=False)
print(board.latest())  # current value of every field, one row per security
await board.unsubscribe()

Rows that cannot be routed or validated come back as unresolved, unsupported, or mismatch and never carry data. subscribe_auction/stream_auction raise BlpValidationError before subscribing if any input fails or two inputs route to the same venue. Routing lookups are cached for 12 hours per input; the venue is still checked against Bloomberg on every call.

ext.AUCTION groups the fields: IMBALANCE, INDICATIVE, STATE, HALTS, RESULTS, COMPOSITE, QUOTES; DEFAULT is the first five. They use streaming names such as THEO_PRICE and BID, which reference data also accepts; live subscriptions reject static names such as PX_THEO and PX_BID.

Reading the data:

• Values are raw and venue-specific. INDICATIVE_NEAR/INDICATIVE_FAR are NYSE's continuous-book and closing-only clearing prices but Nasdaq's near/far indicative prices; IMBALANCE_CROSS_TYPE_RT codes differ by venue.
• IMBALANCE_BUY and IMBALANCE_SELL are prices, not quantities. ext.imbalance_side(code) maps BUY/MBUY/RBUY to "buy", SELL/MSEL/RSEL to "sell", and NOIM/NIMB to "none".
• THEO_PRICE and VOLUME_THEO reset to 0 at the start of each auction call, and Bloomberg sends 0 for a price it does not have. Auction subscriptions therefore show 0 in THEO_PRICE, INDICATIVE_NEAR, INDICATIVE_FAR, IMBALANCE_BUY, IMBALANCE_SELL, and REFERENCE_PRICE_RT (ext.AUCTION.ZERO_PRICE_FIELDS) as missing in latest(); pass zero_as_null=() to keep the zeros. Rows always carry the raw values. Imbalance values can persist after an auction ends: use AUCTION_TYPE_REALTIME, IN_AUCTION_RT, and the live column of latest() to tell current values from leftovers.
• Time-of-day fields such as IMBALANCE_TIMESTAMP_RT are times without a date, in the terminal's local time zone, in snapshots and streams alike. Date fields such as CLOSING_AUCTION_VOLUME_DATE_RT are dates.
• Bloomberg keeps no imbalance history; record the stream to keep it (see Recording a stream). Auction results do have history on the venue listing, for example blp.bdh("IBM UN Equity", "OFFICIAL_CLOSE_AUCTION_VOLUME", ...); the composite returns none.
• Delayed data does not need a subscription: blp.delay_status(...) reports per security whether this session's data is delayed, and bdp/bdh/bdib/bdtick accept on_delayed= (see Delayed data). Live subscriptions also warn when a stream is delayed (see Subscriptions).

Node exposes engine.resolveVenues(), engine.auctionSnapshot(), engine.subscribeAuction(), engine.streamAuction(), AuctionFields, and imbalanceSide(). The LangGraph adapters add xbbg_resolve_venues and xbbg_auction_snapshot, and the MCP server adds resolve_venues and auction_snapshot.

Python LangChain and LangGraph

py-xbbg-langgraph provides the separate xbbg-langgraph distribution, imported as xbbg_langgraph. It exposes the same 35 tool names as the JavaScript adapter: 24 Bloomberg request/recipe/snapshot tools and 11 extension helpers, including inline Vega-Lite chart specifications. Python arguments and factory names use snake_case.

Install from this checkout (the new distribution has not yet been published):

pip install ./py-xbbg-langgraph
# For the agent example below:
pip install langchain langchain-openai
# For custom graphs without the LangChain agent package:
pip install "langgraph>=1.2,<2"

Requires Python 3.11–3.14, xbbg 1.6.0+, and langchain-core 1.4+. Graph workflows target LangGraph 1.2+. The adapter installs langchain-core and Pydantic; ordinary xbbg installs remain unchanged. Live requests still require authorized Bloomberg connectivity and SDK runtime libraries. Tool creation and schema inspection do not import the native extension or start a session.

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from xbbg_langgraph import BLOOMBERG_TOOL_INSTRUCTIONS, create_all_bloomberg_tools

tools = create_all_bloomberg_tools(
    max_securities=10,
    max_fields=25,
    max_rows=500,          # Application artifact
    max_content_rows=50,  # Model-facing preview
    disabled_tools={"xbbg_bql", "xbbg_bsrch"},
)

# Configure OPENAI_API_KEY and Bloomberg access before invoking.
agent = create_agent(
    model=ChatOpenAI(model="gpt-4.1"),
    tools=tools,
    system_prompt=BLOOMBERG_TOOL_INSTRUCTIONS,
)
result = agent.invoke({
    "messages": [{"role": "user", "content": "Get PX_LAST for IBM US Equity."}],
})

For custom LangGraph workflows, pass these tools to langgraph.prebuilt.ToolNode and bind the same list to your model. create_bloomberg_tools() returns only the 23 core tools; create_bloomberg_ext_tools() returns the 11 helpers. Individual factories such as create_bdp_tool() are also exported. Factories accept either keyword options or one BloombergToolsOptions instance, not both.

All tools support .invoke() and .ainvoke(). Use .ainvoke() inside a running event loop. A full LangChain tool call produces a ToolMessage with independently bounded content and artifact:

from xbbg_langgraph import create_bdp_tool

tool = create_bdp_tool(max_securities=1, max_fields=1)
message = tool.invoke({
    "type": "tool_call",
    "id": "reference-price",
    "name": "xbbg_bdp",
    "args": {"securities": ["IBM US Equity"], "fields": ["PX_LAST"]},
})
print(message.content)
print(message.artifact)

Calling with bare arguments instead returns the content string, following LangChain's normal contract. Envelopes retain the JavaScript keys tool, data, rowCount, truncated, and optional truncation/hasErrors. Defaults cap artifacts at 1 MiB and content at 64 KiB, with additional node, depth, and string limits. Native Arrow rows are sliced before conversion; snapshot tables share one materialization allowance. Errors and entitlement metadata take priority over ordinary data. Binary values, including sparse-update presence bitmaps, use tagged base64 rather than losing null-versus-absent information.

Snapshots require max_updates; timeout_ms cannot exceed max_stream_wait_ms (15 seconds by default). They close subscriptions on completion, timeout, error, or cancellation. Successful collection with a cleanup failure retains the updates and reports unsubscribeError. Depth snapshots without explicit fields request all available scalar fields; all_fields=False requires a nonempty field list.

Pass engine=your_xbbg_engine to route tools through an application-owned xbbg.blp.Engine; otherwise they use xbbg's existing global/scoped engine. The adapter never reconfigures or shuts down that engine. request_timeout is a coroutine deadline in seconds (default 60), not a way to preempt synchronous SDK startup or subscription cleanup. Configure the engine's connection/request timeouts for those boundaries.

Output caps do not limit Bloomberg's upstream response size. Native metadata getters and an individual native cell can allocate before projection. Request bounded universes and date ranges even when the returned preview is small.

Python-specific boundaries:

• Recipe tickers must be fully qualified; builders never guess a US Equity suffix. Recipe fields accept identifiers and argument-free BQL field access, not arbitrary query fragments. Use xbbg_bql for parameterized expressions.
• active_only is not exposed because the current native corporate-bond builder does not implement that filter. Unsupported BQL/BFLDS keyword options are also rejected rather than ignored.
• CDX recovery_rate uses Python's percentage convention: 40 means 40%, not 0.40.
• Chart tools do not fetch data or render it. Render only when data.spec is present and data.renderable is not false. Explicit max_points truncation preserves a valid inline spec; structural result clipping disables rendering.

Adapter checks: pip install "./py-xbbg-langgraph[test]", then pytest py-xbbg-langgraph/tests. The existing CI Python matrix and dependency-floor job run this suite.

JavaScript and Node

xbbg also ships supported Node bindings in @xbbg/core. The JS layer uses the same Rust engine through a native N-API addon, so Node can use the same Bloomberg connection modes and request surfaces as Python.

npm install @xbbg/core
# or
bun add @xbbg/core

@xbbg/core targets Node.js 24+ and Bun 1.4+ server runtimes; @xbbg/langgraph targets Node.js 24+. Packaged native addons are provided for macOS arm64, Linux x64 (glibc 2.28+), and Windows x64. You still need Bloomberg access plus Bloomberg SDK runtime libraries on the target system.

import * as xbbg from '@xbbg/core';

xbbg.configure({ host: 'localhost', port: 8194 });

const hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');
const ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);

See js-xbbg/README.md for installation and a quickstart, and js-xbbg/REFERENCE.md for the full JavaScript API notes.

For LangChain and LangGraph agents, use the supported @xbbg/langgraph adapter. It exposes reusable server-side Bloomberg tools backed by @xbbg/core without making MCP, a chat app, or a browser integration the core path:

npm install @xbbg/langgraph @xbbg/core @langchain/core

import { createAllBloombergTools, BLOOMBERG_TOOL_INSTRUCTIONS } from '@xbbg/langgraph';

const tools = createAllBloombergTools({ maxSecurities: 10, maxFields: 10 });

Use the existing apps/xbbg-mcp package only when you specifically need MCP.

Java

java-xbbg provides the same functions as @xbbg/core for the JVM: io.github.underloam:xbbg runs on Java 8 and later through JNI on the same Rust engine, with native libraries for macOS arm64, Linux x64 (glibc 2.28+), and Windows x64 bundled in the jar and no other runtime dependencies. io.github.underloam:xbbg-jdk17 is an optional Java 17+ add-on with java.util.concurrent.Flow publishers, sealed result and error types for pattern matching, Arrow Java (VectorSchemaRoot) interop, and virtual-thread callbacks. Both are published to Maven Central with the releases that include them, so any Maven-repository build tool (Maven, Gradle, sbt, Bazel) can consume them.

<dependency>
  <groupId>io.github.underloam</groupId>
  <artifactId>xbbg</artifactId>
  <version><!-- xbbg release --></version>
</dependency>

import io.github.underloam.xbbg.BdhOptions;
import io.github.underloam.xbbg.Blp;
import io.github.underloam.xbbg.Xbbg;
import io.github.underloam.xbbg.subscription.Subscription;
import io.github.underloam.xbbg.table.Table;
import java.time.Duration;
import java.util.Arrays;

Xbbg.configure("localhost", 8194); // the default: local Terminal / DAPI

Table ref = Xbbg.await(Blp.bdp(Arrays.asList("AAPL US Equity", "MSFT US Equity"),
    Arrays.asList("PX_LAST", "SECURITY_NAME")));
Table hist = Xbbg.await(Blp.bdh("SPX Index", "PX_LAST",
    BdhOptions.builder().start("2024-01-01").end("2024-12-31").build()));

try (Subscription sub = Xbbg.await(Blp.subscribe("AAPL US Equity", "LAST_PRICE"))) {
  sub.next(Duration.ofSeconds(30))
      .ifPresent(tick -> System.out.println(tick.topic() + " " + tick.get("LAST_PRICE")));
}

Every call that reaches Bloomberg returns a CompletableFuture; Xbbg.await blocks for the result and rethrows the original typed exception. The JNI boundary never blocks a Java thread inside native code, so waiting on virtual threads is safe. The jar finds the Bloomberg runtime the same way the Python and Node packages do (an explicit path, BLPAPI_LIB_DIR/BLPAPI_ROOT, or a Terminal install). Machines without one can provision blpapi3_64.dll/libblpapi3_64.so from a Python package index or conda channel, including corporate mirrors, with Xbbg.setSdkSource(...) or -Dxbbg.sdk.source=...; nothing is downloaded unless a source is configured. On JDK 24 and later, start the JVM with --enable-native-access=ALL-UNNAMED to avoid the native-access warning. See java-xbbg/README.md for the full guide.

Configuration and engines

By default, xbbg starts a Rust-backed engine and connects to local Bloomberg Desktop API / DAPI on localhost:8194. Configure the engine before the first request when you need a different transport, authentication mode, worker count, timeout policy, field cache, or logging behavior.

from xbbg import blp, configure

# Equivalent to the default local Terminal / DAPI path
configure(host="localhost", port=8194)

print(blp.bdp("AAPL US Equity", "PX_LAST"))

Set an optional engine-wide BQL request application context before the first request:

from xbbg import configure

configure(bql_app_name="example-bql-app")

bql_app_name supplies BQL sendQuery's clientContext.appName; it is not a session-authentication setting. The authentication-only app_name still requires the corresponding auth_method. A per-call blp.bql(..., app_name="...") or blp.abql(..., app_name="...") value overrides the engine BQL default. With bql_app_name=None and no per-call value, xbbg omits the request element and preserves the service default.

Results name the column holding each row's security ticker. Once a consumer folds identifier case (a database load through unquoted identifiers, or upper-casing columns to match mnemonics), that name collides with Bloomberg's TICKER field, so it is deprecated: results that still use it emit a FutureWarning, and the next major release renames the column security, after Bloomberg's securityData.security element. Switch now with an engine setting:

from xbbg import blp, configure

configure(key_column="security")
blp.bdp("EURUSD BGN Curncy", ["TICKER", "NAME"], format="semi_long")
# columns: security, TICKER, NAME

The setting covers every result keyed by security: reference, historical, and bulk data, intraday bars and ticks, BQL, and the recipes built on them. Scoped engines take Engine(key_column="security"), Node takes keyColumn: 'security', and the MCP server reads XBBG_MCP_KEY_COLUMN. Subscription rows identify securities by topic and are unaffected.

Common environments:

Example B-PIPE/SAPI-style configuration:

from xbbg import configure

configure(
    host="bpipe-host",
    port=8194,
    auth_method="app",
    app_name="my-app",
    request_pool_size=4,
    # Opt-in sharding for wide multi-security BDP/BDH requests:
    # shard_requests=True,
    # shard_threshold=20,
    # shard_chunk_size=16,
    # shard_max_concurrent=4,
    subscription_pool_size=2,
    num_start_attempts=5,
)

Example ZFP leased-line configuration:

from xbbg import configure

configure(
    zfp_remote="8194",
    tls_client_credentials="/path/to/client.p12",
    tls_client_credentials_password="<load from your secret store>",
    tls_trust_material="/path/to/trust.p7",
)

tls_client_credentials and tls_trust_material also accept bytes from a secret store: DER-encoded PKCS#12 client credentials and DER-encoded PKCS#7 trust material. Supply both as paths or both as bytes; missing or mixed pairs are rejected before session startup. The engine passes blobs directly to the SDK without temporary files, shares their immutable storage across session configurations, and redacts blobs and the password from configuration representations.

The engine uses separate worker pools for request/response calls and subscriptions:

• request workers hold independent Bloomberg sessions and dispatch BDP/BDH/BDS/BQL-style calls across the pool
• subscription sessions are isolated from request workers, so live streams do not share a single blocking session with batch requests
• field validation, field-type caching, SDK logging, retry policy, keep-alive, slow-consumer thresholds, TLS, SOCKS5, and failover servers are configuration options rather than per-call ad hoc code

runtime_worker_threads defaults to 2 (minimum 1) and controls the engine's shared Tokio runtime, not the total process thread count. subscription_pool_size is the pre-warm count (default 1, minimum 0); max_subscription_sessions caps concurrent subscription sessions (default 32, minimum 1, and at least subscription_pool_size). Native subscription admission waits for capacity instead of allocating unbounded sessions. Sessions host shared market-data feeds (see Subscriptions): a subscription that only joins existing feeds uses no session, and a session returns to the pool once it hosts no feeds. Node uses the corresponding runtimeWorkerThreads, subscriptionPoolSize, and maxSubscriptionSessions fields.

Use Engine(...) when an application needs a scoped engine with its own connection settings instead of mutating global configuration. Engine(bql_app_name="example-bql-app") gives that scope its own BQL request default without configuring authentication.

Engine shutdown closes subscription admission and signals both idle and checked-out sessions, waking pending operations so termination and errors can reach callers. Close subscriptions explicitly before releasing their engine; do not rely on interpreter teardown for application cleanup.

Field-cache snapshots are published atomically. On Windows this uses FileRenameInfoEx with POSIX rename semantics, requiring Windows 10 1607+ and a supporting filesystem. Existing readers can finish with the old snapshot while new opens see the complete replacement. Unsupported filesystems report persistence errors and retain the prior snapshot; there is no unsafe replacement fallback.

Common API surface

Most sync helpers have async counterparts with an a prefix: bdp → abdp, bdh → abdh, bdib → abdib, request → arequest.

Entitlement IDs

Bloomberg can return entitlement IDs only for these four request operations. Opt in with return_eids=True:

For example, request EIDs with intraday ticks and check them against the default //blp/refdata service:

from xbbg import blp

ticks = blp.bdtick(
    "AAPL US Equity",
    "2024-01-15T09:30:00",
    "2024-01-15T10:00:00",
    return_eids=True,
    backend="native",
)

eid_data = ticks.eid_data or {}
eids = sorted({eid for security_eids in eid_data.values() for eid in security_eids})
if eids:
    print(blp.check_entitlements(eids))

EID metadata remains available through the native ArrowTable.eid_data property, pandas attrs["xbbg_eid_data"], or PyArrow schema metadata under xbbg.eid_data. Polars and DuckDB do not provide a stable entitlement-metadata side channel; use the native, PyArrow, or pandas backend when EIDs are required.

This opt-in request metadata is separate from a subscription message's top-level EID field.

Bloomberg returns EIDs only for exchanges the requester is entitled to, so a security whose data is delayed comes back with none; delay_status reports its feed EIDs.

Response diagnostics

bflds() tables, for both fields= and search_spec=, and FieldInfoRequest tables append an id column holding Bloomberg's field id for each answered field (for example PR005), separately from the canonical field mnemonic. Request ids Bloomberg refuses are keyed verbatim in xbbg.field_errors schema metadata, including their category, code, subcategory, message, and source when supplied. A result with no successful rows still retains these diagnostics.

Native Python tables and batches expose .field_errors and .field_exceptions; pandas retains them in attrs["xbbg_field_errors"] and attrs["xbbg_field_exceptions"]. Node result containers expose fieldErrors and fieldExceptions. PyArrow retains the raw UTF-8 JSON in schema metadata.

Raw xbbg.field_exceptions metadata uses a versioned dictionary so repeated exceptions do not repeat their text for every security:

{
  "version": 1,
  "entries": [
    {"field": "SYN_BAD_FIELD", "category": "BAD_FLD", "code": 9, "subcategory": "NOT_APPLICABLE_TO_REF_DATA", "message": "Synthetic field not applicable"}
  ],
  "securities": {"SYN_A Equity": [0], "SYN_B Equity": [0, 0]}
}

Each index identifies a complete entry; per-security order and repeated occurrences are preserved. Public exception accessors still return the expanded {security: [exception, ...]} map. Readers also accept historical persisted maps, while unsupported versions and invalid dictionary indices are rejected. Code reading raw JSON must handle the versioned shape rather than assuming the legacy map.

Bloomberg support RequestIds

Results retain the SDK-assigned RequestId for Bloomberg support. It is distinct from xbbg's request_id label and the SDK correlation ID.

• Native Python: table.bloomberg_request_id for one ID, or table.bloomberg_request_ids for the complete list.
• PyArrow: schema.metadata[b"xbbg.bloomberg_request_id"] is plain UTF-8; composed results use b"xbbg.bloomberg_request_ids" with a sorted, unique JSON array instead.
• pandas: attrs["xbbg_bloomberg_request_id"] or attrs["xbbg_bloomberg_request_ids"], matching the singular/plural metadata.
• Node Arrow/JSON: result.bloombergRequestId, result.bloombergRequestIds, and the raw result.metadata.

BlpRequestError and BlpTimeoutError carry bloomberg_request_id and bloomberg_request_ids attributes in both Python and Node; request_id remains the xbbg label. Sharding, streaming, and derived recipe composition retain contributing data-request IDs, including completed contributors when a recipe fails. Cached field/exchange introspection is not part of this provenance. An unavailable SDK ID is never replaced with a label. Polars and DuckDB have no stable metadata side channel; retain the native/Arrow result or use pandas when these IDs are needed.

Delayed data

Bloomberg serves delayed data to sessions without a real-time entitlement for an exchange, and requests neither fail nor flag it: bdp returns delayed snapshot values, bdh returns a delayed row for today, and bdib/bdtick stop the delay period before now. Check each security with delay_status:

from xbbg import blp

status = blp.delay_status(["AAPL US Equity", "VOD LN Equity", "CL1 Comdty"])

It makes one reference-data request and works on any Desktop, Server API, or B-PIPE session. Each row has delayed (this session receives delayed data), delay_minutes (minutes behind real time; null when real time), exchange_delay (Bloomberg's EXCHANGE_DELAY text, which also names the delay a real-time security would have), exch_code, the feed entitlement IDs realtime_eid1 to realtime_eid4 and delayed_eid, and error for securities Bloomberg rejects.

check_identity=True also checks the feed EIDs against the engine's authorized identity on //blp/mktdata and fills realtime_entitled (every real-time EID is entitled) and delayed_entitled. It needs SAPI/B-PIPE authorization through configure(auth_method=...) or a Desktop user enrolled in EMRS; otherwise the call raises Bloomberg's identity error.

bdp, bdh, bdib, and bdtick accept on_delayed:

bdp reads the status from the same request. bdh, bdib, and bdtick make one extra reference-data request alongside the data, and only when the requested window ends within the last 24 hours; older windows are complete whatever the entitlement, so they are not checked. The status is in the result metadata under xbbg.delayed as {ticker: {"delayed": bool, "delay_minutes": int | None}}, available through the native ArrowTable.delayed property, pandas attrs["xbbg_delayed"], or PyArrow schema metadata. Warnings are raised before backend conversion, so Polars and DuckDB results still warn.

Node exposes engine.delayStatus(tickers, { checkIdentity }) and onDelayed on bdp, bdh, bdib, and bdtick; the MCP server adds the delay_status tool and on_delayed on bdp, bdh, bdib, and request; the LangGraph adapters add xbbg_delay_status.

Output backends

xbbg defaults to a Narwhals DataFrame. When PyArrow is installed, the Narwhals frame is backed by a real pyarrow.Table; otherwise xbbg falls back through available dataframe libraries and finally to its native Arrow carrier.

from xbbg import Backend, blp

# Default Narwhals output
frame = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")

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

# Optional conversions
as_pyarrow = blp.bdp("IBM US Equity", "PX_LAST", backend=Backend.PYARROW)
as_pandas = blp.bdp("MSFT US Equity", "PX_LAST", backend=Backend.PANDAS)
as_polars = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.POLARS)
as_duckdb = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", backend=Backend.DUCKDB)

Output shape is controlled with format=, including long, long_typed, long_metadata, and semi_long.

field_types accepts float64, int64, int32, string, bool, date32, timestamp, and time64, plus their supported aliases. Unknown type names raise BlpValidationError before a data request is sent. Text-delivered fields remain strings when their dictionary metadata combines Datetime with a textual field kind; stale field-type caches are refreshed automatically.

If a non-null value cannot fit the output column's type, xbbg retains the declared schema, writes a null, and emits one request-level warning containing only field names and failure counts. Missing or already-null values do not count. Counts are available as:

• Native Python: table.type_misses.
• PyArrow: JSON in table.schema.metadata[b"xbbg.type_misses"].
• pandas: frame.attrs["xbbg_type_misses"], including direct native and Narwhals conversions.
• Node Arrow/JSON: JSON in result.metadata["xbbg.type_misses"].

Counts describe source conversion attempts, not a recount of nulls after local dataframe operations. Slices and filters retain source-batch diagnostics. Concatenation sums the supplied batch maps, so combining reused views of the same response can repeat their shared diagnostics. Polars and DuckDB have no stable diagnostic-metadata side channel; use native Arrow, PyArrow, or pandas when the counts are required.

• Native ArrowTable, ArrowRecordBatch, and ArrowColumn slices can retain their source allocations. Use .compact() when retaining a small result should release that backing storage: it returns an independent copy of the logical values with right-sized buffers, preserving schema, nulls, and physical batch/chunk boundaries. Native zero-column tables retain their row count.
• Polars conversion preserves Arrow chunks rather than implicitly rechunking. The supported floor is Polars >=0.20.4; older supported versions use PyArrow when available or schema-aware per-batch materialization, while capsule-capable versions consume the native Arrow stream. Install xbbg[polars] to include the timezone data required on Windows.
• backend="polars_lazy" returns a Polars LazyFrame; backend="narwhals_lazy" returns a genuine Narwhals lazy frame backed by Polars and requires Polars. Bloomberg retrieval and Arrow-to-Polars conversion have already happened: only subsequent local dataframe operations are deferred, with no Bloomberg query pushdown.
• DuckDB results use isolated per-relation connections to one shared process-local in-memory database, not a new database per conversion. A retained relation keeps its connection and registered Arrow input alive; releasing one relation does not invalidate another. The shared database anchor is closed at process exit. If this backend was initialized before a fork, xbbg refuses inherited backend use or explicit close in the child; use multiprocessing spawn or fork before initializing the DuckDB backend.

Async usage

Use async helpers directly in async applications:

import asyncio
from xbbg import blp

async def main():
    aapl, msft = await asyncio.gather(
        blp.abdp("AAPL US Equity", "PX_LAST"),
        blp.abdp("MSFT US Equity", "PX_LAST"),
    )
    return aapl, msft

result = asyncio.run(main())

In Jupyter, VS Code Interactive, and marimo, every sync call, including blp.bdp(...), blp.bql(...), and blp.subscribe(...), uses a notebook-only bridge when the notebook event loop is already running. Generic async applications such as FastAPI or ASGI services should still use the async APIs directly.

Subscriptions: raw, tick mode, and all fields

Use asubscribe() when you need dynamic add/remove, explicit unsubscribe, raw Arrow batches, or subscription health diagnostics. Use astream() for the simple async iterator, or stream() for synchronous iteration.

from xbbg import asubscribe

sub = await asubscribe(
    ["AAPL US Equity"],
    ["LAST_PRICE", "BID", "ASK"],
    tick_mode=True,
    all_fields=True,
    conflate=True,
)

async for tick in sub:
    print(tick)       # dict ticks in tick_mode
    print(sub.stats)  # messages_received, dropped_batches, data_loss_events, ...
    break

await sub.unsubscribe()

raw_sub = await asubscribe(["AAPL US Equity"], ["LAST_PRICE"], raw=True)

async for batch in raw_sub:
    print(batch.to_table())  # raw xbbg ArrowRecordBatch -> ArrowTable
    break

await raw_sub.unsubscribe()

Key behaviors:

• output accepts exactly record_batch, backend, dict, or tick (case-insensitive); an explicit selector overrides both raw and tick_mode
• raw=True or output="record_batch" yields raw xbbg ArrowRecordBatch values for max-performance consumers
• tick_mode=True, output="dict", or output="tick" returns native dict ticks and implies raw subscription mode
• output="backend" returns the configured backend output, the same as default iteration without raw=True
• all_fields=True exposes all top-level scalar Bloomberg subscription fields; unrequested arrays/complex fields are omitted, while explicitly requested unsupported shapes fail rather than being truncated
• filtered mode keeps requested fields plus MKTDATA_EVENT_TYPE and MKTDATA_EVENT_SUBTYPE; market-data rows that contain none of the requested fields are skipped, except the one-row initial image described under shared feeds
• conflate=True requests Bloomberg-conflated quote updates on //blp/mktdata; trades are still delivered as received
• sub.add(...), sub.remove(...), sub.add_fields(...), sub.latest(), sub.status, sub.events, sub.failed_tickers, sub.field_errors, and sub.stats expose runtime control and diagnostics
• use async with on an acquired subscription or try/finally with await sub.unsubscribe() for deterministic cleanup; unsubscribe(drain=True) returns a list in the same dict/raw/backend representation as iteration (an empty drain is []). An unread stream failure is raised after cleanup, never hidden by a successful partial drain.

Default subscription rows are deltas, not complete images. In dict ticks, a missing key means unchanged; a present None means an explicit Bloomberg clear. Arrow batches retain nullable data columns and append non-null binary __xbbg_present: bit i (least-significant bit first) marks whether schema column i + 2 is present, after timestamp and topic. A set bit plus a null cell is a clear; an unset bit is unchanged. Use each batch's current schema because all-fields layouts can grow or promote types. Schema metadata key xbbg.subscription_presence documents the encoding and mapping.

The default delta queues fail closed on a continuity gap: Bloomberg DATALOSS, a full drop_newest buffer, or overflow/timeout of the bounded block forwarder. Already committed queue data is followed by one BlpSubscriptionDataLossError, then EOF; no post-gap deltas are delivered. Its topic and detail identify the gap (topic="*" denotes unattributed/session-wide loss). Resubscribe for a fresh image before applying further deltas. Terminal session errors also wake pending reads, including handles whose topics were all removed. Ordinary connection-down notifications remain nonterminal, and a single rejected topic does not terminate healthy siblings.

Shared feeds. Within one engine, //blp/mktdata subscriptions to the same security with the same options share one Bloomberg subscription that requests the union of their fields, so a second subscription to a security does not open a second feed. A subscription that joins an existing feed immediately receives one SUMMARY/INITPAINT row built from the feed's current values (with no data columns present if none of its fields have a value yet). Asking for fields the feed lacks (a new subscription, add(...), or add_fields(...)) re-subscribes the feed once. The requesting subscription receives Bloomberg's full repaint shortly after the call returns; subscriptions that already had the image receive one SUMMARY/INITPAINT row only if the repaint changes one of their fields, containing just the changed values and clears. Because filtered subscriptions skip rows without their fields, their output does not depend on who else shares the feed; all_fields=True subscriptions see every scalar field the feed receives, including fields other subscriptions requested. Pass isolated=True to keep a subscription on its own feeds and session. vwap, mktbar, depth, chains, and other non-//blp/mktdata services are never shared. When a session terminates, only the securities on that session fail; a stream ends with the session error once none of its securities remain. xbbg.subscription_feeds() returns one dict per feed with its service, topic, options, field union, consumer count, delayed flag, state, and field errors.

Current values and labels. sub.latest() returns one row per security with the current value of each field plus last_update, live (a non-initial update has arrived), and delayed. Column types start from Bloomberg's field metadata when you subscribe, so latest() and stream columns are typed before any value arrives; if the first value Bloomberg sends has a different type, that type wins. zero_as_null=[...] shows 0 as missing in latest() and state deliveries for the listed fields (delta rows keep the raw value). Once a subscription has ended, latest() raises instead of returning an empty table. aliases={"SPY UP Equity": "SPY US Equity"} makes rows, status, and remove(...) use your label instead of the Bloomberg topic.

Boards without rows. asubscribe(..., rows=False) keeps only current values for latest(): nothing is queued, so a subscription you only poll cannot overflow, and iterating it raises RuntimeError. If Bloomberg reports DATALOSS, xbbg re-subscribes the feed for a fresh image instead of ending the subscription: live turns false and a DataLoss event is recorded, then the image is rebuilt from Bloomberg's new paint and a FeedRecovered event follows. Delta subscriptions still fail closed on upstream data loss, including opt-in drop_oldest consumers.

Delayed data and rejected fields. Bloomberg marks delayed streams with IS_DELAYED_STREAM; xbbg reads it for every subscription, records sub.topic_states[topic]["delayed"], and by default warns once per security with BlpDelayedDataWarning (Node: process.emitWarning with type BlpDelayedDataWarning). on_delayed="raise" fails that security instead while its siblings keep streaming; on_delayed="ignore" only records the flag. Requests take the same on_delayed values, unchecked by default (see Delayed data). Fields Bloomberg rejects when the subscription starts (for example static-only PX_BID, which live subscriptions call BAD_FLD) are listed in sub.field_errors and reported once with BlpFieldWarning, instead of silently staying empty. on_field_error="raise" fails the securities that requested a rejected field while their siblings keep streaming; on_field_error="ignore" records the error without a warning.

Python stream() producers share one managed background event-loop thread, not a thread per stream. Each sync bridge has a bounded queue (stream_capacity, default 256, minimum 1) and asynchronously waits for consumer space; native overflow policy remains separate. A sync stream that only joins existing shared feeds needs no subscription session; one that needs a session waits up to 5 seconds for capacity when all max_subscription_sessions are in use and then raises RuntimeError instead of blocking forever. Callbacks run on the consuming thread. Close the generator explicitly when stopping early: close cancels and waits for producer cleanup, and a cleanup timeout is reported. In async applications use astream() directly and close it explicitly when retaining the generator after an early exit.

In Node, pass { allFields: true } to stream() / subscribe() helpers for the same top-level field expansion. Default iteration yields scalar Tick objects; sub.arrow() constructs Arrow JS tables without IPC for supported schemas. Exposed mutable buffers are JS-owned snapshots: exclusive bounded allocations can be transferred, while shared/sliced/oversized storage is copied or canonicalized first. This is not a universal zero-copy Rust/JS boundary. Choose scalar, Arrow, or delivery-envelope reads once per subscription; see the Node lifecycle and benchmark contracts.

Gap-aware delivery and current-state streams

overflow_policy="drop_oldest" keeps the newest pending deltas instead of ending the consumer on local queue overflow. Read through sub.deliveries(): each SubscriptionDelivery has kind, batch data, and optional gap_before. Its cause is "local_overflow" and dropped_updates counts evicted source updates, not Arrow batches. A gap means a delta-derived image is no longer complete; do not blindly apply the retained deltas as if continuity were intact. Bloomberg DATALOSS remains terminal for every delta policy.

For quote boards that need current values rather than every tick, select delivery="state":

sub = await asubscribe(["IBM US Equity"], ["BID", "ASK"], delivery="state")
try:
    async for delivery in sub.deliveries():
        print(delivery.data)  # native ArrowTable: full images for changed topics
finally:
    await sub.unsubscribe()

State delivery reuses the shared feed image and a deduplicated, fair dirty-topic FIFO; it does not build Arrow batches on incoming ticks or scan quiet topics on each read. Apply rows by topic, not as a replacement for the whole board. Columns include topic, last_update, live, delayed, valid, and the selected data fields. These five metadata names are reserved in state mode. valid means source continuity, not field completeness: unknown and explicitly cleared fields can be null in a valid image. Initial unknown images and source-loss/topic-failure invalidations have valid=False and null data fields; recovery emits a fresh valid image afterward. Observed fields and type promotions persist across batches containing different topic subsets.

sub.deliveries() is batch-oriented, independent of tick_mode and ordinary output selectors. Its default payload is a native ArrowTable; raw=True selects ArrowRecordBatch, and backend=... selects a dataframe backend. State conflation does not create a local-overflow gap. State mode rejects rows=False and explicit raw-queue controls (stream_capacity, overflow_policy); flush_threshold remains a maximum batch hint and never waits for a full batch.

Plain subscription iteration and plain draining reject advanced modes instead of hiding delivery metadata. astream() and stream() deliberately yield envelopes when either advanced mode is selected, including inherited drop_oldest. Non-draining unsubscribe() always works. Use await sub.deliveries().unsubscribe(drain=True) to drain envelopes; canceled publication or failed backend conversion retains the native source for retry, including a frozen drain after close. SDK stream failures still take precedence over partial drain results. Bounded LangGraph snapshot tools remain strict: omission selects drop_newest independently of engine defaults; request block explicitly when needed.

Recording a stream

Bloomberg keeps no history for imbalance and other auction-call fields, so record the stream if you need it later. Raw batches convert to PyArrow record batches that can be appended to Parquet. Keep __xbbg_present so a reader can tell unchanged fields from explicit clears, and start a new file when the schema changes:

import pyarrow.parquet as pq
from xbbg import ext

sub = await ext.asubscribe_auction(["IBM US Equity"], raw=True)
writer, part = None, 0
try:
    async for batch in sub:
        batch = batch.to_pyarrow()
        if writer is None or batch.schema != writer.schema:
            if writer is not None:
                writer.close()
            part += 1
            writer = pq.ParquetWriter(f"ibm-auction-{part}.parquet", batch.schema)
        writer.write_batch(batch)
finally:
    await sub.unsubscribe()
    if writer is not None:
        writer.close()

MCP server

The repository also includes a local MCP server for coding-agent workflows. It wraps selected xbbg request/response operations and returns bounded JSON results with schema metadata.

See apps/xbbg-mcp/README.md for installation, supported environment variables, raw GitHub Release tar/zip assets, and the xbbg-mcp-v<VERSION>.mcpb local connector artifact. Official MCP Registry publication uses the generated server.json metadata after the matching GitHub Release contains the .mcpb; no MCP release asset includes Bloomberg SDK files or runtime components.

Troubleshooting

Empty results usually mean one of the inputs or entitlements is wrong rather than that the Python call failed:

from xbbg import blp

# Check security lookup and field discovery
print(blp.blkp("Apple", yellowkey="eqty"))
print(blp.fieldSearch("vwap"))

Connection failures:

• confirm Bloomberg Terminal is running and logged in for local DAPI usage
• confirm the host, port, auth method, TLS files, and entitlements for SAPI/B-PIPE/ZFP environments
• run print(xbbg.get_sdk_info()) to see how the SDK/runtime was detected
• enable SDK logging before the first session when debugging low-level connection problems

Timeouts and large responses:

• increase per-request timeout where appropriate
• split large historical/tick requests into smaller date ranges
• enable opt-in sharding for wide multi-security bdp/bdh requests with shard_requests=True
• tune request_pool_size, subscription_pool_size, queue sizes, and keep-alive settings for managed infrastructure

When reporting issues, include:

1. xbbg version: import xbbg; print(xbbg.__version__)
2. Python version and operating system
3. Bloomberg connection mode: DAPI, SAPI/B-PIPE, ZFP, or other
4. minimal code to reproduce
5. full traceback or error message

Development

Set up the development environment with pixi:

# Stage an authorized Bloomberg SDK locally under vendor/blpapi-sdk/
bash ./scripts/sdktool.sh               # macOS/Linux
# .\scripts\sdktool.ps1                # Windows PowerShell

# Install the environment and compile the Rust extension (rerun `pixi run install`
# after pulling; xbbg warns when the extension was built from another commit)
pixi install
pixi run install

Common checks:

pixi run test
pixi run lint
pixi run ci

For non-live tests, use xbbg.testing:

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": 101.23}},
)

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

Publishing is handled through GitHub Actions and PyPI Trusted Publishing.

Project links

• Documentation: xbbg.org
• JavaScript/Node bindings: js-xbbg/README.md
• Java bindings: java-xbbg/README.md
• Python LangChain/LangGraph tools: usage
• JavaScript LangChain/LangGraph tools: js-xbbg-langgraph/README.md
• PyPI: pypi.org/project/xbbg
• npm: npmjs.com/package/@xbbg/core
• crates.io: crates.io/crates/xbbg_core
• Source: github.com/underloam/xbbg
• Issues: GitHub Issues
• Discord: Join the community
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md
• License: LICENSE

Citation

If you use xbbg in research or published work, please cite:

@software{xbbg,
  author = {{xbbg contributors}},
  title = {{xbbg}: Independent client for Bloomberg-connected data workflows},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/underloam/xbbg},
  version = {1.3.0}
}