By Wallet Type

Withdraw from Wallet - Self-Custody Multisig (Manual)

Overview

You build withdrawals from self-custody multisignature wallets by submitting transaction details to BitGo. BitGo uses the data you pass to construct an unsigned transaction that wallet co-signers can sign and wallet admins can approve. Once the transaction is half signed and approved, you send it to BitGo for final signing and broadcasting to the blockchain.

If you don't need this level of granular control for your withdrawals, see the integration guide for the Express flow.

Prerequisites

Cookbook

Need just the steps? Expand the cookbook below to get started:

Withdraw - Self-Custody Multisig (Manual)Open Cookbook

1. Build Transaction

Build the transaction by specifying the transaction details and sending them to BitGo. The following example is shows the minimum required parameters for sending bitcoin.

Endpoint: Build a Transaction

export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ADDRESS="<DESTINATION_ADDRESS>"
export AMOUNT="<AMOUNT_IN_BASE_UNITS>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/tx/build \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "recipients": [
      {
        "amount": "'"$AMOUNT"'",
        "address": "'"$ADDRESS"'",
      }
    ]
  }'

Note

If you're building transactions for a UTXO asset in quick succession, BitGo recommends reserving unspents by passing the reservation and expireTime parameters. Reserving unspents avoids errors by ensuring the UTXO aren't included in subsequent builds.

Step Result

BitGo uses the data you pass to build an unsigned transaction. The following example builds a withdrawal of 10,000 sats of TBTC4.

{
  "txHex": "01000000010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000000ffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e6269839900000000",
  "txInfo": {
    "nP2SHInputs": 0,
    "nSegwitInputs": 1,
    "nOutputs": 2,
    "unspents": [
      {
        "chain": 10,
        "index": 5,
        "redeemScript": "0020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467daf",
        "witnessScript": "522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae",
        "id": "d5621704d7dd06d55c6016709e75a1787fb661d565290611e3eff914f03a4d0e:0",
        "address": "2N5bzKehiq63uqT9hKDVaPWm1LmrPbHDz2S",
        "value": 100000,
        "valueString": "100000"
      }
    ],
    "changeAddresses": [
      "tb1ps5xs4drx69wtz4ja655dfktsnulydaqag8lxm992qymcucnfswvspwdwxq"
    ],
    "walletAddressDetails": {
      "tb1ps5xs4drx69wtz4ja655dfktsnulydaqag8lxm992qymcucnfswvspwdwxq": {
        "chain": 41,
        "index": 3,
        "coinSpecific": {}
      }
    },
    "txHexes": {}
  },
  "feeInfo": {
    "size": 226,
    "fee": 20451,
    "feeRate": 90491,
    "feeString": "20451",
    "payGoFee": 0,
    "payGoFeeString": "0"
  },
  "debug": {
    "dimensions": {
      "nP2shInputs": 0,
      "nP2shP2wshInputs": 1,
      "nP2wshInputs": 0,
      "nP2trKeypathInputs": 0,
      "nP2trScriptPathLevel1Inputs": 0,
      "nP2trScriptPathLevel2Inputs": 0,
      "nP2shP2pkInputs": 0,
      "outputs": { "count": 2, "size": 75 }
    }
  },
  "coin": "tbtc4"
}

2. Sign Transaction

Using the txHex and txInfo returned in the prior call, sign the transaction using your private key.

Endpoint:

