Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(data): declare per-market volume units in market-data provenance

shadowinlifeda7ae2e1aefd
diff --git a/agent/backtest/loaders/akshare_loader.py b/agent/backtest/loaders/akshare_loader.py
index eca72e875..b773198af 100644
--- a/agent/backtest/loaders/akshare_loader.py
+++ b/agent/backtest/loaders/akshare_loader.py
@@ -77,6 +77,11 @@ class DataLoader:
name = "akshare"
markets = {"a_share", "us_equity", "hk_equity", "futures", "fund", "macro", "forex"}
+ # stock_zh_a_hist empirically returns board lots (HKUDS/Vibe-Trading#1062;
+ # 600519.SH 2026-07-31 ratio 1.00 vs tencent/eastmoney). Note: akshare's
+ # own documentation states shares for this interface — the docs disagree
+ # with the actual behavior. Other markets stay undeclared.
+ volume_units = {"a_share": "lots"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/baostock_loader.py b/agent/backtest/loaders/baostock_loader.py
index 8fb6b4f13..7e66b9bd8 100644
--- a/agent/backtest/loaders/baostock_loader.py
+++ b/agent/backtest/loaders/baostock_loader.py
@@ -35,6 +35,11 @@ class DataLoader:
name = "baostock"
markets = {"a_share"}
+ # BaoStock natively reports volume in single shares, unlike the other
+ # A-share sources which report board lots (HKUDS/Vibe-Trading#1062).
+ # Empirically verified 2026-08-11: 600519.SH 2026-07-31 = 5,512,752
+ # shares vs tencent/eastmoney 55,128 lots (ratio exactly 100.0).
+ volume_units = {"a_share": "shares"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/base.py b/agent/backtest/loaders/base.py
index e19dca51b..ebd1934d0 100644
--- a/agent/backtest/loaders/base.py
+++ b/agent/backtest/loaders/base.py
@@ -617,7 +617,17 @@ def _duckdb_sql_string(path: Path) -> str:
@runtime_checkable
class DataLoaderProtocol(Protocol):
- """Interface that every data source loader must satisfy."""
+ """Interface that every data source loader must satisfy.
+
+ Optional class attribute ``volume_units: dict[str, str]`` (not part of the
+ structural check so existing loaders keep working): declares the unit of
+ the ``volume`` column per market, keyed by market name — e.g.
+ ``{"a_share": "lots", "hk_equity": "shares"}``. ``"lots"`` means board
+ lots (1 A-share lot = 100 shares); ``"shares"`` means single shares.
+ Sources differ natively (see HKUDS/Vibe-Trading#1062), so consumers must
+ read the per-symbol ``volume_unit`` from ``_provenance`` instead of
+ assuming a unit; a missing market entry surfaces as ``null`` (undeclared).
+ """
name: str
markets: set[str]
diff --git a/agent/backtest/loaders/eastmoney_loader.py b/agent/backtest/loaders/eastmoney_loader.py
index bc9582716..12887545f 100644
--- a/agent/backtest/loaders/eastmoney_loader.py
+++ b/agent/backtest/loaders/eastmoney_loader.py
@@ -54,6 +54,12 @@ class DataLoader:
name = "eastmoney"
markets = {"a_share", "hk_equity", "us_equity"}
+ # Volume unit is market-dependent (HKUDS/Vibe-Trading#1062): the A-share
+ # push2 endpoint reports board lots, the HK endpoint single shares —
+ # empirically verified 2026-08-11 (600519.SH ratio 1.00 vs tencent;
+ # 00700.HK ratio 1.00 vs tencent/yfinance). us_equity stays undeclared
+ # until empirically verified.
+ volume_units = {"a_share": "lots", "hk_equity": "shares"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/mootdx_loader.py b/agent/backtest/loaders/mootdx_loader.py
index 2fe9d0bbc..f9177c2e1 100644
--- a/agent/backtest/loaders/mootdx_loader.py
+++ b/agent/backtest/loaders/mootdx_loader.py
@@ -69,6 +69,11 @@ class DataLoader:
name = "mootdx"
markets = {"a_share"}
+ # Tongdaxin K-line convention is board lots (HKUDS/Vibe-Trading#1062).
+ # Tentative declaration: TDX quote servers were unreachable from the
+ # audit environment; the cross-source consistency test pins this at
+ # runtime where TDX access exists.
+ volume_units = {"a_share": "lots"}
requires_auth = False
def __init__(self) -> None:
diff --git a/agent/backtest/loaders/stooq_loader.py b/agent/backtest/loaders/stooq_loader.py
index 4b6aeac9b..18c9bff10 100644
--- a/agent/backtest/loaders/stooq_loader.py
+++ b/agent/backtest/loaders/stooq_loader.py
@@ -77,6 +77,9 @@ class DataLoader:
name = "stooq"
markets = {"us_equity"}
+ # Stooq US EOD volume is single shares (universal US convention,
+ # HKUDS/Vibe-Trading#1062).
+ volume_units = {"us_equity": "shares"}
requires_auth = False
def __init__(self) -> None:
diff --git a/agent/backtest/loaders/tencent_loader.py b/agent/backtest/loaders/tencent_loader.py
index 7e140356f..7180ce7e9 100644
--- a/agent/backtest/loaders/tencent_loader.py
+++ b/agent/backtest/loaders/tencent_loader.py
@@ -38,6 +38,11 @@ class DataLoader:
name = "tencent"
markets = {"a_share", "hk_equity"}
+ # Volume unit is market-dependent (HKUDS/Vibe-Trading#1062): the A-share
+ # endpoint reports board lots (1 lot = 100 shares) while the HK endpoint
+ # reports single shares. Empirically verified 2026-08-11 against
+ # 600519.SH (55,128 lots) and 00700.HK (31,100,240 shares).
+ volume_units = {"a_share": "lots", "hk_equity": "shares"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/tushare.py b/agent/backtest/loaders/tushare.py
index 66bed702f..187c1d595 100644
--- a/agent/backtest/loaders/tushare.py
+++ b/agent/backtest/loaders/tushare.py
@@ -119,6 +119,9 @@ class DataLoader:
name = "tushare"
markets = {"a_share", "hk_equity", "futures", "fund"}
+ # Tushare daily() documents vol in board lots (HKUDS/Vibe-Trading#1062).
+ # hk_equity (hk_daily) stays undeclared until empirically verified.
+ volume_units = {"a_share": "lots"}
requires_auth = True
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/yahoo_loader.py b/agent/backtest/loaders/yahoo_loader.py
index 1ccb531c5..a9c54ac17 100644
--- a/agent/backtest/loaders/yahoo_loader.py
+++ b/agent/backtest/loaders/yahoo_loader.py
@@ -178,6 +178,10 @@ class DataLoader:
markets = {
"us_equity", "hk_equity", "india_equity", "kr_equity", "ca_equity",
}
+ # Yahoo chart volume is single shares for US/HK equities
+ # (HKUDS/Vibe-Trading#1062; HK verified 2026-08-11, 00700.HK ratio 1.00
+ # vs tencent/eastmoney). Other equity markets stay undeclared.
+ volume_units = {"us_equity": "shares", "hk_equity": "shares"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/backtest/loaders/yfinance_loader.py b/agent/backtest/loaders/yfinance_loader.py
index de2cd088a..7dd0dcb59 100644
--- a/agent/backtest/loaders/yfinance_loader.py
+++ b/agent/backtest/loaders/yfinance_loader.py
@@ -234,6 +234,10 @@ class DataLoader:
markets = {
"us_equity", "hk_equity", "india_equity", "kr_equity", "ca_equity", "crypto",
}
+ # yfinance volume is single shares for US/HK equities
+ # (HKUDS/Vibe-Trading#1062; HK verified 2026-08-11, 00700.HK ratio 1.00
+ # vs tencent/eastmoney). Crypto base-asset units stay undeclared.
+ volume_units = {"us_equity": "shares", "hk_equity": "shares"}
requires_auth = False
def is_available(self) -> bool:
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index f7e52b262..f14f85a28 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -1576,6 +1576,12 @@ def get_market_data(
even-stride downsample (every step-th bar, last bar pinned)
plus truncation metadata. Set max_rows=0 for all rows
(unbounded, legacy behavior).
+
+ Volume units: the ``volume`` column unit is source- and market-dependent
+ (A-share sources report board lots of 100 shares; HK/US sources report
+ single shares). Each symbol's ``_provenance.volume_unit`` states the unit
+ of the returned rows ("lots" / "shares"; null = source undeclared) — read
+ it before interpreting or comparing volume values across symbols/sources.
"""
return fetch_market_data_json(
codes=codes,
diff --git a/agent/src/market_data.py b/agent/src/market_data.py
index d27917e40..3aaf9d6e9 100644
--- a/agent/src/market_data.py
+++ b/agent/src/market_data.py
@@ -114,6 +114,13 @@ def fetch_market_data(
the market's :data:`backtest.loaders.registry.FALLBACK_CHAINS` (e.g. crypto
OKX → Binance → CCXT → Yahoo). At most ``max_fallback_attempts`` retries
are attempted before the symbol is recorded as ``_unresolved``.
+
+ With ``include_provenance=True`` each symbol carries ``_provenance``
+ metadata including ``volume_unit`` — the unit of the ``volume`` column as
+ declared by the serving loader for that market (``"lots"`` = board lots of
+ 100 shares, ``"shares"`` = single shares, ``None`` = undeclared). Volume
+ units are source- and market-dependent (HKUDS/Vibe-Trading#1062), so
+ consumers must read this field instead of assuming a unit.
"""
from backtest.engines._market_hooks import _detect_market
from backtest.loaders.base import NoAvailableSourceError
@@ -167,6 +174,7 @@ def fetch_market_data(
data_map: dict[str, Any] = {}
used_source: str | None = None
+ provider_cls: type | None = None
for attempt_src in attempts:
try:
loader_cls = loader_resolver(attempt_src)
@@ -180,6 +188,7 @@ def fetch_market_data(
loader = loader_cls()
data_map = loader.fetch(src_codes, start_date, end_date, interval=interval)
used_source = attempt_src
+ provider_cls = loader_cls
if data_map:
break
except Exception as exc: # noqa: BLE001 — contained per-symbol fallback
@@ -202,12 +211,14 @@ def fetch_market_data(
row[key] = _json_safe(value)
results[symbol] = cap_rows(records, max_rows)
if include_provenance:
+ volume_units = getattr(provider_cls, "volume_units", None) or {}
provenance[symbol] = {
"source": used_source or src,
"requested_source": source,
"detected_source": src,
"fallback_used": bool(used_source and used_source != src),
"currency_conversion": "none",
+ "volume_unit": volume_units.get(market),
}
unresolved = [
diff --git a/agent/src/tools/market_data_tool.py b/agent/src/tools/market_data_tool.py
index c088ebd1d..3fc5ded9b 100644
--- a/agent/src/tools/market_data_tool.py
+++ b/agent/src/tools/market_data_tool.py
@@ -15,7 +15,10 @@ class MarketDataTool(BaseTool):
description = (
"Fetch normalized OHLCV market data through the repository loader layer. "
"Use this for stock, ETF, index, or crypto price bars before writing raw "
- "yfinance/OKX/Tushare scripts."
+ "yfinance/OKX/Tushare scripts. Volume units are source- and market-dependent "
+ "(A-share sources report board lots of 100 shares, HK/US sources report single "
+ "shares); read the per-symbol _provenance.volume_unit field ('lots' / 'shares' / "
+ "null=undeclared) before interpreting or comparing volume values."
)
parameters = {
"type": "object",
diff --git a/agent/tests/test_loader_volume_units.py b/agent/tests/test_loader_volume_units.py
new file mode 100644
index 000000000..1acf8485f
--- /dev/null
+++ b/agent/tests/test_loader_volume_units.py
@@ -0,0 +1,54 @@
+"""Pin the volume-unit declarations of equity loaders (HKUDS/Vibe-Trading#1062).
+
+A-share sources natively report board lots (1 lot = 100 shares) while
+baostock reports single shares; the tencent/eastmoney loaders are
+market-dependent (A-share lots vs HK shares). These pins lock the audit
+matrix from issue #1062 so a declaration cannot drift silently — the
+cross-source 100x discrepancy that motivated the fix was exactly such a
+silent drift.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from backtest.loaders.akshare_loader import DataLoader as AkshareLoader
+from backtest.loaders.baostock_loader import DataLoader as BaostockLoader
+from backtest.loaders.eastmoney_loader import DataLoader as EastmoneyLoader
+from backtest.loaders.local_loader import DataLoader as LocalLoader
+from backtest.loaders.mootdx_loader import DataLoader as MootdxLoader
+from backtest.loaders.stooq_loader import DataLoader as StooqLoader
+from backtest.loaders.tencent_loader import DataLoader as TencentLoader
+from backtest.loaders.tushare import DataLoader as TushareLoader
+from backtest.loaders.yahoo_loader import DataLoader as YahooLoader
+from backtest.loaders.yfinance_loader import DataLoader as YfinanceLoader
+
+
+ ("loader_cls", "market", "expected"),
+ [
+ (TencentLoader, "a_share", "lots"),
+ (TencentLoader, "hk_equity", "shares"),
+ (EastmoneyLoader, "a_share", "lots"),
+ (EastmoneyLoader, "hk_equity", "shares"),
+ (BaostockLoader, "a_share", "shares"),
+ (MootdxLoader, "a_share", "lots"),
+ (AkshareLoader, "a_share", "lots"),
+ (TushareLoader, "a_share", "lots"),
+ (YahooLoader, "us_equity", "shares"),
+ (YahooLoader, "hk_equity", "shares"),
+ (YfinanceLoader, "us_equity", "shares"),
+ (YfinanceLoader, "hk_equity", "shares"),
+ (StooqLoader, "us_equity", "shares"),
+ ],
+)
+def test_loader_volume_unit_declaration(loader_cls, market, expected):
+ assert getattr(loader_cls, "volume_units", {})[market] == expected
+
+
+def test_undeclared_markets_surface_as_missing_not_wrong():
+ """Markets without evidence stay undeclared (null), never guessed."""
+ assert "crypto" not in YfinanceLoader.volume_units
+ assert "us_equity" not in EastmoneyLoader.volume_units
+ assert "hk_equity" not in TushareLoader.volume_units
+ assert getattr(LocalLoader, "volume_units", {}) == {}
diff --git a/agent/tests/test_market_data_tool.py b/agent/tests/test_market_data_tool.py
index afe0ad032..22644b4ca 100644
--- a/agent/tests/test_market_data_tool.py
+++ b/agent/tests/test_market_data_tool.py
@@ -93,9 +93,94 @@ def test_market_data_json_can_include_actual_source_provenance():
"detected_source": "yahoo",
"fallback_used": True,
"currency_conversion": "none",
+ "volume_unit": None,
}
+def test_market_data_provenance_exposes_declared_volume_unit():
+ """Serving loaders declare per-market volume units (#1062)."""
+ idx = pd.date_range("2026-01-01", periods=1, freq="D")
+ idx.name = "trade_date"
+ df = pd.DataFrame(
+ {
+ "open": [1.0],
+ "high": [1.1],
+ "low": [0.9],
+ "close": [1.05],
+ "volume": [100],
+ },
+ index=idx,
+ )
+
+ class _UnitAwareLoader:
+ volume_units = {"a_share": "lots", "hk_equity": "shares"}
+
+ def fetch(self, codes, start, end, interval="1D"):
+ return {code: df for code in codes}
+
+ payload = json.loads(
+ fetch_market_data_json(
+ codes=["600519.SH", "0700.HK"],
+ start_date="2026-01-01",
+ end_date="2026-01-02",
+ source="tencent",
+ loader_resolver=lambda source: _UnitAwareLoader,
+ include_provenance=True,
+ )
+ )
+
+ assert payload["_provenance"]["600519.SH"]["volume_unit"] == "lots"
+ assert payload["_provenance"]["0700.HK"]["volume_unit"] == "shares"
+
+
+def test_market_data_provenance_volume_unit_follows_serving_loader():
+ """After fallback, the unit comes from the loader that actually served."""
+ idx = pd.date_range("2026-01-01", periods=1, freq="D")
+ idx.name = "trade_date"
+ df = pd.DataFrame(
+ {
+ "open": [1.0],
+ "high": [1.1],
+ "low": [0.9],
+ "close": [1.05],
+ "volume": [100],
+ },
+ index=idx,
+ )
+
+ class _PrimaryLoader:
+ volume_units = {"a_share": "lots"}
+
+ def fetch(self, codes, start, end, interval="1D"):
+ raise RuntimeError("primary unavailable")
+
+ class _FallbackLoader:
+ volume_units = {"a_share": "shares"}
+
+ def fetch(self, codes, start, end, interval="1D"):
+ return {codes[0]: df}
+
+ def _resolver(source: str):
+ return _PrimaryLoader if source == "tencent" else _FallbackLoader
+
+ payload = json.loads(
+ fetch_market_data_json(
+ codes=["600519.SH"],
+ start_date="2026-01-01",
+ end_date="2026-01-02",
+ source="tencent",
+ loader_resolver=_resolver,
+ fallback_chain_provider=lambda source: ["tencent", "baostock"],
+ include_provenance=True,
+ )
+ )
+
+ prov = payload["_provenance"]["600519.SH"]
+ assert prov["source"] == "baostock"
+ assert prov["fallback_used"] is True
+ assert prov["volume_unit"] == "shares"
+
+
def test_market_data_json_is_strict_when_loader_returns_nan():
idx = pd.date_range("2026-01-01", periods=1, freq="D")