Babylon allows Bitcoin holders to participate in staking, earning rewards while maintaining their BTC holdings. This guide walks through the process of staking Bitcoin using the Adamik API, including transaction creation, signing, and broadcasting.

I - Stake Bitcoins

Notes

  • The duration of a Bitcoin staking position is 64000 blocks (~444 days). It will naturally end after this period. However the Babylon protocol also allows to manually end the staking position in advance (see part III - Unstake Bitcoins).

  • Babylon offers two registration methods: pre-stake and post-stake. This guide implements the more user-friendly pre-stake registration flow. Refer to Babylon’s documentation for details.

  • The examples are targeting Bitcoin Signet and Babylon Testnet networks. To target the mainnets, simply replace "bitcoin-signet" with "bitcoin" and "babylon-testnet" with "babylon" in API calls.

  • The example data shown is for demonstration purposes. While encoded payloads are valid for signing, they may not match the provided examples exactly.

Overview

1. Collect Required Information

Retrieve Bitcoin Validators

First, fetch the list of available Bitcoin “finality providers” (validators):

GET /api/bitcoin-signet/validators

User Inputs

You’ll need to collect:

  • Chosen validator
  • Staking amount
  • Bitcoin address and Bitcoin public key (NOT the xpub)

2. Create Bitcoin Staking Transaction

Generate the Bitcoin transaction payloads to sign, using transaction mode stake:

POST /api/bitcoin-signet/transaction/encode
{
  "transaction": {
    "data": {
      "mode": "stake",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "targetValidatorAddress": "ee9da95e9fecbb2191943c56a109d1dc81787a77994ad9ef89278850a58e4876",
      "amount": "1000"
    }
  }
}

3. Sign Bitcoin Transactions

Sign the following payloads with a compatible Bitcoin signer:

  • Staking PSBT: The main transaction for staking
  • Slashing PSBT: Required for the slashing mechanism
  • Unbonding Slashing PSBT: For slashing during unbonding
  • Babylon Address: Sign with Bitcoin signer: [ECDSA or BIP322](hex(bech32Address))

ℹ️ The unbonding PSBT does not need to be signed at this stage, but must be included in the registration transaction, see below.

4. Register with Babylon Blockchain

Create the Babylon registration transaction:

POST /api/babylon/transaction/encode
{
  "transaction": {
    "data": {
      "mode": "registerStake",
      // User's Babylon address
      "senderAddress": "xxxxxxxxxxxxxxxxxx",
      // User's Babylon public key
      "senderPubKey": "xxxxxxxxxxxxxxxxxx",
      // User's Bitcoin public key in hexadecimal format
      "senderForeignPubKey": "xxxxxxxxxxxxxxxxxx",
      // User's Babylon address, signed with Bitcoin signer (hex)
      "proofOfPossession": "xxxxxxxxxxxxxxxxxx",
      "amount": "1234",
      // Bitcoin finality provider's public key (hex)
      "validatorPubKey": "xxxxxxxxxxxxxxxxxx",
      // The unbonding PSBT, exactly as provided in the response of the Bitcoin encode
      "unsignedUnbondingTransaction": "xxxxxxxxxxxxxxxxxx",
      // Staking transaction, signed from the provided PSBT (hex)
      "signedStakingTransaction": "xxxxxxxxxxxxxxxxxx",
      // Slashing transaction, signed from the provided PSBT (hex)
      "signedSlashingTransaction": "xxxxxxxxxxxxxxxxxx",
      // Unbonding slashing transaction, signed from the provided PSBT (hex)
      "signedUnbondingSlashingTransaction": "xxxxxxxxxxxxxxxxxx"
    }
  }
}

ℹ️ The returned encoded transaction is in Cosmos’ protobuf format, serialized as hex.

5. Sign Babylon Transaction

Sign the encoded Babylon transaction using a Babylon-compatible wallet.

6. Broadcast Babylon Registration Transaction

