Skip to main content
API docs by Redocly

Obol API (v1.0.0-local)

Download OpenAPI specification:Download

Obol Labs: support@obol.tech URL: https://obol.tech

What is this API?

This API is for creating and managing Distributed Validators. This API works in tandem with Obol's Distributed Validator Launchpad, a dapp designed to allow people to authenticate their counterparties and agree to the terms of a Distributed Validator Cluster. This API will be made more easy for code-only interaction in the coming quarters with the release of the Obol-SDK.

Read more about Obol and how to use the launchpad on our docs site.

For enquiries:

Distributed Validators

Configuration for distributed validator key generation ceremonies.

System

System related endpoints.

Redirect to the API docs

Hitting the root of the domain redirects to /docs and a swagger deployment.

Responses

Response samples

Content type
application/json
{ }

Check the API health

This endpoint reports the API and its dependencies health.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "info": {
    },
  • "error": { },
  • "details": {
    }
}

Get network ETH APR

Proxies Beaconcha.in ethstore/latest to avoid CORS. Returns mainnet network APR.

Responses

Response samples

Content type
application/json
{
  • "apr": 0.029
}

Get network ETH APR

Proxies Beaconcha.in ethstore/latest to avoid CORS. Returns mainnet network APR.

Responses

Response samples

Content type
application/json
{
  • "apr": 0.029
}

Metrics

MetricsController_metrics

Responses

Response samples

Content type
application/json
"string"

Cluster Definition

Retrieve a Distributed Validator Cluster proposal

This endpoint allows a charon client or launchpad interface to retrieve the terms of a proposed DKG. Once all operators listed in the DKG have submitted signed approvals to the terms, this object will be ready for a cluster of operators to use as part of a DKG ceremony. If the objects in the operators array are not fully populated, these operators need to use the PUT request to upload their charon client's public key and a signature from their address to indicate their acceptance of the terms.

path Parameters
configHash
required
string

The config_hash calculated for a cluster definition.

Responses

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ],
  • "consensus_protocol": "qbft",
  • "target_gas_limit": 36000000,
  • "compounding": true
}

Accept a proposed Distributed Validator Cluster

This endpoint is used by the operators present in the operators array of a cluster definition. The operator must have accepted the latest version of Obol's terms and conditions. These operators must submit a public key (in ENR form) to serve as their identity during the DKG, along with EIP712 signatures indicating their acceptance of the terms of this DKG.

Authorizations:
bearer
path Parameters
configHash
required
string

The config_hash calculated for a cluster definition.

header Parameters
authorization
required
string

EIP712 operator hash as bearer token

Request Body schema: application/json
required
address
required
string

Ethereum address of Operator.

enr
required
string
fork_version
required
string
Enum: "mainnet" "0x00000000" "goerli" "0x00001020" "gnosis" "0x00000064" "sepolia" "0x90000069" "hoodi" "0x10000910"
version
required
string
enr_signature
required
string
config_signature
required
string

Responses

Request samples

Content type
application/json
{
  • "address": "0x000000000000000000000000000000000000dead",
  • "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
  • "fork_version": "0x00001020",
  • "version": "v1.8.0",
  • "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
  • "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ],
  • "consensus_protocol": "qbft",
  • "target_gas_limit": 36000000,
  • "compounding": true
}

Retrieve a list of cluster definitions which the address belongs to.

This endpoint allows a charon client or launchpad interface to fetch a specific number of cluster definitions which the address is part of for each page.

path Parameters
address
required
string

The operator address

query Parameters
page
required
number
limit
required
number

Responses

Response samples

Content type
application/json
{
  • "cluster_definitions": [
    ],
  • "total_count": 2,
  • "total_pages": 3
}

Retrieve a list of cluster definitions which the address belongs to.

This endpoint allows a charon client or launchpad interface to fetch a specific number of cluster definitions which the address is part of for each page.

path Parameters
address
required
string

The operator address

query Parameters
page
required
number
limit
required
number

Responses

Response samples

Content type
application/json
{
  • "cluster_definitions": [
    ],
  • "total_count": 2,
  • "total_pages": 3
}

Propose a new Distributed Validator Cluster

