xbbg

https://github.com/xbbg-org/xbbg
Admin
An independent open-source Bloomberg client for Python and JavaScript, powered by a shared Rust...
Tokens:24,401
Snippets:322
Trust Score:6
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install benchmark dependencies

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/README.md

Commands to set up the environment and install the necessary competing packages for benchmarking.

```bash
# Install benchmark dependencies (from project root)
uv sync --group benchmark

# Install competing packages for comparison
uv pip install xbbg==0.10.3  # Legacy version
uv pip install --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/ blpapi
uv pip install bbg-fetch
uv pip install pdblp
```

--------------------------------

### Install @xbbg/core package

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Commands to install the package using npm or bun.

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

--------------------------------

### Install dependencies

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Commands to install the necessary packages for different project types.

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

```bash
npm install @xbbg/langgraph @xbbg/core @langchain/core @langchain/langgraph @langchain/openai
```

```bash
npm install @xbbg/langgraph @xbbg/core @langchain/core langchain @langchain/openai
```

--------------------------------

### Install dependencies and build

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Command to install project dependencies and perform the build using pixi.

```bash
pixi install && pixi run install
```

--------------------------------

### Install xbbg via pip

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Standard installation command for the xbbg library.

```cmd
pip install xbbg
```

--------------------------------

### Set up development environment with pixi

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Commands to stage the Bloomberg SDK and install the project environment.

```bash
# 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
pixi install
pixi run install
```

--------------------------------

### Example of Good Release Notes

Source: https://github.com/xbbg-org/xbbg/blob/main/RELEASE_PROCESS.md

A concrete example demonstrating how to write descriptive, user-focused release notes with proper categorization.

```markdown
## [Unreleased]

### Added
- Native Arrow carrier with explicit `backend="native"`, `backend="pyarrow"` for real PyArrow tables, and a Narwhals default that preserves legacy PyArrow-backed behavior when PyArrow is installed (#173)
- Output format control with `Format` enum (long, semi_long, long_typed, long_metadata)
- `bta()` function for Bloomberg Technical Analysis (#175)
- `get_sdk_info()` as replacement for deprecated `getBlpapiVersion()`

### Changed
- All API functions now accept `backend` and `format` parameters
- Internal pipeline uses xbbg native Arrow tables with explicit optional conversion backends
- **BREAKING**: Deprecated `wide` output removed; use `semi_long` or pivot `long` results explicitly

### Deprecated
- `connect()` / `disconnect()` - engine auto-initializes in v1.0
- `getBlpapiVersion()` - use `get_sdk_info()` instead

### Fixed
- Empty DataFrame handling in helper functions with LONG format output (#180)
- Memory leak in streaming subscriptions (#182)
```

--------------------------------

### Install @xbbg/core wrapper

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/packages/xbbg-core-linux-x64/README.md

Use this command to install the main wrapper package which automatically includes the platform-specific dependency.

```sh
npm install @xbbg/core
```

--------------------------------

### Install blpapi wheel

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Optional command to install the official Bloomberg blpapi wheel for runtime library discovery.

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

--------------------------------

### Run Benchmarks Locally

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Commands to install dependencies and execute the benchmark suite.

```bash
# Install dependencies (from project root)
uv sync --group benchmark

# Run benchmarks (requires Bloomberg terminal/BPIPE access)
cd benchmarks
python run_all.py
```

--------------------------------

### Build project locally

Source: https://github.com/xbbg-org/xbbg/blob/main/RELEASE_PROCESS.md

Commands to install the SDK and build Python distribution packages using uv.

```bash
# Install the SDK into vendor/blpapi-sdk/ and let the build discover it
bash ./scripts/sdktool.sh
# Windows PowerShell: .\scripts\sdktool.ps1

# Build wheel (includes Rust extension)
uv build

# Build sdist only (no Rust compilation)
uv build --sdist
```

--------------------------------

### Install xbbg via conda

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Installation command for users of the conda-forge channel.

```cmd
conda install -c conda-forge xbbg
```

--------------------------------

### Install Bloomberg Python API

