Skip to content
Back to search

xbbg

Intuitive Data Workflows

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/underloam/xbbg with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/underloam/xbbg'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/underloam--xbbg/badge.svg)](/listings/underloam--xbbg)

HTML

<a href="/listings/underloam--xbbg"><img src="/api/listings/underloam--xbbg/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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**.

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())

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 928 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- markdownlint-disable MD013 MD031 MD032 MD033 MD041 MD051 -->
  2. <div align="center">
  3. <p>
  4. <a href="https://xbbg.org/python/quickstart">
  5. <img src=".github/assets/readme-hero-flat.svg" alt="xbbg banner" width="100%">
  6. </a>
  7. </p>
  8. [![Python](https://xbbg.org/badges/xbbg/python.svg)](https://pypi.org/project/xbbg/)
  9. [![TypeScript](https://xbbg.org/badges/xbbg/javascript.svg)](https://www.npmjs.com/package/@xbbg/core)<br>
  10. [![Java](https://xbbg.org/badges/xbbg/java.svg)](java-xbbg/README.md)
  11. [![Rust](https://xbbg.org/badges/xbbg/rust.svg)](https://crates.io/crates/xbbg_core)<br>
  12. [![CI](https://xbbg.org/badges/xbbg/ci.svg)](https://github.com/underloam/xbbg/actions/workflows/ci-rust.yml)
  13. [![Documentation](https://xbbg.org/badges/xbbg/docs.svg)](https://xbbg.org/)
  14. [![Discord](https://xbbg.org/badges/xbbg/discord.svg)](https://discord.gg/P34uMwgCjC)
  15. [![License](https://xbbg.org/badges/xbbg/license.svg)](LICENSE)
  16. **Links:** [Documentation](https://xbbg.org/) · [Python](https://xbbg.org/python/) · [Node.js](https://xbbg.org/javascript/) · [Java](https://xbbg.org/java/) · [Quickstart](#quickstart) · [Configuration](#configuration-and-engines) · [Examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
  17. </div>
  18. ---
  19. <!-- xbbg:latest-release-start -->
  20. Latest release: xbbg==1.8.1 (release: [notes](https://github.com/underloam/xbbg/releases/tag/v1.8.1))
  21. <!-- xbbg:latest-release-end -->
  22. > This `main` branch is the Rust-powered v1 release. For the legacy pure-Python line, use [`release/0.x`](https://github.com/underloam/xbbg/tree/release/0.x).
  23. > **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.
  24. ## Contents
  25. - [What is xbbg?](#what-is-xbbg)
  26. - [Why xbbg?](#why-xbbg)
  27. - [Installation](#installation)
  28. - [Quickstart](#quickstart)
  29. - [Exchange auctions and imbalance](#exchange-auctions-and-imbalance)
  30. - [JavaScript and Node](#javascript-and-node)
  31. - [Java](#java)
  32. - [Configuration and engines](#configuration-and-engines)
  33. - [Common API surface](#common-api-surface)
  34. - [Entitlement IDs](#entitlement-ids)
  35. - [Delayed data](#delayed-data)
  36. - [Output backends](#output-backends)
  37. - [Async usage](#async-usage)
  38. - [Subscriptions: raw, tick mode, and all fields](#subscriptions-raw-tick-mode-and-all-fields)
  39. - [MCP server](#mcp-server)
  40. - [Troubleshooting](#troubleshooting)
  41. - [Development](#development)
  42. - [Project links](#project-links)
  43. ## What is xbbg?
  44. 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.
  45. 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.
  46. Core scope:
  47. - request helpers for BDP, BDS, BDH, intraday bars, ticks, BQL, BEQS, BSRCH, BQR, BTA, YAS, and related analytics
  48. - local Bloomberg Desktop API / DAPI by default
  49. - configuration for managed Bloomberg environments, including B-PIPE/SAPI, ZFP leased lines, TLS, failover hosts, SOCKS5, and SDK logging
  50. - sync and async Python APIs backed by the same engine
  51. - output as Narwhals, native xbbg Arrow carriers, PyArrow, pandas, Polars, DuckDB, and other optional Narwhals-backed libraries
  52. - JavaScript/Node bindings in [`js-xbbg`](js-xbbg/README.md)
  53. - Java bindings (Java 8+, plus a Java 17+ add-on) in [`java-xbbg`](java-xbbg/README.md)
  54. <p align="center">
  55. <img src=".github/assets/readme-architecture.svg" alt="xbbg shared Rust and Arrow architecture" width="720">
  56. </p>
  57. ## Why xbbg?
  58. 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.
  59. 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.
  60. | Capability | xbbg | raw `blpapi` | pdblp / blp | bbg-fetch | polars-bloomberg |
  61. | --- | --- | --- | --- | --- | --- |
  62. | BDP/BDS/BDH helpers | yes | manual SDK code | yes | yes | partial |
  63. | Intraday bars and ticks | yes | manual SDK code | limited / no | no | partial |
  64. | Streaming subscriptions | yes | manual SDK code | no | no | no |
  65. | BQL, BEQS, BSRCH, BQR, YAS, BTA | broad helper coverage | manual SDK code | limited | limited | partial |
  66. | DAPI, SAPI/B-PIPE, ZFP, TLS, failover, SOCKS5 | configurable engine support | manual SDK code | limited | limited | limited |
  67. | Async worker pools and isolated subscription sessions | yes | application-owned | no | no | no |
  68. | Rust request/parsing engine with Arrow-shaped output | yes | no | no | no | no |
  69. | Output backends beyond pandas | Narwhals, native, PyArrow, pandas, Polars, DuckDB | application-owned | pandas-first | pandas-first | Polars-first |
  70. | Typed errors, diagnostics, field cache, testing helpers | yes | application-owned | limited | limited | limited |
  71. <p align="center">
  72. <img src=".github/assets/readme-footprint.svg" alt="xbbg install footprint comparison" width="720">
  73. </p>
  74. ## Installation
  75. ```cmd
  76. pip install xbbg
  77. ```
  78. Conda users can install the conda-forge build:
  79. ```cmd
  80. conda install -c conda-forge xbbg
  81. ```
  82. `blpapi` is **not** required as a Python dependency. xbbg only needs Bloomberg's shared runtime library
  83. (`blpapi3_64.dll` on Windows, `libblpapi3_64.so` on macOS/Linux), which can come from Bloomberg
  84. Terminal/DAPI, a managed Bloomberg C++ SDK install, or Bloomberg's official `blpapi` wheel. Installing
  85. the wheel is just the easiest discovery path for many users:
  86. ```cmd
  87. pip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/
  88. ```
  89. 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](docs/free-threading.md).
  90. Requirements and notes:
  91. - You need an authorized Bloomberg environment: local Terminal/DAPI, SAPI/B-PIPE, or ZFP, depending on your setup.
  92. - 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.
  93. - If you manage the SDK yourself, set `BLPAPI_ROOT` or use `xbbg.set_sdk_path(...)`.
  94. - 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.
  95. - 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.
  96. - Optional dataframe conversions are installed separately: `xbbg[pyarrow]`, `xbbg[pandas]`, `xbbg[polars]`, or `xbbg[duckdb]`.
  97. Verify the install:
  98. ```python
  99. import xbbg
  100. print(xbbg.__version__)
  101. print(xbbg.get_sdk_info())
  102. ```
  103. ## Quickstart
  104. ```python
  105. from xbbg import blp
  106. # Reference data
  107. prices = blp.bdp(["AAPL US Equity", "MSFT US Equity"], "PX_LAST")
  108. # Historical data
  109. hist = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")
  110. # Intraday bars
  111. bars = blp.bdib("TSLA US Equity", dt="2024-01-15", interval=5)
  112. ```
  113. Common request patterns:
  114. ```python
  115. from xbbg import blp, ovr
  116. # Multiple fields
  117. info = blp.bdp("NVDA US Equity", ["Security_Name", "GICS_Sector_Name", "PX_LAST"])
  118. # Bloomberg-style overrides
  119. vwap = blp.bdp("AAPL US Equity", "Eqy_Weighted_Avg_Px", VWAP_Dt="20240115")
  120. adj = blp.bdp("AAPL US Equity", "CRNCY_ADJ_PX_LAST", overrides=ovr(EQY_FUND_CRNCY="EUR"))
  121. per_sec = blp.bdp(
  122. ["AAPL US Equity", "MSFT US Equity"],
  123. "CRNCY_ADJ_PX_LAST",
  124. overrides=ovr(
  125. {
  126. "EQY_FUND_CRNCY": "USD",
  127. "AAPL US Equity": ovr(EQY_FUND_CRNCY="EUR"),
  128. "MSFT US Equity": ovr(EQY_FUND_CRNCY="JPY"),
  129. }
  130. ),
  131. )
  132. # Bulk data
  133. holders = blp.bds("AAPL US Equity", "DVD_Hist_All", DVD_Start_Dt="20240101")
  134. # BQL omits clientContext.appName unless an engine default or per-call value is set.
  135. result = blp.bql("get(px_last) for('AAPL US Equity')")
  136. # Override the engine BQL application context for this request.
  137. # The application name below is synthetic; replace it with one authorized for your environment.
  138. authorized_result = blp.bql(
  139. "get(px_last) for('AAPL US Equity')",
  140. app_name="example-authorized-bql-app",
  141. )
  142. # Field lookup
  143. fields = blp.bflds(search_spec="vwap")
  144. # Equity screening and constituents
  145. screen = blp.beqs(screen="MyScreen", asof="2024-01-01")
  146. members = blp.index_members("SPX Index", asof="2024-01-02")
  147. # Workflow helpers
  148. active = blp.active_futures("ESA Index", "2024-01-15")
  149. surface = blp.vol_surface("SPX Index", start_date="2024-01-02", end_date="2024-01-05")
  150. resolved = blp.resolve_isins(["US0378331005", "INVALIDISIN000"])
  151. ```
  152. ETF NAV / iNAV workflows live in `xbbg.ext` and resolve Bloomberg's authoritative
  153. `ETF_NAV_TICKER` / `ETF_INAV_TICKER` relationships instead of guessing ticker suffixes:
  154. ```python
  155. from xbbg import ext
  156. # Relationship discovery: QQQ US Equity -> QQQNV Index / QXV Index,
  157. # AT1 LN Equity -> null daily NAV / AT1IN Index (independently nullable)
  158. rel = ext.etf_nav_relationships(["QQQ US Equity", "AT1 LN Equity"])
  159. # Daily NAV/iNAV history: mapped Index targets price with PX_LAST; AT1's
  160. # missing daily NAV falls back to the fund's FUND_NET_ASSET_VAL — see the
  161. # nav_source_ticker / nav_source_field columns on every row
  162. hist = ext.etf_nav_history(
  163. ["QQQ US Equity", "AT1 LN Equity"],
  164. start_date="2026-06-01",
  165. end_date="2026-07-01",
  166. )
  167. # Real-time iNAV: validates every mapping first, then subscribes to the
  168. # resolved iNAV topics (here QXV Index) with LAST_PRICE by default
  169. sub = await ext.asubscribe_etf_inav("QQQ US Equity")
  170. async for table in sub:
  171. print(table.to_pylist())
  172. break
  173. await sub.unsubscribe()
  174. ```
  175. For longer walkthroughs and example output shapes, use the [examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) or [xbbg.org](https://xbbg.org/).
  176. ## Exchange auctions and imbalance
  177. 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:
  178. ```python
  179. from xbbg import ext
  180. # SPY US Equity -> SPY UP Equity, IBM US Equity -> IBM UN Equity,
  181. # US0378331005 (Apple's ISIN) -> AAPL UW Equity
  182. venues = ext.resolve_venues(["SPY US Equity", "IBM US Equity", "US0378331005"])
  183. # Default auction fields for each venue in one validated reference-data request
  184. snap = ext.auction_snapshot(["SPY US Equity", "IBM US Equity"])
  185. # Live: resolves every input first, then subscribes the venues;
  186. # rows and status keep the identifiers you passed
  187. sub = await ext.asubscribe_auction(["SPY US Equity", "IBM US Equity"])
  188. async for table in sub:
  189. print(table.to_pylist())
  190. break
  191. await sub.unsubscribe()
  192. # A board you poll instead of iterating: rows=False keeps only current values
  193. board = await ext.asubscribe_auction(["SPY US Equity", "IBM US Equity"], rows=False)
  194. print(board.latest()) # current value of every field, one row per security
  195. await board.unsubscribe()
  196. ```
  197. | Input | Auction venue | Checked against |
  198. | --- | --- | --- |
  199. | Equity or ETF composite ticker, or its ISIN | `{TICKER} {EQY_PRIM_EXCH_SHRT} Equity` | venue `EXCH_CODE` |
  200. | Explicit exchange ticker (`SPY UP Equity`) | unchanged | venue `EXCH_CODE` |
  201. | Preferred (`Pfd`) ISIN | `/isin/<ISIN>@<PCS>`, from a packaged exchange table (`NEW YORK` → `SNY2`, Nasdaq → `NASP`, `NYSE AMERICAN` → `AMEX`) or `pcs_overrides={...}` | venue `PRICING_SOURCE` |
  202. 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.
  203. `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`.
  204. Reading the data:
  205. - 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.
  206. - `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"`.
  207. - `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.
  208. - 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.
  209. - Bloomberg keeps no imbalance history; record the stream to keep it (see [Recording a stream](#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.
  210. - 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](#delayed-data)). Live subscriptions also warn when a stream is delayed (see [Subscriptions](#subscriptions-raw-tick-mode-and-all-fields)).
  211. 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`.
  212. ## Python LangChain and LangGraph
  213. [`py-xbbg-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`.
  214. Install from this checkout (the new distribution has not yet been published):
  215. ```bash
  216. pip install ./py-xbbg-langgraph
  217. # For the agent example below:
  218. pip install langchain langchain-openai
  219. # For custom graphs without the LangChain agent package:
  220. pip install "langgraph>=1.2,<2"
  221. ```
  222. 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.
  223. ```python
  224. from langchain.agents import create_agent
  225. from langchain_openai import ChatOpenAI
  226. from xbbg_langgraph import BLOOMBERG_TOOL_INSTRUCTIONS, create_all_bloomberg_tools
  227. tools = create_all_bloomberg_tools(
  228. max_securities=10,
  229. max_fields=25,
  230. max_rows=500, # Application artifact
  231. max_content_rows=50, # Model-facing preview
  232. disabled_tools={"xbbg_bql", "xbbg_bsrch"},
  233. )
  234. # Configure OPENAI_API_KEY and Bloomberg access before invoking.
  235. agent = create_agent(
  236. model=ChatOpenAI(model="gpt-4.1"),
  237. tools=tools,
  238. system_prompt=BLOOMBERG_TOOL_INSTRUCTIONS,
  239. )
  240. result = agent.invoke({
  241. "messages": [{"role": "user", "content": "Get PX_LAST for IBM US Equity."}],
  242. })
  243. ```
  244. 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.
  245. 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:
  246. ```python
  247. from xbbg_langgraph import create_bdp_tool
  248. tool = create_bdp_tool(max_securities=1, max_fields=1)
  249. message = tool.invoke({
  250. "type": "tool_call",
  251. "id": "reference-price",
  252. "name": "xbbg_bdp",
  253. "args": {"securities": ["IBM US Equity"], "fields": ["PX_LAST"]},
  254. })
  255. print(message.content)
  256. print(message.artifact)
  257. ```
  258. 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.
  259. 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.
  260. 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.
  261. 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.
  262. Python-specific boundaries:
  263. - 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.
  264. - `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.
  265. - CDX `recovery_rate` uses Python's percentage convention: `40` means 40%, not `0.40`.
  266. - 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.
  267. 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.
  268. ## JavaScript and Node
  269. xbbg also ships supported Node bindings in [`@xbbg/core`](js-xbbg/README.md). 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.
  270. ```bash
  271. npm install @xbbg/core
  272. # or
  273. bun add @xbbg/core
  274. ```
  275. `@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.
  276. ```ts
  277. import * as xbbg from '@xbbg/core';
  278. xbbg.configure({ host: 'localhost', port: 8194 });
  279. const hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');
  280. const ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);
  281. ```
  282. See [`js-xbbg/README.md`](js-xbbg/README.md) for installation and a quickstart, and [`js-xbbg/REFERENCE.md`](js-xbbg/REFERENCE.md) for the full JavaScript API notes.
  283. For LangChain and LangGraph agents, use the supported [`@xbbg/langgraph`](js-xbbg-langgraph/README.md) 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:
  284. ```bash
  285. npm install @xbbg/langgraph @xbbg/core @langchain/core
  286. ```
  287. ```ts
  288. import { createAllBloombergTools, BLOOMBERG_TOOL_INSTRUCTIONS } from '@xbbg/langgraph';
  289. const tools = createAllBloombergTools({ maxSecurities: 10, maxFields: 10 });
  290. ```
  291. Use the existing [`apps/xbbg-mcp`](apps/xbbg-mcp/README.md) package only when you specifically need MCP.
  292. ## Java
  293. [`java-xbbg`](java-xbbg/README.md) 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.
  294. ```xml
  295. <dependency>
  296. <groupId>io.github.underloam</groupId>
  297. <artifactId>xbbg</artifactId>
  298. <version><!-- xbbg release --></version>
  299. </dependency>
  300. ```
  301. ```java
  302. import io.github.underloam.xbbg.BdhOptions;
  303. import io.github.underloam.xbbg.Blp;
  304. import io.github.underloam.xbbg.Xbbg;
  305. import io.github.underloam.xbbg.subscription.Subscription;
  306. import io.github.underloam.xbbg.table.Table;
  307. import java.time.Duration;
  308. import java.util.Arrays;
  309. Xbbg.configure("localhost", 8194); // the default: local Terminal / DAPI
  310. Table ref = Xbbg.await(Blp.bdp(Arrays.asList("AAPL US Equity", "MSFT US Equity"),
  311. Arrays.asList("PX_LAST", "SECURITY_NAME")));
  312. Table hist = Xbbg.await(Blp.bdh("SPX Index", "PX_LAST",
  313. BdhOptions.builder().start("2024-01-01").end("2024-12-31").build()));
  314. try (Subscription sub = Xbbg.await(Blp.subscribe("AAPL US Equity", "LAST_PRICE"))) {
  315. sub.next(Duration.ofSeconds(30))
  316. .ifPresent(tick -> System.out.println(tick.topic() + " " + tick.get("LAST_PRICE")));
  317. }
  318. ```
  319. 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`](java-xbbg/README.md) for the full guide.
  320. ## Configuration and engines
  321. 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.
  322. ```python
  323. from xbbg import blp, configure
  324. # Equivalent to the default local Terminal / DAPI path
  325. configure(host="localhost", port=8194)
  326. print(blp.bdp("AAPL US Equity", "PX_LAST"))
  327. ```
  328. Set an optional engine-wide BQL request application context before the first
  329. request:
  330. ```python
  331. from xbbg import configure
  332. configure(bql_app_name="example-bql-app")
  333. ```
  334. `bql_app_name` supplies BQL `sendQuery`'s `clientContext.appName`; it is not a
  335. session-authentication setting. The authentication-only `app_name` still
  336. requires the corresponding `auth_method`. A per-call
  337. `blp.bql(..., app_name="...")` or `blp.abql(..., app_name="...")` value
  338. overrides the engine BQL default. With `bql_app_name=None` and no per-call
  339. value, xbbg omits the request element and preserves the service default.
  340. Results name the column holding each row's security `ticker`. Once a consumer
  341. folds identifier case (a database load through unquoted identifiers, or
  342. upper-casing columns to match mnemonics), that name collides with Bloomberg's
  343. `TICKER` field, so it is deprecated: the first result in a process that still
  344. uses it emits a `FutureWarning`, and the next major release renames the column
  345. `security`, after Bloomberg's `securityData.security` element. Switch now with
  346. an engine setting:
  347. ```python
  348. from xbbg import blp, configure
  349. configure(key_column="security")
  350. blp.bdp("EURUSD BGN Curncy", ["TICKER", "NAME"], format="semi_long")
  351. # columns: security, TICKER, NAME
  352. ```
  353. The setting covers every result keyed by security: reference, historical, and
  354. bulk data, intraday bars and ticks, BQL, and the recipes built on them. Scoped
  355. engines take `Engine(key_column="security")`, Node takes
  356. `keyColumn: 'security'`, and the MCP server reads `XBBG_MCP_KEY_COLUMN`.
  357. Subscription rows identify securities by `topic` and are unaffected.
  358. Common environments:
  359. | Environment | Use when | Configuration shape |
  360. | --- | --- | --- |
  361. | Desktop API / DAPI | Local Bloomberg Terminal session | no config, or `configure(host="localhost", port=8194)` |
  362. | Direct server / SAPI | Firm-managed Bloomberg server | `configure(host="bpipe-host", port=8194, auth_method="app", app_name="...")` |
  363. | B-PIPE | Enterprise Bloomberg feed infrastructure | direct host/failover config plus the auth/TLS settings your Bloomberg setup requires |
  364. | ZFP leased line | Bloomberg zero-footprint leased-line path | `configure(zfp_remote="8194", tls_client_credentials="...", tls_trust_material="...")` |
  365. Example B-PIPE/SAPI-style configuration:
  366. ```python
  367. from xbbg import configure
  368. configure(
  369. host="bpipe-host",
  370. port=8194,
  371. auth_method="app",
  372. app_name="my-app",
  373. request_pool_size=4,
  374. # Opt-in sharding for wide multi-security BDP/BDH requests:
  375. # shard_requests=True,
  376. # shard_threshold=20,
  377. # shard_chunk_size=16,
  378. # shard_max_concurrent=4,
  379. subscription_pool_size=2,
  380. num_start_attempts=5,
  381. )
  382. ```
  383. Example ZFP leased-line configuration:
  384. ```python
  385. from xbbg import configure
  386. configure(
  387. zfp_remote="8194",
  388. tls_client_credentials="/path/to/client.p12",
  389. tls_client_credentials_password="<load from your secret store>",
  390. tls_trust_material="/path/to/trust.p7",
  391. )
  392. ```
  393. `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.
  394. The engine uses separate worker pools for request/response calls and subscriptions:
  395. - request workers hold independent Bloomberg sessions and dispatch BDP/BDH/BDS/BQL-style calls across the pool
  396. - subscription sessions are isolated from request workers, so live streams do not share a single blocking session with batch requests
  397. - 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
  398. `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](#subscriptions-raw-tick-mode-and-all-fields)): 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.
  399. 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.
  400. 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.
  401. 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.
  402. ## Common API surface
  403. | Area | Functions |
  404. | --- | --- |
  405. | Reference and bulk data | `bdp`, `bds`, `bflds`, `fieldInfo`, `fieldSearch`, `blkp`, `bport` |
  406. | Historical data | `bdh`, `dividend`, `earnings`, `turnover`, `dividend_yield` |
  407. | Intraday data | `bdib`, `bdtick` |
  408. | Query and screening | `bql`, `beqs`, `bsrch`, `bqr`, `bcurves`, `bgovts`, `etf_holdings`, `index_members` |
  409. | Analytics and utilities | `yas`, `bta`, `ta_studies`, `ta_study_params`, `convert_ccy`, `fut_ticker`, `active_futures`, `futures_curve`, `vol_surface`, `resolve_isins`, `issuer_isins`, `cdx_ticker`, `active_cdx` |
  410. | Exchange auctions (`xbbg.ext`) | `resolve_venues`, `auction_snapshot`, `subscribe_auction`, `stream_auction`, `AUCTION`, `imbalance_side` |
  411. | Real-time data | `subscribe`, `stream`, `vwap`, `mktbar`, `depth`, `chains`, `subscription_feeds` |
  412. | Generic requests | `request`, `Service`, `Operation`, `RequestParams`, `OutputMode` |
  413. | Entitlements and delayed data | `delay_status`, `check_entitlements`, `seat_type`, `identity_is_authorized` |
  414. | Schema and diagnostics | `bops`, `bschema`, `get_sdk_info`, `enable_sdk_logging`, `print_backend_status` |
  415. | Testing helpers | `xbbg.testing.create_mock_response`, `xbbg.testing.mock_engine` |
  416. Most sync helpers have async counterparts with an `a` prefix: `bdp` → `abdp`, `bdh` → `abdh`, `bdib` → `abdib`, `request` → `arequest`.
  417. ## Entitlement IDs
  418. Bloomberg can return entitlement IDs only for these four request operations. Opt in with `return_eids=True`:
  419. | Bloomberg operation | Python routes |
  420. | --- | --- |
  421. | `ReferenceDataRequest` | `blp.bdp`, `blp.bds` (BDS uses the reference-data operation) |
  422. | `HistoricalDataRequest` | `blp.bdh` |
  423. | `IntradayBarRequest` | `blp.bdib` |
  424. | `IntradayTickRequest` | `blp.bdtick` |
  425. For example, request EIDs with intraday ticks and check them against the default `//blp/refdata` service:
  426. ```python
  427. from xbbg import blp
  428. ticks = blp.bdtick(
  429. "AAPL US Equity",
  430. "2024-01-15T09:30:00",
  431. "2024-01-15T10:00:00",
  432. return_eids=True,
  433. backend="native",
  434. )
  435. eid_data = ticks.eid_data or {}
  436. eids = sorted({eid for security_eids in eid_data.values() for eid in security_eids})
  437. if eids:
  438. print(blp.check_entitlements(eids))
  439. ```
  440. 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.
  441. This opt-in request metadata is separate from a subscription message's top-level `EID` field.
  442. Bloomberg returns EIDs only for exchanges the requester is entitled to, so a security whose data is delayed comes back with none; [`delay_status`](#delayed-data) reports its feed EIDs.
  443. ## Response diagnostics
  444. `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.
  445. 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.
  446. Raw `xbbg.field_exceptions` metadata uses a versioned dictionary so repeated exceptions do not repeat their text for every security:
  447. ```json
  448. {
  449. "version": 1,
  450. "entries": [
  451. {"field": "SYN_BAD_FIELD", "category": "BAD_FLD", "code": 9, "subcategory": "NOT_APPLICABLE_TO_REF_DATA", "message": "Synthetic field not applicable"}
  452. ],
  453. "securities": {"SYN_A Equity": [0], "SYN_B Equity": [0, 0]}
  454. }
  455. ```
  456. 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.
  457. ## Bloomberg support RequestIds
  458. Results retain the SDK-assigned RequestId for Bloomberg support. It is distinct from xbbg's `request_id` label and the SDK correlation ID.
  459. - Native Python: `table.bloomberg_request_id` for one ID, or `table.bloomberg_request_ids` for the complete list.
  460. - 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.
  461. - pandas: `attrs["xbbg_bloomberg_request_id"]` or `attrs["xbbg_bloomberg_request_ids"]`, matching the singular/plural metadata.
  462. - Node Arrow/JSON: `result.bloombergRequestId`, `result.bloombergRequestIds`, and the raw `result.metadata`.
  463. `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.
  464. ## Delayed data
  465. 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`:
  466. ```python
  467. from xbbg import blp
  468. status = blp.delay_status(["AAPL US Equity", "VOD LN Equity", "CL1 Comdty"])
  469. ```
  470. 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.
  471. `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.
  472. `bdp`, `bdh`, `bdib`, and `bdtick` accept `on_delayed`:
  473. | Value | Behavior |
  474. | --- | --- |
  475. | `None` (default) | No check. |
  476. | `"warn"` | One `BlpDelayedDataWarning` per delayed security. |
  477. | `"raise"` | `BlpRequestError` naming the delayed securities. |
  478. | `"ignore"` | Status recorded in the result metadata only. |
  479. `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.
  480. 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`.
  481. ## Output backends
  482. 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.
  483. ```python
  484. from xbbg import Backend, blp
  485. # Default Narwhals output
  486. frame = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")
  487. # Explicit native xbbg Arrow carrier
  488. table = blp.bdp("AAPL US Equity", "PX_LAST", backend="native")
  489. # Optional conversions
  490. as_pyarrow = blp.bdp("IBM US Equity", "PX_LAST", backend=Backend.PYARROW)
  491. as_pandas = blp.bdp("MSFT US Equity", "PX_LAST", backend=Backend.PANDAS)
  492. as_polars = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.POLARS)
  493. as_duckdb = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", backend=Backend.DUCKDB)
  494. ```
  495. Output shape is controlled with `format=`, including `long`, `long_typed`, `long_metadata`, and `semi_long`.
  496. `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.
  497. 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:
  498. - Native Python: `table.type_misses`.
  499. - PyArrow: JSON in `table.schema.metadata[b"xbbg.type_misses"]`.
  500. - pandas: `frame.attrs["xbbg_type_misses"]`, including direct native and Narwhals conversions.
  501. - Node Arrow/JSON: JSON in `result.metadata["xbbg.type_misses"]`.
  502. 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.
  503. - 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.
  504. - 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.
  505. - `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.
  506. - 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.
  507. ## Async usage
  508. Use async helpers directly in async applications:
  509. ```python
  510. import asyncio
  511. from xbbg import blp
  512. async def main():
  513. aapl, msft = await asyncio.gather(
  514. blp.abdp("AAPL US Equity", "PX_LAST"),
  515. blp.abdp("MSFT US Equity", "PX_LAST"),
  516. )
  517. return aapl, msft
  518. result = asyncio.run(main())
  519. ```
  520. 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.
  521. ## Subscriptions: raw, tick mode, and all fields
  522. 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.
  523. ```python
  524. from xbbg import asubscribe
  525. sub = await asubscribe(
  526. ["AAPL US Equity"],
  527. ["LAST_PRICE", "BID", "ASK"],
  528. tick_mode=True,
  529. all_fields=True,
  530. conflate=True,
  531. )
  532. async for tick in sub:
  533. print(tick) # dict ticks in tick_mode
  534. print(sub.stats) # messages_received, dropped_batches, data_loss_events, ...
  535. break
  536. await sub.unsubscribe()
  537. ```
  538. ```python
  539. raw_sub = await asubscribe(["AAPL US Equity"], ["LAST_PRICE"], raw=True)
  540. async for batch in raw_sub:
  541. print(batch.to_table()) # raw xbbg ArrowRecordBatch -> ArrowTable
  542. break
  543. await raw_sub.unsubscribe()
  544. ```
  545. Key behaviors:
  546. - `output` accepts exactly `record_batch`, `backend`, `dict`, or `tick` (case-insensitive); an explicit selector overrides both `raw` and `tick_mode`
  547. - `raw=True` or `output="record_batch"` yields raw xbbg `ArrowRecordBatch` values for max-performance consumers
  548. - `tick_mode=True`, `output="dict"`, or `output="tick"` returns native dict ticks and implies raw subscription mode
  549. - `output="backend"` returns the configured backend output, the same as default iteration without `raw=True`
  550. - `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
  551. - 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
  552. - `conflate=True` requests Bloomberg-conflated quote updates on `//blp/mktdata`; trades are still delivered as received
  553. - `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
  554. - 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.
  555. 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.
  556. 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.
  557. **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.
  558. **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.
  559. **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.
  560. **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](#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.
  561. 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.
  562. 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](js-xbbg/REFERENCE.md).
  563. ### Gap-aware delivery and current-state streams
  564. `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.
  565. For quote boards that need current values rather than every tick, select `delivery="state"`:
  566. ```python
  567. sub = await asubscribe(["IBM US Equity"], ["BID", "ASK"], delivery="state")
  568. try:
  569. async for delivery in sub.deliveries():
  570. print(delivery.data) # native ArrowTable: full images for changed topics
  571. finally:
  572. await sub.unsubscribe()
  573. ```
  574. 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.
  575. `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.
  576. 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.
  577. ### Recording a stream
  578. 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:
  579. ```python
  580. import pyarrow.parquet as pq
  581. from xbbg import ext
  582. sub = await ext.asubscribe_auction(["IBM US Equity"], raw=True)
  583. writer, part = None, 0
  584. try:
  585. async for batch in sub:
  586. batch = batch.to_pyarrow()
  587. if writer is None or batch.schema != writer.schema:
  588. if writer is not None:
  589. writer.close()
  590. part += 1
  591. writer = pq.ParquetWriter(f"ibm-auction-{part}.parquet", batch.schema)
  592. writer.write_batch(batch)
  593. finally:
  594. await sub.unsubscribe()
  595. if writer is not None:
  596. writer.close()
  597. ```
  598. ## MCP server
  599. 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.
  600. See [`apps/xbbg-mcp/README.md`](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.
  601. ## Troubleshooting
  602. Empty results usually mean one of the inputs or entitlements is wrong rather than that the Python call failed:
  603. ```python
  604. from xbbg import blp
  605. # Check security lookup and field discovery
  606. print(blp.blkp("Apple", yellowkey="eqty"))
  607. print(blp.fieldSearch("vwap"))
  608. ```
  609. Connection failures:
  610. - confirm Bloomberg Terminal is running and logged in for local DAPI usage
  611. - confirm the host, port, auth method, TLS files, and entitlements for SAPI/B-PIPE/ZFP environments
  612. - run `print(xbbg.get_sdk_info())` to see how the SDK/runtime was detected
  613. - enable SDK logging before the first session when debugging low-level connection problems
  614. Timeouts and large responses:
  615. - increase per-request timeout where appropriate
  616. - split large historical/tick requests into smaller date ranges
  617. - enable opt-in sharding for wide multi-security `bdp`/`bdh` requests with `shard_requests=True`
  618. - tune `request_pool_size`, `subscription_pool_size`, queue sizes, and keep-alive settings for managed infrastructure
  619. When reporting issues, include:
  620. 1. xbbg version: `import xbbg; print(xbbg.__version__)`
  621. 2. Python version and operating system
  622. 3. Bloomberg connection mode: DAPI, SAPI/B-PIPE, ZFP, or other
  623. 4. minimal code to reproduce
  624. 5. full traceback or error message
  625. ## Development
  626. Set up the development environment with [pixi](https://pixi.sh/):
  627. ```bash
  628. # Stage an authorized Bloomberg SDK locally under vendor/blpapi-sdk/
  629. bash ./scripts/sdktool.sh # macOS/Linux
  630. # .\scripts\sdktool.ps1 # Windows PowerShell
  631. # Install the environment and compile the Rust extension (rerun `pixi run install`
  632. # after pulling; xbbg warns when the extension was built from another commit)
  633. pixi install
  634. pixi run install
  635. ```
  636. Common checks:
  637. ```bash
  638. pixi run test
  639. pixi run lint
  640. pixi run ci
  641. ```
  642. For non-live tests, use `xbbg.testing`:
  643. ```python
  644. from xbbg import blp
  645. from xbbg.testing import create_mock_response, mock_engine
  646. response = create_mock_response(
  647. service="//blp/refdata",
  648. operation="ReferenceDataRequest",
  649. data={"AAPL US Equity": {"PX_LAST": 101.23}},
  650. )
  651. with mock_engine([response]):
  652. df = blp.bdp("AAPL US Equity", "PX_LAST")
  653. ```
  654. Publishing is handled through GitHub Actions and PyPI Trusted Publishing.
  655. ## Project links
  656. - Documentation: [xbbg.org](https://xbbg.org/)
  657. - JavaScript/Node bindings: [js-xbbg/README.md](js-xbbg/README.md)
  658. - Java bindings: [java-xbbg/README.md](java-xbbg/README.md)
  659. - Python LangChain/LangGraph tools: [usage](#python-langchain-and-langgraph)
  660. - JavaScript LangChain/LangGraph tools: [js-xbbg-langgraph/README.md](js-xbbg-langgraph/README.md)
  661. - PyPI: [pypi.org/project/xbbg](https://pypi.org/project/xbbg/)
  662. - npm: [npmjs.com/package/@xbbg/core](https://www.npmjs.com/package/@xbbg/core)
  663. - crates.io: [crates.io/crates/xbbg_core](https://crates.io/crates/xbbg_core)
  664. - Source: [github.com/underloam/xbbg](https://github.com/underloam/xbbg)
  665. - Issues: [GitHub Issues](https://github.com/underloam/xbbg/issues)
  666. - Discord: [Join the community](https://discord.gg/P34uMwgCjC)
  667. - Changelog: [CHANGELOG.md](CHANGELOG.md)
  668. - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
  669. - Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
  670. - Security: [SECURITY.md](SECURITY.md)
  671. - License: [LICENSE](LICENSE)
  672. ## Citation
  673. If you use xbbg in research or published work, please cite:
  674. ```bibtex
  675. @software{xbbg,
  676. author = {{xbbg contributors}},
  677. title = {{xbbg}: Independent client for Bloomberg-connected data workflows},
  678. year = {2026},
  679. publisher = {GitHub},
  680. url = {https://github.com/underloam/xbbg},
  681. version = {1.3.0}
  682. }
  683. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.