POST/api/v1/create-psbt

Create a transaction proposal

Creates a transaction proposal that spends from a vault, returning the proposal id and the unsigned PSBT for the vault's approvers to sign.

AccessRequires a permission in the workspaceMANAGE_WORKSPACE

Every movement out of a vault, whether a transfer, a mint, a burn, or a token deployment, is carried by an underlying transaction proposal that collects member approvals until the vault's threshold is met. This call creates that proposal for a direct Bitcoin send. Nothing is signed and nothing reaches the network yet. The signing workflow describes how the same sequence appears in the application.

The vault in wallet_id must belong to the workspace in workspace_id, and you must hold MANAGE_WORKSPACE in that workspace. The response carries the proposal's id and the unsigned PSBT in base64. Pass the PSBT to the members who will approve it, and they return their signatures through POST /api/v1/sign-psbt.

Token movements do not start here

Use this endpoint for a direct Bitcoin send, with tx_type set to send. Token actions such as transfer, mint, and burn go through POST /api/v1/call-contract, which sets tx_type itself and applies the permission for the action being requested.

Body parameters

wallet_idstringrequired

The vault the proposal spends from. It must belong to the workspace in workspace_id.

workspace_idnumberrequired

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

tx_typestringrequired

The kind of proposal to build. Direct callers use send. Token flows set this value internally.

recipientsstring[]optional

Destination addresses for the spend.

descriptionstringoptional

A note describing the movement. It comes back on the proposal.

op_returnstringoptional

Data to carry in the transaction's OP_RETURN output.

contract_idsstring[]optional

Ids of the token contracts the proposal relates to.

bash

curl -X POST "$SQRL_API/api/v1/create-psbt" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "wallet_id": "vault_01HZXB2K7P",
        "workspace_id": 342,
        "tx_type": "send",
        "recipients": ["bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"],
        "description": "August settlement to custody partner"
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/create-psbt`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    wallet_id: "vault_01HZXB2K7P",
    workspace_id: 342,
    tx_type: "send",
    recipients: ["bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"],
    description: "August settlement to custody partner",
  }),
});
const { psbt_id, psbt_base64 } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/create-psbt", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "wallet_id": "vault_01HZXB2K7P",
        "workspace_id": 342,
        "tx_type": "send",
        "recipients": ["bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"],
        "description": "August settlement to custody partner",
    }))
    .send()
    .await?;

Response200 OK

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

#What happens next

The proposal now waits for approvals. Each approver signs the PSBT with their own key and submits the result through POST /api/v1/sign-psbt, and GET /api/v1/psbt shows who has approved so far. When the approval that meets the vault's threshold arrives, the proposal is finalised and submitted to the Bitcoin network automatically.

Was this page helpful?