Ctrl+K

Unstake from Self-Custody Wallet

Overview

To transact using your staked assets, including the rewards you earned, you must first unstake them. Unstaked assets stop receiving rewards. When unstaking, some assets have a defined cooldown period when the asset can't be used. Once the delegated amount is unlocked, you can transfer the funds out of the staking wallet.

For many assets, unstaking requires 2 transactions:

  • An unstaking transaction to start the unstaking process.
  • A claim transaction to retrieve the delegated amount which, including rewards.

Each transaction must abide by your policies, requiring approval, if configured, followed by signing and broadcasting.

When you submit an unstaking request, BitGo determines the number of transactions needed to unstake and generates the first unstaking transaction for you to approve and sign. After BitGo broadcasts the full-signed unstaking transaction, the cooldown period begins. When the cooldown period finishes, BitGo automatically generates the claim transaction you to approve and sign.

Note: Unstaking protocols differ by asset. To learn asset-specific unstaking details, you can call the List coins available for staking endpoint.

Prerequisites

1. Create Unstaking Request

Create an unstaking request by specifying the unstaking details and sending them to BitGo. The following example shows the minimum required parameters for unstaking ether.

Note: For ether, currently only wallet administrators can create an unstaking request.

Endpoint: Create staking request

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export CLIENT_ID="<YOUR_CLIENT_ID>"
export DELEGATION_ID="<YOUR_DELEGATION_ID>"

curl -X POST \
  https://app.bitgo-test.com/api/staking/v1/$COIN/wallets/$WALLET_ID/requests \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "clientId": "'"$CLIENT_ID"'",
    // For assets other than ETH, pass delegationId
    "delegationId": "'"$DELEGATION_ID"'",
    // For ETH, pass delegationIds
    // Excluding delegationIds unstakes from all validators
    "type": "UNSTAKE"
  }'

Step Result

BitGo generates an unstaking transaction for you to approve and sign.

Note: For ETH, you must wait for the unstaking transaction to complete before initiating a new unstaking request for the same wallet.

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "id": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
  "requestingUserId": "6092e75c451052000636831deb797bd1",
  "type": "UNSTAKE",
  "enterpriseId": "1032e75c451052000436831deb797af1",
  "walletId": "2032e75g451052000636831abd797bd3",
  "walletType": "custody",
  "withdrawalAddress": "0xeea83a40a0fd35096b84395c1ae14900e460c7a3",
  "coin": "hteth",
  "status": "NEW",
  "statusModifiedDate": "2023-04-19T23:15:12.7244Z",
  "createdDate": "2023-04-19T23:15:12.724395Z",
  "delegations": [
    {
      "id": "e0225adbc-66a3-4ccd-9a9d-726a05bca0cf",
      "delegationAddress": "8dcf640ca21a6e411ce8a2645febdb45cc247272e9fe71246006a54222bcdf0c4881ed30b787d5383f622514483bb427",
      "withdrawalAddress": "0xeea83a40a0fd35096b84395c1ae14900e460c7a3",
      "delegated": "32003969181000000000",
      "coin": "eth",
      "walletId": "2032e75g451052000636831abd797bd3",
      "status": "ACTIVE",
      "rewards": "807047532000000000",
      "lockedRewards": "0",
      "pendingUnstake": "32003969181000000000",
      "pendingStake": "0",
      "reserved": "0",
      "pendingReserved": "0",
      "apy": "4.7200"
    }
  ]
}

2. Get Request Status (Optional)

Validators must process your unstaking request before the request is ready for approval and signing. To get notified when unstaking requests are pending approval, you can Create Webhooks. To get notified when unstaking requests are pending approval or signature, you can call the following:

Endpoint: List staking requests by enterprise

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export WALLET_TYPE="<YOUR_WALLET_TYPE>"
export WALLET_ID="<YOUR_WALLET_ID>"

curl -X GET \
  https://app.bitgo-test.com/api/staking/v1/enterprises/$ENTERPRISE_ID/requests/transactions \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "walletType": "'"$WALLET_TYPE"'",
    "walletId": "'"$WALLET_ID"'",
    "requestType": "STAKE",
    "requestStatus": "PENDING_APPROVAL"
  }'

