Skip to main content
Vaults are the on-chain treasury containers for all FlowGuard products. A vault requires exactly 3 signers and 3 signer public keys for the on-chain multisig covenant.

​
List Vaults

GET /api/vaults
x-user-address: bchtest:q...
Returns vaults grouped by the caller’s role: 
{
  "created": [...],
  "signerIn": [...],
  "public": [...],
  "all": [...]
}
Each vault object includes a "role" field: "creator", "signer", or "viewer".

​
Get Vault

GET /api/vaults/:id
x-user-address: bchtest:q...
Returns a single vault with the caller’s role. Returns 403 if the vault is private and the caller is not a member.

​
Create Vault

POST /api/vaults
x-user-address: bchtest:q...
Deploys the VaultCovenant on-chain. Requires exactly 3 signers and 3 corresponding public keys. Body 
{
  "name": "Operations Treasury",
  "signers": ["bchtest:qr...", "bchtest:qs...", "bchtest:qt..."],
  "signerPubkeys": ["02hex...", "03hex...", "02hex..."],
  "totalDeposit": 10,
  "isPublic": false
}
Response — 201 
{
  "id": "uuid",
  "vaultId": "hex32",
  "contractAddress": "bchtest:p...",
  "status": "pending",
  ...
}

​
Get Vault State

GET /api/vaults/:id/state
x-user-address: bchtest:q...
Returns { "state": "...", "vaultId": "hex32" }.

​
Get Deposit Info

GET /api/vaults/:id/deposit
x-user-address: bchtest:q...
Only the vault creator can call this. Returns the unsigned wcTransaction to fund the vault with its state NFT (required for the first deposit). Subsequent deposits are plain P2SH sends to contractAddress. Response 
{
  "contractAddress": "bchtest:p...",
  "totalDeposit": 10,
  "currentBalance": 0,
  "amountToDeposit": 10,
  "wcTransaction": { ... },
  "stateNft": {
    "tokenCategory": "hex32",
    "commitment": "hex..."
  },
  "depositSatoshis": "1000000000"
}

​
Update Balance (Confirm Deposit)

POST /api/vaults/:id/update-balance
x-user-address: bchtest:q...

{ "txid": "hex64", "amount": 10 }
Verifies the transaction on-chain and updates the vault balance. The first deposit must include a mutable NFT output to the contract address.

​
Add Signer (Off-chain)

POST /api/vaults/:id/signers
x-user-address: bchtest:q...

{ "signerAddress": "bchtest:qu..." }
Creator-only. Adds a viewer-level signer record in the database.