Building Shared Vaults

Once members have shared devices with an organization, an admin (or any member with the wallet:create permission) can build a multisig vault from those devices. This page walks through the full flow, including the per-vault consent step that every device owner participates in.

Overview of the flow

sequenceDiagram participant Admin as Org admin participant SV as Sigvault participant Owners as Device owners Admin->>SV: Pick devices + threshold SV-->>Admin: Wallet created<br/>(status: NOT_STARTED) SV->>Owners: Consent request in Inbox<br/>(one per device) Owners->>SV: Accept or decline alt All accepted SV->>SV: Provision vault on-chain<br/>(status: READY) else Any declined SV->>SV: Mark wallet FAILED SV-->>Admin: Notify and suggest retry<br/>with different devices end

The vault only becomes spendable once every selected device’s owner has explicitly accepted. If anyone declines, the vault is marked failed and the admin is notified to try again with a different set of devices.

Step by step

1. Open the org’s wallet builder

From the dashboard sidebar, switch to the organization and go to Wallets → New wallet. The vault builder is scoped to that org — only devices in the org’s pool will appear.

2. Configure the vault

Set:

Name and optional description for the vault
Network (mainnet, testnet, signet, or regtest)
Walletrs agent — the wallet runtime that will operate the vault. All selected devices must share the same agent binding; the dashboard enforces this.
Threshold (M) — how many signatures will be required to spend (e.g., 2 for a 2-of-3)

3. Select devices

Pick the N devices that will participate. The picker shows every device that’s been shared with the org, grouped by the user who shared it. You can see at a glance who contributed each key.

The threshold cannot exceed the number of devices selected (a 3-of-2 is rejected). Choose your M-of-N to match the trust model you want — see Multisig Wallets for guidance.

4. Submit — consents are issued

When you submit, Sigvault:

Creates the wallet record with status NOT_STARTED
Issues one key participation consent per selected device, addressed to that device’s owner
Sends a notification (ORG_KEY_PARTICIPATION_REQUEST) to each device owner’s Inbox

The wallet exists at this point but is not yet provisioned on-chain. No addresses are derived and no signing can happen until consents resolve.

5. Device owners respond

Each notified user opens their Inbox and sees a pending consent request. The request shows:

Which org is asking
Which of their devices is being requested
The vault’s name, threshold, and total device count
Which user initiated the request

They click Accept or Decline. They can ignore the request indefinitely — there is no automatic timeout — but the vault stays in NOT_STARTED until everyone responds.

6. Outcome

All accepted — the wallet provisioning worker picks up the wallet, derives the descriptor, and the vault becomes spendable.
At least one declined — the wallet flips to FAILED. The admin gets a notification and can either build a new wallet with different devices or talk to the declining member.

The consent step is what makes cross-org key sharing safe. A few properties to understand:

Per-vault, not per-org. Sharing a device with an org grants visibility, not blanket signing authority. Each new vault triggers a fresh consent request.
One consent per device, not per owner. If you’ve shared multiple devices and the admin selects more than one of yours into the same vault, you’ll see one consent request per device.
Notification dedup. If you own multiple devices in the same vault, you receive a single Inbox notification with a single pending consent thread, even though each device has its own consent row.
Immutable after response. Once you accept or decline, the response is final for that wallet. Subsequent vaults will issue new, independent consents.

Reviewing pending consents

Open Inbox from the dashboard sidebar at any time to see your pending consents and pending org invites in one place. You can also call the API directly:

GET /api/v2/consents/mine

Or respond programmatically:

POST /api/v2/consents/{consent_id}/respond
{ "accept": true }

When to use cross-org vaults

Cross-org vaults are powerful when:

A deal requires keys from multiple parties (e.g., escrow between two companies)
A family office holds keys across multiple personal accounts that each belong to a different family member’s org
A DAO wants signers drawn from several member organizations
A service provider participates as a co-signer in a customer’s vault without merging into a single org

For more uniform setups — for example, an entirely internal company treasury — the simpler pattern is to keep all signers as members of one organization. Cross-org sharing adds an extra layer of consent that’s valuable when trust boundaries don’t line up with the org structure.

Troubleshooting

A device I expected doesn’t show up in the picker. Confirm that the device’s owner has shared it with this org (check Settings → Device Shares). A device shared with another org isn’t visible here.

The wallet is stuck in NOT_STARTED. At least one device owner hasn’t responded to their consent request. Check the consent list on the wallet page; the admin can nudge them out-of-band.

The wallet went to FAILED. Someone declined. Build a new wallet with a different device set.

An owner accepted but the wallet still isn’t ready. All consents must be accepted before provisioning starts. Check that no other owner is still pending.