Alpaca 券商金额精度

要解决的问题

金融类 Bug 往往静默发生，等发现账目不对时已经很难回溯。Alpaca 的报文格式与 JSON 浮点数的现实之间存在几个特定陷阱：金额字段以字符串传输，顺手转成 float 或 double，十进制精度在入库那一刻就丢了；发送前不做显式舍入，可能被服务端拒收或静默截断；用自己取回的价格反推数量再下单，也会引入漂移。

核心能力与关键步骤

这套规则语言无关、观点明确，直接落到代码层面：

• 字符串进出，decimal 运算：price、qty、notional 等字段保持为字符串，解析时进入十进制类型——Python 用 decimal.Decimal，TypeScript 用 decimal 库，Go 用 shopspring/decimal，Java/Kotlin 用 BigDecimal。资金路径上不允许出现 IEEE-754 浮点数。
• 发送前显式舍入：现金金额一般接受 2 位小数，碎股 qty/notional 最多 9 位。调用 API 之前就要按目标精度舍入，并明确选择舍入模式——转出或扣款场景一律向下取整，例如 floor(amount * 100) / 100，不要继承语言默认的浮点格式化行为。
• 每步重算后再舍入：拆分金额这类中间计算会重新引入精度，每一步之后都要重新对齐，而不是只在最后处理一次。
• 碎股下单：qty 与 notional 二选一，永远不要同时传；不要由 notional / price 反推 qty 再发送，直接传 notional，让 Alpaca 计算成交。
• 存储：数据库用定点小数（如 DECIMAL(20, 8)）并留足精度余量；同时原样保存 Alpaca 返回的值，与转换后的派生值分开存放，便于对账与审计；显式记录币种。
• 多币种：交易流大多是 USD，但 funding wallet 通道支持多种货币且带换汇费用，涉及它时必须读取并存储币种，换汇金额端到端按十进制处理。

适用边界与注意点

并非所有端点都一致：部分行情字段（如 bar 的 OHLC）以 JSON 数字返回。用于展示或分析的价格可以容忍浮点，但要移动或存储的资金不能，先确认当前字段属于哪一类。这套技能只覆盖精度规则，下单字段约束、转账与对账请参考相关的 Alpaca broker 技能。