Source: https://github.com/xbbg-org/xbbg/blob/main/apps/xbbg-mcp/README.md

Installs the official blpapi package from the Bloomberg repository to satisfy runtime requirements.

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

--------------------------------

### Install xbbg-mcp via shell script

Source: https://github.com/xbbg-org/xbbg/blob/main/apps/xbbg-mcp/README.md

Downloads and executes the installation script for macOS arm64 and Linux amd64 platforms.

```bash
curl -fsSL https://raw.githubusercontent.com/xbbg-org/xbbg/main/scripts/install-xbbg-mcp.sh | sh
```

```bash
curl -fsSL https://raw.githubusercontent.com/xbbg-org/xbbg/main/scripts/install-xbbg-mcp.sh | sh -s -- 1.0.0
```

--------------------------------

### Verify xbbg installation

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Python script to check the installed version and Bloomberg SDK configuration.

```python
import xbbg

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

--------------------------------

### Benchmark Output Table Example

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/README.md

An example of the performance comparison table generated in the markdown report.

```text
┌─────────────────┬──────────┬─────────────┬──────────────┬──────────┐
│ Package         │ BDP (ms) │ BDH (ms)    │ Memory (MB)  │ Winner   │
├─────────────────┼──────────┼─────────────┼──────────────┼──────────┤
│ xbbg (Rust)     │  12 ✅   │  145 ✅     │  8.2 ✅      │ 🏆       │
│ xbbg (legacy)   │ 120      │ 1200        │ 45.1         │          │
│ blpapi          │  35      │  380        │ 22.3         │          │
│ bbg-fetch       │  95      │  920        │ 38.7         │          │
│ pdblp           │  85      │  890        │ 32.4         │          │
└─────────────────┴──────────┴─────────────┴──────────────┴──────────┘

Speedup vs legacy xbbg: 10.0x faster, 5.5x less memory
Speedup vs pdblp:       7.1x faster, 3.9x less memory
```

--------------------------------

### Install LangGraph adapter dependencies

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Install the necessary packages for using Bloomberg tools within LangGraph.

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

--------------------------------

### Benchmark Comparison Example

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Markdown format for displaying performance comparisons between versions.

```markdown
## BDP - Reference Data

| Package         | Warm Mean (ms) | Memory (MB) |
|-----------------|----------------|-------------|
| xbbg v1.0.0 ✅  |  12.3          |  8.2        |
| xbbg v0.10.3    | 120.7          | 45.1        |

**Speedup:** 9.8x faster, 5.5x less memory
```

--------------------------------

### Example of Bad Release Notes

Source: https://github.com/xbbg-org/xbbg/blob/main/RELEASE_PROCESS.md

An example of poor release notes that should be avoided due to vague descriptions and placeholder text.

```markdown
## [Unreleased]

- Various bug fixes
- Performance improvements
- TODO: add more details
- Updated some stuff
```

--------------------------------

### Import agent instructions

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Import the system prompt instructions to guide the model in using Bloomberg tools effectively.

```ts
import { BLOOMBERG_TOOL_INSTRUCTIONS } from "@xbbg/langgraph";
```

--------------------------------

### Example Tool Output Format

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

The text-based summary format returned by tools for model consumption.

```text
xbbg_bdp: 1 row; truncated=false
{"tool":"xbbg_bdp","rowCount":1,"truncated":false,"data":[{"security":"<TICKER> <MARKET_SECTOR>","field":"<FIELD>","value":"<VALUE>"}]}
```

--------------------------------

### Retrieve Bloomberg data via CLI

Source: https://github.com/xbbg-org/xbbg/blob/main/apps/xbbg-cli/README.md

Examples of various data retrieval commands including reference, historical, bulk, intraday, and live streaming, along with output format specifications.

```bash
# Reference data
xbbg bdp "AAPL US Equity" --fields PX_LAST,SECURITY_NAME

# Historical data
xbbg bdh "AAPL US Equity" --fields PX_LAST --start 2024-01-01 --end 2024-12-31

# Bulk data
xbbg bds "AAPL US Equity" --fields TOP_20_HOLDERS_PUBLIC_FILINGS

