This page is for heirs, not vault owners. If you are an owner looking to manage your vault, go to the Dashboard instead.
Prerequisites
- A Stacks wallet (Leather or Xverse) installed and connected
- Your wallet address must be registered as an heir in the vault you are trying to claim
- The vault must have reached the Claimable state (both the heartbeat interval and grace period must have elapsed without a heartbeat from the owner)
Auto-discovery
When you connect your wallet and navigate to the claim page, Heirloom automatically searches for vaults where your address is a registered heir. How it works: The app callsfindVaultsForHeir(stxAddress) from src/lib/contracts.ts, which scans recent transactions on the Hiro API for create-vault calls that include your address in their heir list. Each matched vault is then queried for its current state, your allocation percentage, and the calculated token amounts for your share.
While the search is running, animated loading dots are shown. The scan covers recent contract activity — if the vault was created before the scan window, use manual lookup instead.
Auto-discovery runs once when you connect your wallet. It does not re-run automatically. Refresh the page to trigger a new scan if the vault was recently created.
Understanding vault cards
Each vault found by auto-discovery appears as a card. The card shows: Vault header (color-coded by state):- Owner address — the truncated Stacks address of the vault creator
- Status — the vault’s current state in large uppercase text
| State color | Vault state | Meaning |
|---|---|---|
| Green | Active | The owner is still sending heartbeats. You cannot claim yet. |
| Yellow | Grace period | A heartbeat was missed. The vault is not claimable yet. |
| Red | Claimable | The grace period has expired. You can claim now. |
| Gray | Distributed | All claims have been completed. |
- Share — your percentage of the vault (e.g., 50%)
- sBTC — your calculated sBTC amount based on the current vault balance
- USDCx — your calculated USDCx amount (shown only if the vault holds USDCx)
- Claim status — “Pending” if you haven’t claimed, “Claimed” with a green checkmark if you have
When the claim button is enabled
The Claim Inheritance button at the bottom of each vault card is enabled only when both conditions are true:- The vault state is
claimable - You have not already claimed from this vault
| Button label | Condition |
|---|---|
| ”Vault Not Yet Claimable (active)“ | Vault is still active |
| ”Vault Not Yet Claimable (grace)“ | Vault is in grace period |
| ”Already Claimed” | You have already claimed from this vault |
| ”Claim Inheritance” | Ready to claim — button is enabled |
How to claim: step by step
Connect your wallet
Open the claim page and connect your Stacks wallet. Auto-discovery starts immediately after connection.
Wait for the search to complete
The page shows a loading indicator while scanning the blockchain. When it finishes, your vault cards appear.
Find a claimable vault
Look for a vault card with a red header and the status “Claimable”. The claim button at the bottom of the card will be active.
Click Claim Inheritance
Click the Claim Inheritance button. The button shows a spinner while the transaction is being prepared.
Confirm in your wallet
Your wallet extension opens and asks you to confirm the
claim transaction. This calls claimInheritance(ownerAddress) on the contract, which transfers your share of sBTC and/or USDCx directly to your wallet address.Each heir claims independently. Claiming your share does not affect other heirs — they claim their own percentages separately. Your claim only transfers your allocation, not the entire vault balance.
Manual lookup
If auto-discovery does not find a vault you expect to be listed in (for example, because the vault was created before the scan window), use manual lookup. After the auto-discovery scan completes, a collapsible Manual vault lookup section appears at the bottom of the page.Enter the vault owner's address
Type or paste the full Stacks address of the vault owner (e.g.,
SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ). The field accepts both SP... (mainnet) and ST... (testnet) addresses.Click Lookup
Click the Lookup button. The app calls
lookupSingleVault(ownerAddress, yourAddress) to check whether you are a registered heir for that specific vault.After claiming
Once your claim transaction is submitted:- The claim button is replaced with a Claim Submitted! confirmation and a View on Explorer link.
- Your sBTC and/or USDCx share is transferred to your wallet address as part of the transaction confirmation.
- The claim status on the vault card updates to “Claimed” with a green checkmark.