Broker accounts

broker 账户是通往你实际交易场所的只读密钥。它回答三个不该再手工重复输入的问题：我成交了什么、我持有什么、我挂了什么单。

可在设置 → Brokers 中管理，或通过任何读取你账本的模块放在其账户选择器旁边的 Brokers 按钮管理。两者显示的是同一个界面。

只读，从构造上保证

broker 账户只读，而且只读：其背后没有任何路由会下单、修改或撤销订单。向你索取的凭据是只读类型的，所以请恰好提供这种：当 broker 能签发仅查看密钥时，表单会这样说明。如果将来发布订单路由，它会是一个独立的功能，索取它自己的密钥和权限，并会在这里说明。

请勿与 data connector 混淆：后者读取价格，这里读取你的账户。两种不同的凭据、两份不同的列表、两种不同的授权，这是有意为之。

连接需要什么

Broker	凭据	需要授予的权限	读取
Alpaca	api_key、api_secret	你所选环境的 Trading API 密钥（实盘或模拟，它们是不同的密钥）	成交、持仓、订单、资产
Binance	api_key、api_secret	仅 Enable Reading。不含交易、不含提现	成交、订单、资产
Binance USDⓈ-M Futures	api_key、api_secret	Enable Reading 加期货权限。不含交易、不含提现	成交、持仓、订单、保证金余额
Bitget	api_key、api_secret、api_passphrase	Read-only。不含交易、不含提现	成交、持仓、订单、资产
OKX	api_key、api_secret、api_passphrase	仅 Read。不含交易、不含提现	成交、持仓、订单、资产
OANDA	api_token + 账户 ID	个人访问 token。OANDA 没有只读 token：同一个 token 可以交易	成交、持仓、订单、资产
Coinbase Advanced Trade	api_private_key + 完整的密钥名称	CDP 密钥，仅 View，以 Ed25519 创建。不含 Trade、不含 Transfer	成交、订单、资产
TradeStation	client_id、client_secret、refresh_token + 账户 ID	授予 ReadAccount、MarketData、openid、offline_access 的 OAuth 登录。不含 Trade	成交、持仓、订单、资产
FOREX.com (StoneX)	username、password、app_key	你的登录信息加 StoneX 签发的 AppKey。不存在只读凭据	成交、持仓、订单、资产
Capital.com	api_key、identifier、api_password	一个 API 密钥（必须开启双因素）及其自定义密码。没有只读等级	成交、持仓、订单、资产
NinjaTrader	username、password、cid、sec	平台登录加开发者 API 密钥对。没有只读密钥	成交、持仓、订单、资产
Kraken	api_key、api_secret	Query Ledger & Trade History 和 Query Open Orders	成交、订单、资产
Interactive Brokers (Flex)	flex_token + 一个 Flex query id	Flex Web Service token：它读取对账单，无法交易	成交、持仓、资产

机密是只写的：应用只知道设置了哪些名称。可以直接输入，或从保险库接入，这样一个密钥可以服务多个账户。

各 broker 说明

