The Merge Stake Account flow allows you to merge two stake accounts that have the same authorities and lockup, into a single stake account. A merge is possible between two stakes in the following states with no additional conditions:

Two deactivated stakes
An inactive stake into an activating stake during its activation epoch

For the following cases, the voter public key and vote credits observed must match:

Two activated stakes
Two activating accounts that share an activation epoch, during the activation epoch

All other combinations of stake account states will fail to merge, including all "transient" states (where a stake is activating or deactivating with a non-zero effective stake).

To merge two separate stake accounts into one, you will need:

destination_stake_account_pubkey - Public key of the stake account into which you want to merge another stake account
source_stake_account_pubkey - Public key of the stake account which you want to merge into a destination stake account
funding_account_pubkey - Public key of the account which will pay the transaction fee

In the following guide we will illustrate how to merge stake accounts.

Create New Merge Stake Account Flow

To initiate the merge stake account process with Staking API, create a new flow with a POST request to /flows.

URL

https://api.figment.io/flows

Request

protocol* : string Protocol on which this flow operates (ex. solana).
network* : string Network on which this flow operates (ex. devnet).
operation* : string The operation to perform (ex. merge_stake_account).

{
  "protocol": "solana",
  "network": "devnet",
  "operation": "merge_stake_account"
}

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
actions : array It includes the name & inputs of all next possible actions.
- create_merge_tx : Use this Action to create a merge stake account transaction.
  - destination_stake_account_pubkey : Public key of the stake account into which you want to merge another stake account.
  - source_stake_account_pubkey : Public key of the stake account which you want to merge with the destination stake account.
  - funding_account_pubkey : Public key of the account which will pay the transaction fee.
data : object Flow & transaction data.