This endpoint allows the caller to propose a distributed key generation ceremony.The caller must have accepted the latest version of Obol's terms and conditions. The caller must specify the configuration of a Distributed Validator Cluster; such as the participating operators and the validator exit details. Operators invited to participate in this cluster must submit a public key (in ENR form) to serve as their node's identity, along with EIP712 signatures indicating their acceptance of the terms of this cluster.

Authorizations:
bearer
header Parameters
authorization
required
string

EIP712 cluster definition hash as bearer token

Request Body schema: application/json
required
name
required
string
required
Array of objects (OperatorDto) >= 3 items

operator data.

required
Array of objects (CreatorDto)

creator data.

uuid
required
string
version
required
string
num_validators
required
number >= 1
threshold
required
number >= 1
dkg_algorithm
required
string
Enum: "frost" "keycast" "default"
fork_version
required
string
Enum: "mainnet" "0x00000000" "goerli" "0x00001020" "gnosis" "0x00000064" "sepolia" "0x90000069" "hoodi" "0x10000910"
timestamp
required
string
required
Array of objects (ClusterDefValidator)

validator withdrawal configuration.

deposit_amounts
required
Array of strings

partial deposits.

consensus_protocol
required
string
Enum: "qbft" ""
target_gas_limit
required
number >= 1
compounding
required
boolean

Flag that enables compounding rewards for validators by using 0x02 withdrawal credentials

config_hash
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "operators": [
    ],
  • "creator": [
    ],
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "consensus_protocol": "qbft",
  • "target_gas_limit": 36000000,
  • "compounding": true,
  • "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ],
  • "consensus_protocol": "qbft",
  • "target_gas_limit": 36000000,
  • "compounding": true
}

Cluster Lock

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object.

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object.

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Retrieve a list of Distributed Validator Cluster Lock Objects

This endpoint is used to search for Cluster Lock Objects that match a substring of their lock_hash.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve clusters on

query Parameters
partialLockHash
required
string

A substring of the lock_hash calculated for a cluster lock.

partialClusterName
required
string

A substring of the cluster name.

page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Cluster Lock Objects

This endpoint is used to search for Cluster Lock Objects that match a substring of their lock_hash.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve clusters on

query Parameters
partialLockHash
required
string

A substring of the lock_hash calculated for a cluster lock.

partialClusterName
required
string

A substring of the cluster name.

page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it.

path Parameters
configHash
required
string

The config_hash calculated for a cluster configuration.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it.

path Parameters
configHash
required
string

The config_hash calculated for a cluster configuration.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Redirect to the launchpad cluster status page

This endpoint is used to redirect users to the created cluster status page after DKG is completed.

path Parameters
lockHash
required
string

The lock_hash calculated for a Distributed Validator Cluster.

Responses

Redirect to the launchpad cluster status page

This endpoint is used to redirect users to the created cluster status page after DKG is completed.

path Parameters
lockHash
required
string

The lock_hash calculated for a Distributed Validator Cluster.

Responses

Get average peer scores for operators in a cluster

This endpoint returns the average peer_score for each operator address in a cluster lock within a specified date range. Results are sorted by peer_score in descending order.

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

query Parameters
startDate
string
Example: startDate=2026-01-21T00:00:00.000Z

Start date for the range (ISO 8601 format). If not provided, defaults to endDate - 7 days.

endDate
string
Example: endDate=2026-01-28T00:00:00.000Z

End date for the range (ISO 8601 format). If not provided, defaults to the latest available date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get average peer scores for operators in a cluster

This endpoint returns the average peer_score for each operator address in a cluster lock within a specified date range. Results are sorted by peer_score in descending order.

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

query Parameters
startDate
string
Example: startDate=2026-01-21T00:00:00.000Z

Start date for the range (ISO 8601 format). If not provided, defaults to endDate - 7 days.

endDate
string
Example: endDate=2026-01-28T00:00:00.000Z

End date for the range (ISO 8601 format). If not provided, defaults to the latest available date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a list of Distributed Validator Clusters for which this address is an operator

This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.

path Parameters
address
required
string

The operator address.

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for which this address is an operator

This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.

path Parameters
address
required
string

The operator address.

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for which this address is an operator

This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.

path Parameters
address
required
string

The operator address.

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for which this address is an operator

This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.

path Parameters
address
required
string

The operator address.

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for a given network

