alpaca-broker-money-precision

Alpaca — 资金与数值精度

金融错误往往悄无声息，却代价高昂。Alpaca 的传输格式和十进制运算的实际情况会带来一些特定陷阱。本指南篇幅短、观点明确，且不依赖特定语言。

请先阅读 alpaca-broker-integration，了解基础 URL 和身份验证（客户端凭据 Bearer 令牌；旧版 Basic 仍然可用）。

1. 数字以字符串形式返回——保持原样

Alpaca 会将价格、数量、名义金额和资金金额作为 JSON 字符串（"100.50"、"1.5"、"190.2345"）返回，提交时也接受字符串。这是有意为之：这样可以避免 JSON 二进制浮点数带来的精度损失。

规则： 将字符串形式的资金字段解析为 十进制类型，绝不要使用二进制 float/double。序列化时再转回字符串。资金处理流程中绝不能让数字以 IEEE-754 浮点数的形式存在。

语言	使用	避免
Python	decimal.Decimal("100.50")	float("100.50")
TypeScript/JS	十进制库（decimal.js/big.js）或字符串运算	Number(...)、parseFloat
Go	shopspring/decimal	用 float64 累加
Java/Kotlin	java.math.BigDecimal	double

实际情况提醒：并非每个 Alpaca 端点都一致——一些市场数据数值字段会以 JSON 数字形式返回（例如 K 线 OHLC）。用于显示/分析的价格可以使用浮点数；但要转移或存储的资金绝不能如此。务必弄清自己处理的是哪个字段。

2. 发送前进行舍入/截断——并弄清方向

订单的 notional 最多接受 2 位小数，qty 最多接受 9 位小数（Broker API 常见问题；订单架构中 qty 的“2 位小数”规定已过时）。Journal 的 amount 没有文档说明的精度限制——但现金仍应按 2 位小数发送（§3）。

规则： 在调用 API 之前，明确地按目标精度进行舍入/截断，并有意识地选择舍入模式。

• 对于要转出/收取的资金，按 2 位小数截断（向下舍入），确保转出的金额不超过预期（例如 floor(amount * 100) / 100）。这是内部政策，不是 API 限制，且仅适用于现金——绝不要用这种方式截断股票 qty。
• 有意识地选择舍入模式（ROUND_DOWN 与 ROUND_HALF_UP）——不要沿用浮点数格式化的默认行为。
• 运算过程中保留完整精度，只在发送或显示数值的边界处舍入一次。中间步骤舍入会累积误差。

# splitting a deposit across holdings — round each slice down, track remainder
slice = truncate(total * (pct / 100), 2)

3. 零碎股

• notional 接受 2 位小数，qty 接受 9 位小数。发送前分别按各自的限制舍入。
• qty 与 notional 二选一——绝不能同时提供（参见 alpaca-broker-trading-orders）。
• 不要用 notional / price 重新计算 qty 并发送——请传入 notional，让 Alpaca 计算成交量。通过你获取的价格进行往返换算会引入偏差。

4. 存储

• 在数据库中将资金存为定点十进制数，而不是浮点数；精度至少要达到所接收字段中最高的精度——qty 的精度至少为 9，这样 9 位小数的零碎股场景就不会被静默截断。
• 逐字保存 Alpaca 发送的值，并同时保留任何转换值/派生值。如果为 API 调用将数值截断到 2 位小数，但返回值带有更高精度，就两种值都保留——这样才能进行对账和审计。
• 明确保留 currency 列；Alpaca 的某些通道（资金钱包）支持多种货币，尽管大多数交易使用 USD。

5. 多币种说明

• 大多数 Broker/交易流程使用 USD；journal 默认使用 USD。
• 资金钱包通道支持多种货币（USD、EUR、JPY 等），并会产生外汇费用。使用该通道时，绝不要假定货币为 USD——读取并存储 currency，并在整个处理流程中将外汇金额视为十进制数。

6. 检查清单

• 将字符串格式的金额字段解析为 decimal 类型；序列化时再转回字符串。
• 资金转移路径中 不使用二进制浮点数。
• 调用前，将金额舍入或截断到允许的精度，并明确舍入模式（转出资金时向下舍入）。
• 算术运算中保留完整精度；仅在发送或显示时舍入一次。
• 数据库列使用小数位数 ≥ 9 的定点十进制类型；原样存储 Alpaca 值。
• 显式跟踪货币。

相关技能： 订单数量／名义金额规则 → alpaca-broker-trading-orders；日记账／转账金额 → alpaca-broker-journals、alpaca-broker-funding-transfers；核对存储值与 Alpaca 值 → alpaca-broker-reconciliation-idempotency。