export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export COIN="<ASSET_ID>"
export WALLET="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export PRV="<YOUR_PRIVATE_KEY>"
export USER_PUB="<YOUR_USER_PUBLIC_KEY>"
export BACKUP_PUB="<YOUR_BACKUP_PUBLIC_KEY>"
export BITGO_PUB="<BITGO_PUBLIC_KEY>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST/api/v2/$COIN/signtx \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "prv": "'"$PRV"'",
    "pubs": [
      "'"$USER_PUB"'",
      "'"$BACKUP_PUB"'",
      "'"$BITGO_PUB"'"
    ],
    "txPrebuild": {
      "wallet": ""'"$WALLET"'"",
      "txHex": "01000000010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000000ffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e6269839900000000",
      "txInfo": {
        "nP2SHInputs": 0,
        "nSegwitInputs": 1,
        "nOutputs": 2,
        "unspents": [
          {
            "chain": 10,
            "index": 5,
            "redeemScript": "0020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467daf",
            "witnessScript": "522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae",
            "id": "d5621704d7dd06d55c6016709e75a1787fb661d565290611e3eff914f03a4d0e:0",
            "address": "2N5bzKehiq63uqT9hKDVaPWm1LmrPbHDz2S",
            "value": 100000,
            "valueString": "100000"
          }
        ],
        "changeAddresses": [
          "tb1ps5xs4drx69wtz4ja655dfktsnulydaqag8lxm992qymcucnfswvspwdwxq"
        ],
        "walletAddressDetails": {
          "tb1ps5xs4drx69wtz4ja655dfktsnulydaqag8lxm992qymcucnfswvspwdwxq": {
            "chain": 41,
            "index": 3,
            "coinSpecific": {}
          }
        },
        "txHexes": {}
      },
      "feeInfo": {
        "size": 226,
        "fee": 20451,
        "feeRate": 90491,
        "feeString": "20451",
        "payGoFee": 0,
        "payGoFeeString": "0"
      },
      "debug": {
        "dimensions": {
          "nP2shInputs": 0,
          "nP2shP2wshInputs": 1,
          "nP2wshInputs": 0,
          "nP2trKeypathInputs": 0,
          "nP2trScriptPathLevel1Inputs": 0,
          "nP2trScriptPathLevel2Inputs": 0,
          "nP2shP2pkInputs": 0,
          "outputs": { "count": 2, "size": 75 }
        }
      },
      "coin": "tbtc4"
    }
  }'

Step Result

BitGo returns a txHex for the half-signed transaction.

{
  "txHex": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990500483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201000069522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000"
}

3. Send Transaction

Using the txHex returned in the prior step, send the half-signed transaction to BitGo.

Endpoint: Send Half-Signed Transaction

export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/tx/send \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "halfSigned": {
    "txHex": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990500483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201000069522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000"
  }
}'

Step Result

If your withdrawal doesn't require approval, BitGo applies the final signature using the BitGo key and broadcasts the transaction to the blockchain. If you Create Policy Rules to require approvals on withdrawals, the transaction remains in a pending-approval status until a wallet admin approves it.

{
  "transfer": {
    "entries": [
      {
        "address": "2NAVwU9KtPyE4h3RyHkhbLgQQvrc4EuSXD3", // sender address
        "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
        "value": -100000,
        "valueString": "-100000"
      },
      {
        "address": "2Mw241n14gJx2PcK2kijidZ2BPGeJBdwp1A", // receiver address
        "value": 10000,
        "valueString": "10000",
        "isChange": false,
        "isPayGo": false
      },
      {
        "address": "tb1pq9m0lqjg4lfa0rj9wzjjjumk3l6vecndt8wla5756ktre6h6fexqg7z0vq", // change address that collects the UTXO
        "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
        "value": 70013,
        "valueString": "70013",
        "isChange": true,
        "isPayGo": false
      }
    ],
    "id": "65528cde229f765c57a8f4d1eb762908",
    "coin": "tbtc4",
    "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
    "walletType": "hot",
    "enterprise": "62c5ae8174ac860007aff138a2d74df7",
    "txid": "c68916ddc1672ec62c474ef0839ec479ad9b2dabc2249177ce6be6247f81dfe7",
    "txidType": "transactionHash",
    "height": 999999999,
    "heightId": "999999999-65528cde229f765c57a8f4d1eb762908",
    "date": "2023-11-13T20:53:51.445Z",
    "type": "send",
    "value": -29987,
    "valueString": "-29987",
    "intendedValueString": "-29987",
    "baseValue": -10000,
    "baseValueString": "-10000",
    "baseValueWithoutFees": -10000,
    "baseValueWithoutFeesString": "-10000",
    "feeString": "19987",
    "payGoFee": 0,
    "payGoFeeString": "0",
    "usd": -11.0275843085,
    "usdRate": 36774.55,
    "state": "signed",
    "instant": false,
    "isReward": false,
    "isFee": false,
    "tags": [
      "654ec786c07fe8dc0dcfe03916ec5bb0",
      "62c5ae8174ac860007aff138a2d74df7"
    ],
    "history": [
      { "date": "2023-11-13T20:53:51.444Z", "action": "signed" },
      {
        "date": "2023-11-13T20:53:50.646Z",
        "user": "62ab90e06dfda30007974f0a52a12995",
        "action": "created"
      }
    ],
    "signedDate": "2023-11-13T20:53:51.444Z",
    "vSize": 225,
    "metadata": [],
    "signedTime": "2023-11-13T20:53:51.444Z",
    "createdTime": "2023-11-13T20:53:50.646Z"
  },
  "txid": "c68916ddc1672ec62c474ef0839ec479ad9b2dabc2249177ce6be6247f81dfe7",
  "tx": "01000000000101c76ddd01e185e12e995c6f4f36bd440867296d3f224751d73432d465be93478100000000232200204fe0358ee98bef039832fa3a4dc96cb4b265448f3d89c4a05a997a3481f3da6effffffff02102700000000000017a9142962c500562c9db56434702a629ff08fcbd5add0877d110100000000002251200176ff8248afd3d78e4570a52973768ff4cce26d59ddfed3d4d5963ceafa4e4c0400483045022100c4db3db14398d5cc4c9a2a3e4a8fa4fa3b8960ad80eb840e51e182f7561cf6c102207a6410e68aaf7327a1daed83838a39b96e37e22783d879a838640035b6059bcc0147304402205888b2863bb8fc296ed51374db2d03c7fdc746fd0d6c5ceebbe2246bb76b67840220730c8b8395285767ef1049c40cd6cbdecfb5ecfefd795ac2053b28b7a6b0790f0169522103a4c6a0aa167ef75fcf4a96c53b2dd20aee3afa19d1bc2ec4354328ae87c0976621022e4d77a9d0fecafc7ad4f9cfd9144082cf146b27de945ba26d22f26438c5784b2103ee2fef2c21d48bbd0d3813c71269fca6e1bff51e676b1f0131aa29afceb08f8853ae00000000",
  "status": "signed"
}