This endpoint fetches a number of cluster lock objects for a given network.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve clusters on

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

sortBy
string
Default: "avg_effectiveness"

numerical field to sort by

sortOrder
string
Default: "desc"

order of sorting the field

pool
string

cluster type or pool

details
required
string
Default: "false"

The flag to populate cluster definition information.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for a given network

This endpoint fetches a number of cluster lock objects for a given network.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve clusters on

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of cluster lock objects to return.

sortBy
string
Default: "avg_effectiveness"

numerical field to sort by

sortOrder
string
Default: "desc"

order of sorting the field

pool
string

cluster type or pool

details
required
string
Default: "false"

The flag to populate cluster definition information.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_active_stake_eth": 128.5,
  • "total_active_stake_usd": 128.5,
  • "unique_validators_count": 10,
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for a given network

This endpoint fetches a nsummary of the lock files stored for a given network

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network

The network to retrieve clusters on

Responses

Response samples

Content type
application/json
{
  • "eth_staked": 2,
  • "total_clusters": 2,
  • "total_operators": 4
}

Retrieve a list of Distributed Validator Clusters for a given network

This endpoint fetches a nsummary of the lock files stored for a given network

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network

The network to retrieve clusters on

Responses

Response samples

Content type
application/json
{
  • "eth_staked": 2,
  • "total_clusters": 2,
  • "total_operators": 4
}

Push Distributed Validator Cluster Lock Data

This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster. If the lock_hash is already stored, the existing lock is returned (idempotent; no re-validation) with the same 201 response.

Request Body schema: application/json
required
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings[ items^(0x|0h)?[0-9A-F]+$ ]

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Push Distributed Validator Cluster Lock Data

This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster. If the lock_hash is already stored, the existing lock is returned (idempotent; no re-validation) with the same 201 response.

Request Body schema: application/json
required
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings[ items^(0x|0h)?[0-9A-F]+$ ]

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Verify Distributed Validator Cluster Lock Data

This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.

Request Body schema: application/json
required
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings[ items^(0x|0h)?[0-9A-F]+$ ]

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Verify Distributed Validator Cluster Lock Data

This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.

Request Body schema: application/json
required
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings[ items^(0x|0h)?[0-9A-F]+$ ]

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

State

Retrieve the Validator states for a cluster

This endpoint is used to retrieve the states of all validators in a DV Cluster

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "index": "12345",
  • "status": "active_ongoing",
  • "balance": "32",
  • "effective_balance": "32",
  • "withdrawal_credentials": "0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec",
  • "pending_partial_withdrawals": "3",
  • "pending_partial_deposits": "3",
  • "is_not_within_committee": true,
  • "0x000000000000000000000000000000": {
    }
}

DV Exit

Retrieve validators exit status summary

It shows data of operators who have signed and the count of validators ready to exit

path Parameters
lockHash
required
string

The cluster lock hash.

Responses

Response samples

Content type
application/json
{
  • "operator_exits": {
    },
  • "ready_exits": 2
}

Retrieve validators exit status summary

It shows data of operators who have signed and the count of validators ready to exit

path Parameters
lockHash
required
string

The cluster lock hash.

Responses

Response samples

Content type
application/json
{
  • "operator_exits": {
    },
  • "ready_exits": 2
}

Retrieve validators exit status

It shows data of operators who have signed and who have not

path Parameters
lockHash
required
string

The cluster lockHash.

query Parameters
page
number
limit
number
operatorAddress
required
string

The operatorAddress.

validatorPubkey
required
string

The pubkey in a cluster lock.

Responses

Response samples

Content type
application/json
{ }

Retrieve validators exit status

It shows data of operators who have signed and who have not

path Parameters
lockHash
required
string

The cluster lockHash.

query Parameters
page
number
limit
number
operatorAddress
required
string

The operatorAddress.

validatorPubkey
required
string

The pubkey in a cluster lock.

Responses

Response samples

Content type
application/json
{ }

Retrieve Distributed Validator threshold aggregated signed exit msg

This endpoint is used to retrieve validator exit message

Authorizations:
bearer
path Parameters
validatorPubkey
required
string

The distributed_public_key in a cluster lock.

shareIdx
required
any

Represents the cluster operatorIndex+1.

lockHash
required
any

