Documentation

Withrawal

Suggest Edits

Since the Bitcoin staking flow is currently limited to only locking bitcoins according to the Babylon launching phases, for the moment there are two ways to initiate the withdrawal process using the Staking API:

  • Wait until the time lock expires and withdraw the staked assets.
  • Unbond the stake before time-lock expiration and withdraw it.

In the first flow, it is considered that a stake will automatically expire after the time-lock period, so that it will be enough to submit the withdrawal transaction to the Bitcoin ledger to withdraw bitcoins.

Unbonding the stake before its expiration involves more steps. First, an additional unstaking request is required to be followed then by a call to a separate API method to broadcast the partially signed unbonding transaction. Only after that, a withdrawal request can be created.

❗️

Please note

In the case of early withdrawal, a fee for unlocking the staked bitcoins is charged. The exact amount to be paid depends on the current chain load.

Request examples are provided using cURL.

Withdrawal after time-lock expiration

  1. Wait until the time lock period set in the stakingDuration parameter expires so that the stake becomes available for withdrawal.

  2. To withdraw an expired stake, generate a withdrawal transaction by sending a POST request to /api/v1/babylon-btc/{network}/staking/withdrawal.

    Example request (for sigNet network):

    curl --request POST \
     --url https://api-test.p2p.org/api/v1/babylon-btc/signet/transaction/withdrawal \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
     {
     "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
     "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
     "withdrawalAddress": "tb1p3e5dfkaxxqgq4vgv4peujcg8dwqe7ry9ky9702hx7jfmvrk5a3yq4q5ua9"
     }'
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.
    • withdrawalAddress — staker withdrawal address.

    Example response:

    {
    "error": null,
    "result": {
      "withdrawalAddress": "tb1p3e5dfkaxxqgq4vgv4peujcg8dwqe7ry9ky9702hx7jfmvrk5a3yq4q5ua9",   
      "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
      "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
      "withdrawalTransactionHex": "70736274ff0100e402000000014f0d8e70d376cda7200bc900803d35dab2658fad9ce15454326b642523660ae90200000000fdffffff04b80b000000000000225120df0ec02350705a695b526f5c7662f33d8f8256cbd80cf8cda6d7c46d7d1578d00000000000000000496a4762626434002be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4bf609ba8977d3fbf4dee7f9d993c41f2fa584ccd27b3e4bf04a5376267e13c000c8025d0000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec48102700000000000000000000000001012bc5690000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec480000000000",
      "fee": 1000
    }
}
    • withdrawalAddress — staker withdrawal address.
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.
    • withdrawalTransactionHex — unsigned transaction for withdrawal request in the hexadecimal format. Sign the transaction and submit it to the Bitcoin blockchain to perform the called action.
    • fee — total fee in SATOSHI charged for processing the transaction.

  3. Use unstakeTransactionHex from the previous step to sign and send the signed transaction to the Bitcoin chain.

Early unbonding and withdrawal

The unbonding process for early withdrawal in the Bitcoin network using the Staking API can be done in a few steps:

  1. Create an unstaking transaction.
  2. Broadcast partially signed transaction to unbond the stake.
  3. Create a withdrawal transaction.

1. Create Unstaking Transaction

  1. Set up the unstake request by sending a POST request to /api/v1/babylon-btc/{network}/staking/unstake.

    Example request (for sigNet network):

    curl --request POST \
     --url https://api-test.p2p.org/api/v1/babylon-btc/signet/staking/unstake \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
     {
     "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
     "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028"
     }'
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.

    Example response:

    {
    "error": null,
    "result": {
       "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
       "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
       "unstakeTransactionHex": "70736274ff0100e402000000014f0d8e70d376cda7200bc900803d35dab2658fad9ce15454326b642523660ae90200000000fdffffff04b80b000000000000225120df0ec02350705a695b526f5c7662f33d8f8256cbd80cf8cda6d7c46d7d1578d00000000000000000496a4762626434002be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4bf609ba8977d3fbf4dee7f9d993c41f2fa584ccd27b3e4bf04a5376267e13c000c8025d0000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec48102700000000000000000000000001012bc5690000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec480000000000",
       "unstakeFee": 1000
    }
}
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.
    • unstakeTransactionHex — unsigned transaction for the unstake request in the hexadecimal format. Sign the transaction to consequently send it to the Bitcoin blockchain.
    • unstakeFee — total fee in SATOSHI charged for unlocking the staked assets and processing the transaction.

  2. Use unstakeTransactionHex from the previous step to sign the transaction. Note that this transaction will only be partially signed, since it must be signed by validators too.

2. Broadcast Unstaking Transaction

To broadcast the partially signed unstaking transaction to the Bitcoin network and unbond your stake before its expiration, send a POST request to /api/v1/babylon-btc/{network}/transaction/unbonding.

Example request (for sigNet network):

