Skip to main content

Staking API - Ethereum


API AuthenticationClick to view API Authentication details
API calls require authentication with API key via Authorization request header or URL property. Calls are made to one of the Ethereum Staking API endpoints found in your app's dashboard.

For example: https://eth-slate.datahub.figment.io

Here's some boilerplate to get you started. 
fetch("https://eth-slate.datahub.figment.io/api/v1/flows", {
    method: 'POST', // can also be 'GET', 'PUT' or any appropriate method
    headers: {
        "Authorization" : "<api_key>",
        "Content-Type": "application/json" // if method is 'POST'
    },
    body: JSON.stringify({
      // JSON Payload
    })
})

Available Methods

Create New Staking Flow

To initiate the staking process, create a new flow with a POST request to /api/v1/flows.

Request Body
Example Response
{
  "id": "a11ff244-18b9-470e-b018-d0f3614e75a5",
  "operation": "staking",
  "state": "initialized",
  "actions": [
    {
      "name": "create_deposit_tx",
      "inputs": [
        {
          "name": "funding_account_address",
          "display": "Funding Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "validator_pub_key",
          "display": "Validator Pub Key",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            },
            {
              "type": "unfunded_validator",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "withdrawal_credentials",
          "display": "Withdrawal Credentials",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "signature",
          "display": "Signature",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "deposit_data_root",
          "display": "Deposit Data Root",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "only_integer": true,
                "greater_than": 0
              }
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "in GWEI",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "greater_than": 0
              }
            },
            {
              "type": "precision",
              "options": {
                "allow_blank": true,
                "max": 9
              }
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "funding_account_address": null,
    "validator_pub_key": null,
    "withdrawal_credentials": null,
    "signature": null,
    "deposit_data_root": null,
    "amount": "32.0",
    "gas_price": null,
    "gas_limit": null,
    "estimated_active_at": null,
    "transactions": []
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-14T20:32:52.388Z",
  "updated_at": "2023-03-14T20:32:52.388Z"
}
SpecificationView Specification

Parameters

  • flow — object
    • network_code — string Network this flow operates on (ex. ethereum) (required).
    • chain_code — string Chain this flow operates on (ex. goerli) (required).
    • operation — string The operation to perform (ex. staking) (required).
    • version — string API version to use (ex. v1) (optional).

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_deposit_tx — Use this action to generate a deposit transaction to stake your ETH.
      • funding_account_address — The wallet ETH will be originating from.
      • validator_pub_key — The public key of the validator that the ETH is to be deposited to.
      • withdraw_credentials — The withdrawal address for the given validator.
      • signature — A BLS proof of possession, i.e. a proof that the private key corresponding to the validator_pub_key is known by the signer.
      • deposit_data_root — Uniquely identifies the set of deposits made so far.
      • gas_limit — Adjust the gas limit.
      • gas_price — Adjust the gas price.
  • data — object Staking flow & transaction data.
    • amount — Defaults to 32.0 ETH

Submit Deposit Data

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

Request Body
Example Response
{
  "id": "a11ff244-18b9-470e-b018-d0f3614e75a5",
  "operation": "staking",
  "state": "deposit_tx_signature",
  "actions": [
    {
      "name": "refresh_deposit_tx",
      "inputs": []
    },
    {
      "name": "sign_deposit_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [],
          "array": false,
          "default_value": null,
          "signers": [
            "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31"
          ],
          "transaction_payload": "0x02f901d7054e8459682f008502072e61b682c55e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001208167c5820c06d6a8808bd4e44c01ed0a3a1b2cfbb2934ff58707c7d650b188da0000000000000000000000000000000000000000000000000000000000000030a379ce0e862828fd80d5d60494645fcc1ba17a5e2c3560f63c05c65e98d3e2246e5fe9f2a9299c62b5c36bd77899f946000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed850000000000000000000000000000000000000000000000000000000000000060b51d5e8b6cee6870f997c7870362ac3e552677c1fb817d51ee7a5567485b71e9c3f8c1cd699dfa322c2d87c3fadfaf370ee19c551d1982eab74b82c055393580c751eb68647fec7f0a8723c593fec3505e4855721c74239a9bb91b1e4be998cdc0"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data",
          "signers": [
            "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31"
          ],
          "transaction_payload": "0x02f901d7054e8459682f008502072e61b682c55e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001208167c5820c06d6a8808bd4e44c01ed0a3a1b2cfbb2934ff58707c7d650b188da0000000000000000000000000000000000000000000000000000000000000030a379ce0e862828fd80d5d60494645fcc1ba17a5e2c3560f63c05c65e98d3e2246e5fe9f2a9299c62b5c36bd77899f946000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed850000000000000000000000000000000000000000000000000000000000000060b51d5e8b6cee6870f997c7870362ac3e552677c1fb817d51ee7a5567485b71e9c3f8c1cd699dfa322c2d87c3fadfaf370ee19c551d1982eab74b82c055393580c751eb68647fec7f0a8723c593fec3505e4855721c74239a9bb91b1e4be998cdc0",
          "signing_payload": "0x5beb0495b1cf5028fe16ce5b79b9348c054564161cee4883d1d00633ad9b6025",
          "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_deposit_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": {
    "estimated_active_at": null,
    "transactions": [
      {
        "code": "deposit",
        "amount": "32.0",
        "raw": "0x02f901d7054e8459682f008502072e61b682c55e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001208167c5820c06d6a8808bd4e44c01ed0a3a1b2cfbb2934ff58707c7d650b188da0000000000000000000000000000000000000000000000000000000000000030a379ce0e862828fd80d5d60494645fcc1ba17a5e2c3560f63c05c65e98d3e2246e5fe9f2a9299c62b5c36bd77899f946000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed850000000000000000000000000000000000000000000000000000000000000060b51d5e8b6cee6870f997c7870362ac3e552677c1fb817d51ee7a5567485b71e9c3f8c1cd699dfa322c2d87c3fadfaf370ee19c551d1982eab74b82c055393580c751eb68647fec7f0a8723c593fec3505e4855721c74239a9bb91b1e4be998cdc0",
        "signing_payload": "0x5beb0495b1cf5028fe16ce5b79b9348c054564161cee4883d1d00633ad9b6025",
        "signed": null,
        "hash": null,
        "status": null,
        "error": null,
        "signatures": null,
        "block_time": null,
        "inputs": {
          "funding_account_address": "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31",
          "validator_pub_key": "0xa379ce0e862828fd80d5d60494645fcc1ba17a5e2c3560f63c05c65e98d3e2246e5fe9f2a9299c62b5c36bd77899f946",
          "withdrawal_credentials": "0x010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85",
          "signature": "0xb51d5e8b6cee6870f997c7870362ac3e552677c1fb817d51ee7a5567485b71e9c3f8c1cd699dfa322c2d87c3fadfaf370ee19c551d1982eab74b82c055393580c751eb68647fec7f0a8723c593fec3505e4855721c74239a9bb91b1e4be998cd",
          "deposit_data_root": "0x8167c5820c06d6a8808bd4e44c01ed0a3a1b2cfbb2934ff58707c7d650b188da",
          "gas_price": null,
          "gas_limit": null,
          "amount": "32.0"
        }
      }
    ]
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-14T20:32:52.388Z",
  "updated_at": "2023-03-14T21:19:14.960Z"
}
SpecificationView Specification

Parameters

  • name — string Name of the action to execute (required).
  • inputs — object (required).
    • funding_account_address — string The wallet from which the ETH will originate. (required).
    • validator_pub_key — string The public key of the validator to which the ETH will be deposited. (required).
    • withdrawal_credentials — string The withdrawal address for the given validator. (required).
    • signature — string A BLS proof of possession i.e., a proof that the private key corresponding to the validator_pub_key is known by the signer. (required).
    • deposit_data_root — string Uniquely identifies the set of deposits made so far (required).
    • amount — number Number of tokens you want to delegate. (required).
    • gas_price — string Adjust the gas price (optional).
    • gas_limit — string Adjust the gas limit (optional).

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_deposit_tx — If you need to get a fresh version of the transaction payload (i.e., the nonce has increased).
    • sign_deposit_tx — Submit a signed transaction payload ready to be broadcast to the network.
    • confirm_deposit_tx_by_hash — Submit a previously completed transaction hash to continue the flow.
  • data — object Staking flow & transaction data.

Submit Signed 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 /api/v1/flows/[:flow_id]/next with the signed payload. The Staking API will broadcast the transaction to the Ethereum network.

Request Body
Example Response
{
  "id": "8307b0d1-fc17-45b1-b540-2d9c31578d99",
  "state": "deposit_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2022-10-07T17:26:08.237Z",
      "inputs": []
    }
  ],
  "data": {
    "funding_account_address": "0x387462761F706AA7c1DA71FBA1c545724928b67b",
    "validator_pub_key": "0xa0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640",
    "withdrawal_credentials": "0x010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010",
    "signature": "0x88cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413",
    "deposit_data_root": "0x021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a4830823",
    "amount": "32.0",
    "gas_price": null,
    "gas_limit": null,
    "deposit_transaction": {
      "raw": "0x02f901d605808459682f008459682f1c82dc9e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a48308230000000000000000000000000000000000000000000000000000000000000030a0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010000000000000000000000000000000000000000000000000000000000000006088cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413c0",
      "signing_payload": null,
      "signed": "0x02f9021905808459682f008459682f1c82dc9e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a48308230000000000000000000000000000000000000000000000000000000000000030a0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010000000000000000000000000000000000000000000000000000000000000006088cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413c080a0a0a59a1a2c4e03582ad842293a2dd2ee17f4f9f71f46a06ea59447eee9a71a20a00545743e3159ff27ae44e6fdaa2f434e033438d661cccf9f5ba202ea64e25d64",
      "hash": "0x6acc6aa30c09ba30a4cc4ece382b6956cf23e0c80ea518b030c9185588ea40a6",
      "status": "broadcast",
      "error": null,
      "signatures": null
    }
  },
  "network_code": "ethereum",
  "chain_code": "goerli-prater",
  "created_at": "2022-10-06T23:40:33.826Z",
  "updated_at": "2022-10-07T17:24:17.339Z"
}
SpecificationView Specification

Parameters

  • name — string Name of the action to execute (required).
  • inputs — object
    • transaction_payload — Signed transaction payload from the previous step's response.

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.
    • deposit_tx_broadcasting — Transaction has been broadcast and confirmed.
    • deposited — Transaction has been confirmed.
  • actions — array It includes the name & inputs of all next possible actions.
  • data — object Staking flow & transaction data.

Get Flow Status

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

Request Query
Example Response
{
  "id": "ad904171-5051-40dd-bfba-d9c710174881",
  "operation": "staking",
  "state": "deposited",
  "actions": [],
  "data": {
    "funding_account_address": "0x387462761F706AA7c1DA71FBA1c545724928b67b",
    "validator_pub_key": "0xa0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640",
    "withdrawal_credentials": "0x010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010",
    "signature": "0x88cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413",
    "deposit_data_root": "0x021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a4830823",
    "amount": "32.0",
    "gas_price": null,
    "gas_limit": null,
    "deposit_transaction": {
      "raw": "0x02f901d605808459682f008459682f1c82dc9e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a48308230000000000000000000000000000000000000000000000000000000000000030a0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010000000000000000000000000000000000000000000000000000000000000006088cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413c0",
      "signing_payload": null,
      "signed": "0x02f9021905808459682f008459682f1c82dc9e94ff50ed3d0ec03ac01d4c79aad74928bff48a7b2b8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120021db2ee51da4e420dac8310928e2c3c25b7f8b5056dc792a206e680a48308230000000000000000000000000000000000000000000000000000000000000030a0b60b10bdae3bdc526586163bc83a928f14c9bcb8244816f23395692a7cd613e0f3ea23aa295ae0467dc65002c95640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc94dbfac39af945c8186a6b3fc738c5ce97b010000000000000000000000000000000000000000000000000000000000000006088cce9fcadc43c58db4d5c0e7101cb27537be0a37b1e2fb2c096e72aee14b3bce20fca87ff11f92744abc71a221a9ceb11f52e1cfae59af00e7e42f83d482901223a100f88b532e19bc776786cd4baaddb6ec4290fdedfc3ebefcbf44fe7e413c080a0a0a59a1a2c4e03582ad842293a2dd2ee17f4f9f71f46a06ea59447eee9a71a20a00545743e3159ff27ae44e6fdaa2f434e033438d661cccf9f5ba202ea64e25d64",
      "hash": "0x6acc6aa30c09ba30a4cc4ece382b6956cf23e0c80ea518b030c9185588ea40a6",
      "status": "broadcast",
      "error": null,
      "signatures": null
    }
  },
  "network_code": "ethereum",
  "chain_code": "goerli-prater",
  "created_at": "2022-04-26T18:23:46.702Z",
  "updated_at": "2022-04-27T22:24:47.738Z"
}
SpecificationView Specification

Parameters

  • 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.
    • deposit_tx_broadcasting — Transaction is broadcasting and not confirmed yet.
    • deposited — Transaction has been confirmed and stake deposited.
  • actions — array It includes the name & inputs of all next possible actions.
  • data — object Staking flow & transaction data.

Create New Aggregated Staking Flow

To initiate the aggregated staking process, create a new flow with a POST request to /api/v1/flows.

Request Body
Example Response
{
  "id": "b2d87fd3-6446-4bde-95ad-ecb7ed75b185",
  "operation": "aggregated_staking",
  "state": "initialized",
  "actions": [
    {
      "name": "create_aggregated_deposit_tx",
      "inputs": [
        {
          "name": "funding_account_address",
          "display": "Funding Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "deposits",
          "display": "Deposits",
          "description": "",
          "type": "array_of_validator_deposit_data",
          "validations": [
            {
              "type": "array",
              "options": {
                "allow_empty": false,
                "allow_duplicates": false
              }
            },
            {
              "type": "length",
              "options": {
                "maximum": 100,
                "message": "cannot fund more than 100 validators in single transaction"
              }
            },
            {
              "type": "array_of_objects",
              "options": {
                "merge_array_errors": true
              }
            }
          ],
          "array": true,
          "default_value": null,
          "element_type": "validator_deposit_data",
          "inputs": [
            {
              "name": "validator_pub_key",
              "display": "Validator Pub Key",
              "description": "",
              "type": "hex",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                },
                {
                  "type": "hex",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "withdrawal_credentials",
              "display": "Withdrawal Credentials",
              "description": "",
              "type": "hex",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                },
                {
                  "type": "hex",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "signature",
              "display": "Signature",
              "description": "",
              "type": "hex",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                },
                {
                  "type": "hex",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "deposit_data_root",
              "display": "Deposit Data Root",
              "description": "",
              "type": "hex",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                },
                {
                  "type": "hex",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            }
          ]
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "only_integer": true,
                "greater_than": 0
              }
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "greater_than": 0
              }
            },
            {
              "type": "precision",
              "options": {
                "allow_blank": true,
                "max": 9
              }
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "deposits": [],
    "funding_account_address": null,
    "gas_price": null,
    "gas_limit": null,
    "estimated_active_at": null,
    "transactions": []
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-14T12:53:08.782Z",
  "updated_at": "2023-03-14T12:53:08.782Z"
}
SpecificationView Specification

Parameters

  • flow — object
    • network_code — string Network this flow operates on (ex. ethereum) (required).
    • chain_code — string Chain this flow operates on (ex. goerli) (required).
    • operation — string The operation to perform (ex. aggregated_staking) (required).
    • version — string API version to use (ex. v1) (optional).

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_aggregated_deposit_tx — Use this action to generate an aggregated deposit transaction to stake your ETH.
      • funding_account_address — The wallet from which the ETH will originate.
      • deposits — Array of validator deposit data:
        • validator_pub_key — The public key of the validator to which the ETH will be deposited.
        • withdrawal_credentials — The withdrawal address for the given validator.
        • signature — A BLS proof of possession, i.e. a proof that the private key corresponding to the validator_pub_key is known by the signer.
        • deposit_data_root — Uniquely identifies the set of deposits made so far.
      • gas_limit — Adjust the gas limit.
      • gas_price — Adjust the gas price.
  • data — object Aggregated staking flow & transaction data.

Submit Aggregated Staking Data

After collecting the required inputs, PUT /api/v1/flows/[:flow_id]/next to move on to the next step.

Request Body
Example Response
{
  "id": "55d5fcb4-9334-46f2-bc07-739737755b46",
  "operation": "aggregated_staking",
  "state": "aggregated_deposit_tx_signature",
  "actions": [
    {
      "name": "refresh_aggregated_deposit_tx",
      "inputs": []
    },
    {
      "name": "sign_aggregated_deposit_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [],
          "array": false,
          "default_value": null,
          "signers": [
            "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31"
          ],
          "transaction_payload": "0x02f902d8054e8459682f008501e7c6031e83010b66943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c0"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data",
          "signers": [
            "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31"
          ],
          "transaction_payload": "0x02f902d8054e8459682f008501e7c6031e83010b66943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c0",
          "signing_payload": "0x09d1516ac312b850c49b267eb2687134f2b25e3a13228cdd9183b0a96a52af0c",
          "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_aggregated_deposit_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": {
    "estimated_active_at": null,
    "transactions": [
      {
        "code": "aggregated_deposit",
        "amount": "32.0",
        "raw": "0x02f902d8054e8459682f008501e7c6031e83010b66943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c0",
        "signing_payload": "0x09d1516ac312b850c49b267eb2687134f2b25e3a13228cdd9183b0a96a52af0c",
        "signed": null,
        "hash": null,
        "status": null,
        "error": null,
        "signatures": null,
        "block_time": null,
        "inputs": {
          "funding_account_address": "0xD0D77667f64CAd06a4789497065F2aaF1636Ee31",
          "gas_price": null,
          "gas_limit": null,
          "deposits": [
            {
              "validator_pub_key": "0x8d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d33",
              "withdrawal_credentials": "0x010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85",
              "signature": "0xa5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064",
              "deposit_data_root": "0x67b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8"
            }
          ],
          "amount": "32.0"
        }
      }
    ]
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-14T21:21:45.804Z",
  "updated_at": "2023-03-14T21:23:31.379Z"
}
SpecificationView Specification

Parameters

  • name — string Name of the action to execute (required).
  • inputs — object (required).
    • funding_account_address — string The wallet from which the ETH will originate (required).
    • deposits — Array of validator deposit data:
      • validator_pub_key — string The public key of the validator to which the ETH will be deposited (required).
      • withdrawal_credentials — string The withdrawal address for the given validator (required).
      • signature — string A BLS proof of possession i.e., a proof that the private key corresponding to the validator_pub_key is known by the signer. (required).
      • deposit_data_root — string Uniquely identifies the set of deposits made so far (required).
    • gas_price — string Adjust the gas price (optional).
    • gas_limit — string Adjust the gas limit (optional).

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_aggregated_deposit_tx — If you need to get a fresh version of the transaction payload (i.e., the nonce has increased).
    • sign_aggregated_deposit_tx — Submit a signed transaction payload ready to be broadcast to the network.
    • confirm_aggregated_deposit_tx_by_hash — Submit a previously completed transaction hash to continue the flow.
  • data — object Aggregated staking flow & transaction data.

Submit Signed 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 /api/v1/flows/[:flow_id]/next with the signed payload. The Staking API will broadcast the transaction to the Ethereum network.

Request Body
Example Response
{
  "id": "336d0a12-4902-4b18-9219-3f0ed2ffcac7",
  "state": "aggregated_deposit_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2022-12-20T14:00:36.269Z",
      "inputs": []
    }
  ],
  "data": {
    "deposits": [
      {
        "validator_pub_key": "0x8d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d33",
        "withdrawal_credentials": "0x010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85",
        "signature": "0xa5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064",
        "deposit_data_root": "0x67b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8"
      }
    ],
    "funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
    "gas_price": null,
    "gas_limit": null,
    "aggregated_deposit_transaction": {
      "raw": "0x02f902d705808459682f0084598ab15683011706943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c0",
      "signing_payload": "0x13ac527a761599ba44d47eb3957d63257b835b3e1be410e5578f91bef55e298b",
      "signed": "0x02f9031a05808459682f0084598ab15683011706943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c001a01c6536f2d69dddb7b10c653e7f7055a63fc870fcf7597c6f80d89a9a5234d238a015a74ac864235652dd0dace203aeae3343f44c4fb4d6328b61bad2719d7141dd",
      "hash": "0x26b0c13f0ecce4049dd7d9ac885d6898e3bceafca25304aee51fc3cd39cb1460",
      "status": null,
      "error": null,
      "signatures": [
        {
          "account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
          "signature": ""
        }
      ]
    },
    "estimated_active_at": null
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2022-12-20T13:20:08.057Z",
  "updated_at": "2022-12-20T13:59:35.263Z"
}
SpecificationView Specification

Parameters

  • name — string Name of the action to execute (required).
  • inputs — object
    • transaction_payload — Signed transaction payload from the previous step's response.

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.
    • aggregated_deposit_tx_broadcasting — Transaction broadcasting to the network.
    • activating — Transaction has been confirmed and stake is now activating.
    • active — Stake is successfully active and earning rewards.
  • actions — array It includes the name & inputs of all next possible actions.
  • data — object Aggregated staking flow & transaction data.

Get Flow Status

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

Request Query
Example Response
{
  "id": "336d0a12-4902-4b18-9219-3f0ed2ffcac7",
  "state": "active",
  "actions": [],
  "data": {
    "deposits": [
      {
        "validator_pub_key": "0x8d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d33",
        "withdrawal_credentials": "0x010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85",
        "signature": "0xa5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064",
        "deposit_data_root": "0x67b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8"
      }
    ],
    "funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
    "gas_price": null,
    "gas_limit": null,
    "aggregated_deposit_transaction": {
      "raw": "0x02f902d705808459682f0084598ab15683011706943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c0",
      "signing_payload": "0x13ac527a761599ba44d47eb3957d63257b835b3e1be410e5578f91bef55e298b",
      "signed": "0x02f9031a05808459682f0084598ab15683011706943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000308d161816dbcf2c85f053701818c688530a31ebeb1d677ccd261e2fd4aed20863885d092ec0df3698178d435d71912d3300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dc780aac63683d9bd1e5be8dd8453d03f802ed85000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000060a5c28fa1507168ad64e00b4f81bb2b985f47d6129ce2d566e0103c5862acb807fd29915f106d82256c77e4dc6c6164ff12a8c76b21afe3eb693337d7885cccc38346092ded912988e26667ae17acff790fc24f8abc2d01fa05b604f9ef778064000000000000000000000000000000000000000000000000000000000000000167b2a367dfbb04d8f5ccf9e27619901289197f6e9aa558a7e0d855e6c13b36c8c001a01c6536f2d69dddb7b10c653e7f7055a63fc870fcf7597c6f80d89a9a5234d238a015a74ac864235652dd0dace203aeae3343f44c4fb4d6328b61bad2719d7141dd",
      "hash": "0x26b0c13f0ecce4049dd7d9ac885d6898e3bceafca25304aee51fc3cd39cb1460",
      "status": "confirmed",
      "error": null,
      "signatures": [
        {
          "account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
          "signature": ""
        }
      ]
    },
    "estimated_active_at": "2022-12-20T21:59:53.300Z"
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2022-12-20T13:20:08.057Z",
  "updated_at": "2022-12-20T23:52:43.307Z"
}
SpecificationView Specification

Parameters

  • 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.
    • aggregated_deposit_tx_broadcasting — Transaction broadcasting to the network.
    • activating — Transaction has been confirmed and stake is now activating.
    • active — Stake is successfully active and earning rewards.
  • actions — array It includes the name & inputs of all next possible actions.
  • data — object Staking flow & transaction data.

Create New Unstaking Flow

To initiate the unstaking process, create a new flow with a POST request to /api/v1/flows.

Request Body
Example Response
{
  "id": "96d16e6f-4984-4a8e-9018-9e4a7da54dfe",
  "operation": "unstaking",
  "state": "initialized",
  "actions": [
    {
      "name": "broadcast_unstaking_msg",
      "inputs": [
        {
          "name": "validator_index",
          "display": "Validator Index",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "only_integer": true,
                "greater_than_or_equal_to": 0
              }
            },
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "epoch",
          "display": "Epoch",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "only_integer": true,
                "greater_than_or_equal_to": 0
              }
            },
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "signature",
          "display": "Signature",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    },
    {
      "name": "unstaking_msg_expired",
      "inputs": []
    }
  ],
  "data": {
    "validator_index": null,
    "epoch": null,
    "signature": null,
    "estimated_principal_return_at": null,
    "transactions": []
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-10T15:19:51.359Z",
  "updated_at": "2023-03-10T15:19:51.359Z"
}
SpecificationView Specification

Parameters

  • flow — object
    • network_code — string Network this flow operates on (ex. ethereum) (required).
    • chain_code — string Chain this flow operates on (ex. goerli) (required).
    • operation — string The operation to perform (ex. unstaking) (required).
    • version — string API version to use (ex. v1) (optional).

Response

  • id — string ID of the flow.
  • operation — string The 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.
    • broadcast_unstaking_msg — Use this action to broadcast a transaction to unstake your ETH.
      • validator_index — The validator from which the ETH will be unstaked.
      • epoch - The Ethereum epoch number during which the ETH will be unstaked.
      • signature — A BLS proof of possession, i.e. a proof that the private key corresponding to the validator_index is known by the signer.
    • unstaking_msg_expired — Use this action to indicate that the unstaking message has expired. This action has no inputs.
  • data — object Staking flow & transaction data.

Submit Unstaking Data

After collecting the required inputs, PUT /api/v1/flows/[:flow_id]/next to move on to the next step.

Request Body
Example Response
{
  "id": "5d3fb8e0-bf2d-4fcc-9ff8-ed9d02d47659",
  "operation": "unstaking",
  "state": "broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-24T11:36:45.451Z",
      "inputs": []
    }
  ],
  "data": {
    "validator_index": 398094,
    "epoch": 158149,
    "signature": "0xa5ccd66f59898d3b655affe90ca328849c5993a54e4f63ed5447ce0f3bb6b5918bf72f06cbaec29af169abc433209eb30aa95d7ac1513c79887e2b552590119c32f350924e8f1dda2f2c1a5a68d801f3c150e8234493e0658031abdddcc9b2e3",
    "estimated_principal_return_at": null
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-02-23T05:16:02.187Z",
  "updated_at": "2023-02-24T11:28:44.565Z"
}
SpecificationView Specification

Parameters

  • name — string Name of the action to execute (required).
  • inputs — object (required).
    • epoch — string Earliest epoch when a voluntary exit can be processed for the given validator. This value must be for a past or current epoch, not a future epoch (required).
    • validator_index — number Index of the validator to exit (required).
    • signature — hexadecimal A BLS signature of the VoluntaryExit message by the validator's signing key (required).

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.
    • wait — Provides an estimated_state_change_at timestamp. This action has no inputs.
  • data — object Staking flow & transaction data.

Get Flow Status

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

Request Query
Example Response
{
  "id": "5d3fb8e0-bf2d-4fcc-9ff8-ed9d02d47659",
  "operation": "unstaking",
  "state": "unstaked",
  "actions": [],
  "data": {
    "validator_index": 398094,
    "epoch": 158149,
    "signature": "0xa5ccd66f59898d3b655affe90ca328849c5993a54e4f63ed5447ce0f3bb6b5918bf72f06cbaec29af169abc433209eb30aa95d7ac1513c79887e2b552590119c32f350924e8f1dda2f2c1a5a68d801f3c150e8234493e0658031abdddcc9b2e3",
    "estimated_principal_return_at": "2023-02-25T14:16:36.302Z"
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-02-23T05:16:02.187Z",
  "updated_at": "2023-02-25T14:18:36.302Z"
}
SpecificationView Specification

Parameters

  • 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.
    • broadcasting — Transaction broadcasting to the network.
    • exiting — Exit transaction has been confirmed and validator is in exit queue.
    • withdrawing — Validator has exited the active set and stake will be returned to the withdrawal address.
  • actions — array It includes the name & inputs of all next possible actions.
  • data — object Staking flow & transaction data.
    • estimated_principal_return_at — A timestamp tracking when the unstaked ETH will be available at the withdrawal address.