| name | blnk-precision |
| description | Encode and display Blnk amounts correctly with precise_amount and a single precision source of truth (prefer currency enums). Use when handling cents, zero-decimal currencies, available balance display, converting human amounts, or preventing precision drift across services. |
| metadata | {"author":"blnk","version":"0.2"} |
Precision
Wrong precision causes silent money bugs. Blnk stores ledger amounts as integers; precision is how you map human decimals to those integers.
Decide encoding before the first post, put it in one shared module (prefer enums), and reuse that module everywhere. Never sprinkle magic 100s across services.
Docs: Transaction precision.
Quick start
human $10.00 → precise_amount: 1000, precision: 100
- Define a currency → precision map once (references/currency-rules.md). Prefer enums / typed constants, not env vars or copy-pasted literals.
- Convert only through shared helpers (references/amount-helpers.md).
- Prefer
precise_amount + precision on every write. Do not send both amount and precise_amount.
- For spendable UI while holds exist, use references/available-balance.md.
Mental model
| Field | Role |
|---|
precise_amount | Integer in smallest units (recommended write path) |
blnk-precision | Scale factor (human ≈ precise_amount / precision) |
amount | Float path Blnk can derive; avoid for app writes (15-digit limit, drift risk) |
Balance fields are integers in minor units. Core does not return precision on balances. Your app must divide by the same precision used when posting.
Workflow
- Lock the precision table for every currency in the product (and highest-precision strategy if multi-currency / crypto+fiat).
- Encode that table as enums or typed constants in one package. Import it from API, workers, SDKs wrappers, and UI formatters.
- Convert human ↔ precise only via helpers that read that table (never hardcode
precision: 100 at call sites).
- Post with
precise_amount + precision from the table.
- Display balances with the same table. For holds, apply available-balance rules.
- For FX legs, also load the
blnk-fx skill.
Hard rules
- Different currencies may use different precisions. USD at
100 and BTC at 100000000 in the same product is fine and expected.
- One precision per currency across the whole product. No drift between services for the same currency code.
- Enums (or typed constants) beat env for the precision map. Env is for secrets and URLs, not money scale.
- Prefer
precise_amount with an explicit precision on every write.
- Never send
amount and precise_amount together.
- For multi-currency products (especially crypto + fiat), follow Blnk multi-currency guidance when a shared ledger scale is required. See Multi-currency balances. That does not forbid a per-currency table for ordinary posts.
- Round with an explicit policy inside helpers; do not rely on float leftovers.
References
