The 10-minute human path: 12 words → passcode → qoll-code → first payment · content/guides/getting-started.md

Getting Started — your first ten minutes

From nothing to "I sent money in a chat message." Numbered steps, real screens and commands, verified on the live system.

✓ verified against the live stack, 2026-09-12 — every command below was run that day: qalchat init --from-seed (12 words shown once), backup, recover --force, invite, topup, send, pay, recv, anchor, verify-convo; all core services green (bash scripts/status.sh: 11/14 up, core GREEN).

What you need

A computer (Windows, macOS or Linux) — the desktop wallet, or this repo's CLI for the walk-through.
A pen and paper (yes, really — step 2).
About ten minutes.

Everything runs on the qalarc network: one wallet, one balance, chat and compute included.

The 10 steps

1. Open the wallet (or the CLI)

Desktop: run Qal Wallet (Tauri app — see using-the-wallet). It needs the local services running (bash scripts/status.sh tells you). Command line equivalent (what we verify with):

python3 qalchat/qalchat.py init <your-handle> --from-seed

2. Create your identity — the 12 words

Pick a handle (a name, like alice). The wallet generates 12 words and shows them once, in a grid, with an "I wrote it down" checkbox you must tick before continuing.

Real output (2026-09-12, handle gsg):

seed-phrase: sibling tumble distance frost tooth flat harbor glad final drive cabbage bachelor
╔══════════════════════════════════════════════════════════════════╗
║ SEED PHRASE — the ONLY way to recover this identity.             ║
║ Write it on paper NOW. Shown ONCE; never stored in the identity. ║
╚══════════════════════════════════════════════════════════════════╝

Why the words matter (the one paragraph to remember): the 12 words are your identity. Every key you will ever have — chat keys, your money credential, device keys — is mathematically grown from them. There is no password reset and no support desk. Anyone holding the words is you; you losing the words is losing the account. Paper or stamped steel, two places, never a photo, never a cloud note. Full story: login-and-accounts.

3. Set your passcode (the vault)

The wallet asks for an app password. This encrypts everything on this device (AES-256-GCM, PBKDF2 200k). Wrong password 5 times → 60-second lockout; it auto-locks after 5 minutes idle.

Plain split: the words = who you are, forever. The passcode = may this device open the wallet now. The passcode can be reset by re-entering your 12 words; the words can never be reset.

4. Meet your qoll-code

Success screen: "your messaging code — share it, people find you with it." It looks like qoll-gka5-js — short, human-typeable, derived from your keys. It is shown big in the sidebar and you can click to copy.

To be found, give people your handle or qoll-code. For the stronger handshake, open Contacts ▸ My invite — a QR code and a signed qalchat://invite?… link. When you add someone, the wallet shows their code and asks you to confirm it out-of-band (a voice call) — that kills fake-key attacks. See using-chat §Adding a person.

6. Top up your credit

Money in this phase is honest paper: zero real Qals exist yet; the ledger runs on test cents (ground truth F21). Two ways to fill a balance:

Real path (live when sales open): card payment → the payments bridge credits your wallet (qalpay, one webhook, one ledger).
Today's test path (this machine):

bash python3 qalchat/qalchat.py topup alice 500 # paper-phase test cents: +500c = 5.00 Qals # → topup: +500c → ag_b09991e90d (paper-mode test cents, Phase 0)

Units: 1 Qal = AU$1 of service credit = 100 cents = 1,000,000 doofs (F6). People see 5.00 Qals; machines count doofs.

7. Say hello

python3 qalchat/qalchat.py send bob "first message" --as alice
# → sent #3 → bob (convo qc1:cb3a56391993…, hash bf681fed58f66db3…)

In the wallet: Chat ▸ pick the person ▸ type ▸ Enter. Messages are sealed on your device before they leave; the relay in the middle carries envelopes it cannot read.

8. First payment in chat

python3 qalchat/qalchat.py pay bob 25 "latte" --as alice
# → transfer ok: r_d90476b7ac 25c (0.25 B-QALS) → bob
# → payment message sealed into the conversation

In the wallet: 📎 attach menu ▸ ⚡ Attach Qals ▸ amount ▸ Confirm — the gold chip rides your next message. On the other side it lands as a gold ⚡ payment card with the receipt id. That receipt is real: the transfer is in the ledger, and the conversation can be stamped into the chain (next step).

9. Stamp the conversation into the chain

python3 qalchat/qalchat.py anchor bob --as alice
# → tx 2YdPGUwVAcadS8Fja4T9jKa727jgxRE34B5bLnLUNuFR
python3 qalchat/qalchat.py verify-convo bob --as alice
# → ✔ conversation verified against Qalnet anchor

The anchor is a fingerprint (sha256) of the conversation pushed onto Qalnet with a timestamp — later, anyone can re-check that nothing was edited. In the wallet the message ticks change from ✓ to ⚓.

10. Where to next

Daily driving: using-chat · using-the-wallet
How login actually works: login-and-accounts
Use QALS to log in to other apps: digital-identity-login
Earn: sell compute (selling-compute) · turn loyalty points into credit (claims-and-points)
Everything at a glance: use-cases-visual

What success looks like

Twelve words written on paper, checked twice, wallet says success and shows your qoll-code.
balance shows cents; a ⚡ gold card in the transcript with a r_… settle id.
verify-convo prints ✔ — your receipt is anchored where nobody can quietly rewrite it.

Troubleshooting

Symptom	Fix
"could not publish pubkey"	A relay is down — re-run the command (it republishes); check `bash scripts/status.sh`.
Payment refuses	Balance or daily cap — `balance` shows `spent today / cap`. Caps are enforced by the ledger, not politely (F-spend-caps).
Phone page 401 / empty	Bridge token mismatch — see login-and-accounts §The phone bridge.
Lost the words already?	There is no recovery without them. Nothing to buy, nobody to email. This is the deal.

Ground rules used throughout: ground truth · the magic explained: how it works.