用途:帮助开发者在使用 Alpaca API 时正确处理金额与数值精度,避免静默且昂贵的金融计算错误。该技能语言无关,建议先阅读 alpaca-broker-integration。
主要能力与规则:
- 数字以字符串传输。Alpaca 返回的价格、数量、名义金额和金额均为 JSON 字符串(如 "100.50"、"1.5"、"190.2345"),入参也接受字符串,以避免 JSON 二进制浮点的精度损失。应将字符串金额解析为 decimal 类型,绝不使用二进制 float/double,再序列化回字符串。Python 用 decimal.Decimal("100.50"),TypeScript/JS 用 decimal.js/big.js 或字符串运算,Go 用 shopspring/decimal,Java/Kotlin 用 java.math.BigDecimal。注意并非所有端点一致,部分行情数值字段(如 bar OHLC)是 JSON 数字;展示/分析可用浮点,但移动或存储的金额不可。
- 发送前舍入/截断。现金金额一般接受 2 位小数,分数股 qty/notional 最多 9 位。应在调用前显式按目标精度舍入/截断,并选择明确的舍入模式;对外支付/扣款应向下截断到 2 位(如 floor(amount * 100) / 100)。每次可能重新引入精度的运算后都要重新舍入,而非只在最后处理。
- 分数股:qty 与 notional 最多 9 位小数,二者互斥不可同时传;不要用 notional / price 反推 qty 再发送,应直接传 notional 让 Alpaca 计算成交,避免价格漂移。
- 存储:数据库用定点 decimal 而非 float,例如 DECIMAL(20, 8);原样保存 Alpaca 返回值与转换/派生值,便于对账与审计;保留显式 currency 列。
- 多币种:多数 Broker/交易流程为 USD,journal 默认 USD;funding wallet 支持多币种并含 FX 费用,处理时不可假设 USD,应读取并存储币种,全程用 decimal 处理 FX 金额。
限制:资料未提供具体端点清单、完整代码示例或各语言库版本要求;实际精度上限与舍入行为以 Alpaca 官方文档为准。相关技能包括 alpaca-broker-trading-orders、alpaca-broker-journals、alpaca-broker-funding-transfers、alpaca-broker-reconciliation-idempotency。