The cluster lockHash.

Responses

Response samples

Content type
application/json
{ }

Retrieve Distributed Validator threshold aggregated signed exit msg

This endpoint is used to retrieve validator exit message

Authorizations:
bearer
path Parameters
validatorPubkey
required
string

The distributed_public_key in a cluster lock.

shareIdx
required
any

Represents the cluster operatorIndex+1.

lockHash
required
any

The cluster lockHash.

Responses

Response samples

Content type
application/json
{ }

Push Distributed Validator partial signed exit message

This endpoint saves partial signed exit messages.

path Parameters
lockHash
required
string

The lockHash of the cluster which the validator belongs to

Request Body schema: application/json
required
required
Array of objects (ExitBlobDto) non-empty
share_idx
required
number
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "partial_exits": [
    ],
  • "share_idx": 42,
  • "signature": ""
}

Push Distributed Validator partial signed exit message

This endpoint saves partial signed exit messages.

path Parameters
lockHash
required
string

The lockHash of the cluster which the validator belongs to

Request Body schema: application/json
required
required
Array of objects (ExitBlobDto) non-empty
share_idx
required
number
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "partial_exits": [
    ],
  • "share_idx": 42,
  • "signature": ""
}

Cluster Effectiveness

Retrieve a Distributed Validator Cluster Effectiveness Object

This endpoint is used to retrieve the effectiveness of a cluster by pubkey

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "all": 0
}

Terms And Conditions

Saves user's approval latest terms and conditions

Saves user's signature to latest Obol's terms and conditions hash and it's version

Authorizations:
bearer
header Parameters
authorization
required
string

EIP712 terms and conditions hash as bearer token

Request Body schema: application/json
required
address
required
string
version
required
number
terms_and_conditions_hash
required
string
fork_version
string
Enum: "mainnet" "0x00000000" "goerli" "0x00001020" "gnosis" "0x00000064" "sepolia" "0x90000069" "hoodi" "0x10000910"

Responses

Request samples

Content type
application/json
{
  • "address": "v1.0.0",
  • "version": 1,
  • "terms_and_conditions_hash": "",
  • "fork_version": "0x00000000"
}

Verify Signature on Terms and Conditions

This endpoint is used to check whether the Terms and Conditions has been signed by the user.

path Parameters
address
required
string

The address to check the Terms and Conditions.

Responses

Response samples

Content type
application/json
{
  • "isTermsAndConditionsSigned": true
}

Techne Credentials

Retrieve Base techne credential metadata

This endpoint is used to retrieve Base techne credential metadata

Authorizations:
bearer
path Parameters
index
required
number

The techne index.

Responses

Response samples

Content type
application/json
{}

Retrieve Bronze techne credential metadata

This endpoint is used to retrieve Bronze techne credential metadata

Authorizations:
bearer
path Parameters
index
required
number

The techne index.

Responses

Response samples

Content type
application/json
{}

Retrieve Silver techne credential metadata

This endpoint is used to retrieve Silver techne credential metadata

Authorizations:
bearer
path Parameters
index
required
number

The techne index.

Responses

Response samples

Content type
application/json
{}

Retrieve Gold techne credential metadata

This endpoint is used to retrieve Gold techne credential metadata

Authorizations:
bearer
path Parameters
index
required
number

The techne index.

Responses

Response samples

Content type
application/json
{}

Address

Retrieve obol techne credentials of an address

This endpoint is used to retrieve obol techne credentials an address owns

path Parameters
address
required
string

The address to check the techne credentials for.

Responses

Response samples

Content type
application/json
{
  • "base": [
    ],
  • "bronze": [
    ],
  • "silver": [
    ],
  • "gold": [
    ]
}

Retrieve badges for an address

This endpoint is used to retrieve the badges an address owns

path Parameters
address
required
string

The address to check the techne credentials for.

Responses

Response samples

Content type
application/json
{
  • "badges": [
    ]
}

Retrieve obol incentives of an address

This endpoint is used to retrieve incentives an address owns

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • sepolia - Sepolia Test Network

The network to retrieve operators on

address
required
string

The address to check the incentives for.

Responses

Response samples

Content type
application/json
{
  • "operator_address": "string",
  • "amount": "string",
  • "index": 0,
  • "merkle_proof": [
    ],
  • "contract_address": "string"
}