# Intraday bars
xbbg bdib "AAPL US Equity" --interval 5 --start 2024-01-15

# Live streaming
xbbg subscribe "AAPL US Equity" --fields LAST_PRICE,BID,ASK

# Output formats
xbbg bdp "AAPL US Equity" --fields PX_LAST --format csv
xbbg bdp "AAPL US Equity" --fields PX_LAST --format json
```

--------------------------------

### Install blpapi Python Package for CI

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/blpapi-sys/README.md

Command to install the official blpapi Python package for CI runtime and testing.

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

--------------------------------

### Time-of-Day Volume Analysis Setup

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Fetches historical intraday data for multiple tickers to perform volume analysis.

```python
jp_hist = pd.concat([
    pd.concat([
        blp.bdib(ticker, dt=dt, session='day')
        for ticker in ['7974 JP Equity', '9984 JP Equity']
    ], axis=1)
    for dt in pd.bdate_range(end='today', periods=10)[:-1]
], sort=False)
unique(jp_hist.index.date)
```

--------------------------------

### SDK directory layout

Source: https://github.com/xbbg-org/xbbg/blob/main/vendor/blpapi-sdk/README.md

Visual representation of the vendor directory structure for versioned SDK installations.

```text
vendor/
└── blpapi-sdk/
    ├── README.md            # This file (tracked in git)
    ├── .cache/              # Downloaded archives (reusable)
    ├── 3.26.2.1/            # Extracted SDK
    │   ├── include/         # C/C++ headers (blpapi_*.h)
    │   ├── Darwin/          # macOS runtime libraries
    │   ├── Linux/           # Linux runtime libraries
    │   ├── lib/             # Windows import/runtime libraries
    │   ├── bin/             # Windows runtime DLLs + tools
    │   └── ...
    └── <another-version>/   # Another version (optional)
```

--------------------------------

### Check xbbg version

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Verify the installed version of the xbbg library.

```python
blp.__version__
```

--------------------------------

### Historical Request Tool Input Example

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Example input structure for historical data requests to be processed by the chart-spec helper.

```json
{
  "source": "bdh",
  "rows": [{ "ticker": "AAPL US Equity", "date": "20240102", "value": 190.1 }],
  "xField": "date",
  "yFields": ["value"],
  "seriesField": "ticker",
  "title": "AAPL PX_LAST"
}
```

--------------------------------

### Check xbbg version

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Command to retrieve the currently installed version of xbbg for bug reporting.

```bash
python -c "import xbbg; print(xbbg.__version__)"
```

--------------------------------

### Check project versions

Source: https://github.com/xbbg-org/xbbg/blob/main/RELEASE_PROCESS.md

Commands to retrieve the latest git tags, the current development version, and the installed package version.

```bash
# Latest release tags
git tag --sort=-version:refname | head -5

# Local dev version (from setuptools_scm)
python -c "from setuptools_scm import get_version; print(get_version())"

# Installed package version
python -c "import xbbg; print(xbbg.__version__)"
```

--------------------------------

### Advanced Bloomberg Request Patterns

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Examples for handling multiple fields, Bloomberg-style overrides, bulk data, BQL, field lookups, and equity screening.

```python
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
result = blp.bql("get(px_last) for('AAPL US Equity')")

