Getting Started

The Obol API provides endpoints for deploying clusters and generating deposit data for ETH on the Obol network. Currently, it offers a service for creating clusters to facilitate the batch deployment of ETH validators on Obol, making it easy to integrate our API into your system for ETH validator operations.

To get started with using our DVT Staking API for staking on the Obol network, there are a few basic prerequisites to ensure a smooth and efficient setup:

Minimum Staking Requirement: You need a minimum of 32 ETH for each validator you want to run.
API Key Request: Get authentication token to start using the Ebunker staking API.
FeeRecipientAddress: To receive incentives on the Obol network, Ebunker needs to provide an Obol split address for distributing EL rewards. Please note that this address must be obtained from Ebunker before creating the cluster, otherwise it may affect your Boost rewards.

The Obol API provides the following interfaces:

Create Obol cluster: Build an Obol cluster to generate deposit data and cluster deployment data associated with the cluster.Pectra upgrade is now supported, including the generation of validator clusters with 0x02 credential type.
Query Obol cluster: Query the deposit data generated by an cluster for staking validators. Each cluster can contain between 1 and 2000 validators. It is recommended to generate a sufficient number of validators in a single cluster, allowing you to activate some initially and activate the remaining ones later as needed.
Cancel Obol cluster: Used to cancel generated Obol clusters. Please use with caution.Once canceled, the cluster will no longer continue running. Please ensure that no validators have been run on the cluster.

Steps

1. Create Obol cluster

To create an Obol cluster, cluster node data and the validator pool will be generated. The cluster data is produced asynchronously as a Job task. Once the cluster status changes to ready, you can retrieve the deposit data via the query API to perform validator staking on the Beacon Chain.

The query API will return the deposit data for all generated validators. If you plan to stake and activate validators in batches, you may extract and use only the necessary deposit data based on your actual needs.

Note: The request parameter feeRecipientAddress is an Obol split address, which must include the revenue share address of the Obol project. Please contact Ebunker to confirm before generating the cluster. The feeRecipientAddresswill be provided to the user by Ebunker.

Example Request

curl -X 'POST' \
  'https://api-test.ssv.ebunker.io/api/v1/eth/obol/cluster' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "deed7216-21dc-4101-b66e-8f8e46a3a82e",
  "validatorsCount": 500,
  "amount": 64,
  "credentialsType": "0x02",
  "withdrawalAddress": "0xaC8583143bD6dCE71D15d26833CaF638A4b925b5",
  "feeRecipientAddress": "0xA67a8F15E3b4780cb88e3f1B2702D0357fb2134f"
}'

Request Parameters

id — The UUID of the cluster, used later to query cluster data.
validatorsCount — Number of validators.
amount — The amount of ETH staked per validator, ranging from 32 to 2048.
credentialsType — The type of validator credentials, either 0x01 or 0x02.
withdrawalAddress — The withdrawal address for the validator.
feeRecipientAddress — The address for receiving EL rewards. This address is the Obol split address provided by Ebunker.

Example Response

{
  "code": 200,
  "message": "Success"
}

2. Get cluster Data

Retrieve cluster data using the cluster ID. When the asynchronous task is completed and the cluster status changes to "ready", it will return depositData for users to complete validator staking on Beacon.

Example Request

curl --request GET \
     --url https://api-test.ssv.ebunker.io/api/v1/eth/obol/cluster?id=deed7216-21dc-4101-b66e-8f8e46a3a82e \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \

Request Parameters

id — The UUID of the cluster, used to query cluster data.

Example Response

{
    "code": 200,
    "message": "Success",
    "result": {
        "id": "deed7216-21dc-4101-b66e-8f8e46a3a82e",
        "validatorsCount": 1,
        "withdrawalAddress": "0xaC8583143bD6dCE71D15d26833CaF638A4b925b5",
        "feeRecipientAddress": "0xA67a8F15E3b4780cb88e3f1B2702D0357fb2134f",
        "status": "ready",
        "depositData": [
            {
                "pubkey": "866b5ce06ffae156595f287c51423251ea118bb97dcc0231a777bf849b01103faf11757b1c18aa974e8c804047541a2b",
                "withdrawal_credentials": "010000000000000000000000ac8583143bd6dce71d15d26833caf638a4b925b5",
                "amount": 32000000000,
                "signature": "8b7fdf95776f8adea1450499593c7c2dec44e70ea378c5fbe62fe1ee7d2534add2491c342e36a8905eedf0169c87972715c2e17b95c4c3a62661e64f6afa4852c4727ec6e575a6a51efab68f5fa5ce4529f86ceb9f69e14cad63ed16ab774813",
                "deposit_message_root": "3d66694e657adf5fa5c3d23de7d233e4b395998c16861cc5890b1eabda102a30",
                "deposit_data_root": "b72bb42f0dfd8e7a62cf4e7a2bd5f38639f8807555df207f1253e13092e9d42a",
                "fork_version": "01017000",
                "network_name": "holesky",
                "deposit_cli_version": "2.3.0"
            }
        ]
    }
}

Response Parameters

id — The UUID of the cluster.
amount — The amount of ETH staked per validator, ranging from 32 to 2048.
credentialsType — The type of validator credentials, either 0x01 or 0x02.
validatorsCount — Number of validators.
withdrawalAddress — The withdrawal address for the validator.
feeRecipientAddress — The address for receiving EL rewards. This address is the Obol split address provided by Ebunker.
status - cluster status: init (cluster initialization) processing (cluster data Job task execution in progress) deploying (cluster node deployment in progress) ready (cluster completed) cancel (cluster cancelled)
depositData - The deposit data for validators generated by the cluster, used for staking on ETH Beacon

3. Cancel cluster

Change the created cluster to cancelled status. After the cluster is cancelled, Ebunker will no longer deploy and run the cluster generated by this cluster. Please use with caution. If the cluster status is "processing", it means the asynchronous Job task for generating the cluster is being executed, and the cluster cannot be cancelled at this time. Note: If you cancel an cluster after the cluster information has been uploaded to Obol, your cluster will still appear in the Obol explorer, but do not stake validators for cancelled clusters.

Example Request

curl --request DELETE \
     --url https://api-test.ssv.ebunker.io/api/v1/eth/obol/cluster?id=deed7216-21dc-4101-b66e-8f8e46a3a82e \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
'

Request Parameters

id — The UUID of the cluster.

Example Response

{
    "code": 200,
    "message": "Success",
    "result": {
        "id": "deed7216-21dc-4101-b66e-8f8e46a3a82e",
        "validatorsCount": 1,
        "withdrawalAddress": "0xaC8583143bD6dCE71D15d26833CaF638A4b925b5",
        "feeRecipientAddress": "0xA67a8F15E3b4780cb88e3f1B2702D0357fb2134f",
        "status": "cancel",
        "createdTime": "2025-04-11T09:18:36.654Z",
        "updatedTime": "2025-04-15T06:38:04.107Z"
    }
}

Response Parameters

id — The UUID of the cluster.
amount — The amount of ETH staked per validator, ranging from 32 to 2048.
credentialsType — The type of validator credentials, either 0x01 or 0x02.
validatorsCount — Number of validators.
withdrawalAddress — The withdrawal address for the validator.
feeRecipientAddress — The address for receiving EL rewards. This address is the Obol split address provided by Ebunker.
status - cluster status: cancel (cluster cancelled)

Getting Started

Steps​

1. Create Obol cluster​

2. Get cluster Data​

3. Cancel cluster​

Steps

1. Create Obol cluster

2. Get cluster Data

3. Cancel cluster