Retrieve the historical incentives of an address

This endpoint is used to retrieve the inventives given to Obol Public Goods by an address.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • sepolia - Sepolia Test Network

The network to retrieve operators on

address
required
string

The address to check the incentives for.

query Parameters
date
required
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "operator_address": "string",
  • "amount": "string",
  • "index": 0,
  • "merkle_proof": [
    ],
  • "contract_address": "string"
}

Retrieve operators on a given network

This endpoint fetches a number of operators for a given network.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve operators on

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of operators to return.

sortBy
string
Default: "active_validators_count"

numerical field to sort by

sortOrder
string
Default: "desc"

order of sorting the field

object

techne to filter by

object

badges to filter by

details
required
string
Default: "false"

The flag to populate operators information.

Responses

Response samples

Content type
application/json
{
  • "operators": [
    ],
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list operators on a given network

This endpoint is used to search for operators that match a substring of their address.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve operators on

query Parameters
partialAddress
required
string

A substring of the address of Operator.

page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 100

The number of operators to return.

Responses

Response samples

Content type
application/json
{
  • "operators": [
    ],
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve migrateable validators for withdrawal address

This endpoint is used fetch eligible validators for migration .

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve active validators on

withdrawalAddress
required
string

Withdrawal address of source validators.

query Parameters
limit
required
integer
Default: 50

The number of validators to return.

offset
required
integer
Default: 0

The number of items to skip before starting to collect the result set

Responses

Response samples

Content type
application/json
{
  • "validators": [
    ],
  • "hasMore": true
}

OWR Information

Retrieve OWR tranch information

This endpoint is used to retrieve information on the tranches of an OWR.

Authorizations:
bearer
path Parameters
network
required
string

The network of the OWR.

address
required
string

The address of the OWR.

Responses

Response samples

Content type
application/json
{
  • "reward_recipient": "0xA",
  • "principal_recipient": "0xA",
  • "threshold": "32000000000000000000"
}

DV Migrate

Retrieve validators migrate status

It shows data of validators status

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • hoodi - Hoodi Test Network
  • sepolia - Sepolia Test Network

The network to retrieve clusters on

query Parameters
limit
required
integer
Default: 50

The number of validators to return.

page
required
integer
Default: 0

The page number to retrieve.

withdrawalAddress
required
string

Withdrawal address of target validators.

targetPubKey
required
string

The pubkey of target validator.

Responses

Response samples

Content type
application/json
{
  • "validators": [
    ]
}

Test

Store test result data

Accepts the JSON body produced by Charon when running charon test … --publish: enr, sig, and data. Authentication is not a Bearer token: TestEnrGuard verifies that sig is a valid secp256k1 ECDSA signature (base64, as emitted by Go json.Marshal on the signature bytes) over the SSZ hash of JSON.stringify(data) for the public key embedded in enr. Only Content-Type: application/json is required.

Request Body schema: application/json
required
object

Nested test categories (charon_peers, beacon_node, validator_client, mev, infra). Charon signs JSON.stringify of this object (after json.Marshal in Go); the guard recomputes the hash from the parsed data value.

enr
string

ENR text for the Charon node whose private key signed the payload

sig
string

Base64-encoded secp256k1 ECDSA signature (65 bytes: 32-byte r + 32-byte s + 1-byte recovery id) over the SSZ hashTreeRoot of the UTF-8 bytes of JSON.stringify(data), matching Charon publishResultToObolAPI

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "enr": "enr:-IS4QAnExamplePlaceholderReplaceWithRealEnrFromCharon",
  • "sig": "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghijklmnoPQRSTUVWxyZ"
}

Get test results by ENR

This endpoint retrieves test results for a specific ENR.

path Parameters
enr
required
string

ENR to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deposit Data

Retrieve partial deposit data for a validator

This endpoint returns all partial deposit data grouped by amount for a specific validator

path Parameters
lockHash
required
string

The cluster lock hash

pubkey
required
string

The validator public key (distributed_public_key)

Responses

Response samples

Content type
application/json
{
  • "lock_hash": "",
  • "pubkey": "0xFULL_1",
  • "withdrawal_credentials": "0xWITHDRAW_1",
  • "amounts": [
    ]
}

Retrieve partial deposit data for a validator

This endpoint returns all partial deposit data grouped by amount for a specific validator

path Parameters
lockHash
required
string

The cluster lock hash

pubkey
required
string

The validator public key (distributed_public_key)

Responses

Response samples

Content type
application/json
{
  • "lock_hash": "",
  • "pubkey": "0xFULL_1",
  • "withdrawal_credentials": "0xWITHDRAW_1",
  • "amounts": [
    ]
}

Push partial deposit data

This endpoint saves partial deposit data signed by an operator

path Parameters
lockHash
required
string

The lock hash of the cluster

share_index
required
number

The share index (operator index + 1)

Request Body schema: application/json
required
required
Array of objects (PartialDepositDataDto) non-empty
Array (non-empty)
pubkey
required
string^(0x|0h)?[0-9A-F]+$

Public key of the validator (should be in lock file)

withdrawal_credentials
required
string

Withdrawal credentials (0x01 or 0x02)

amount
required
string^\d+$

Amount in Gwei as string (between 1 and 2048 ETH)

signature
required
string

BLS signature over (pubkey, withdrawal_credentials, amount)

Responses

Request samples

Content type
application/json
{
  • "partial_deposit_data": [
    ]
}

Push partial deposit data

This endpoint saves partial deposit data signed by an operator

path Parameters
lockHash
required
string

The lock hash of the cluster

share_index
required
number

The share index (operator index + 1)

Request Body schema: application/json
required
required
Array of objects (PartialDepositDataDto) non-empty
Array (non-empty)
pubkey
required
string^(0x|0h)?[0-9A-F]+$

Public key of the validator (should be in lock file)

withdrawal_credentials
required
string

Withdrawal credentials (0x01 or 0x02)

amount
required
string^\d+$

Amount in Gwei as string (between 1 and 2048 ETH)

signature
required
string

BLS signature over (pubkey, withdrawal_credentials, amount)

Responses

Request samples

Content type
application/json
{
  • "partial_deposit_data": [
    ]
}

Fee Recipient

Submit partial fee recipient registrations

Stores partial BLS-signed builder registration messages for a given cluster operator. Partials are grouped into builder registrations by message content (fee_recipient, gas_limit, timestamp). The timestamp must be greater than or equal to the highest timestamp any operator has submitted for each pubkey. Equal timestamps are allowed so operators can join an existing registration group.

path Parameters
lockHash
required
string
Example: 0x1234abcd...

The cluster lock hash.

shareIdx
required
number
Example: 1

The operator share index (1-based).

Request Body schema: application/json
required
required
Array of objects (PartialRegistrationDto) non-empty
Array (non-empty)
required
object (RegistrationMessageDto)
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "partial_registrations": [
    ]
}