# 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"])
```

--------------------------------

### Execute High-Level Bloomberg Workflow Recipes

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Provides examples of using high-level engine methods for fixed income, futures, historical data, and ETF-specific analytics.

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

const engine = await xbbg.connect({ host: 'localhost', port: 8194 });

// Fixed income
const yas = await engine.yas(['US912810TM69 Govt'], ['YAS_BOND_YLD'], {
  settleDt: '20240115',
  yieldType: 1, // 1=YTM, 2=YTC, 3=YTW, 4=YTB, 5=YTP, 6=YTN, 7=OAS, 8=YTS, 9=YTAL
  price: 99.5,
});
const bqr = await engine.bqr('US912810TM69 Govt', {
  startDatetime: '2024-06-03T14:30:00',
  endDatetime: '2024-06-03T15:00:00',
  eventTypes: ['BID', 'ASK'],
});
const preferreds = await engine.preferreds('BAC US Equity');
const corpBonds = await engine.corporateBonds('AAPL', { ccy: 'USD' });

// Futures and CDX resolution
const front = await engine.futTicker('ES1 Index', '20240301');
const active = await engine.activeFutures('CL1 Comdty', '20240301', { freq: 'M' });
const curve = await engine.futuresCurve('ES1 Index', { maxContracts: 6 });
// cdxTicker resolves the series whose first accrual date is on or before the
// date, so historical dates return the series that was on the run then; the
// resolved Vn is included by default (versionless: true gives a legacy alias).
const cdx = await engine.cdxTicker('CDX IG CDSI GEN 5Y Corp', '20240301');
// activeCdx additionally waits for the new series' first print after a roll.
const activeCdx = await engine.activeCdx('CDX IG CDSI GEN 5Y Corp', '20240301', {
  lookbackDays: 10,
});

// Historical helpers
const dvd = await engine.dividend(['AAPL US Equity'], '20230101', '20231231');
const turn = await engine.turnover(['AAPL US Equity'], '20240101', '20240131', {
  ccy: 'USD',
});
const holdings = await engine.etfHoldings('SPY US Equity');
const realizedYield = await engine.dividendYield('AAPL US Equity', '20230101', '20231231', {
  dividendTypes: ['Regular Cash'],
});
const members = await engine.indexMembers('SPX Index', { field: 'INDX_MWEIGHT', asof: '20240102' });
const surface = await engine.volSurface('SPX Index', '20240102', '20240105', {
  preset: 'MONEYNESS_30D',
  includeDerived: true,
  riskFreeRate: 0.05,
});
const resolved = await engine.resolveIsins(['US0378331005', 'INVALIDISIN000']);
const issuers = await engine.issuerIsins(['US037833FB15', 'INVALIDISIN000']);

// ETF NAV / iNAV toolkit — resolves Bloomberg's authoritative
// ETF_NAV_TICKER / ETF_INAV_TICKER relationships (no suffix guessing):
// QQQ US Equity -> QQQNV Index / QXV Index; AT1 LN Equity -> null / AT1IN Index
const navRel = await engine.etfNavRelationships(['QQQ US Equity', 'AT1 LN Equity']);

// Daily 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
const navHist = await engine.etfNavHistory(
  ['QQQ US Equity', 'AT1 LN Equity'],
  '20260601',
  '20260701',
);

// Real-time iNAV: validates every mapping first, then subscribes to the
// resolved iNAV topics (here QXV Index) with LAST_PRICE by default
const inavSub = await engine.subscribeEtfInav('QQQ US Equity');
for await (const tick of inavSub) {
  console.log(tick.topic, tick.get('LAST_PRICE'));
  break;
}
await inavSub.unsubscribe();

// Currency-converted prices
const px = await engine.currencyConversion('700 HK Equity', 'USD', '20240101', '20240131');
```

--------------------------------

### Retrieve Bloomberg Data with xbbg

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Basic examples for fetching reference data, historical data, and intraday bars.

```python
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)
```

--------------------------------

### Subscribe to Bloomberg data with asubscribe

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Use asubscribe for dynamic subscription management, health diagnostics, and raw data access. This example demonstrates tick-mode and all-fields configuration.

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

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

--------------------------------

### Check xbbg Version

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Use this command to report the installed version of xbbg when submitting issue reports.

```python
import xbbg; print(xbbg.__version__)
```

--------------------------------

### Date and Datetime Request Examples

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Demonstrates passing various date formats to Bloomberg API functions like bdh and bdtick.

```typescript
import { bdh, bdtick } from '@xbbg/core';

await bdh('AAPL US Equity', 'PX_LAST', { start: new Date('2024-01-01'), end: '20240630' });
await bdtick('AAPL US Equity', new Date('2024-12-01T09:30Z'), Date.UTC(2024, 11, 1, 16, 0));
```

--------------------------------

### Set up Bloomberg SDK

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Commands to configure the Bloomberg SDK for different operating systems.