Step Result

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
{
        "summary": "Ethereum Staking Request Results Example",
        "value": {
          "page": 1,
          "totalPages": 1,
          "totalElements": 1,
          "requests": [
            {
              "id": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
              "clientId": "f054adbc-26a3-4acd-8a9d-726a05bca0dr",
              "requestUserId": "6092e75c451052000636831deb797bd1",
              "enterpriseId": "1032e75c451052000436831deb797af1",
              "walletId": "2032e75g451052000636831abd797bd3",
              "walletType": "hot",
              "type": "UNSTAKE",
              "coin": "hteth",
              "createdDate": "2022-01-10T14:32:28.000Z",
              "statusModifiedDate": "2022-01-10T14:32:28.000Z",
              "status": "NEW",
              "withdrawalAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecd7c",
              "delegations": [
                {
                  "id": "e0225adbc-66a3-4ccd-9a9d-726a05bca0cf",
                  "delegationAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecdy5",
                  "withdrawalAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecd7c",
                  "delegated": "3200000000000000000",
                  "status": "PENDING_APPROVAL",
                  "rewards": "0",
                  "lockedRewards": "0",
                  "pendingUnstake": "3200000000000000000",
                  "pendingStake": "0",
                  "apy": "8.3",
                  "coin": "hteth",
                  "walletId": "2032e75g451052000636831abd797bd3",
                  "unstakingFee": "100000000000000",
                  "unstakingMin": "0"
                },
                {
                  "id": "e0225adbc-55b43-5tta-9a9d-726a05bca0ai",
                  "delegationAddress": "0x3b6406c9710f588ca733360bfa8033d0ef9ecre4",
                  "withdrawalAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecd7c",
                  "delegated": "3200000000000000000",
                  "status": "PENDING_APPROVAL",
                  "rewards": "0",
                  "lockedRewards": "0",
                  "pendingUnstake": "3200000000000000000",
                  "pendingStake": "0",
                  "apy": "8.3",
                  "coin": "hteth",
                  "walletId": "2032e75g451052000636831abd797bd3",
                  "unstakingFee": "1000000000000000",
                  "unstakingMin": "0"
                }
              ],
              "transactions": [
                {
                  "id": "d0355adbc-55b43-5tta-9a9d-726a05bca0ai",
                  "stakingRequestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
                  "createdDate": "2022-01-10T14:32:28.000Z",
                  "statusModifiedDate": "2022-01-10T14:32:28.000Z",
                  "status": "PENDING_APPROVAL",
                  "amount": "3200000000000000000",
                  "transactionType": "delegate",
                  "delegationId": "e0225adbc-66a3-4ccd-9a9d-726a05bca0cf",
                  "buildParams": {
                    "recipients": {
                      "amount": "3200000000000000000",
                      "address": "0xff50ed3d0ec03aC01D4C79aAd74928BFF48a7b2b",
                      "data": "fds0934rnnio390nw"
                    },
                    "stakingParams": {
                      "requestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
                      "amount": "3200000000000000000",
                      "validator": "0x5a6406c9710f588ca733360bfa8033d0ef9ecdy5",
                      "actionType": "delegate"
                    },
                    "gasPrice": "1000000000000000",
                    "gasLimit": "3000000000000000"
                  }
                },
                {
                  "id": "i0500adbc-55b43-5tta-9a9d-726a05bca0op",
                  "stakingRequestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
                  "createdDate": "2022-01-10T14:32:28.000Z",
                  "statusModifiedDate": "2022-01-10T14:32:28.000Z",
                  "status": "PENDING_APPROVAL",
                  "amount": "3200000000000000000",
                  "transactionType": "delegate",
                  "delegationId": "e0225adbc-55b43-5tta-9a9d-726a05bca0ai",
                  "buildParams": {
                    "recipients": {
                      "amount": "3200000000000000000",
                      "address": "0xff50ed3d0ec03aC01D4C79aAd74928BFF48a7b2b",
                      "data": "fds0934rnnio390nw"
                    },
                    "stakingParams": {
                      "requestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
                      "amount": "3200000000000000000",
                      "validator": "0x3b6406c9710f588ca733360bfa8033d0ef9ecre4",
                      "actionType": "delegate"
                    },
                    "gasPrice": "1000000000000000",
                    "gasLimit": "3000000000000000"
                  }
                }
              ],
              "amount": "6400000000000000000",
              "gasPrice": "1000000000000000"
            }
          ]
        }
      }

3. Approve Request (Optional)

If you have a policy that requires approval, you must approve the unstaking request before signing and broadcasting.

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

Endpoint: Update Pending Approval

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
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

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    "id": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
    "coin": "hteth",
    "wallet": "2032e75g451052000636831abd797bd3",
    "enterprise": "1032e75c451052000436831deb797af1",
    "creator": "62ab90e06dfda30007974f0a52a12995",
    "createDate": "2022-01-10T14:32:28Z",
    "info": {
        "type": "transactionRequest",
        "transactionRequest": {
            "requestedAmount": "3200000000000000000",
            "fee": 20451,
            "sourceWallet": "2032e75g451052000636831abd797bd3",
            "policyUniqueId": "654ec786c07fe8dc0dcfe03f",
            "recipients": [
                {
                    "address": "0x5a6406c9710f588ca733360bfa8033d0ef9ecdy5",
                    "amount": "3200000000000000000",
                    "_id": "65529448bd87efe59c3b0158"
                }
            ],
            "coinSpecific": {}
        }
    },
    "state": "approved",
    "scope": "wallet",
    "userIds": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc"
    ],
    "approvalsRequired": 1,
    "singleRunResults": [
        {
            "ruleId": "Custody Enterprise Transaction ID Verification",
            "triggered": false,
            "_id": "65529448bd87efe59c3b0157"
        }
    ],
    "resolvers": [
        {
            "user": "621d08a634ad8a0007fcddffd7c429cc",
            "date": "2022-01-11T13:30:14Z",
            "resolutionType": "pending"
        }
    ]
}

