Desktop guide · macOS, Windows and Linux

Using SpiffyVault

SpiffyVault pays people, not addresses. You add the people you pay as contacts, and the app pays them directly, peer to peer, with proof. This guide follows the desktop app from the first start to your first payments.

Testnet beta. This release runs on the BSV testnet only. Testnet coins have no value, so you can try everything without risk.

New here? Start with First start. To let Claude or another AI agent use a wallet you set aside, read AI agents (MCP).

Install

Download SpiffyVault from the download section.

macOS (Apple silicon and Intel): open the .dmg and drag SpiffyVault to Applications. The app is signed and notarized by Apple.
Windows 10 and 11: run the setup program. It is not code-signed yet, so Windows SmartScreen asks once: choose More info, then Run anyway.
Linux (x86-64): use the AppImage, or unpack the .tar.gz. SpiffyVault keeps its keys with libsecret, which most desktops already have.

Each file has a .sha256 checksum beside it, and all of them are listed in SHA256SUMS.

First start

On the first start SpiffyVault shows a Welcome screen. Nothing is created or sent anywhere until you choose.

Create a new vault

Click Create a new vault. SpiffyVault makes your identity: the keys that other people know you by.
Write down the identity's 12-word phrase. Open Profile in the sidebar, then the identity's More (⋯) menu, and choose Export Mnemonic. Your backups open only with this phrase.
Create a wallet: see Wallets.

Restore

Click I already have one · Restore.

Type or paste your 12-word identity phrase, then click Continue.
Click Choose the backup file. SpiffyVault shows what the backup holds: its date, your wallets, payments and contacts. Click Restore.
The last screen shows what came back. Click Open SpiffyVault.

Without a backup, click I don't have a backup. Your phrase alone brings back your identity, your public profile and ordinary payments (import each wallet's phrase in Wallets). It cannot bring back your contacts, or payments made to you through PeerPay and offline payments: only a backup holds those.

The window

The sidebar on the left has these sections:

Vault: Overview (total balance, network, recent activity, wallets) and Activity (every payment, with filters).
Wallets: All wallets, then each wallet with its balance. A count on a wallet shows payments you have not seen yet.
People: Contacts.
Identity: Profile.
Agents: Requests and Activity. This section shows only while agent access is on: see AI agents.
Settings, at the foot, with the network status below it.

The toolbar has Back and Forward, the search box, Receive and Send.

The search box opens the command palette. Type to pay someone, open a wallet or find a payment. With nothing typed it lists the actions, such as New payment…, Move money between my wallets… and Check for updates.

On a Mac, the menu bar has the same commands, with these shortcuts:

Shortcut	Does
`⌘K`	Command palette
`⌘N`	New payment
`⇧⌘R`	Receive
`⇧⌘N`	New wallet
`⌘1` … `⌘4`	Overview, Activity, Contacts, Profile
`⌘[` / `⌘]`	Back / Forward
`⌘,`	Settings

Wallets

Create a wallet

Click New wallet… in the sidebar.
Type a Wallet Name.
Under What is it for?, choose Everyday (pay and get paid, no limits) or Agent (for an AI agent on this computer, with spending limits).
Click Create Wallet.
Write down the 12-word recovery phrase that SpiffyVault shows, then click I Have Backed It Up. Anyone with this phrase can take the wallet's funds.

To use a wallet you already have, click Import… on All wallets.

On the first start SpiffyVault downloads the blockchain's block headers. A banner shows the progress. You can create wallets and receive payments in the meantime, but new payments show as pending and balances can be incomplete until it finishes.

The active wallet

The active wallet is the one the toolbar's Send and Receive use, and the one a payment to you goes into unless the payer's code names another wallet. To change it, click Make active on All wallets, or Set as Active in the wallet's More (⋯) menu.

The wallet page

A wallet's page shows its balance and its payments. The Send button has a menu with Send to a contact…, Send to an address… and Move to my other wallet…. The More (⋯) menu has, among others:

Wallet kind: … to make the wallet an Everyday or an Agent wallet;
Get paid into this wallet: a code that pays into this wallet (see Get paid);
Export Keys and Delete Wallet.

Pay someone

Pay a contact

Open Contacts and choose the contact.
In the Pay box, type the amount in sats, add a Note if you want, and choose the wallet to pay From.
Click Pay.

When the contact is online, SpiffyVault pays them directly, with proof. When they are offline, the payment waits, encrypted, in their mailbox until their app collects it. You can also click Send in the toolbar and choose the contact: that screen also takes amounts in BSV.

Other ways to pay

Between your own wallets: Move money between my wallets… in the command palette, or Move to my other wallet… on a wallet. No contact or code is needed.
A BRC-100 wallet (BSV Desktop, BSV Browser and others): Pay a BRC-100 payment key. The payment goes through the payee's message box, and they collect it when their wallet opens.
An address (for example an exchange): Send to an address…. A payment to an address cannot be taken back.

Get paid

A SpiffyVault contact pays you from their app, by your name. To be paid by someone who is not a contact yet:

Open the wallet that should receive the money.
In its More (⋯) menu, choose Get paid into this wallet.
Under My code, click Ask for an amount if you want a fixed amount, then Share link.

A SpiffyVault payer pays you directly, with proof, and can add you as a contact. The code holds your peer ID and payment key, never a balance or an address. For a BRC-100 wallet, choose Other BRC-100 wallet under Who will scan it?.

When a payment arrives, a count shows on the wallet in the sidebar.

Contacts

Click Add a contact on Contacts. Find the person by their display name under Directory, or paste their peer ID under Peer ID and click Lookup Profile, then Add Contact.

A contact's page shows every payment between you, by date, with its status. Their profile has Advanced networking: how your computers are linked (direct or relayed) and two connection tests.

Payments waiting to be collected

A payment to someone who was offline is held until their app collects it. A banner on the wallet shows how many payments wait. Click it to review them.

A payment that waited more than three days was probably never collected, and you can click Reclaim. SpiffyVault asks the network first: if the payee already has the payment, theirs stands and nothing comes back. Otherwise the funds come back to your wallet, less a small network fee.

Back up and restore

Settings › Back up, then Back up now, makes one file with every wallet, its keys and history, payments to your payment keys that your phrase alone can't find, and your contacts. Save it wherever you like. It is never sent to us.

The backup file is locked with your identity phrase. Keep the two apart: anyone with both holds every wallet.

To restore, use Restore on the Welcome screen, or Settings › Restore. A backup opens only with the phrase of the identity that made it.

Identities

Profile lists your identities. Click New or imported identity to create one or import one from its phrase. To switch, choose Set as Active in the identity's More (⋯) menu. While you are switched away, contacts cannot reach you under the old identity.

Delete identity… removes it from this computer only. Export its phrase first: it is the only way back.
Destroy identity & data… also deletes everything it published: profile, photos, payment keys, mailboxes and directory listing.

Updates

Once a day SpiffyVault reads the signed release information on download.spiffyvault.net. The request carries nothing about you or your computer, and the app never installs anything by itself. When a new release is out, the Overview shows a banner: click Get it. You can also check now with Check for updates in the command palette, or in Settings › Updates.

Read AI agents (MCP) to let Claude or another agent use a wallet you set aside. For help, see Support.