POST /api/babylon/transaction/broadcast
{
  "transaction": {
    "data": {
      "mode": "registerStake",
      "senderAddress": "xxxxxxxxxxxxxxxxxx",
      "senderPubKey": "xxxxxxxxxxxxxxxxxx",
      "senderForeignPubKey": "xxxxxxxxxxxxxxxxxx",
      "proofOfPossession": "xxxxxxxxxxxxxxxxxx",
      "amount": "1234",
      "validatorPubKey": "xxxxxxxxxxxxxxxxxx",
      "unsignedUnbondingTransaction": "xxxxxxxxxxxxxxxxxx",
      "signedStakingTransaction": "xxxxxxxxxxxxxxxxxx",
      "signedSlashingTransaction": "xxxxxxxxxxxxxxxxxx",
      "signedUnbondingSlashingTransaction": "xxxxxxxxxxxxxxxxxx",
      "fees": "12432",
      "gas": "1775858"
    },
    "encoded": "0a330a310a2d2f626162796c6f6e2e6274637374616b696e672e76312e4d736743726561746542544344656c65676174696f6e120012650a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2103833d5aebe72ca68e3816c4a466d395280929f07ccf5e75dc4e2d71c2c92da45812040a020801180712110a0b0a047562626e120337303010a08d061a0a62626e2d746573742d3520eac404",
    "signature": "xxxxxxxxxxxxxxxxxx"
  }
}

7. Wait for Confirmation

Monitor the transaction status until it’s confirmed:

GET /api/babylon/transaction/{hash}

⚠️ Important: Wait for transaction.parsed.state to be confirmed before proceeding to the next step.

8. Broadcast Bitcoin Staking Transaction

Once the Babylon registration is confirmed, broadcast the signed Bitcoin staking transaction:

POST /api/bitcoin-signet/transaction/broadcast
{
  "transaction": {
    "data": {
      "mode": "stake",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "targetValidatorAddress": "ee9da95e9fecbb2191943c56a109d1dc81787a77994ad9ef89278850a58e4876",
      "amount": "1000",
      "fees": "1896"
    },
    "encoded": "70736274ff010089020000000144a549ead63ac9c6987b90669208ece5e93f28de4b1f97b5e4036c995f47b3d50100000000ffffffff0250c3000000000000225120a80fe5278c52cab2e0a0c9702713f61fe8f2f248346a6d7dcc1245338c14ec1609dd06000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041000000000001012b31a507000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041011720bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c000000",
    "signature": "xxxxxxxxxxxxxxxxxx"
  }
}

II - Manage Staking Positions

View Bitcoin Staking Positions

Retrieve all staking positions for a Bitcoin public key:

GET /api/bitcoin-signet/account/state/{address}?pubkey={publicKey}

ℹ️ The stakeId is the hash of the Bitcoin staking transaction

III - Unstake Bitcoins

The Babylon protocol allows to end an active Bitcoin staking position in advance, i.e before the end of the default staking period of 64000 blocks. This is done by sending a dedicated bitcoin transaction, that is a request for unbonding, after which there is an unbonding period of 7 days. When the unbonding duration is complete, users must then send a withdrawal transaction to retrieve their bitcoins and make them spendable again (see part IV - Withdraw Bitcoins).

1. Create Bitcoin Transaction

Generate the Bitcoin transaction payload to sign, using transaction mode unstake:

POST /api/bitcoin-signet/transaction/encode
{
  "transaction": {
    "data": {
      "mode": "unstake",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "validatorAddress": "d23c2c25e1fcf8fd1c21b9a402c19e2e309e531e45e92fb1e9805b6056b0cc76",
      "stakeId": "52bfb146f0f8c8b98b0fa584056dfb75658b078aac04f3c5a641db9df297387b"
    }
  }
}

2. Sign Bitcoin Transaction

Sign the encoded payload with a compatible Bitcoin signer.

3. Broadcast Bitcoin Transaction

Broadcast the signed Bitcoin staking transaction:

POST /api/bitcoin-signet/transaction/broadcast
{
  "transaction": {
    "data": {
      "mode": "unstake",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "validatorAddress": "d23c2c25e1fcf8fd1c21b9a402c19e2e309e531e45e92fb1e9805b6056b0cc76",
      "stakeId": "52bfb146f0f8c8b98b0fa584056dfb75658b078aac04f3c5a641db9df297387b",
      "useMaxAmount": false,
      "recipientAddress": "",
      "fees": "2000"
    },
    "encoded": "70736274ff01005e02000000017b3897f29ddb41a6c5f304ac8a078b6575fb6d0584a50f8bb9c8f8f046b1bf520000000000ffffffff0180bb000000000000225120925f6e5d2f54928dbbf7c7b989e2d0e8b6023baece6b7ae6efed0c4f54891999000000000001012b50c3000000000000225120a80fe5278c52cab2e0a0c9702713f61fe8f2f248346a6d7dcc1245338c14ec166215c050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac08b47c4bf56db05be7cc5f84b03d14987e05392d76b88d6875136d66d34db31d697cb47898d4200f9dbfb360a7dc2402178e9acd31f8c1167ae9afec71b8c34b4fd570120bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499cad200aee0509b16db71c999238a4827db945526859b13c95487ab46725357c9a9f25ac20113c3a32a9d320b72190a04a020a0db3976ef36972673258e9a38a364f3dc3b0ba2017921cf156ccb4e73d428f996ed11b245313e37e27c978ac4d2cc21eca4672e4ba203bb93dfc8b61887d771f3630e9a63e97cbafcfcc78556a474df83a31a0ef899cba2040afaf47c4ffa56de86410d8e47baa2bb6f04b604f4ea24323737ddc3fe092dfba2079a71ffd71c503ef2e2f91bccfc8fcda7946f4653cef0d9f3dde20795ef3b9f0ba20d21faf78c6751a0d38e6bd8028b907ff07e9a869a43fc837d6b3f8dff6119a36ba20f5199efae3f28bb82476163a7e458c7ad445d9bffb0682d10d3bdb2cb41f8e8eba20fa9d882d45f4060bdb8042183828cd87544f1ea997380e586cab77d5fd698737ba569cc001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac00000"
  }
}

IV - Withdraw Bitcoins

After a staking position has ended, users have to send a withdrawal transaction before being able to spend their bitcoins again. This transaction is mandatory whether the position has ended naturally after the default staking duration or after the manual unbonding period has eneded.

1. Create Bitcoin Transaction

Generate the Bitcoin transaction payload to sign, using transaction mode withdraw:

POST /api/bitcoin-signet/transaction/encode
{
  "transaction": {
    "data": {
      "mode": "withdraw",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "recipientAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "validatorAddress": "d66124f8f42fd83e4c901a100ae3b5d706ef6cfd217b04bc64152e739a30c41e",
      "stakeId": "943b38b6e1d6ffe0194f93dbfbe36499d1eaa625867aae17a59aff2825d42109"
    }
  }
}

2. Sign Bitcoin Transaction

Sign the encoded payload with a compatible Bitcoin signer.

3. Broadcast Bitcoin Transaction

Broadcast the signed Bitcoin staking transaction:

POST /api/bitcoin-signet/transaction/broadcast
{
  "transaction": {
    "data": {
      "mode": "withdraw",
      "senderPubKey": "02bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499c",
      "validatorAddress": "d66124f8f42fd83e4c901a100ae3b5d706ef6cfd217b04bc64152e739a30c41e",
      "stakeId": "943b38b6e1d6ffe0194f93dbfbe36499d1eaa625867aae17a59aff2825d42109",
      "recipientAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "senderAddress": "tb1pwj4q5jhwlszj6rnrahd95huu6j56dvj9ltfnag55prqnpc53vpqsxh76tx",
      "fees": "159"
    },
    "encoded": "70736274ff01005e0200000001fd2f56d383b71a98d0f86780aa591f1eca05c44e581d47e1e3838b05df259a3b0000000000f003000001e1ba00000000000022512074aa0a4aeefc052d0e63edda5a5f9cd4a9a6b245fad33ea29408c130e2916041000000000001012b80bb0000000000002251206f5554b3505cbccc88c8e86541dbac87e53f962c18b953780ccde2e4d5969d3c4215c150929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac099c5eb18cdfad5d84d849d1aa9e883c313b19b2a89726b534534dd064587eb512720bd2eb288281a9e7a15ec81b8b593f243b96fbcd2b16a1a509c1b87df95fc499cad02f003b2c001172050929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac00000"
  }
}

V. Claim Rewards on secured chains

The reward claiming process for Babylon staking will be documented soon.