fxxking-data-client

0.5.0 保留 CN、HK、US、CRYPTO 的 Contract 2 行情与监控协议，并新增独立的 Contract 3 数据集查询、刷新任务与 Arrow 结果能力， 并保留历史 close 序列和 bars v2：bars Arrow Schema 的 currency 允许来源事实缺失时保持 null，同步/异步 HTTP 请求默认携带 X-API-Contract-Version: 2，实时连接默认携带 api_contract_version=2。两条 A 股 ashare-lake 独立订阅能力继续保留：

async with MarketDataStreamClient(base_url, token) as client:
    latest = await client.open_latest_price_subscription(
        market="CN",
        symbol="600519.SH",
        poll_interval="5m",
    )
    closed = await client.open_closed_bar_subscription(
        market="CN",
        symbol="600519.SH",
        interval="5m",
    )

两个句柄均提供 initial_status()、current_status()、 status_updates()、events() 和 aclose()。 CLIENT_VERSION_SERIES="0.5.x"；Contract 2 方法继续发送版本 2，Contract 3 方法 逐请求发送版本 3，不会切换共享请求头。

fxxking-data-client 是 fxxking-data 服务的来源无关 Python Client。 当前候选版本为 0.5.0，Python import package 保持为 market_data_client。

本包提供同步 HTTP Client、异步 HTTP Client、WebSocket Client，以及搜索、标的详情、 K 线、报价、日历和市场状态的强类型请求与响应模型。它不包含服务端实现、存储实现或 Longbridge、Bitget、OpenFIGI 等金融上游 SDK。

安装

正式发布门禁关闭后，从 PyPI 安装精确版本：

python -m pip install fxxking-data-client==0.5.0

当前仓只生成并验证本地 wheel/sdist 发布候选，尚未执行 PyPI 发布。client/dist/ 不是正式 registry，不得据此声明该版本已经发布。

兼容范围

Client 0.5.x 同时支持 API contract 2 和 3。同步和异步 Client 的既有搜索、详情、K 线 或 backfill 创建前读取服务的公开只读 GET /v1/capabilities；实时 Client 在建立 bars WebSocket 前执行同一握手。成功后在当前实例内缓存。capabilities 缺失、Schema 错误、 contract 不是 2 或缺少必需能力时抛出 CompatibilityError，不会继续访问旧接口或使用 fallback。

M1 最小使用

from market_data_client import MarketDataClient

with MarketDataClient(
    "https://data.example.invalid",
    "service-token",
) as client:
    search = client.search_instruments("AAPL", market="US")
    instrument_id = search.items[0].instrument_id
    details = client.get_instrument(instrument_id)
    bars = client.get_bars_by_instrument(
        instrument_ids=[instrument_id],
        market="US",
        interval="1d",
        start="2025-07-29T00:00:00Z",
        end="2026-07-30T00:00:00Z",
        adjustment="none",
    )

assert details.instrument_id == instrument_id
assert bars.items[0].instrument_id == instrument_id

只需要历史收盘事实时，使用独立 close 序列接口；该接口不会把尚未通过完整 OHLC 门禁的行声明为 Canonical bars：

from datetime import UTC, datetime

with MarketDataClient("https://data.example.invalid", "service-token") as client:
    closes = client.get_close_series(
        symbols=(".NDX.US", ".SPX.US"),
        market="US",
        start=datetime(2021, 1, 1, tzinfo=UTC),
        end=datetime(2026, 1, 1, tzinfo=UTC),
        source="longbridge",
    )

同步与异步 Client 使用相同公共模型、稳定错误层级和兼容握手。搜索与详情成功响应 保留服务 request ID；K 线结果保留 request/result ID、row count、data version、 generated time 和 canonical hash。Client 只解释数据与协议事实，不决定业务是否运行。 Client 0.5.0 会在同步查询、异步查询和 get_result() 下载后，使用唯一基础 BARS_SCHEMA 对每个成功 item 重算 row count 和 canonical hash；任何内容、 result identity 或 Schema metadata 不一致都会明确失败，不会静默降级。