```bash
# macOS/Linux
bash ./scripts/sdktool.sh

# Windows PowerShell
# .\scripts\sdktool.ps1
```

--------------------------------

### Clone the repository

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Initial steps to download the source code and enter the project directory.

```bash
git clone https://github.com/xbbg-org/xbbg.git
cd xbbg
```

--------------------------------

### Build and Test Commands

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Commands for building the native addon, staging the package, and running smoke tests.

```bash
# Preferred: build and copy js-xbbg/napi_xbbg.node into the package directory
npm --prefix js-xbbg run build

# Lower-level Rust build (useful while hacking on napi-xbbg itself)
cargo build -p napi-xbbg

# Stage the current platform package template with the built addon
npm --prefix js-xbbg run stage:native-package

# Run package smoke tests from js-xbbg/
npm run test:smoke
```

--------------------------------

### Build xbbg-mcp from source

Source: https://github.com/xbbg-org/xbbg/blob/main/apps/xbbg-mcp/README.md

Execute these commands to build the project using the provided script and cargo.

```bash
bash ./scripts/sdktool.sh
cargo build --release -p xbbg-mcp --locked
./scripts/xbbg-mcp
```

--------------------------------

### Run the benchmark suite

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/xbbg-bench/README.md

Execute the full benchmark suite using cargo.

```bash
cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Check SDK Information

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Run this command to inspect how the Bloomberg SDK and runtime environment are detected.

```python
print(xbbg.get_sdk_info())
```

--------------------------------

### Run SDK Tool for Development

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/blpapi-sys/README.md

Commands to download and extract the Bloomberg SDK for development environments.

```bash
bash ./scripts/sdktool.sh
```

```powershell
.\scripts\sdktool.ps1            # downloads and extracts SDK
```

--------------------------------

### Configure and Connect to Bloomberg Services

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Initializes the xbbg client and demonstrates connection patterns for B-PIPE and ZFP environments.

```typescript
import * as xbbg from '@xbbg/core';
import { bdp, ovr } from '@xbbg/core';

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

// Direct B-PIPE / leased-line hosts with ordered failover
const bpipeEngine = await xbbg.connect({
  servers: [
    { host: 'bpipe-primary.example.com', port: 8194 },
    { host: 'bpipe-secondary.example.com', port: 8196 },
  ],
  auth: { method: 'userapp', appName: 'my-bpipe-app' },
  tls: {
    clientCredentials: '/secure/client.p12',
    clientCredentialsPassword: process.env.BPIPE_TLS_PASSWORD,
    trustMaterial: '/secure/trust.p7',
  },
});

// Authorized ZFP over leased lines: use Bloomberg-provisioned endpoints via zfpRemote
const zfpEngine = await xbbg.connect({
  zfpRemote: '8194',
  tls: {
    clientCredentials: '/secure/client.p12',
    clientCredentialsPassword: process.env.BPIPE_TLS_PASSWORD,
    trustMaterial: '/secure/trust.p7',
  },
});
```

--------------------------------

### Subscription Replay Benchmark Commands

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg/README.md

Commands for running performance benchmarks on subscription processing, including synthetic replay and live capture.

```bash
# Synthetic one-update replay, no Bloomberg connection needed; row materialization is the default
npm run bench:subscription-replay -- --rows 100000 --iterations 3

# Time JS Arrow decode only, with IPC buffers precomputed outside the timed loop
npm run bench:subscription-replay -- --path arrow-decode-only --rows 100000 --iterations 3

# Time the current JS Subscription wrapper around fake native zero-copy descriptors
npm run build:ts
npm run bench:subscription-replay -- --path subscription-wrapper --rows 100000 --iterations 3

# Capture real XBTUSD ticks to JSONL, printing existing sub.stats telemetry
npm run bench:subscription-replay -- --capture-live "XBTUSD Curncy" --capture-ms 10000 --out tmp/xbtusd-ticks.jsonl

