How to use it

Your first BitLooper account

Today the wallet is the bitlooper command-line tool. A phone wallet with local-currency display comes later. Every step below works on the local testnet.

Testnet only. Test coins have no value. Key files are stored unencrypted on disk, which is fine for testing but not for real money.

  1. Create your key

    Your key is a post-quantum ML-DSA key pair. The address is derived from it and never changes, even if you later replace the key through recovery.

    bitlooper keygen --out me.key.json
bitlooper address --key me.key.json

  2. Get test coins

    The local testnet has a faucet. You can also use the button on the Explorer.

    bitlooper faucet <YOUR_ADDRESS>
bitlooper balance <YOUR_ADDRESS>

  3. Send coins

    Your first transaction publishes your public key once (about 3.9 KB). Later ones are smaller (about 2.6 KB). Payments are final in about 2 seconds.

    bitlooper send --key me.key.json --to <FRIEND> --amount 12.5

  4. Protect the account

    Make a second key and keep it offline, on paper or a USB stick in a drawer. It becomes your cancel key. Then set a daily limit: anything above it waits 24 hours and can be cancelled.

    bitlooper keygen --alg slh-dsa-sha2-128s --out cancel.key.json
bitlooper protect --key me.key.json --vault-limit 100 --vault-delay-hours 24 \
  --canceller $(bitlooper address --key cancel.key.json)

  5. Stop a theft

    If a transfer you didn't make appears as pending, cancel it with the offline key and the coins return.

    bitlooper balance <YOUR_ADDRESS>          # shows "pending" with an id
bitlooper cancel --key cancel.key.json --account <YOUR_ADDRESS> --id <ID>

  6. Add guardians

    Pick three people you trust. Two of them can restore your account after a 48-hour wait. During the wait you, or your cancel key, can stop a recovery you didn't ask for.

    bitlooper protect --key me.key.json --vault-limit 100 --canceller <CANCEL_ADDR> \
  --guardians <G1>,<G2>,<G3> --threshold 2 --recovery-delay-hours 48

    Lost your phone? Make a new key and ask two guardians to run:

    bitlooper recover-propose --key g1.key.json --account <YOUR_ADDRESS> --new-key new.key.json
bitlooper recover-approve --key g2.key.json --account <YOUR_ADDRESS> --new-key new.key.json
# 48 hours later, your new key controls the same account:
bitlooper send --key new.key.json --from <YOUR_ADDRESS> --to <X> --amount 1

  7. Name your heirs

    If the account signs nothing for the chosen period, anyone can trigger the payout to your heirs. A heartbeat proves you're still here.

    bitlooper protect --key me.key.json ... --heirs <CHILD1>:60,<CHILD2>:40 --inactivity-days 365
bitlooper heartbeat --key me.key.json

For businesses: pay your customers' fees

Your business key signs each customer payment a second time and pays the fee. The customer pays nothing.

bitlooper send --key customer.key.json --to <SHOP> --amount 10 --sponsor-key shop.key.json

In a real checkout, your app builds the payment, the customer signs it on their phone, and your server adds the sponsor signature. The node's HTTP API (POST /tx) accepts the signed JSON.

Good habits

Keep the cancel key offline

It protects you only if a thief who steals your phone can't also reach it.

Choose guardians who don't know each other

A recovery needs the threshold to agree, so independent guardians are harder to trick or pressure together.

Watch for pending actions

Delays only help if someone notices. Future wallets will alert you and your guardians automatically.

Back up your key file

Guardians are the safety net, not the plan. Keep an encrypted backup too.