POST/api/v1/create_wallet

Create a vault

Creates a multi-signature vault in a workspace on the chosen Bitcoin network, setting how many approvals a spend requires, which registered keys may approve, and the vault's spending limit.

AccessRequires a signed-in caller

The vault address is derived from the signer set and the threshold, so both are fixed once the vault exists. Choose them deliberately: the current interface does not add or remove signers afterwards. Every key in key_ids must already be registered through POST /api/v1/register-key and must belong to the network you are creating the vault on.

Mainnet moves real value

A vault created on mainnet transacts in real Bitcoin and real tokens. Confirm the network before you call this endpoint. Testnet is for supervised training and pre-production testing only.

Body parameters

namestringrequired

Display name for the vault, shown throughout the application.

networkstringrequired

The Bitcoin network the vault operates on. Either mainnet or testnet, and it must match the network of every key in key_ids.

mnumberrequired

Required approvals. The M in M-of-N, so 2 for a 2-of-3 vault.

nnumberrequired

Total registered signers. The N in M-of-N, and the number of entries key_ids must contain.

script_typestringrequired

Address format for the vault. Use p2wsh unless your organisation has a specific requirement.

key_idsstring[]required

Ids of the registered signing keys that may approve spends from this vault.

workspace_idnumberrequired

The workspace the vault belongs to. The vault inherits this workspace's network.

transaction_limitstringrequired

Maximum value for a single spend from this vault, as a decimal string.

cycle_periodstringrequired

How often the vault's usage counter resets. W for weekly or M for monthly.

cycle_daynumberrequired

The day the counter resets. Day of the week for a weekly cycle, day of the month for a monthly cycle.

bash

curl -X POST "$SQRL_API/api/v1/create_wallet" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "name": "Issuance vault",
        "network": "mainnet",
        "m": 2,
        "n": 3,
        "script_type": "p2wsh",
        "key_ids": ["key_01HZX4M8QT", "key_01HZX52NRB", "key_01HZX5A3WD"],
        "workspace_id": 342,
        "transaction_limit": "250000.00",
        "cycle_period": "M",
        "cycle_day": 1
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/create_wallet`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "Issuance vault",
    network: "mainnet",
    m: 2,
    n: 3,
    script_type: "p2wsh",
    key_ids: ["key_01HZX4M8QT", "key_01HZX52NRB", "key_01HZX5A3WD"],
    workspace_id: 342,
    transaction_limit: "250000.00",
    cycle_period: "M",
    cycle_day: 1,
  }),
});
const { wallet_id } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/create_wallet", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "name": "Issuance vault",
        "network": "mainnet",
        "m": 2,
        "n": 3,
        "script_type": "p2wsh",
        "key_ids": ["key_01HZX4M8QT", "key_01HZX52NRB", "key_01HZX5A3WD"],
        "workspace_id": 342,
        "transaction_limit": "250000.00",
        "cycle_period": "M",
        "cycle_day": 1,
    }))
    .send()
    .await?;

Response200 OK

{
"wallet_id": "vault_01HZXB2K7P"
}

#What happens next

The vault appears on the Vaults page and every signer receives a notification. Fund it by sending BTC to its address, which GET /api/v1/get-vault returns. From then on, moving value out of it goes through a transaction proposal that collects approvals until the threshold is met.

Was this page helpful?