# Replay captured ticks one update at a time with schema-only consumption after one warmup iteration
npm run bench:subscription-replay -- --fixture tmp/xbtusd-ticks.jsonl --iterations 10 --warmup-iterations 1 --consume schema
```

--------------------------------

### Example Tool Artifact JSON

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

The structured JSON artifact returned by tools for programmatic access.

```json
{
  "tool": "xbbg_bdp",
  "rowCount": 1,
  "truncated": false,
  "data": [{ "security": "<TICKER> <MARKET_SECTOR>", "field": "<FIELD>", "value": "<VALUE>" }]
}
```

--------------------------------

### Post-Benchmark Workflow

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Commands for reviewing, committing, and comparing benchmark results.

```bash
cat results/benchmark_v1.0.0.md
```

```bash
git add results/benchmark_v*.json
git add results/benchmark_v*.md
git commit -m "chore: add benchmark results for v1.0.0"
```

```bash
# Compare current vs previous version
diff results/benchmark_v0.10.3.md results/benchmark_v1.0.0.md
```

--------------------------------

### Retrieve dividend data

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Fetch historical dividend information for a security starting from a specific date.

```python
blp.dividend('SPY US Equity', start_date='2019')
```

--------------------------------

### Initialize Bloomberg Data Tools

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Create standard Bloomberg tools or a restricted BDP-only tool instance.

```typescript
import { createBloombergTools, createBdpTool } from "@xbbg/langgraph";

const tools = createBloombergTools();
const bdpOnly = createBdpTool({ maxSecurities: 3 });
```

--------------------------------

### Configure xbbg output backends

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Demonstrates how to specify different backend libraries like PyArrow, Pandas, Polars, or DuckDB for Bloomberg data requests.

```python
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)
```

--------------------------------

### Entitlement Data Structure

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Example of the JSON structure returned when requesting entitlement data with returnEids set to true.

```json
{
  "data": {
    "rows": [],
    "eidData": { "<TICKER> <MARKET_SECTOR>": [101, 202] },
    "metadata": { "xbbg.eid_data": "{\"<TICKER> <MARKET_SECTOR>\":[101,202]}" }
  },
  "rowCount": 0,
  "truncated": false
}
```

--------------------------------

### Run tests

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Command to execute the project test suite.

```bash
pixi run test
```

--------------------------------

### Create a LangChain Agent with Bloomberg Tools

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Initializes a LangChain agent using Bloomberg tools and system instructions.

```ts
import { createAgent } from "langchain";
import { ChatOpenAI } from "@langchain/openai";
import { createAllBloombergTools, BLOOMBERG_TOOL_INSTRUCTIONS } from "@xbbg/langgraph";

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

const agent = createAgent({
  model: new ChatOpenAI({ model: "gpt-4.1" }),
  tools,
  systemPrompt: BLOOMBERG_TOOL_INSTRUCTIONS,
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Get <FIELD> for <TICKER> <MARKET_SECTOR>." }],
});
```

--------------------------------

### Initialize Bloomberg Extension Tools

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Create helper tools or a comprehensive tool set with optional tool disabling.

```typescript
import { createBloombergExtTools, createAllBloombergTools } from "@xbbg/langgraph";

const helperTools = createBloombergExtTools();
const allTools = createAllBloombergTools({
  disabledTools: ["xbbg_bql", "xbbg_bsrch"],
});
```

--------------------------------

### Configure ZFP leased-line connection

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Sets up a zero-footprint leased-line connection requiring TLS credentials and trust material.

```python
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.pem",
)
```

--------------------------------

### Generate blpapi-sys bindings locally

Source: https://github.com/xbbg-org/xbbg/blob/main/docker/README.md

Runs the container to generate blpapi-sys bindings, mounting the current directory to the container workspace.

```bash
mkdir -p target/ci-bindings

podman run --rm \
  -v "$PWD:/work" \
  -w /work \
  -e BLPAPI_BINDINGS_EXPORT_PATH=/work/target/ci-bindings/bindings.rs \
  xbbg-ci:local \
  bash -lc '
    BLPAPI_VERSION=${BLPAPI_VERSION:-3.26.2.1}
    bash ./scripts/sdktool.sh --version "$BLPAPI_VERSION" --no-set-active
    export BLPAPI_ROOT=/work/vendor/blpapi-sdk/$BLPAPI_VERSION
    export LD_LIBRARY_PATH=/work/vendor/blpapi-sdk/$BLPAPI_VERSION/Linux:$LD_LIBRARY_PATH
    cargo build -p blpapi-sys
  '