Submit partial fee recipient registrations

Stores partial BLS-signed builder registration messages for a given cluster operator. Partials are grouped into builder registrations by message content (fee_recipient, gas_limit, timestamp). The timestamp must be greater than or equal to the highest timestamp any operator has submitted for each pubkey. Equal timestamps are allowed so operators can join an existing registration group.

path Parameters
lockHash
required
string
Example: 0x1234abcd...

The cluster lock hash.

shareIdx
required
number
Example: 1

The operator share index (1-based).

Request Body schema: application/json
required
required
Array of objects (PartialRegistrationDto) non-empty
Array (non-empty)
required
object (RegistrationMessageDto)
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "partial_registrations": [
    ]
}

Fetch partial fee recipient registrations

Returns builder registration status for validators in a cluster. For each validator, returns at most two registrations: the latest one that reached quorum (quorum: true) and the latest one still collecting signatures (quorum: false). Validators with no registration data are omitted. Optionally pass an array of pubkeys in the request body to filter results.

path Parameters
lockHash
required
string
Example: 0x1234abcd...

The cluster lock hash.

Request Body schema: application/json
required
pubkeys
Array of strings

Optional list of validator pubkeys to filter by. If omitted or empty, returns all validators with registrations.

Responses

Request samples

Content type
application/json
{
  • "pubkeys": [
    ]
}

Fetch partial fee recipient registrations

Returns builder registration status for validators in a cluster. For each validator, returns at most two registrations: the latest one that reached quorum (quorum: true) and the latest one still collecting signatures (quorum: false). Validators with no registration data are omitted. Optionally pass an array of pubkeys in the request body to filter results.

