alpaca-broker-money-precision

Alpaca — Money & Numeric Precision

Financial bugs are silent and expensive. Alpaca's wire format and the realities of decimal arithmetic create a few specific traps. This skill is short, opinionated, and language-agnostic.

Read alpaca-broker-integration first.

1. Numbers come as strings — keep them that way

Alpaca returns prices, quantities, notional, and money amounts as JSON strings ("100.50", "1.5", "190.2345"), and accepts them as strings on the way in. This is deliberate: it avoids the precision loss of JSON's binary floats.

Rule: parse string money fields into a decimal type, never a binary float/double. Serialize back to a string. Don't let a number ever live as an IEEE-754 float in the money path.

Language	Use	Avoid
Python	decimal.Decimal("100.50")	float("100.50")
TypeScript/JS	a decimal lib (decimal.js/big.js) or string arithmetic	Number(...), parseFloat
Go	shopspring/decimal	float64 for accumulation
Java/Kotlin	java.math.BigDecimal	double

Real-world caveat: not every Alpaca endpoint is consistent — some market-data numeric fields come as JSON numbers (e.g. bar OHLC). Prices for display/analytics can tolerate floats; money you move or store must not. Know which field you're touching.

2. Round/truncate before sending — and know the direction

Alpaca generally accepts 2 decimal places for cash amounts and up to 9 for fractional share qty/notional. If you send more precision than allowed, you risk rejection or silent rounding on their side.

Rule: explicitly round/truncate to the target precision before the API call, using a deliberate rounding mode.

• For money you're moving out / charging, truncate (round down) to 2 dp so you never move more than intended. (e.g. floor(amount * 100) / 100.)
• Pick the rounding mode consciously (ROUND_DOWN vs ROUND_HALF_UP) — don't inherit whatever the default float formatting does.
• Re-round after every arithmetic step that could reintroduce precision (e.g. computing amount * percentage for a split allocation), not just at the end.