```

--------------------------------

### Run common development checks

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Standard commands for testing, linting, and CI verification.

```bash
pixi run test
pixi run lint
pixi run ci
```

--------------------------------

### Configure and fetch Bloomberg data in Node.js

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Initialize the Bloomberg connection and perform historical or reference data requests.

```ts
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']);
```

--------------------------------

### Manage Bloomberg SDK versions with helper scripts

Source: https://github.com/xbbg-org/xbbg/blob/main/vendor/blpapi-sdk/README.md

Use these scripts to download, list, or remove specific versions of the Bloomberg SDK. Ensure you are authorized to download the SDK under your Bloomberg agreements.

```bash
# Add the latest SDK version (auto-detected)
bash ./scripts/sdktool.sh

# Add a specific version
bash ./scripts/sdktool.sh --version <version>

# List installed versions
bash ./scripts/sdktool.sh --list

# Remove a version
bash ./scripts/sdktool.sh --remove <version>

# Re-download and re-extract
bash ./scripts/sdktool.sh --version <version> --force

# Free disk space by clearing cached archives
bash ./scripts/sdktool.sh --clean-cache
```

```powershell
# Windows PowerShell equivalents
.\scripts\sdktool.ps1
.\scripts\sdktool.ps1 -Version <version>
.\scripts\sdktool.ps1 -List
.\scripts\sdktool.ps1 -Remove <version>
.\scripts\sdktool.ps1 -Version <version> -Force
.\scripts\sdktool.ps1 -CleanCache
```

--------------------------------

### Initialize Bloomberg tools for LangGraph

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Create Bloomberg tools for use in LangGraph agents with specified constraints.

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

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

--------------------------------

### Run benchmark scripts

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/README.md

Commands to execute the full benchmark suite or specific individual benchmark scripts.

```bash
# Run all benchmarks
python py-xbbg/benchmarks/run_all.py

# Run all benchmarks without the offline handoff lane
python py-xbbg/benchmarks/run_all.py --no-offline

# Run specific benchmark
python py-xbbg/benchmarks/bench_bdp.py
python py-xbbg/benchmarks/bench_bdh.py
python py-xbbg/benchmarks/bench_bdib.py
python py-xbbg/benchmarks/bench_handoff_offline.py --quick
```

--------------------------------

### Initialize xbbg imports

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Standard imports required to use the xbbg library.

```python
import pandas as pd
import numpy as np

from xbbg import blp, pipeline
```

--------------------------------

### Build the CI image

Source: https://github.com/xbbg-org/xbbg/blob/main/docker/README.md

Builds the OCI-compatible container image using the provided Dockerfile.

```bash
podman build -f docker/ci/Dockerfile -t xbbg-ci:local .
```

--------------------------------

### Run benchmarks with specific profiles

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/xbbg-bench/README.md

Run the benchmark suite using different predefined profiles via the BENCH_PROFILE environment variable.

```bash
BENCH_PROFILE=smoke cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
BENCH_PROFILE=standard cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
BENCH_PROFILE=stress cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Configure B-PIPE or SAPI connection

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Configures connection settings for firm-managed Bloomberg servers, including request and subscription pool sizes.

```python
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,
)
```

--------------------------------

### Check PyPI package versions

Source: https://github.com/xbbg-org/xbbg/blob/main/RELEASE_PROCESS.md

Command to list available versions of the xbbg package on PyPI.

```bash
pip index versions xbbg
```

--------------------------------

### Run detailed benchmark profiling

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/xbbg-bench/README.md

Executes the benchmark suite with detailed profiling enabled for a specific scenario.

