alpaca-broker-money-precision

Alpaca — 金融データと数値精度

金融関連のバグは気づかれにくく、コストもかさみます。Alpaca のワイヤ形式と小数演算の実情には、いくつか特有の落とし穴があります。このスキルは簡潔で、明確な方針を示し、特定のプログラミング言語に依存しません。

ベース URL と認証（クライアント認証情報による Bearer トークン。従来の Basic も引き続き使用可能）については、先に alpaca-broker-integration を読んでください。

1. 数値は文字列として返されます — 文字列のまま扱います

Alpaca は価格、数量、想定元本、金額を JSON 文字列（"100.50"、"1.5"、"190.2345"）として返し、リクエストでも文字列として受け付けます。これは意図的な仕様であり、JSON の二進浮動小数点数による精度損失を防ぎます。

ルール： 文字列の金額フィールドは 10 進数型に変換し、二進数の float／double は決して使わないでください。文字列に戻してシリアライズします。金額を扱う処理では、数値を IEEE-754 浮動小数点数として扱わないでください。

言語	使用するもの	避けるもの
Python	decimal.Decimal("100.50")	float("100.50")
TypeScript/JS	10 進数ライブラリ（decimal.js／big.js）または文字列演算	Number(...)、parseFloat
Go	shopspring/decimal	集計での float64
Java/Kotlin	java.math.BigDecimal	double

実運用上の注意：Alpaca のすべてのエンドポイントで仕様が一貫しているわけではありません。一部のマーケットデータの数値フィールドは JSON 数値（例：バーの OHLC）として返されます。表示や分析用の価格なら浮動小数点数でも問題ありませんが、移動または保存する金額には使わないでください。扱っているフィールドを把握してください。

2. 送信前に丸める／切り捨てる — 方向も把握する

注文では、notional は 小数点以下 2 桁まで、qty は 小数点以下 9 桁まで指定できます（Broker API FAQ に基づきます。注文スキーマにある qty の「小数点以下 2 桁」は古い情報です）。Journal の amount には公表された精度制限はありませんが、現金は§3に従い小数点以下 2 桁で送信してください。

ルール： 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. 保存

• DB では金額を浮動小数点数ではなく 固定小数点の 10 進数として保存し、受け取るフィールドのうち最も広い精度に対応できるスケールを指定してください。qty の場合はスケールを 9 以上にし、小数点以下 9 桁の端株数量が気づかないうちに切り捨てられないようにします。
• Alpaca から受け取った値をそのまま保存し、変換値や派生値と併せて保持してください。API 呼び出し用に小数点以下 2 桁へ切り捨てても、より高い精度で値が返された場合は両方を保持します。照合や監査が可能になります。
• 通貨列を明示的に設けてください。多くの処理では USD が使われますが、一部のレール（資金調達ウォレット）は複数通貨に対応しています。

5. 複数通貨に関する注意

• Broker／取引関連の処理の多くは USD を使います。Journal のデフォルト通貨も USD です。
• 資金調達ウォレットのレールは多くの通貨（USD、EUR、JPY など）に対応し、為替手数料が発生します。ここを扱う場合、USD だと決めつけず、currency を読み取って保存し、為替金額はすべて 10 進数として扱ってください。

6. チェックリスト

• 金額フィールドは文字列から10進数型に変換して解析し、シリアライズ時に文字列に戻します。
• 資金移動の処理経路では、バイナリ浮動小数点数を一切使用しません。
• 呼び出し前に、金額を許容される精度に丸める／切り捨てるようにし、丸めモードを明示します（出金額は切り下げます）。
• 算術演算では完全な精度を維持し、送信時／表示時に一度だけ丸めます。
• DB の列にはスケールが 9 以上の固定小数点数を使用し、Alpaca の生値はそのまま保存します。
• 通貨を明示的に管理します。

関連スキル： 注文の数量／想定元本のルール → alpaca-broker-trading-orders；仕訳／送金の金額 → alpaca-broker-journals、alpaca-broker-funding-transfers；保存値と Alpaca の値の照合 → alpaca-broker-reconciliation-idempotency。