path Parameters
lockHash
required
string
Example: 0x1234abcd...

The cluster lock hash.

Request Body schema: application/json
required
pubkeys
Array of strings

Optional list of validator pubkeys to filter by. If omitted or empty, returns all validators with registrations.

Responses

Request samples

Content type
application/json
{
  • "pubkeys": [
    ]
}

tvs

Get Total Value Staked Of Obol for a network

Returns either summary (total balance) or detailed (validator-level) TVS data for a specific timestamp. All returned data (balances, counts, totals) corresponds to the timestamp shown in the response. Each network has one data snapshot per day.

path Parameters
network
required
string
Example: mainnet

Network name (e.g., mainnet, hoodi)

query Parameters
limit
integer <= 1000
Default: 100

Number of results per page (only applies when details=true).

page
integer
Default: 0

Page number (only applies when details=true)

details
string
Default: "false"

If true, returns detailed validator-level data

timestamp
any
Example: timestamp=2025-10-02

ISO 8601 timestamp or date (YYYY-MM-DD). If date-only format is used, returns data for that day regardless of exact time. If not provided, returns the latest available data.

Responses

Response samples

Content type
application/json
Example
{
  • "total_balance_eth": 12346,
  • "total_balance_usd": 45678901,
  • "timestamp": "2025-10-02T00:00:00.000Z",
  • "network": "mainnet",
  • "total_unclaimed_balance_eth_denominated": 67.45,
  • "total_claimed_balance_eth_denominated": 71.23,
  • "total_eth_transferred": 4.56,
  • "total_revenue": 142.89,
  • "total_fees_eth_denominated": 504.12
}

Get Total Value Staked Of Obol for a network

Returns either summary (total balance) or detailed (validator-level) TVS data for a specific timestamp. All returned data (balances, counts, totals) corresponds to the timestamp shown in the response. Each network has one data snapshot per day.

path Parameters
network
required
string
Example: mainnet

Network name (e.g., mainnet, hoodi)

query Parameters
limit
integer <= 1000
Default: 100

Number of results per page (only applies when details=true).

page
integer
Default: 0

Page number (only applies when details=true)

details
string
Default: "false"

If true, returns detailed validator-level data

timestamp
any
Example: timestamp=2025-10-02

ISO 8601 timestamp or date (YYYY-MM-DD). If date-only format is used, returns data for that day regardless of exact time. If not provided, returns the latest available data.

Responses

Response samples

Content type
application/json
Example
{
  • "total_balance_eth": 12346,
  • "total_balance_usd": 45678901,
  • "timestamp": "2025-10-02T00:00:00.000Z",
  • "network": "mainnet",
  • "total_unclaimed_balance_eth_denominated": 67.45,
  • "total_claimed_balance_eth_denominated": 71.23,
  • "total_eth_transferred": 4.56,
  • "total_revenue": 142.89,
  • "total_fees_eth_denominated": 504.12
}

Positions

Get positions for an address

Returns all DV clusters where the address (or any additional address) appears as withdrawal_address or fee_recipient. Also checks Lido protocol_fee_splitters.

path Parameters
network
required
string

Network name (mainnet, hoodi, etc.)

address
required
string

The address to look up positions for

Request Body schema: application/json
required
additionalAddresses
Array of strings

Additional addresses to search (e.g. split addresses from getRelatedSplits, DeFi wrapper WA)

Responses

Request samples

Content type
application/json
{
  • "additionalAddresses": [
    ]
}

Response samples

Content type
application/json
{
  • "positions": [
    ]
}

Get positions for an address

Returns all DV clusters where the address (or any additional address) appears as withdrawal_address or fee_recipient. Also checks Lido protocol_fee_splitters.

path Parameters
network
required
string

Network name (mainnet, hoodi, etc.)

address
required
string

The address to look up positions for

Request Body schema: application/json
required
additionalAddresses
Array of strings

Additional addresses to search (e.g. split addresses from getRelatedSplits, DeFi wrapper WA)

Responses

Request samples

Content type
application/json
{
  • "additionalAddresses": [
    ]
}

Response samples

Content type
application/json
{
  • "positions": [
    ]
}