```bash
BENCH_PROFILE_MODE=detail BENCH_ONLY=synthetic_bdh \
  cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Configure default local DAPI connection

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Sets up the connection to a local Bloomberg Terminal session on the default port.

```python
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"))
```

--------------------------------

### Benchmark Output Structure

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Expected file structure after running the benchmark suite.

```text
results/
├── benchmark_v1.0.0.json           # Version file (overwrites)
├── benchmark_v1.0.0.md
├── benchmark_v1.0.0_20260108_153045.json  # Timestamped archive (keeps)
├── benchmark_v1.0.0_20260108_153045.md
├── latest.json                     # Symlink/copy (ignored)
└── latest.md
```

--------------------------------

### View Crate Structure

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/blpapi-sys/README.md

Displays the directory layout of the blpapi-sys crate.

```text
blpapi-sys/
├── Cargo.toml      Features (static/dynamic), bindgen + cty deps
├── build.rs        SDK discovery, bindgen generation, link directives
└── src/
    └── lib.rs      include!(bindings.rs) — 9 lines
```

--------------------------------

### Initialize Bloomberg Tools with a Custom Engine

Source: https://github.com/xbbg-org/xbbg/blob/main/js-xbbg-langgraph/README.md

Manually connect to a Bloomberg engine and provide it to the tool factory to override default lazy initialization.

```typescript
import * as xbbg from "@xbbg/core";
import { createBloombergTools } from "@xbbg/langgraph";

const engine = await xbbg.connect({ host: "localhost", port: 8194 });
const tools = createBloombergTools({ engine });
```

--------------------------------

### Apply Currency Conversion Pipeline

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Uses pipeline utilities to extract closing prices from a DataFrame and convert them to USD using FX rates.

```python
prices = (
    jp
    .pipe(pipeline.get_series, col='close')
    .pipe(pipeline.apply_fx, fx=fx)
    .tz_convert('Asia/Tokyo')
)
prices.tail()
```

--------------------------------

### Benchmark File Naming Conventions

Source: https://github.com/xbbg-org/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Naming patterns for version-specific, timestamped, and latest benchmark files.

```text
benchmark_v{version}.json
benchmark_v{version}.md
```

```text
benchmark_v{version}_{YYYYMMDD_HHMMSS}.json
benchmark_v{version}_{YYYYMMDD_HHMMSS}.md
```

```text
latest.json
latest.md
```

--------------------------------

### Perform mock testing with xbbg.testing

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Use create_mock_response and mock_engine to simulate Bloomberg API responses for non-live testing.

```python
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")
```

--------------------------------

### ETF NAV and iNAV Workflows

Source: https://github.com/xbbg-org/xbbg/blob/main/README.md

Workflows for resolving ETF NAV relationships and retrieving history or real-time iNAV data using xbbg.ext.

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

--------------------------------

### Check Bloomberg SDK ABI compatibility

Source: https://github.com/xbbg-org/xbbg/blob/main/CONTRIBUTING.md

Scripts to verify ABI compatibility against the minimum supported SDK version or specific versions.

```bash
# Check against min SDK (reads defs/bloomberg.toml)
bash scripts/abi-check.sh

# Check against specific versions
bash scripts/abi-check.sh --versions "3.24.6.1 3.26.2.1"
```

--------------------------------

### Run smoke test

Source: https://github.com/xbbg-org/xbbg/blob/main/apps/xbbg-mcp/README.md

Executes the smoke test script to verify the stdio handshake and live Bloomberg connectivity.

```bash
uv run python -X utf8 scripts/xbbg_mcp_smoke.py
```

--------------------------------

### Benchmark result file paths

Source: https://github.com/xbbg-org/xbbg/blob/main/crates/xbbg-bench/README.md

Shows the directory structure and naming convention for generated benchmark reports.

```text
crates/xbbg-bench/benchmarks/results/xbbg_benchmark_suite_<timestamp>.json
crates/xbbg-bench/benchmarks/results/xbbg_benchmark_suite_latest.json
crates/xbbg-bench/benchmarks/results/xbbg_benchmark_suite_<timestamp>.md
crates/xbbg-bench/benchmarks/results/xbbg_benchmark_suite_latest.md
```
Tokens:
Raw