4. Sign and Send Request

  • JavaScript
1
2
3
4
5
6
 const transactions = await stakingWallet.getTransactionsReadyToSign(stakingRequest.id);
 if (!transactions.allSigningComplete && transactions.transactions.length > 0) {
      transactions.transactions.forEach((transaction: StakingTransaction) => {
           await stakingWallet.buildSignAndSend({ walletPassphrase: 'walletPassphrase' }, transaction);
       });
 }

Step Result

The unstaking request is half-signed and sent to BitGo for final signing and broadcasting to the blockchain.

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
{
  "id": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
  "clientId": "f054adbc-26a3-4acd-8a9d-726a05bca0dr",
  "requestUserId": "6092e75c451052000636831deb797bd1",
  "enterpriseId": "1032e75c451052000436831deb797af1",
  "walletId": "2032e75g451052000636831abd797bd3",
  "walletType": "hot",
  "type": "UNSTAKE",
  "coin": "hteth",
  "createdDate": "2022-01-10T14:32:28Z",
  "statusModifiedDate": "2022-01-10T14:32:28Z",
  "status": "NEW",
  "withdrawalAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecd7c",
  "delegations": [
    {
      "id": "e0225adbc-66a3-4ccd-9a9d-726a05bca0cf",
      "delegationAddress": "0x5a6406c9710f588ca733360bfa8033d0ef9ecdy5",
      "delegated": 3200000000000000000,
      "status": "PENDING",
      "rewards": 0,
      "pendingUnstake": 3200000000000000000,
      "apy": 8.3,
      "coin": "hteth",
      "walletId": "2032e75g451052000636831abd797bd3",
      "unstakingFee": 100000000000000,
      "unstakingMin": 0
    },
    {
      "id": "e0225adbc-55b43-5tta-9a9d-726a05bca0ai",
      "delegationAddress": "0x3b6406c9710f588ca733360bfa8033d0ef9ecre4",
      "delegated": 3200000000000000000,
      "status": "PENDING",
      "rewards": 0,
      "pendingUnstake": 3200000000000000000,
      "apy": 8.3,
      "coin": "hteth",
      "walletId": "2032e75g451052000636831abd797bd3",
      "unstakingFee": 1000000000000000,
      "unstakingMin": 0
    }
  ],
  "transactions": [
    {
      "stakingRequestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
      "createdDate": "2022-01-10T14:32:28Z",
      "statusModifiedDate": "2022-01-10T14:32:28Z",
      "status": "PENDING",
      "amount": 3200000000000000000,
      "transactionType": "delegate",
      "delegationId": "e0225adbc-66a3-4ccd-9a9d-726a05bca0cf",
      "buildParams": {
        "recipients": {
          "amount": 3200000000000000000,
          "address": "0xff50ed3d0ec03aC01D4C79aAd74928BFF48a7b2b",
          "data": "fds0934rnnio390nw"
        },
        "stakingParams": {
          "requestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
          "amount": 3200000000000000000,
          "validator": "0x5a6406c9710f588ca733360bfa8033d0ef9ecdy5",
          "actionType": "delegate"
        },
        "gasPrice": 1000000000000000,
        "gasLimit": 3000000000000000
      }
    },
    {
      "stakingRequestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
      "createdDate": "2022-01-10T14:32:28Z",
      "statusModifiedDate": "2022-01-10T14:32:28Z",
      "status": "PENDING",
      "amount": 3200000000000000000,
      "transactionType": "delegate",
      "delegationId": "e0225adbc-55b43-5tta-9a9d-726a05bca0ai",
      "buildParams": {
        "recipients": {
          "amount": 3200000000000000000,
          "address": "0xff50ed3d0ec03aC01D4C79aAd74928BFF48a7b2b",
          "data": "fds0934rnnio390nw"
        },
        "stakingParams": {
          "requestId": "e055adbc-66a3-4ccd-9a9d-726a05bca0cf",
          "amount": 3200000000000000000,
          "validator": "0x3b6406c9710f588ca733360bfa8033d0ef9ecre4",
          "actionType": "delegate"
        },
        "gasPrice": 1000000000000000,
        "gasLimit": 3000000000000000
      }
    }
  ],
  "amount": 6400000000000000000,
  "gasPrice": 1000000000000000
}

Next

You can view the completed unstaking transaction in BitGo or on a blockchain explorer. Depending on the blockchain, it may have a cooldown period before you can create further transactions with the asset.

If necessary, BitGo automatically generates a second claim transaction after the unstaking cooldown period. Like the unstaking transaction, you must approve and sign the transaction using the same steps above.

See Also