{
  "id": "07fa6b05-476e-493e-aa02-0d855fe98b78",
  "operation": "merge_stake_account",
  "state": "initialized",
  "actions": [
    {
      "name": "create_merge_tx",
      "inputs": [
        {
          "name": "destination_stake_account_pubkey",
          "display": "Destination Stake Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "source_stake_account_pubkey",
          "display": "Source Stake Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "funding_account_pubkey",
          "display": "Funding Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "destination_stake_account_pubkey": null,
    "source_stake_account_pubkey": null,
    "stake_authority_pubkey": null,
    "funding_account_pubkey": null,
    "merge_transaction": null
  },
  "protocol": "solana",
  "network": "devnet",
  "created_at": "2023-02-28T09:12:59.071Z",
  "updated_at": "2023-02-28T09:12:59.071Z"
}

Submit Merge Stake Account Data

After collecting the required inputs, send a PUT request to /flows/[:flow_id]/next to proceed to the next step.

Request

name* : create_merge_tx
inputs* : object
- source_stake_account_pubkey* : string Public key of the stake account from which you want to merge.
- destination_stake_account_pubkey* : string Public key of the stake account into which you want to merge the stake account balances.
- funding_account_pubkey* : string Public key of the account which will pay the transaction fee.

{
  "name": "create_merge_tx",
  "inputs": {
    "destination_stake_account_pubkey": "9UPYJp5pApSEaeCizrvqe6vx7hSj3ZPzVDLZHG4hxk3x",
    "source_stake_account_pubkey": "23ANo1epPVGhGHyfsJP9581nNULGK7UoM7LPFyhx45Ss",
    "funding_account_pubkey": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy"
  }
}

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
actions : array It includes the name & inputs of all next possible actions.
- refresh_merge_tx : If you need to get a fresh version of the transaction payload (i.e., the recent blockhash has expired).
- sign_merge_tx : Submit a signed transaction payload or an array of signatures to continue the flow. Refer to the guides Signing Transactions with Figment's npm Package and Signing Transactions with the Fireblocks API for details.
- confirm_merge_tx_by_hash : Submit a previously completed transaction hash to continue the flow. Refer to the guide Advance Flows Using a Transaction Hash.
data : object Flow & transaction data.

{
  "id": "07fa6b05-476e-493e-aa02-0d855fe98b78",
  "operation": "merge_stake_account",
  "state": "merge_tx_signature",
  "actions": [
    {
      "name": "refresh_merge_tx",
      "inputs": [
        {
          "name": "destination_stake_account_pubkey",
          "display": "Destination Stake Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "9UPYJp5pApSEaeCizrvqe6vx7hSj3ZPzVDLZHG4hxk3x"
        },
        {
          "name": "source_stake_account_pubkey",
          "display": "Source Stake Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "23ANo1epPVGhGHyfsJP9581nNULGK7UoM7LPFyhx45Ss"
        },
        {
          "name": "funding_account_pubkey",
          "display": "Funding Account Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy"
        }
      ]
    },
    {
      "name": "sign_merge_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [
            {
              "type": "sign_payload",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null,
          "signers": [
            "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy"
          ],
          "transaction_payload": "010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data",
          "signers": [
            "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy"
          ],
          "transaction_payload": "010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
          "signing_payload": "01000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
          "inputs": [
            {
              "name": "account_address",
              "display": "Account Address",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "signature",
              "display": "Signature",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            }
          ]
        }
      ]
    },
    {
      "name": "confirm_merge_tx_by_hash",
      "inputs": [
        {
          "name": "hash",
          "display": "Hash",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "block_number",
          "display": "Block Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "destination_stake_account_pubkey": "9UPYJp5pApSEaeCizrvqe6vx7hSj3ZPzVDLZHG4hxk3x",
    "source_stake_account_pubkey": "23ANo1epPVGhGHyfsJP9581nNULGK7UoM7LPFyhx45Ss",
    "stake_authority_pubkey": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy",
    "funding_account_pubkey": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy",
    "merge_transaction": {
      "raw": "010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
      "signing_payload": "01000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
      "signed": null,
      "hash": null,
      "status": null,
      "error": null,
      "signatures": null,
      "block_time": null
    }
  },
  "protocol": "solana",
  "network": "devnet",
  "created_at": "2023-02-28T09:12:59.071Z",
  "updated_at": "2023-02-28T09:18:37.497Z"
}

Submit Signed Merge Stake Account Transaction for Broadcast

Before broadcasting the transaction, you must sign the transaction_payload you received in the previous step. After signing the transaction, send a PUT request to /flows/[:flow_id]/next and the Staking API will broadcast the transaction to the network.

🚧
The transaction signing window on Solana is sometimes less than 90 seconds.
If you encounter an error "Transaction simulation failed: Blockhash not found", refresh the transaction, sign the newly created payload and submit it in < 90 seconds.

URL

https://api.figment.io/flows/[:flow_id]/next

Request

name* : sign_merge_tx
inputs* : object
- transaction_payload* : Signed transaction payload from the previous step's response.
- signatures : array of object The signatures array can be used instead of sending a transaction payload when the signing keys are kept in a custodial solution, such as Fireblocks. Refer to the guide Signing Transactions with the Fireblocks API for details.

{
  "name": "sign_merge_tx",
  "inputs": {
    "transaction_payload": "010df1df512ef26a08c91b7ed68a53aab28a4b434650c9f2f1b2778ce6012fae33d339803d4e7ad8cbbb233248d472ed7a843a9e54b245983192cbb9c6eb3f320801000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000"
  }
}

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
- merge_tx_broadcasting : Transaction has been broadcast and is awaiting confirmation.
- completed : Transaction has been confirmed and the merge is complete.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

{
  "id": "07fa6b05-476e-493e-aa02-0d855fe98b78",
  "operation": "merge_stake_account",
  "state": "merge_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-28T09:20:07.155Z",
      "inputs": []
    }
  ],
  "data": {
    "destination_stake_account_pubkey": "9UPYJp5pApSEaeCizrvqe6vx7hSj3ZPzVDLZHG4hxk3x",
    "source_stake_account_pubkey": "23ANo1epPVGhGHyfsJP9581nNULGK7UoM7LPFyhx45Ss",
    "stake_authority_pubkey": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy",
    "funding_account_pubkey": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy",
    "merge_transaction": {
      "raw": "010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
      "signing_payload": "01000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
      "signed": "010df1df512ef26a08c91b7ed68a53aab28a4b434650c9f2f1b2778ce6012fae33d339803d4e7ad8cbbb233248d472ed7a843a9e54b245983192cbb9c6eb3f320801000306f8c4898641adada76eeeee2de872d931bc58bfb2ce5b79734e32808cc501a5340f697321d318f2f1c2e891ee2d6b6bdb44f720c581e463d2a0c93e3e6d1885547de1a9be894d367a1544b885b2e3c4f9f7e79728ae5177f7b39c76a35112136f06a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff400000020d3ed297260dfd3906862d59d97517fd4adc1c3270d4b5c7143b71cbf68361b01030502010405000407000000",
      "hash": "HAtWyX8EPwCQZZpdazBLrj1ZwZxCtMHWEekDC34GMVx9Rx4q6CaVSBSpMwbJR2Hn11UdRrZMacELB2TDBQ9wXgj",
      "status": null,
      "error": null,
      "signatures": [
        {
          "account_address": "Hk5voGB7wh9HtXTeszbW7AFm3A4B94xWkXeeaqTYspqy",
          "signature": ""
        }
      ],
      "block_time": null
    }
  },
  "protocol": "solana",
  "network": "devnet",
  "created_at": "2023-02-28T09:12:59.071Z",
  "updated_at": "2023-02-28T09:19:06.417Z"
}

Get Merge Stake Account Flow Status

To get the current state of the existing flow, send a GET request to /flows/[:flow_id] using the flow ID from the previous step.

URL

https://api.figment.io/flows/[:flow_id]

Request

None

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
- merge_tx_broadcasting : Transaction has been broadcast but not confirmed.
- completed : Transaction broadcasted and confirmed.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

{
  "id": "7c859709-b2e7-4e32-94bb-234b66db9251",
  "operation": "merge_stake_account",
  "state": "completed",
  "actions": [],
  "data": {
    "destination_stake_account_pubkey": "AKqCviCNHAk9qG8iWRnsqUemvsq4NnW3u5Rn6xwdWGcq",
    "source_stake_account_pubkey": "FqLfJw2zXUoiYBUgHjHB5C3LVpFZVxdT6Jfhnsn3jbQv",
    "stake_authority_pubkey": "ZWmvcfpjRJi12wPv2AaooXFDZtFVeXrk7WuAX5XTntN",
    "funding_account_pubkey": "ZWmvcfpjRJi12wPv2AaooXFDZtFVeXrk7WuAX5XTntN",
    "merge_transaction": {
      "raw": "010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000306085440890ab57cf018e04cbe2d06f3a91c798e12b83c2df99b058b18d2ab81678a8c24a6d037267874fce747fbdba294b1085d6f98bef48f57a098e29aa0c302dc65b9db875810a82c40f0c829762eca07b31312408e0e34a8b0159be2cad70306a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff4000000625fc666064782f3af9580ddc8542b250ce8c9b8a87937c5b823ae882f1b7d1601030501020405000407000000",
      "signing_payload": "01000306085440890ab57cf018e04cbe2d06f3a91c798e12b83c2df99b058b18d2ab81678a8c24a6d037267874fce747fbdba294b1085d6f98bef48f57a098e29aa0c302dc65b9db875810a82c40f0c829762eca07b31312408e0e34a8b0159be2cad70306a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff4000000625fc666064782f3af9580ddc8542b250ce8c9b8a87937c5b823ae882f1b7d1601030501020405000407000000",
      "signed": "01ee9b1dcbfc9df0a4d615cc4220539584ab91757b77060d54850f549b87381a4990fe740b94b4eb3b969e48aa769dbf43d545b04cca77bf994b46f4207ca5dd0301000306085440890ab57cf018e04cbe2d06f3a91c798e12b83c2df99b058b18d2ab81678a8c24a6d037267874fce747fbdba294b1085d6f98bef48f57a098e29aa0c302dc65b9db875810a82c40f0c829762eca07b31312408e0e34a8b0159be2cad70306a1d8179137542a983437bdfe2a7ab2557f535c8a78722b68a49dc00000000006a7d51718c774c928566398691d5eb68b5eb8a39b4b6d5c73555b210000000006a7d517193584d0feed9bb3431d13206be544281b57b8566cc5375ff4000000625fc666064782f3af9580ddc8542b250ce8c9b8a87937c5b823ae882f1b7d1601030501020405000407000000",
      "hash": "5mgx9JKnckAYfkYWdm3LxVTHTM4tVyx2Je7ZhzHNNsLu8icc4p9Vi9veCrGu6J96QmjGdJd3i3y6fABYqJ8xoqJi",
      "status": "confirmed",
      "error": null,
      "signatures": [],
      "block_time": "2023-07-04T16:41:03.000Z",
      "block_number": null
    }
  },
  "protocol": "solana",
  "network": "devnet",
  "created_at": "2023-07-04T16:37:15.610Z",
  "updated_at": "2023-07-04T16:41:20.883Z"
}