POST/api/v1/forward-to-vault

Forward Bitcoin to a vault

Moves Bitcoin from the caller's signing profile into one of the workspace's vaults, returning a transaction proposal for the caller to sign, and recording the movement in the audit log.

AccessRequires a permission in the workspacePAYMENT_INIT

Purchased Bitcoin arrives at the member's own profile address, which only that member can spend from. This call moves it on into a vault, and it does so as a normal transaction proposal rather than as a special case: the response carries a psbt_id and the unsigned PSBT, which you sign and submit through POST /api/v1/sign-psbt. Because spending from a signing profile needs only its owner's signature, you approve this proposal alone. The movement is recorded in the audit log.

wallet_address names the profile address to forward from. Read it from GET /api/v1/signing-profile-address: where a member has several registered keys, that address is what identifies which key is meant, and if your application and the platform disagree about it the request is rejected rather than guessed. The destination vault must be one of the workspace's own vaults, which GET /api/v1/list-wallets lists.

Forward an amount or sweep the balance

Send amount_sats to forward a fixed amount, or sweep set to true to move the whole balance of the profile address. fee_sats is required in both cases. Set allow_unconfirmed to true to let the forward chain off a deposit that has not confirmed yet, for example a purchase MoonPay has only just sent.

Body parameters

workspace_idnumberrequired

The workspace the vault belongs to. You must hold PAYMENT_INIT in it.

vault_idstringrequired

The vault to forward into. It must be one of the workspace's vaults.

networkstringrequired

The Bitcoin network the forward happens on. Either mainnet or testnet.

amount_satsnumberoptional

Amount to forward, in satoshis. Use this instead of sweep to move a fixed amount.

fee_satsnumberrequired

Miner fee to pay for the forwarding transaction, in satoshis.

sweepbooleanoptional

Set to true to forward the whole balance of the profile address instead of naming an amount.

allow_unconfirmedbooleanoptional

Set to true to let the forward chain off a deposit that has not confirmed yet.

wallet_addressstringoptional

The profile address to forward from, as returned by signing-profile-address.

bash

curl -X POST "$SQRL_API/api/v1/forward-to-vault" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "workspace_id": 342,
        "vault_id": "vault_01HZXB2K7P",
        "network": "mainnet",
        "amount_sats": 8120000,
        "fee_sats": 2400,
        "allow_unconfirmed": false,
        "wallet_address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h"
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/forward-to-vault`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: 342,
    vault_id: "vault_01HZXB2K7P",
    network: "mainnet",
    amount_sats: 8120000,
    fee_sats: 2400,
    allow_unconfirmed: false,
    wallet_address: "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
  }),
});
const { psbt_id, psbt_base64 } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/forward-to-vault", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "workspace_id": 342,
        "vault_id": "vault_01HZXB2K7P",
        "network": "mainnet",
        "amount_sats": 8120000,
        "fee_sats": 2400,
        "allow_unconfirmed": false,
        "wallet_address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    }))
    .send()
    .await?;

Response200 OK

{
"psbt_id": "psbt_01HZXC9F4R",
"psbt_base64": "cHNidP8BAH0CAAAAAe1f…AAAA"
}

#What happens next

Sign the PSBT with the key your profile address is derived from and submit it through POST /api/v1/sign-psbt. Yours is the only approval the proposal needs, so it is finalised and submitted to the Bitcoin network as soon as your signature is recorded, and that is irreversible. GET /api/v1/psbt shows the proposal's status and its Bitcoin transaction id once broadcast, and the coins then count towards the vault's balance.

Was this page helpful?