Skip to main content
This guide walks you through creating your first Heirloom vault on Stacks testnet — from installing a wallet to sending your first heartbeat.
Heirloom runs on Stacks testnet. You will need testnet STX and testnet sBTC to complete this guide. No real funds are at risk.

​
Prerequisites

Node.js v18+

Required if you plan to run the app locally. Download the LTS release.

Stacks wallet

Leather or Xverse. Install one before continuing — instructions are in step 1 below.

​
Create your vault

1

Install a Stacks wallet

Heirloom supports two Stacks wallets. Install one as a browser extension.

Leather

The original Hiro wallet, now Leather. Available for Chrome and Firefox.

Xverse

Mobile-first wallet with a full browser extension. Available for Chrome.
After installation, create a new wallet and save your seed phrase in a secure location before continuing.
Never share your seed phrase with anyone, including Heirloom support. Heirloom is non-custodial — no one can recover your wallet for you.
2

Get testnet STX from the faucet

You need testnet STX to pay transaction fees on Stacks.
  1. Open the Hiro testnet faucet.
  2. Connect your wallet when prompted.
  3. Click Request STX. You will receive 500 testnet STX within a few seconds.
The faucet enforces a cooldown period between requests. One request is enough to cover all the transactions in this guide.
3

Get testnet sBTC

sBTC is the Bitcoin-backed SIP-010 token you will deposit into your vault.
  1. Open the Hiro testnet explorer.
  2. Search for the sBTC faucet or use the Sandbox to interact with the sBTC token contract at:
ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token
  1. Call the faucet function from your wallet address to receive testnet sBTC.
You can also deposit USDCx (contract: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx). A vault can hold sBTC, USDCx, or both — you only need one to get started.
4

Open the Heirloom app

The Heirloom frontend runs on Stacks testnet. To start it locally:
cd heirloom-app
npm install
npm run dev
Then open http://localhost:5173 in your browser.
5

Connect your wallet

  1. Click Connect Wallet in the top-right corner of the app.
  2. Select Leather or Xverse — whichever you installed.
  3. Approve the connection request in the wallet extension.
Your Stacks address will appear in the navbar once connected.
6

Create your vault

Click Create Vault and fill in the vault parameters:
FieldDescriptionExample
Heartbeat intervalHow often you must check in (1–365 days)30 days
Grace periodHow long heirs wait after a missed heartbeat (1–90 days)30 days
Heir addressesUp to 10 Stacks addressesYour test address
Percentage splitsAllocations that must total 100%100% for one heir
Splits are stored as basis points internally (100% = 10000 bps). The app handles this conversion for you — enter plain percentages.
Click Create Vault and confirm the transaction in your wallet. The vault is created by calling create-vault on:
STZJWVYSKRYV1XBGS8BZ4F81E32RHBREQSE5WAJM.heirloom-vault-v10
Wait for the transaction to confirm on Stacks (roughly 10–15 seconds on testnet).
7

Deposit sBTC or USDCx

Once your vault is confirmed, open the Deposit panel from your vault dashboard.
  • To deposit sBTC, enter an amount and click Deposit sBTC. This calls deposit-sbtc on the contract.
  • To deposit USDCx, enter an amount and click Deposit USDCx. This calls deposit-usdcx on the contract.
Confirm each transaction in your wallet.
Deposited assets are locked in the contract. You can only retrieve them via Emergency Withdraw (which returns everything to you) or via heir claims after the heartbeat expires. There is no partial withdrawal.
8

Send your first heartbeat

After depositing, your vault countdown begins. Reset it immediately by sending your first heartbeat.
  1. From your vault dashboard, click Send Heartbeat.
  2. Confirm the transaction in your wallet.
This calls heartbeat() on the contract and resets the last-heartbeat timestamp. Your vault is now active.
Set a calendar reminder for slightly before your heartbeat interval expires. If you miss a heartbeat and the grace period passes, your heirs can claim the vault.
9

Share your vault with your heirs

Your heirs do not need to do anything now, but they should know:
  • Your Stacks address — heirs look up vault status by the owner’s address.
  • How to access the app — point them to the Heirloom app URL.
  • When to act — after the grace period passes, they navigate to Claim Inheritance, enter your address, and call claim for their share.
Each heir claims independently. One heir claiming does not block others. Each claim distributes only that heir’s percentage of the vault balance.

​
What’s next

Heartbeat mechanism

Understand how the liveness check works and what triggers vault expiry.

Vault lifecycle

Learn the five vault states: active, grace, claimable, distributed, and cancelled.

Heirs and splits

Configure up to 10 beneficiaries with basis-point percentage splits.

Emergency withdrawal

Recover all vault assets to your wallet at any time before distribution.

Build docs developers (and LLMs) love

Get started for freeTalk to us