4. Approve Transaction (Optional)

Note

If you configure an approval requirement for withdrawals, you can't approve your own transactions - another admin must approve them.

Endpoint: Update Pending Approval

export APPROVAL_ID="<APPROVAL_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export OTP="<YOUR_OTP>"

curl -X PUT \
  https://app.bitgo-test.com/api/v2/pendingApprovals/$APPROVAL_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "state": "approved",
    "otp": "'"$OTP"'"
  }'

Step Result

Once approved, BitGo rebuilds the half-signed transaction, applying the most up-to-date fees. BitGo then applies the final signature using the BitGo key and broadcasts the transaction to the blockchain.

{
    "id": "65529448bd87efe59c3b0156ddfce867",
    "coin": "tbtc4",
    "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
    "enterprise": "62c5ae8174ac860007aff138a2d74df7",
    "creator": "62ab90e06dfda30007974f0a52a12995",
    "createDate": "2023-11-13T21:25:28.022Z",
    "info": {
        "type": "transactionRequest",
        "transactionRequest": {
            "requestedAmount": "10000",
            "fee": 20451,
            "sourceWallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
            "policyUniqueId": "654ec786c07fe8dc0dcfe03f",
            "recipients": [
                {
                    "address": "2N1UvKhtSHLUa9YomSH7n9YMFCkMG2pbmsQ",
                    "amount": "10000",
                    "_id": "65529448bd87efe59c3b0158"
                }
            ],
            "coinSpecific": {
                "tbtc4": {
                    "txHex": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990500483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201000069522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000"
                }
            },
            "validTransaction": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990400483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201473044022049e20c0073f42c9636408efc6c833ebf0e1a8ef13e8cb818dde2f4e2af7f7b7f022000cb3a321d65605b9d51d7f87e34306169607646c8d54a44011b021eff3dbe500169522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000",
            "validTransactionHash": "5ea8d2b93997ed9fa3597a2f3113817c8216f573a0278c2533bb5db50fdb0dff"
        }
    },
    "state": "approved",
    "scope": "wallet",
    "userIds": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc"
    ],
    "approvalsRequired": 1,
    "singleRunResults": [
        {
            "ruleId": "Custody Enterprise Transaction ID Verification",
            "triggered": false,
            "_id": "65529448bd87efe59c3b0157"
        }
    ],
    "resolvers": [
        {
            "user": "621d08a634ad8a0007fcddffd7c429cc",
            "date": "2023-11-13T21:44:27.794Z",
            "resolutionType": "pending"
        }
    ]
}

Next

You can view your completed withdrawal in BitGo or on a blockchain explorer.

See Also