Skip to main content

Vaults

A vault is a security and governance boundary backed by its own MPC key material and access control. Each vault has an independent set of signing permissions and approval rules.

Create a Vault​

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "organizationId": "djk2wDuMhsx9KR2r7JgBQW",
       "name": "Treasury Vault",
       "quorum": [
         {
           "approvers": ["client-id-1", "client-id-2"],
           "consensus": 2,
           "group": "default"
         }
       ]
     }' \
     https://api.carabaas.com/api/v1/vaults

After creation, the vault enters pending state while MPC key generation runs between cosigners. Once complete, the vault transitions to active.

Vault States​

StatusDescription
pendingVault is being set up, MPC key generation in progress
activeVault is ready for use
suspendedOperations temporarily disabled
inactiveVault is archived

List Vaults​

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults?organizationId=djk2wDuMhsx9KR2r7JgBQW"

With Relations​

Load related data in a single request using the relations[] parameter:

# Include organization info, account count, and quorum settings
curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults?organizationId=djk2wDuMhsx9KR2r7JgBQW&relations[]=organization&relations[]=accountsCount&relations[]=quorum"

Filter by Status​

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults?organizationId=djk2wDuMhsx9KR2r7JgBQW&filter[status]=active"

Get Vault Details​

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults/{vaultId}"

Response includes: id, name, quorum, pending quorum, addresses count, accounts count, and balances.

Get Vault Balances​

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.carabaas.com/api/v1/vaults/{vaultId}?relations[]=balances"
{
  "data": {
    "id": "kR7mNpX2wQvL9sYhBjD4eT",
    "name": "Treasury Vault",
    "balances": [
      {
        "network": "ethereum-mainnet",
        "asset": "c1",
        "amount": "5000000000000000000",
        "amountFormatted": "5.0",
        "availableBalance": "4800000000000000000",
        "availableBalanceFormatted": "4.8"
      }
    ]
  }
}

Manage Vault Clients​

Assign a Client to a Vault​

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "clientId": "f7hJ9kL1mN3pQ5rS7tUvWx",
       "role": "Operator"
     }' \
     https://api.carabaas.com/api/v1/vaults/{vaultId}/clients

List Vault Clients​

curl -H "Authorization: Bearer $TOKEN" \
     https://api.carabaas.com/api/v1/vaults/{vaultId}/clients

Change Client Role in Vault​

curl -X PATCH \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "role": "Treasurer" }' \
     https://api.carabaas.com/api/v1/vaults/{vaultId}/clients/{clientId}/role

Quorum Management​

Vaults support quorum-based approval (M-of-N): N required approvals from M eligible approvers.

Create a Quorum​

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "vaultId": "kR7mNpX2wQvL9sYhBjD4eT",
       "approvers": ["client-id-1", "client-id-2", "client-id-3"],
       "consensus": 2,
       "group": "default"
     }' \
     https://api.carabaas.com/api/v1/vaults/quorums

List Vault Quorums​

curl -H "Authorization: Bearer $TOKEN" \
     https://api.carabaas.com/api/v1/vaults/{vaultId}/quorums

Vault Design Patterns​

PatternDescription
Hot / Cold splitHot vault for daily operations, cold vault for reserves
Per-customer custodyOne vault per customer with isolated approval policies
DepartmentalSeparate vaults for finance, ops, and risk teams
Strategy-basedDedicated vaults for staking, DeFi, and trading

See Also​