• Alpaca：Environment 设置为 live 或 paper，必须明确指定而不是猜测，因为两者位于不同的主机，使用不同的密钥。Alpaca 不报告成交的佣金，所以导入的交易不带手续费：对免佣金股票是正确的，对加密货币和期权则低于实际，它们的手续费作为单独的账户活动到达。
• Binance，无论现货还是期货，都一次只回答一个品种的成交历史，所以拉取必须指明品种（BTCUSDT、ETHEUR）。这里的其他每个 broker 都回答整个账户。
• **三家加密货币交易场所止步于 90 天。**Bitget、OKX 和 Binance 期货通过 API 只提供三个月的成交，再早的需要从它们的网站下载。导入对话框会显示此限制，并拒绝早于它的时间段，而不是悄悄返回一个不完整的答案。
• **衍生品账户不同于现货账户。**Bitget、OKX 和 Binance 期货可以做空，所以那里默认勾选该账户可以做空。对于仅设为现货账簿的 Bitget 账户，请取消勾选：没有未平仓头寸的现货卖出，是卖掉先前买入的币，而不是做空。
• **合约按张计数。**OKX 以张报告衍生品成交，并公布一张的价值（ctVal × ctMult），该值从其品种列表中读取，并作为该交易的点值携带。Bitget USDT-M 和 Binance USDⓈ-M 合约以基础币计量，所以它们的点值为一。Coin-M（反向）合约在任何地方都不读取：它们以计价货币计量，其盈亏不是数量乘以价格。
• **TradeStation 是唯一使用 OAuth 的。**没有静态密钥：一次性的浏览器登录会产生 refresh token，应用随时把它兑换为 20 分钟有效的访问 token。在该登录时授予 ReadAccount、MarketData、openid 和 offline_access，并去掉 Trade；能交易的 token 是白白留下的长期风险。这里的成交是一个订单腿，因为 TradeStation 发布的是已关闭的订单而不是执行记录，重新同步用于去重的标识是订单 ID 加上该腿在其中的位置。
• FOREX.com 是登录，而不是用密钥。凭据是账户自己的用户名和密码，加上签署其 API 条款后 StoneX 一次性签发的 AppKey，所以同一个登录可以交易：请把它当作完全访问的机密，并在移除账户时更改密码。从那里导入的交易不含佣金，因为 StoneX 通过点差收费；如果你的账户改收佣金，这里的数字会低于实际。成交历史端点不接受结束日期，也没有游标，所以较宽的时间段会按每页 200 条向前遍历。
• **Capital.com 一次只回答一天。**它的活动日志把两个日期之间的范围上限设为 24 小时，所以一年的交易每天要一次调用；超过 400 天的时间段会被明确拒绝，而不是任其撞上速率限制器。平台上的每个品种都是 CFD，所以股票 CFD 会被归为衍生品，而不是股票本身，这正是税表想要的。deal id 指的是一个头寸而不是一笔成交，所以重新同步用于去重的标识是 deal、它的时间戳和它的方向三者合在一起。
• NinjaTrader 每个登录允许两个会话，第三个会关闭最旧的那个：这个 connector 占一个，与它并存登录的交易应用占另一个。它的交易 API 是其收购的 Tradovate 平台，这也是错误信息中出现 tradovateapi 的原因。它回答其会话能看到的成交，并且不公布深度限制，所以在依赖它做某个税务年度之前，请先检查首次拉取返回的最早一行。期货点值是从合约的产品中读取的，绝不会从根代码假定。
• **OANDA 不提供只读 token。**读取该账户的个人访问 token 也可以用来交易，所以表单会这样说明：请把它当作完全访问的凭据，并在移除账户时撤销它。应用中没有任何地方会用它来写入。
• Interactive Brokers 根本不是 API 密钥：它通过 Flex Web Service 读取保存的报表。设置、时间段规则和时区设置见下方单独一节。
• 速率限制是 broker 的，每一行都显示适用的那个。IBKR 是最严格的：它按需构建对账单，并在上一个仍在生成时拒绝第二个请求。

连接一个

1. 添加账户，选择 broker 并命名：这个名称就是模块选择器中显示的内容，所以 Kraken main 比 Kraken 2 更好。
2. 填写凭据，或从保险库中选择。缺少凭据的账户会显示为不完整，在你设置之前，每个模块都会跳过它。
3. 填写 broker 需要的非机密设置：环境（Alpaca、Binance 期货、TradeStation、Capital.com、NinjaTrader）、账户 ID（OANDA、TradeStation、Capital.com、FOREX.com、NinjaTrader）、Coinbase 密钥名称、IBKR query id 和偏移量，或 Bitget 账簿。
4. 选择它服务的模块，或所有模块。
5. 测试连接会联系 broker 并报告应答内容：账户号码和状态、多少资产有余额，或 Flex token 返回了哪份对账单。如果有问题，错误信息会指出要更改的设置。

授权在服务端强制执行：请求一个从未授予它的账户的模块会被拒绝。

它能让你做什么

四个目的地，一个形状。无论你导入什么、落在哪里，broker 导入都与文件导入走同样的两条轨道：

1. **先拉取，再查看。**应用询问 broker，把答案折叠成模块所存储的形式（journal 的头寸、投资组合的资产负债表、税表的已平仓处置），并展示给你。这一步不写入任何内容，所以你不喜欢的拉取不会有任何代价。
2. **提交，并保留线索。**写入的所有内容都带有该次导入的 id，因此之后它仍是一个整体：Revert 恰好删除它创建的内容，不多不少；Keep, untrack 切断链接，让这些行保留原位。两者都在模块的导入历史中。

重复项是这条轨道的工作，而不是你的。每个导入的行都有指纹，所以再次拉取重叠的时间段时，会识别出已有内容，在预览中标记出来，并只写入一次。

将交易导入 journal

Journal → Import → Pull from a broker。选择账户、时间段和要归档到的账簿，成交会被折叠成头寸返回，并在写入任何内容之前预览。