curl --request POST \
     --url https://api-test.p2p.org/api/v1/babylon-btc/signet/transaction/unbonding \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
     {
     "stakingTxHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
     "unbondingTxHex": "70736274ff0100e402000000014f0d8e70d376cda7200bc900803d35dab2658fad9ce15454326b642523660ae90200000000fdffffff04b80b000000000000225120df0ec02350705a695b526f5c7662f33d8f8256cbd80cf8cda6d7c46d7d1578d00000000000000000496a4762626434002be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4bf609ba8977d3fbf4dee7f9d993c41f2fa584ccd27b3e4bf04a5376267e13c000c8025d0000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec48102700000000000000000000000001012bc5690000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec480000000000"
     }'
  • stakingTxHash — hash of the initial staking transaction.
  • unbondingTxHex — unsigned transaction for the unbonding request in the hexadecimal format.

Example response:

{
    "error": null,
    "result": {
      "stakingTxHash": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
      "unbondingTxHex": "70736274ff0100e402000000014f0d8e70d376cda7200bc900803d35dab2658fad9ce15454326b642523660ae90200000000fdffffff04b80b000000000000225120df0ec02350705a695b526f5c7662f33d8f8256cbd80cf8cda6d7c46d7d1578d00000000000000000496a4762626434002be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4bf609ba8977d3fbf4dee7f9d993c41f2fa584ccd27b3e4bf04a5376267e13c000c8025d0000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec48102700000000000000000000000001012bc5690000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec480000000000",
      "unbondingTxHash": "02000000000101e64994aad9ebe5f9bbe8344a743aa6dbbc9d5ecab0cc135b2697bbeef7834bfd0000000000ffffffff017869000000000000225120abc575829d73ef108ceba4f1686f657e6e2f70852208eabaa0cd74e248f203a7034031226d5e6be2988bc81b4ede2e507e8795992e2f8dbf73c3c7887ca611ef74d46e4ddcf41734478e088a2c9f110be6bb29f4d8fc9a6c0aca6b2ba648bdb850208a20be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4ad2017921cf156ccb4e73d428f996ed11b245313e37e27c978ac4d2cc21eca4672e4ac2049766ccd9e3cd94343e2040474a77fb37cdfd30530d05f9f1e96ae1e2102c86eba2076d1ae01f8fb6bf30108731c884cddcf57ef6eef2d9d9559e130894e0e40c62cba529c61c050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac073c168cce70e3d66240fcd3ef216f083436f448372fe7cccb668449cbcb15b26639fa5fb4094c2f7ea65e9c176ccd983b1cda874de942d6fb8cd3b4f2e2aa14b00000000",
      "stakerSignature": "304402203f7c0f6c1f7a8f7"
  }
}
  • stakingTxHash — hash of the initial staking transaction.
  • unbondingTxHex — unsigned transaction for the unbonding request in the hexadecimal format.
  • unbondingTxHash — hash of the partially signed unbonding transaction.
  • stakerSignature — staker signature of the unbonding transaction.

3. Create Withdrawal Transaction

  1. Generate a withdrawal transaction by sending a POST request to /api/v1/babylon-btc/{network}/staking/withdrawal.

    Example request (for sigNet network):

    curl --request POST \
     --url https://api-test.p2p.org/api/v1/babylon-btc/signet/transaction/withdrawal \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
     {
     "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
     "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
     "withdrawalAddress": "tb1p3e5dfkaxxqgq4vgv4peujcg8dwqe7ry9ky9702hx7jfmvrk5a3yq4q5ua9"
     }'
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.
    • withdrawalAddress — staker withdrawal address.

    Example response:

    {
    "error": null,
    "result": {
      "withdrawalAddress": "tb1p3e5dfkaxxqgq4vgv4peujcg8dwqe7ry9ky9702hx7jfmvrk5a3yq4q5ua9",   
      "stakerPublicKey": "02be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4",
      "stakeTransactionHash": "80410b51dabc9d31edab7fbdff26ac3bda70d3131830239ac0e3e9c8c1fc4028",
      "withdrawalTransactionHex": "70736274ff0100e402000000014f0d8e70d376cda7200bc900803d35dab2658fad9ce15454326b642523660ae90200000000fdffffff04b80b000000000000225120df0ec02350705a695b526f5c7662f33d8f8256cbd80cf8cda6d7c46d7d1578d00000000000000000496a4762626434002be65fdd561fee421c4f4564b02e4de31f74836b9b8cd1bbbf9d9c544733614e4bf609ba8977d3fbf4dee7f9d993c41f2fa584ccd27b3e4bf04a5376267e13c000c8025d0000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec48102700000000000000000000000001012bc5690000000000002251208e68d4dba630100ab10ca873c961076b819f0c85b10be7aae6f493b60ed4ec480000000000",
      "fee": 1000
    }
}
    • withdrawalAddress — staker withdrawal address.
    • stakerPublicKey — staker public key.
    • stakeTransactionHash — hash of the initial staking transaction.
    • withdrawalTransactionHex — unsigned transaction for withdrawal request in the hexadecimal format. Sign the transaction and submit it to the Bitcoin blockchain to perform the called action.
    • fee — total fee in SATOSHI charged for processing the transaction.

  2. Use unstakeTransactionHex from the previous step to sign and send the signed transaction to the Bitcoin chain.

What's Next?

Updated 3 days ago