Blockstream Swaps copy guide
Self-custodial web app for Bitcoin and Lightning atomic swaps
- Name fits the new convention; joins the consumer lineup (App, Jade, Lend, Swaps).
- Launch positioning deliberately muted: alternate provider, trusted brand.
- Open: context page vs straight into the product. Michael leans straight in.
Golden rules
Get these right and most copy takes care of itself.
- It is the swaps backup (the 12-word phrase plus swap state), never "wallet." The top Swaps rule.
- Blockstream never holds funds: it coordinates; hash-locked contracts enforce complete-or-refund.
- Boltz stays invisible: neutral fee labels ("Swap fee," "Network fee"), Blockstream-voiced narration.
- Three products, never conflated: Blockstream Swaps, the in-app swap feature, the Liquid Swap Tool.
- Fees are deducted, never added; "You Receive" is always net.
Who you're writing for
Meet the reader before touching the rules.
Reader: consumer self-custody users; assume wallet fluency, not swap experience.
Write for three states: first-time swappers, mid-problem users (stuck swap, wrong address), self-custody devotees; calm first.
Names
The product names and exactly how to write them.
Write "Blockstream Swaps": no article, always plural, both capitalized. Never "the Blockstream Swaps" or "Blockstream Swap."
Full name only; never "Blockstream Swaps app" or "the Swaps app." "Swaps web app" is OK to clarify format.
Lowercase "a swap" for the action; capitalize only in the product name or Title Case headings.
Singular verb for the product ("Blockstream Swaps is"); plural for swaps ("swaps are self-custodial").
Never conflate the three products: Blockstream Swaps, the in-app swap feature, the Liquid Swap Tool; name which one you mean.
Order product lists with Swaps among consumer products: "Jade, the Blockstream app, Blockstream Swaps."
Say this, not that
The usage dictionary. When in doubt, search it.
| Topic | Write | Never write | Why |
|---|---|---|---|
| Backup words | recovery phrase | seed phrase · mnemonic · backup phrase · backup seed | the only approved term |
| Custody vocabulary | self-custodial (adj) · self-custody (noun) | non-custodial | |
| Fees | fees are deducted; "You Receive" is net after fees | fees are added | |
| Swap arrows | the ↔ arrow for two-way swaps ("Liquid ↔ Lightning") | "X-to-Y" phrasing · ↔ in mere lists | |
| The backup | swaps backup (the 12-word phrase + swap state) | wallet, for the backup | the top Swaps terminology rule |
| Intra-Liquid swaps | Liquid swaps · swaps on Liquid | Liquid atomic swaps · Liquid Swaps | |
| The base chain | mainnet, when "on-chain" already appears nearby | the "-chain" echo | |
| Custody | Blockstream coordinates; the contract enforces the outcome | Blockstream holds funds | |
| Third-party infra | Swap fee · Network fee, neutral labels | Boltz or any provider brand in user copy | generic protocol terms are fine |
| The old backup name | swaps backup | wallet · swaps wallet · restore wallet | retired May 2026; correct older drafts and screenshots |
| Liquid Swap Tool | Liquid Swap Tool (exact casing) | Liquid Swap tool · Liquid Swaps Tool | a separate product |
| Refund key | child key: BIP85 key signing only the timeout refund | implying general swap authority | in-wallet feature only |
| Swap statuses | Completed · In Progress · Cancelled · Failed | invented status names | the documented set |
Voice & tone
How the copy sounds, and where the register switches.
Write for self-custody consumers still learning Lightning: accessible, patient, precise on timers, confirmations, addresses.
Archetype: knowledgeable friend in Bitcoin security; patient when funds are at stake, never condescending, assume no prior swaps.
Second person always; never "the user" or passive voice. Reassure when funds are at stake; no marketing language in support.
Register by surface: HC guides step-by-step; security copy precise and reassuring; error guidance calm, recovery-path first; launch copy confident.
HC format: numbered steps, bold UI elements, screenshot after its step, sparing callouts, ~14-16 word sentences, no emoji.
Verb-first steps ("Tap Receive"); never branch within a step; split articles when platform flows differ. Headings Title Case; HC H1s sentence case.
Positioning
What to lead with, what to always pair, what never to claim.
These points are an amalgamation of what has been learned so far, from product docs, launches, and reviewer feedback. They are not definitive or authoritative positioning from anyone. Product marketing still needs to clearly define positioning for this product, which will happen in a follow-up.
Position as the self-custodial web app for Bitcoin on-chain ↔ Lightning atomic swaps; no account, no custodian, no mid-swap seizure.
Lead with the direct path: base layer ↔ Lightning without installing a wallet; open the web app, pick a direction, swap.
Frame self-custody absolutely: funds never leave user control; Blockstream coordinates, never takes custody.
Name the mechanism: hash-locked contracts complete in full or refund in full; no half-paid state. Browser-based, no account or download.
Refunds are enforced by Bitcoin, not Blockstream; the 12-word swaps backup signs the refund path. A failed swap cannot cause permanent loss.
Launch gating: public marketing held until after the June 1, 2026 soft launch; confirm status with the Swaps team before promoting.
Claims
What a page or post may cite. Confirm, correct, or kill each row; an unconfirmed claim does not ship.
| Claim | As of | Status |
|---|---|---|
| Portfolio one-liner: "Self-custodial web app for Bitcoin and Lightning atomic swaps" | current docs | approved |
| Every swap completes in full or refunds in full (hash-locked contracts) | current docs | approved |
| Soft launch June 1, 2026; current marketing-hold status unknown | stale in products-swaps.md | confirm or kill |
Open questions
Unresolved tensions for review. Don't resolve these in copy; flag them.
- No Swaps product doc in blockstream-ai/Products/ (blockstream-app.md covers only the in-wallet Boltz feature); no public company-brain product page either.
- Launch status stale: products-swaps.md still says pre-launch with a June 1, 2026 marketing hold; writers cannot tell if the hold is lifted.
- No approved Swaps boilerplate exists anywhere (boilerplates.md has zero Swaps content).
- The "swaps backup" rule (called the most important Swaps terminology rule) is absent from canonical terminology.md; terminology.md has zero Blockstream Swaps entries.
- product-brands.md has no Swaps entry (sub-brand/lockup undocumented); personas-consumer.md Products list omits Swaps despite being its voice guide.
- Boltz non-attribution rule lives only in project CLAUDE.md, not brand-docs; overall coverage thin (only products-swaps.md dedicated, no visual/social guidance or examples).
Notepad
Scribble anything: loose thoughts, questions, things that don't fit a pin or a highlight. Saves automatically with the review feedback.