Flow Overview
At a high level
Click to expand
Requests Flow
Initialize Staking Flow
To start the aggregated staking process, you'll need to create a new flow. This can be done by sending a POST request to the endpoint/flows.
URL
https://api.figment.io/flows
Request
protocol* —stringProtocol this flow operates on (ethereum).network* —stringNetwork this flow operates on (mainnet,goerliorholesky).operation* —stringThe operation to perform (aggregated_staking).
{
"protocol": "ethereum",
"network": "holesky",
"operation": "aggregated_staking"
}
Response
id—stringID of the newly created flow.operation—stringThe Staking API operation being performed by this flow (aggregated_staking).state—stringThe current state of the flow (initialized).actions—arrayAn array of action objects containing the name, inputs, and validations for advancing the flow with each action.assign_staking_data— Use this action to generate an aggregated deposit transaction to stake your ETH. Theassign_staking_dataaction indicates eleven fields for data collection.
data: Data specific to this flow.funding_account_address— The wallet holding the ETH to be staked.withdrawal_address— The withdrawal address into which you want to receive your rewards and principal after withdrawal.amount— The amount of ETH you want to stake. Multiple of 32 less than or equal to 3200.deposits—arrayof 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 thevalidator_pub_keyis known by the signer.deposit_data_root— Uniquely identifies the set of deposits made so far.genesis_fork_version— The fork version of Ethereum you used as an input to createsignature.
gas_limit— Adjust the gas limit.gas_price— Adjust the gas price.estimated_active_at:stringA high fidelity estimation of when a given validator will become active.
{
"id": "7d0c5354-72f0-4bac-bc29-b7384d0321a8",
"operation": "aggregated_staking",
"state": "initialized",
"actions": [
{
"name": "assign_staking_data",
"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": true,
"allow_duplicates": false
}
},
{
"type": "length",
"options": {
"maximum": 250,
"message": "cannot fund more than 250 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": "genesis_fork_version",
"display": "Genesis Fork Version",
"description": "",
"type": "hex",
"validations": [
{
"type": "acceptable_genesis_fork_version",
"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
},
{
"name": "withdrawal_address",
"display": "Withdrawal Address",
"description": "",
"type": "string",
"validations": [],
"array": false,
"default_value": null
},
{
"name": "amount",
"display": "Amount",
"description": "",
"type": "decimal",
"validations": [],
"array": false,
"default_value": null
}
]
}
],
"data": {
"deposits": [],
"funding_account_address": null,
"withdrawal_address": null,
"amount": null,
"validators_to_provision": null,
"gas_price": null,
"gas_limit": null,
"estimated_active_at": null,
"transactions": []
},
"protocol": "ethereum",
"network": "holesky",
"created_at": "2023-04-06T06:37:06.055Z",
"updated_at": "2023-04-06T06:37:06.055Z"
}
Submit Staking Data
Once you have collected all the required inputs, proceed to the next step by sending a PUT request to /flows/[:flow_id]/next.
URL
https://api.figment.io/flows/[:flow_id]/next
Request
name* :assign_staking_datainputs* :objectfunding_account_address* :stringThe wallet holding the ETH to be staked.withdrawal_address* :hexThe withdrawal address into which you want to receive your rewards and principal after withdrawal.amount* :numberThe amount of ETH you want to stake. Multiple of 32 less than or equal to 3200.gas_limit: Adjust the gas limitgas_price: Adjust the gas price
{
"name": "assign_staking_data",
"inputs": {
"funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"withdrawal_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"amount": 32
}
}
Response
The aggregated staking flow ensures sufficient provision of validators to stake your full amount, even if your organization hasn't pre-provisioned enough validators.
Warning
This process operates asynchronously and may require awaiting a webhook indicating successful provisioning or polling before proceeding.
Best Practice
To monitor progress effectively, consider polling the flow until it reaches the state of
aggregated_deposit_tx_signature. This should not take longer than 2.5 minutes.This allows you to handle the subsequent steps with greater efficiency and accuracy.
Therefore, two possible states may be returned:
awaiting_provision: The Staking API is in communication with internal systems to provision validators for your organization.aggregated_deposit_tx_signature: Your organization has enough validators available, allowing you to proceed to transaction signing. This can be due to preprovisioned validators or the Staking API provisioning validators for you and moving out of theawaiting_provisionstate.
Notes
Within the data object, the field estimated_active_at provides a high fidelity estimation of when all validators funded in this flow will be active.
{
"id": "7d0c5354-72f0-4bac-bc29-b7384d0321a8",
"operation": "aggregated_staking",
"state": "awaiting_provision",
"actions": [
{
"name": "wait",
"estimated_state_change_at": "2023-04-06T06:44:08.345Z",
"inputs": []
}
],
"data": {
"deposits": [],
"funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"withdrawal_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"amount": "32.0",
"validators_to_provision": 1,
"gas_price": null,
"gas_limit": null,
"estimated_active_at": "2023-04-08T12:10:21.412Z",
"transactions": []
},
"protocol": "ethereum",
"network": "holesky",
"created_at": "2023-04-06T06:37:06.055Z",
"updated_at": "2023-04-06T06:39:07.287Z"
}
Sign Staking Transaction
Sign transaction payload
When the flow reaches
aggregated_deposit_tx_signature, you will find an unsigned transaction payload that is ready to be signed for staking with your organization's validators.
Furthermore, within the state aggregated_deposit_tx_signature, you have the option to take one of three potential actions:
refresh_aggregated_deposit_tx: If you require an updated version of the transaction payload, usually when the transaction nonce of yourfunding_accounthas increased.sign_aggregated_deposit_tx: You can proceed by submitting a signed transaction payload or an array of signatures. For detailed instructions on signing transactions, please refer to the guides Signing Transactions with Figment's npm Package and Signing Transactions with the Fireblocks API for details.confirm_aggregated_deposit_tx_by_hash: Another option is to submit a previously completed transaction hash to advance the flow. For more information on this method, please consult the guide Advance Flows Using a Transaction Hash.
Broadcast Staking Transaction
Warning
Before broadcasting the transaction, you must sign the
transaction_payloadyou received in the previous step.
After successfully signing the transaction, you have two methods to proceed. Both methods involve sending a PUT request to the following URL: https://api.figment.io/flows/[:flow_id]/next. Choose the appropriate method based on your signing approach.
Method 1 - Submitting Transaction Payload:
If you signed the transaction and have the transaction payload available, use the following request details:
API Endpoint
https://api.figment.io/flows/[:flow_id]/next
Request Details
name*:sign_aggregated_deposit_txinputs*:objecttransaction_payload*: The signed transaction payload obtained from the previous step's response.
{
"name": "sign_aggregated_deposit_tx",
"inputs": {
"transaction_payload": "0x02f9031b05028459682f0085293dc82d66830116fa943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000309855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf27600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff3000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006094c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb00000000000000000000000000000000000000000000000000000000000000001348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6c001a0e65fa70c0c8224d19a18fffaabd4f1d76773d6e86aa1b95e416d10b2fe799738a07c8430f7f6e566e0647fd2295c0ba1b2e0d8f7cd212b7bae9aa0365f69d590a9"
}
}
Method 2 - Submitting Signatures:
If your signing keys are managed by a custodial solution (e.g., Fireblocks), you can use an alternative method by submitting an array of object containing the signatures. Here are the request details:
API Endpoint
https://api.figment.io/flows/[:flow_id]/next
Request Details
name*:sign_aggregated_deposit_txinputs*:objectsignatures: Anarrayofobjectrepresenting the signatures. This method is useful when you don't send the transaction payload directly. For more information, refer to the guide Signing Transactions with the Fireblocks API.
Wether you opt for Method 1 or Method 2, the response will look like this:
Response
id:stringID of the flow.operation:stringThe Staking API operation being performed by this flow.state:stringThe 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 active and earning rewards.
actions:arrayIt includes thename&inputsof all next possible actions.data:objectFlow & transaction data.estimated_active_at:stringA high fidelity estimation of when a given validator will become active.
{
"id": "7d0c5354-72f0-4bac-bc29-b7384d0321a8",
"operation": "aggregated_staking",
"state": "aggregated_deposit_tx_broadcasting",
"actions": [
{
"name": "wait",
"estimated_state_change_at": "2023-04-06T06:45:19.485Z",
"inputs": []
}
],
"data": {
"withdrawal_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"validators_to_provision": 1,
"estimated_active_at": "2022-04-08T12:10:21.412Z",
"transactions": [
{
"code": "aggregated_deposit",
"amount": "32.0",
"raw": "0x02f902d805028459682f0085293dc82d66830116fa943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000309855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf27600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff3000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006094c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb00000000000000000000000000000000000000000000000000000000000000001348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6c0",
"signing_payload": "0xbf2cd8a721c4845f9a13813c680ba205f166da1d5a6e0e42f92baca723feb5d0",
"signed": "0x02f9031b05028459682f0085293dc82d66830116fa943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000309855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf27600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff3000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006094c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb00000000000000000000000000000000000000000000000000000000000000001348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6c001a0e65fa70c0c8224d19a18fffaabd4f1d76773d6e86aa1b95e416d10b2fe799738a07c8430f7f6e566e0647fd2295c0ba1b2e0d8f7cd212b7bae9aa0365f69d590a9",
"hash": "0xfd0160813b6fe74b68c35e17d15b2dea59d6544fbbd761d8705764fe7dda17ff",
"status": null,
"error": null,
"signatures": [
{
"account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"signature": ""
}
],
"block_time": null,
"inputs": {
"funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"gas_price": null,
"gas_limit": null,
"deposits": [
{
"validator_pub_key": "0x9855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf276",
"withdrawal_credentials": "0x010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff30",
"signature": "0x94c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb0",
"deposit_data_root": "0x348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6",
"genesis_fork_version": "0x00001020"
}
],
"amount": "32.0"
}
}
]
},
"protocol": "ethereum",
"network": "holesky",
"created_at": "2023-04-06T06:37:06.055Z",
"updated_at": "2023-04-06T06:44:18.777Z"
}
Get Staking Flow
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.
URL
https://api.figment.io/flows/[:flow_id]
Request
- None
Response
id:stringID of the flow.operation:stringThe Staking API operation being performed by this flow.state:stringThe current state of the flow.aggregated_deposit_tx_broadcasting: Transaction is broadcasting and not confirmed yet.activating: The validator is in the activation queue and will join the active set.active: The validator has successfully joined the active set.- Refer to the Ethereum Validator Lifecycle guide for more information.
actions:arrayIt includes thename&inputsof all next possible actions.data:objectFlow & transaction data.estimated_active_at:stringA high fidelity estimation of when the validator will become active.
{
"id": "7d0c5354-72f0-4bac-bc29-b7384d0321a8",
"operation": "aggregated_staking",
"state": "active",
"actions": [],
"data": {
"withdrawal_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"validators_to_provision": 1,
"estimated_active_at": "2023-04-06T22:44:54.112Z",
"transactions": [
{
"code": "aggregated_deposit",
"amount": "32.0",
"raw": "0x02f902d805028459682f0085293dc82d66830116fa943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000309855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf27600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff3000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006094c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb00000000000000000000000000000000000000000000000000000000000000001348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6c0",
"signing_payload": "0xbf2cd8a721c4845f9a13813c680ba205f166da1d5a6e0e42f92baca723feb5d0",
"signed": "0x02f9031b05028459682f0085293dc82d66830116fa943e30fc2cc800af86e88b69d32d9daf7eccb3a5208901bc16d674ec800000b902a44f498c730000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001a000000000000000000000000000000000000000000000000000000000000002600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000309855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf27600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff3000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000006094c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb00000000000000000000000000000000000000000000000000000000000000001348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6c001a0e65fa70c0c8224d19a18fffaabd4f1d76773d6e86aa1b95e416d10b2fe799738a07c8430f7f6e566e0647fd2295c0ba1b2e0d8f7cd212b7bae9aa0365f69d590a9",
"hash": "0xfd0160813b6fe74b68c35e17d15b2dea59d6544fbbd761d8705764fe7dda17ff",
"status": "confirmed",
"error": null,
"signatures": [
{
"account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"signature": ""
}
],
"block_time": "2023-04-06T06:44:24.000Z",
"inputs": {
"funding_account_address": "0xB458D87418e6020260C92e18b11b64F1ed6fFF30",
"gas_price": null,
"gas_limit": null,
"deposits": [
{
"validator_pub_key": "0x9855d353352eefb56929801e0d376cf6e5973d18c39424fe42c829cb62a6ff17648e6fdbf0c7259d25d09e17769cf276",
"withdrawal_credentials": "0x010000000000000000000000b458d87418e6020260c92e18b11b64f1ed6fff30",
"signature": "0x94c7e3414664f4dbd1cc8d326de278ee0e4fcf4bc74fb1ea74216bab8c644ddc4fd1ed59dca7db60959f81d4dd5dd8271175113fbc0decb19486f885a5e2bc440a5b3b33184be66dd069290ebe7f47024d2799ea7b1c1eb829cc018b8334fdb0",
"deposit_data_root": "0x348de8001f6b5ce424f93ca0ca090ad1986ee5969991fa02af345980e874ade6",
"genesis_fork_version": "0x00001020"
}
],
"amount": "32.0"
}
}
]
},
"protocol": "ethereum",
"network": "holesky",
"created_at": "2023-04-06T06:37:06.055Z",
"updated_at": "2023-04-06T22:44:54.133Z"
}