1. **账户。**只列出授权给 journal 的账户，不完整的会注明。某个账簿上次使用的账户和时间段会被记住，所以下一次拉取只需点两下。
2. 时间段，按日期或使用 7 / 30 / 90 / 365 天快捷项。请将其理解为成交所在的窗口，而不是交易平仓所在的窗口：头寸是由时间段内的成交折叠而成的，所以要足够早地开始，以便抓到入场。
3. **品种。**Binance 一次只回答一个品种的历史，所以那里必须填写品种，Suggest 会提供账户持有的品种。其他地方该字段是过滤器：留空表示整个账户。
4. **做空。**现货账户不能做空，所以没有未平仓头寸的卖出会作为行错误报告，并指出解决办法（扩大时间段），而不是变成虚构的空头。在保证金账户上，请勾选该账户可以做空。
5. 预览，然后导入。计数器包括成交数、交易数（其中已平仓和未平仓的各多少），以及账簿中已有的和无法构建的。每一行在你提交之前都会说明它属于哪种。

• 目的地和折叠方式与文件导入相同，只是没有映射：API 返回类型明确的字段，因此 CSV 带来的问题（哪一列是日期、小数是不是逗号）在这里不存在。
• **重复运行是安全的。**头寸的标识是它的开仓成交，所以扩大窗口并再次拉取，会刷新此后已平仓的部分，其余保持不动，而不是把同一笔交易归档两次。
• **刷新仅限机械数据。**价格、数量、手续费和日期再次来自 broker；你的笔记、标签、策略和模板字段属于你，刷新后仍然保留。

让投资组合与账户持仓对齐

Portfolio → From a broker。它读取的是资产负债表，而不是成交历史：与你的账本之间的差异会逐行显示，你选择要对齐哪些行。你接受的每一行都会写入使投资组合一致的那一个操作。

• 投资组合已持有的品种会自行解析；其他的会询问，因为交易所上的“BTC”是一个字符串，而这里的资产是一个价格来源。
• **成本基础绝不会虚构。**Interactive Brokers 会发布一个，并且会使用它。加密货币交易所只发布数量，别无其他，所以这些行会如实说明，并默认使用今天的价格，这是唯一不会被误认为对过去所作声明的价格。
• **从交易所获取价格。**对于没有成本基础的行，点击一下会向交易场所询问该资产此刻的成交价并填入价格。随后该行会指明应答的市场（BTCUSDT、XBT/USD），并在该市场的计价货币不是资产自身货币时说明这一点：Binance 的价格以 USDT 计，而不是美元。交易场所没有报价的资产会被保持原样，而不是从别处估值，由你自己输入价格。

Alpaca、Binance（现货和期货）、Bitget、Coinbase、Kraken、OKX、OANDA 和 TradeStation 能回答这个问题。Interactive Brokers Flex 不行：对账单不是报价源；FOREX.com 以数字 ID 而不是投资组合行所带的名称给市场报价；NinjaTrader 通过单独的行情数据权限提供价格。Capital.com 以其交易的买卖双方的中间价作答。

在图表上画出你的账簿

Chart → Broker book。同步一个账户后，它的头寸和挂单会作为价位绘制在匹配品种的图表上，头寸为平均成本，订单为限价和止损。匹配依据代码，忽略标点。没有平均成本的头寸不会有线，并会如实计数。

读取税务年度

Taxes → From a broker。拉取成交，将其折叠为已平仓头寸，并汇总税务年度内已实现的部分，分摊到税表的资本、衍生品和加密货币几行。它不写入任何内容：你自己把数字应用到表单上，并自行保存该情景。

• **窗口不是税务年度。**你在三月卖出的是更早买入的，没有那笔买入就没有成本基础：请把起始日期往前移足够远以覆盖它。缺少买入记录的处置会被报告，绝不会针对空值估值。
• 每个已平仓头寸都按其自身退出日期的汇率换算。没有汇率的会被列出并排除在合计之外，而不是用错误的货币加进去。

Interactive Brokers：Flex Web Service

IBKR 是这里唯一不通过交易 API 读取的 broker。它通过 Flex（Account Management 的报表服务）读取：你保存一个描述对账单内容的查询，应用用 token 通过 HTTPS 获取该对账单。

为什么用 Flex 而不是 TWS

行情数据 connector 通过 TWS socket 与你自己运行的 Gateway 通信。该 socket 是处理当下的正确工具，却是处理历史的错误工具：它回答未平仓头寸和当前会话的成交，所以“导入我三月的交易”根本没有 socket 形式。Flex 提供时间段，这正是导入所提出的问题。

