按币种账户值前缀

这个设置影响账户数据回调里的字段名，尤其是多币种账户。

官方位置：

File / 文件 -> Global Configuration / 全局配置 -> API -> Settings / 设置
Checkbox: Prepend "$LEDGER-" prefix to per-currency account values

为什么需要这个设置

订阅账户更新时，TWS API 会返回两类数据：

类型	含义
Account-level values	整个账户级别的汇总值。
Per-currency values	按币种拆开的 ledger 值。

问题是，某些 key 会重复出现。例如 AccruedCash 既可能代表账户汇总，也可能代表某个币种的 ledger 值。只看 key 很难判断来源。

启用前后对比

未启用时：

key	currency	含义
AccruedCash	USD	可能是账户级，也可能是 USD ledger。
AccruedCash	EUR	可能是 EUR ledger。

启用后：

key	currency	含义
AccruedCash	USD	账户级汇总值。
$LEDGER-AccruedCash	USD	USD ledger 值。
$LEDGER-AccruedCash	EUR	EUR ledger 值。

新老用户差异

官方说明：

• 新用户默认启用，按币种 key 会带 $LEDGER- 前缀。
• 升级用户可能默认关闭，用来避免破坏旧程序。

如果你的程序已经按旧字段名解析账户数据，启用前要先改解析逻辑。

代码解析建议

解析账户数据时，不要只按 key 建一个字典覆盖旧值。更稳妥的结构是同时保留 key、currency 和来源含义：

def normalize_account_value(key: str, value: str, currency: str) -> dict:
    # $LEDGER- 前缀表示这是按币种拆分的 ledger 字段。
    is_ledger_value = key.startswith("$LEDGER-")
    normalized_key = key.removeprefix("$LEDGER-")

    return {
        "key": normalized_key,
        "raw_key": key,
        "value": value,
        "currency": currency,
        "is_ledger_value": is_ledger_value,
    }

字段解释：

字段	含义
key	去掉 $LEDGER- 后的标准字段名，方便统一展示。
raw_key	TWS 原始返回字段，方便排查兼容性问题。
currency	币种，例如 USD、EUR、BASE。
is_ledger_value	是否为按币种拆分的 ledger 值。

官方依据

官方 TWS API 文档说明了该设置，用于区分账户级字段和按币种 ledger 字段。实际默认状态可能受账户创建时间、TWS / IB Gateway 版本和历史设置影响，开发时应以当前 TWS 设置页与实际回调为准。

• IBKR TWS API Documentation