Skip to content

Add language to Units & Symbols page describing new ₿-only convention for displaying bitcoin quantities #1171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Jun 23, 2025
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 54 additions & 0 deletions guide/designing-products/units-and-symbols.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,13 @@ images_app:
- file: settings-local-currency
alt: Mobile phone screen showing currency unit options by country.
caption: Local currency options.
images_b:
- file: before
alt: Wallet homescreen showing traditional display of bitcoin quantities.
caption: Before - bitcoin quantities represented in traditional formats.
- file: after
alt: Wallet homescreen showing use of bitcoin quantities in ₿-only format.
caption: After - bitcoin quantities represented in ₿-only format.
images_home:
- file: home-unit-sats
alt: Home screen showing user funds displays in satoshis.
Expand Down Expand Up @@ -245,6 +252,53 @@ Typically, the word "bitcoin" can mean a singular or a plural. In the early days

Whatever pluralization scheme you choose, it's good to be consistent with this choice throughout your product.

## New convention: ₿-only format

A new convention is emerging whereby all bitcoin quantities are displayed alongside the ₿ symbol and shown in integer base units only, hereafter referred to as "₿-only format".

### Motivation

This ₿-only format is motivated by wanting to minimize potential user confusion posed by several aspects of the traditional approach to showing bitcoin quantities:

1. **Inscrutable decimals.** For small quantities it is often difficult for users to parse numbers with many leading zeroes.
2. **Meaning of "sats".** "The word "satoshis" or "sats" appearing in product UIs, often alongside BTC or bitcoin, raises the question for new users: what are these units and how do they relate to bitcoin? It presents an eduation/understanding hurdle that can be avoided.
3. **Inconsistency.** The current dual convention that is typically employed by wallets sometimes shows quantities in decimal representation (typically if larger) and other times integer quantities (typically if smaller). This inconsistency creates unpredictability in the product experience.

The BEFORE & AFTER [sample mockups](#sample-mockup) below demonstrate how these points of potential confusion are manifest in traditional wallet UIs and might be remedied under this new ₿-only format.

### Proposed best practices

The following best practices are proposed for products wanting to adopt the ₿-only format:

- Show quantities only in integers form, representing the number of base units of bitcoin
- Label quantities with ₿ symbol (either pre-fix or post-fix per local custom)
- Include a fiat value below the bitcoin quantity for maximum clarity
- Use 'BTC' to refer to 100M base units (i.e. 1BTC = ₿100,000,000)
- Deprecate use of decimal representation
- Deprecate explicit use of "satoshis" or "sats" in product UIs

### Examples

Examples of how legacy bitcoin quantities would be represented under this new convention:

- `0.00000100 BTC -> ₿100`
- `0.00005449 BTC -> ₿5,449`
- `3.25 BTC -> ₿325,000,000 or ₿325M`
- `15,000 sats -> ₿15,000 or ₿15K`

### Sample mockups

This ₿-only format is easily accommodated in bitcoin product UIs.

For example, the mockups below show how a typical wallet activity screen might be redesigned to adopt the new ₿-only format.

{% include image-gallery.html pages = page.images_b %}

### Adoption

As of June 2025, wallets that have adopted this new ₿-only format include: [Boardwalk Cash](https://boardwalkcash.com/) and [BitKit](https://bitkit.to/). [Square's next generation POS](https://x.com/Square/status/1927396327039684690) is being marketed with this convention.


---

On to [interoperability]({{ '/guide/designing-products/interoperability/' | relative_url }}) which is essential for smooth interaction and migration between bitcoin products.
Expand Down