实际区别：

	Flex Web Service	TWS / IB Gateway socket
你要运行什么	什么都不用，这是一个 HTTPS 调用	在机器上登录的 Gateway 或 TWS
历史	查询的时间段，最多回溯一年	仅当前会话
凭据	读取报表的 token	你的实时会话，能够交易
在这里用于	journal 导入、投资组合资产、税务年度、图表头寸	价格、图表、实时 K 线

为什么这是安全的入口

• **token 无法交易。**它是为 Flex Web Service 签发的，而该服务提供的是对账单。它背后没有需要记得禁用的订单端点，也没有可能选错的权限复选框。对比交易所 API 密钥，只读是你必须记得勾选的一个框。
• **没有任何东西在监听。**没有运行的 Gateway，没有开放的 API 端口，没有需要声明的 Trusted IP，应用空闲时你的机器上没有任何东西在等待。
• **它会自行过期。**IBKR 给 token 设定有效期，并在过期前发送邮件提醒。被遗忘的 token 会失效，而不是永远有效。
• **查询就是围栏。**token 只能返回你保存的查询所描述的内容。把查询限制为交易和未平仓头寸，那就是应用能看到的全部，无论它请求什么。
• 与这里的每个凭据一样，token 在应用中只写：可以直接输入或从保险库接入，之后不再显示。

一次拉取实际是如何运行的

1. 应用用你的 token 和 query id 调用 SendRequest。IBKR 返回一个参考码，并开始构建对账单。
2. 随后它用该参考码轮询 GetStatement，直到 XML 到达，通常需要几秒钟，查询范围较宽时可能更久。对账单仍在生成是最初几次尝试的预期答复，而不是错误。
3. 对账单被解析为成交（执行级别的 Trade 行）和持仓（Open Positions），应用再按你选择的时间段过滤它们。

如果一分钟后 IBKR 仍在生成，应用会如实说明，而不是一直挂起：请缩小查询的日期范围，或稍后再试。

设置

1. token：Account Management → Settings → Flex Web Service。生成一个，只复制一次，记下到期日期。

2. 查询：Account Management → Performance & Reports → Flex Queries → 新建 Activity 查询。包含：

   • Trades，详细程度 Execution，用于 journal 和税表；
   • Open Positions，用于投资组合对齐和图表叠加。

   保存并记下 query id，即显示在其名称旁边的数字。

3. 在 OpenTraderWorld 中：添加账户，粘贴 token，填写 Flex query id 和 Statement time offset，然后测试连接。它会报告账户号码、对账单覆盖的时间段以及它携带的交易行数，这是发现查询缺少某一部分的最快方式。

决定导入是否正确的两项设置

时间段是查询的，不是你的。Flex 查询自带日期范围（Last 365 Calendar Days、Year to Date、自定义窗口），而该 web 服务根本不接受日期。你在应用中选择的日期是对返回的对账单进行过滤，所以设为 Last 30 days 的查询无论你回溯多远都不会产出三月的数据，而且 IBKR 提供的数据不超过一年。把查询设宽，在应用中过滤。

**Flex 对账单从不指明其时区。**它按查询自己的时区打时间戳，却没有说明是哪个，所以请把 Statement time offset 设为该时区对应的分钟数（纽约冬令时为 -300，巴黎为 60），否则每笔成交都会落在错误的小时，日内交易会落在错误的日期。

Flex 做不到的

• 没有挂单，所以图表叠加按平均成本绘制 IBKR 头寸，没有订单价位。
• 没有报价。对账单不是价格源：投资组合的从交易所获取价格按钮由 API broker 提供，这里没有。IBKR 是五者中唯一发布成本基础的，而这正是账本最重要的数字。
• **一次一份对账单。**IBKR 按需构建，并在上一份仍在生成时拒绝第二个请求，所以对同一查询连续发起的拉取会彼此等待。

模块授权

模块	它读取什么
Trading Journal	时间段内的成交，用于导入
Portfolios	账户持有的内容
Visualization	头寸和挂单，用于图表叠加
Tax Calculator	一个税务年度的成交

勾选所有模块会折叠回所有模块通配符，它也涵盖未来版本中新增的模块。

限制

• **代码绝不会被猜测。**应用无法解析的品种是一个指明解决办法的错误，而不是尽力而为的匹配。
• broker 不发布的内容保持为空，而不是看似合理：不虚构成本基础，不虚构手续费，不虚构方向。
• 删除账户会移除其凭据。它已经导入的内容会保留。
• broker 账户在演示模式下被禁用。