Download OpenAPI specification:Download
This API is for creating and managing Distributed Validators. It works in tandem with Obol's Distributed Validator Launchpad, a dapp for authenticating counterparties and agreeing on the terms of a Distributed Validator Cluster. For code-only use, the Obol SDK wraps it with types. Endpoints are listed under /v1; older clients may still call most of them without the prefix.
{ "statusCode": 404, "message": "Cluster not found" }. Validation errors carry a list of messages and an error reason. A 500 always says Internal server error.X-Request-Id header (Cloudflare's Ray ID for requests through Cloudflare). Quote it when reporting a problem.Retry-After in seconds.Read more about Obol and the launchpad on our docs site.
For enquiries:
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.
| configHash required | string The |
{- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}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. Once a cluster lock has been posted for the definition, it can no longer be changed and this endpoint returns 409.
| configHash required | string The |
| authorization required | string EIP712 operator hash as bearer token |
| 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 |
{- "address": "0x000000000000000000000000000000000000dead",
- "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
- "fork_version": "0x00001020",
- "version": "v1.8.0",
- "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}{- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}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.
| address required | string The operator address |
| page required | number |
| limit required | number |
{- "cluster_definitions": [
- {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}
], - "total_count": 2,
- "total_pages": 3
}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.
| address required | string The operator address |
| page required | number |
| limit required | number |
{- "cluster_definitions": [
- {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}
], - "total_count": 2,
- "total_pages": 3
}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.
| authorization required | string EIP712 cluster definition hash as bearer token |
| 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 |
{- "name": "My Obol Cluster",
- "operators": [
- {
- "address": "0x000000000000000000000000000000000000dead",
- "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
- "fork_version": "0x00001020",
- "version": "v1.8.0",
- "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}, - {
- "address": "0x000000000000000000000000000000000000dead",
- "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
- "fork_version": "0x00001020",
- "version": "v1.8.0",
- "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}, - {
- "address": "0x000000000000000000000000000000000000dead",
- "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
- "fork_version": "0x00001020",
- "version": "v1.8.0",
- "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}
], - "creator": [
- {
- "address": "0x000000000000000000000000000000000000dead",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}
], - "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": [
- {
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead"
}
], - "deposit_amounts": [
- "string"
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true,
- "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}{- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}This endpoint is used to retrieve a cluster lock object.
| lockHash required | string The |
| validators | boolean Default: true Set to |
{- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- { }
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "string"
], - "definition_stored": true,
- "is_current": true,
- "superseded_by": null
}Returns a slice of the distributed_validators array for a cluster lock. Use together with GET /lock/{lockHash}?validators=false to lazy-load very large clusters.
| lockHash required | string The |
| page | integer Default: 0 The page number to retrieve. |
| limit | integer Default: 100 The number of validators to return per page (max 1000). |
{- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "total_count": 10000,
- "page": 0,
- "limit": 100,
- "distributed_validators": [
- { }
]
}Returns locked revisions that share the same definition UUID and fork_version as the given lock, ordered by definition Mongo _id (insertion order). Diffs between revisions are not included; clients should compute them from lock details if needed.
| lockHash required | string The |
{- "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
- "current_lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "latest_lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "revisions": [
- {
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "name": "My Obol Cluster",
- "definition_timestamp": "2022-07-19T18:19:58+02:00",
- "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7"
}
]
}This endpoint is used to search for Cluster Lock Objects that match a substring of their lock_hash.
| network required | string Examples:
The network to retrieve clusters on |
| partialLockHash required | string A substring of the |
| 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. |
{- "cluster_locks": [
- "string"
], - "total_active_stake_eth": 128.5,
- "total_active_stake_usd": 128.5,
- "unique_validators_count": 10,
- "total_count": 2,
- "total_pages": 4
}This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it. Several cluster locks can share a config_hash (for example when the DKG is run again with the same configuration); this endpoint returns the most recently created one, so the answer only changes when another lock is posted for the config_hash. Its is_current / superseded_by fields say whether it is the lock Obol monitoring sees running (an older lock whose Charon nodes report more recently can be current instead). Use GET /lock/{lockHash} to retrieve a specific lock. Responses may be cached for a short time.
| configHash required | string The |
{- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- { }
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "string"
], - "definition_stored": true,
- "is_current": true,
- "superseded_by": null
}This endpoint is used to redirect users to the created cluster status page after DKG is completed.
| lockHash required | string The |
{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}Returns cluster network performance percentile vs sampled baseline (30d cluster avg) from ClickHouse cluster_effectiveness_percentiles. Metrics are null when no snapshot exists.
| lockHash required | string The |
{- "lock_hash": "0xabcdef1234567890abcdef1234567890abcdef12",
- "avg_effectiveness": 0.985,
- "effectiveness_percentile": 72.5,
- "active_validators_count": 4,
- "date": "2026-08-01"
}Returns average peer_score (and nicknames) for operators in a cluster, sorted by peer_score descending.
| lockHash required | string The |
| 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. |
[- {
- "operator_address": "0x7a82E643B0c8AE619f71d9667559180c33c92277",
- "avg_peer_score": 99.89,
- "peer_name": "puzzled-pen",
- "peer_nickname": "Alice node",
- "last_updated": "2026-02-10T00:00:00.000Z"
}
]Returns current-state peer rows from Mongo peer_info keyed by lock_hash (identity fields by default). Does not require the lock to exist in clusterlocks; returns an empty array when no peer_info rows match. Client-only stubs with null lock_hash are included when their cluster_hash matches the lock hash prefix. Pass client-details=true to include BN/VC/EL/Charon versions. Optional filters: node-index, operator-address. Note: until the data-pipelines peer_key/stub merge fix is deployed, the same Charon peer name may appear twice (a thin client stub with null node_index and a full identity row).
| lockHash required | string Lock hash used to look up peer_info rows (and stub cluster_hash prefix). |
| client-details | string Example: client-details=true When true, include nested client_details (beacon, validator, execution, charon). |
| node-index | string Example: node-index=0 Filter to a single peer by node index (integer or numeric string). |
| operator-address | string Example: operator-address=0x7a82E643B0c8AE619f71d9667559180c33c92277 Filter to a single peer by operator address (any EIP-55 casing). |
[- {
- "peer": "affectionate-fish",
- "peer_nickname": "DSRV",
- "node_index": 0,
- "operator_address": "0x7a82E643B0c8AE619f71d9667559180c33c92277",
- "peer_info_last_updated_at": "2026-08-03",
- "last_checked_at": "2019-08-24T14:15:22Z",
- "client_details": {
- "beacon_client": "string",
- "beacon_client_last_updated_at": "2019-08-24T14:15:22Z",
- "validator_client": "string",
- "validator_client_last_updated_at": "2019-08-24T14:15:22Z",
- "execution_client": "string",
- "execution_client_last_updated_at": "2019-08-24T14:15:22Z",
- "charon_version": "string",
- "charon_version_last_updated_at": "2019-08-24T14:15:22Z"
}
}
]This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.
| address required | string The operator address. |
| page required | integer Default: 0 The page number to retrieve. |
| limit required | integer Default: 100 The number of cluster lock objects to return. |
{- "cluster_locks": [
- {
- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- { }
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "string"
], - "definition_stored": true,
- "is_current": true,
- "superseded_by": null,
- "validator_status_counts": {
- "active": 3,
- "exiting": 0,
- "exited": 1,
- "pending": 1,
- "not_deposited": 0,
- "total": 5,
- "active_balance_eth": "96.012345678"
}
}
], - "total_active_stake_eth": 128.5,
- "total_active_stake_usd": 128.5,
- "unique_validators_count": 10,
- "total_count": 2,
- "total_pages": 4
}This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.
| address required | string The operator address. |
| page required | integer Default: 0 The page number to retrieve. |
| limit required | integer Default: 100 The number of cluster lock objects to return. |
{- "cluster_locks": [
- {
- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- { }
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "string"
], - "definition_stored": true,
- "is_current": true,
- "superseded_by": null,
- "validator_status_counts": {
- "active": 3,
- "exiting": 0,
- "exited": 1,
- "pending": 1,
- "not_deposited": 0,
- "total": 5,
- "active_balance_eth": "96.012345678"
}
}
], - "total_active_stake_eth": 128.5,
- "total_active_stake_usd": 128.5,
- "unique_validators_count": 10,
- "total_count": 2,
- "total_pages": 4
}This endpoint fetches a number of cluster lock objects for a given network.
| network required | string Examples:
The network to retrieve clusters on |
| 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. |
{- "cluster_locks": [
- "string"
], - "total_active_stake_eth": 128.5,
- "total_active_stake_usd": 128.5,
- "unique_validators_count": 10,
- "total_count": 2,
- "total_pages": 4
}This endpoint fetches a nsummary of the lock files stored for a given network
| network required | string Examples:
The network to retrieve clusters on |
{- "eth_staked": 2,
- "total_clusters": 2,
- "total_operators": 4
}This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster. The lock is stored with its own cluster_definition (the one covered by lock_hash), which is what lock reads return. If the lock_hash is already stored with its definition, the existing lock is returned (idempotent; no re-validation) with the same 201 response. If it is stored without one (saved by an earlier API version, definition_stored: false), the posted file is validated and its definition stored. The posted cluster_definition.config_hash must be the hash of the posted definition, and when a definition record exists for it the lock must have the same operator and creator addresses and configuration (400 otherwise). Several locks can share a config_hash (the DKG run again, or the same validator keys re-split to other nodes): each is stored. For definitions whose operators do not sign their ENRs (solo flow, charon create cluster), a further lock must re-split the validator keys of a stored lock (409 otherwise). GET /lock/configHash/{configHash} returns the most recently created of them. The current lock for a config_hash and its validators (is_current, superseded_by, positions and counts) is the one whose Charon nodes reported most recently, else the most recently created. The cluster definition record (GET /definition/{configHash}) is never changed by this endpoint.
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]+$ ] |
{- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- {
- "distributed_public_key": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "public_shares": [
- "string"
], - "deposit_data": {
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "withdrawal_credentials": "0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec",
- "amount": "32000000000",
- "deposit_data_root": "5e58a5d8f1e53479343cb6188f061f6b1a46c521c53eef0580b04f485ad62bad",
- "signature": "0x88fe84889608a8b2424bddae2047d2ee4b42f72c4d8201d69e732d7c3bfa1bcb00f930979770b7d00071673fde8f205108dabe8d83ec49aa6de1b7869966b555be80a159e6ad11e273c4e0234038cfa525923044d6a89a4924fdc178f333568b"
}, - "builder_registration": {
- "message": {
- "fee_recipient": "0x86B8145c98e5BD25BA722645b15eD65f024a87EC",
- "gas_limit": 30000000,
- "timestamp": 1616508000,
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6"
}, - "signature": "0x851e4f196b7e7bda6429b94cceb92d480f53fa9753e1d6c830ff2706acb8cd866d81d5533db7dcfac1dc9d00a16e5e4801d33f36bdf1c2a2003e1c586466109e7851c79179b2c46d69c53c4a59e361d2727186a7e72bbd11debad1f2fae6f97d"
}, - "partial_deposit_data": {
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "withdrawal_credentials": "0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec",
- "amount": "32000000000",
- "deposit_data_root": "5e58a5d8f1e53479343cb6188f061f6b1a46c521c53eef0580b04f485ad62bad",
- "signature": "0x88fe84889608a8b2424bddae2047d2ee4b42f72c4d8201d69e732d7c3bfa1bcb00f930979770b7d00071673fde8f205108dabe8d83ec49aa6de1b7869966b555be80a159e6ad11e273c4e0234038cfa525923044d6a89a4924fdc178f333568b"
}
}
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "0xe6e531be7bbf6cee37d80ab489ade6491469e10743d3c1496a3e66fe989eb4c100c260eaee4ef1aa08fdb79ea05bb8c12970dec1a296abe627ac25a2515373b301"
]
}{- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- { }
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "string"
], - "definition_stored": true,
- "is_current": true,
- "superseded_by": null
}This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.
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]+$ ] |
{- "cluster_definition": {
- "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": [
- "8000000000",
- "16000000000",
- "8000000000"
], - "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
- "fee_recipient_address": "0x000000000000000000000000000000000000dead",
- "withdrawal_address": "0x000000000000000000000000000000000000dead",
- "operators": [
- { }
], - "consensus_protocol": "qbft",
- "target_gas_limit": 36000000,
- "compounding": true
}, - "distributed_validators": [
- {
- "distributed_public_key": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "public_shares": [
- "string"
], - "deposit_data": {
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "withdrawal_credentials": "0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec",
- "amount": "32000000000",
- "deposit_data_root": "5e58a5d8f1e53479343cb6188f061f6b1a46c521c53eef0580b04f485ad62bad",
- "signature": "0x88fe84889608a8b2424bddae2047d2ee4b42f72c4d8201d69e732d7c3bfa1bcb00f930979770b7d00071673fde8f205108dabe8d83ec49aa6de1b7869966b555be80a159e6ad11e273c4e0234038cfa525923044d6a89a4924fdc178f333568b"
}, - "builder_registration": {
- "message": {
- "fee_recipient": "0x86B8145c98e5BD25BA722645b15eD65f024a87EC",
- "gas_limit": 30000000,
- "timestamp": 1616508000,
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6"
}, - "signature": "0x851e4f196b7e7bda6429b94cceb92d480f53fa9753e1d6c830ff2706acb8cd866d81d5533db7dcfac1dc9d00a16e5e4801d33f36bdf1c2a2003e1c586466109e7851c79179b2c46d69c53c4a59e361d2727186a7e72bbd11debad1f2fae6f97d"
}, - "partial_deposit_data": {
- "pubkey": "0xb51336c31c4f0cc365d6c7b5d8ff1b4b7d4cf7c70163f9fd51a2badc854f5e29823fa11e3d7749d207807867149508d6",
- "withdrawal_credentials": "0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec",
- "amount": "32000000000",
- "deposit_data_root": "5e58a5d8f1e53479343cb6188f061f6b1a46c521c53eef0580b04f485ad62bad",
- "signature": "0x88fe84889608a8b2424bddae2047d2ee4b42f72c4d8201d69e732d7c3bfa1bcb00f930979770b7d00071673fde8f205108dabe8d83ec49aa6de1b7869966b555be80a159e6ad11e273c4e0234038cfa525923044d6a89a4924fdc178f333568b"
}
}
], - "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
- "node_signatures": [
- "0xe6e531be7bbf6cee37d80ab489ade6491469e10743d3c1496a3e66fe989eb4c100c260eaee4ef1aa08fdb79ea05bb8c12970dec1a296abe627ac25a2515373b301"
]
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}This endpoint is used to retrieve the states of all validators in a DV Cluster
| lockHash required | string The |
{- "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,
- "credentials_conflict": false,
- "0x000000000000000000000000000000": {
- "index": "0",
- "status": "active_ongoing",
- "balance": "32"
}
}It shows data of operators who have signed and the count of validators ready to exit
| lockHash required | string The cluster lock hash. |
{- "operator_exits": {
- "0x000000000000000000000000000000000000dea1": 5,
- "0x000000000000000000000000000000000000dead": 10
}, - "ready_exits": 2
}It shows data of operators who have signed and who have not
| lockHash required | string The cluster lockHash. |
| page | number |
| limit | number |
| operatorAddress required | string The operatorAddress. |
| validatorPubkey required | string The |
{ }This endpoint is used to retrieve validator exit message
| lockHash required | string The cluster lockHash. |
| validatorPubkey required | string A |
| shareIdx required | any Represents the cluster operatorIndex+1. |
{ }This endpoint saves partial signed exit messages. Every partial_exits[].public_key must be a distributed_public_key of the lock (matched case-insensitively). epoch and validator_index are uint64 decimal strings.
The API keeps exactly one exit per validator pubkey: the first accepted partial exit fixes its epoch and validator_index, and later partial exits for that pubkey from any operator must use the same values or are rejected with 400. To change the epoch, every operator must first delete their partial exit. A pubkey whose exit is stored under a different lock hash is rejected with 409.
| lockHash required | string The |
required | Array of objects (ExitBlobDto) non-empty |
| share_idx required | number >= 1 |
| signature required | string^0x[0-9a-fA-F]{130}$ |
{- "partial_exits": [
- {
- "public_key": "0x8b69c67720c909423d7edc5d3a7554e1d1e50f6d7d5f8d18548d68daf424e536afba8b31fbd15df1970ba4af4a7d944c",
- "signed_exit_message": {
- "message": {
- "epoch": "162304",
- "validator_index": "42"
}, - "signature": "0xa8f503b58ad5e41153a6b125078adc4d0d448c0ce1878a910aaebd52f3458cb01b3f64bda575c76a59ca057c42be30ad163f5e6cbe32b4fbfd2e127d9f6663a16fe90e97f1429fa6c98eaf77470c0d025fbc843becc5343b822a33ea1f425b83"
}
}
], - "share_idx": 42,
- "signature": "0x9fd33d13a49d1103fd96dc7f7361cbc1f901d392b3c9a531b110daafe3def58f2699da5b28a6282da1c8fb87bfa8102b8e1bb0151c6ae1643857c80e355c7d4f01"
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}Saves user's signature to latest Obol's terms and conditions hash and it's version
| authorization required | string EIP712 terms and conditions hash as bearer token |
| 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" |
{- "address": "v1.0.0",
- "version": 1,
- "terms_and_conditions_hash": "",
- "fork_version": "0x00000000"
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}This endpoint is used to check whether the Terms and Conditions has been signed by the user.
| address required | string The address to check the Terms and Conditions. |
{- "isTermsAndConditionsSigned": true
}This endpoint is used to retrieve Base techne credential metadata
| index required | number The techne index. |
{- "description": "Obol Techne Bronze Credential",
- "name": "Obol Techne - Bronze"
}This endpoint is used to retrieve Bronze techne credential metadata
| index required | number The techne index. |
{- "description": "Obol Techne Bronze Credential",
- "name": "Obol Techne - Bronze"
}This endpoint is used to retrieve Silver techne credential metadata
| index required | number The techne index. |
{- "description": "Obol Techne Bronze Credential",
- "name": "Obol Techne - Bronze"
}This endpoint is used to retrieve Gold techne credential metadata
| index required | number The techne index. |
{- "description": "Obol Techne Bronze Credential",
- "name": "Obol Techne - Bronze"
}This endpoint is used to retrieve obol techne credentials an address owns
| address required | string The address to check the techne credentials for. |
{- "base": [
- "string"
], - "bronze": [
- "string"
], - "silver": [
- "string"
], - "gold": [
- "string"
]
}This endpoint is used to retrieve incentives an address owns
| network required | string Examples:
The network to retrieve operators on |
| address required | string The address to check the incentives for. |
{- "operator_address": "string",
- "amount": "string",
- "index": 0,
- "merkle_proof": [
- "string"
], - "contract_address": "string"
}This endpoint is used to retrieve the inventives given to Obol Public Goods by an address.
| network required | string Examples:
The network to retrieve operators on |
| address required | string The address to check the incentives for. |
| date | string <date-time> Example: date=2026-10-01 The UTC day to retrieve incentives for. Defaults to today. |
{- "operator_address": "string",
- "amount": "string",
- "index": 0,
- "merkle_proof": [
- "string"
], - "contract_address": "string"
}This endpoint fetches a number of operators for a given network.
| network required | string Examples:
The network to retrieve operators on |
| 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, e.g. | |
object badges to filter by, e.g. | |
| details required | string Default: "false" The flag to populate operators information. |
{- "operators": [
- "string"
], - "total_count": 2,
- "total_pages": 4
}This endpoint is used to search for operators that match a substring of their address.
| network required | string Examples:
The network to retrieve operators on |
| partialAddress required | string A substring of the |
| page required | integer Default: 0 The page number to retrieve. |
| limit required | integer Default: 100 The number of operators to return. |
{- "operators": [
- "string"
], - "total_count": 2,
- "total_pages": 4
}This endpoint is used to retrieve information on the tranches of an OWR.
| network required | string The network of the OWR. |
| address required | string The address of the OWR. |
{- "reward_recipient": "0xA",
- "principal_recipient": "0xA",
- "threshold": "32000000000000000000"
}It shows data of validators status
| network required | string Examples:
The network to retrieve clusters on |
| 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 |
{- "validators": [
- {
- "pubkey": "12345",
- "status": "fully_migrated",
- "effective_balance": "32000000000",
- "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048"
}
]
}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 data serialised as Go json.Marshal does (&, <, >, U+2028 and U+2029 escaped as \uXXXX; plain JSON.stringify(data) is also accepted) for the public key embedded in enr. Only Content-Type: application/json is required.
object Nested test categories ( | |
| 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 |
{- "data": {
- "charon_peers": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "beacon_node": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "validator_client": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "mev": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "infra": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}
}, - "enr": "enr:-IS4QAnExamplePlaceholderReplaceWithRealEnrFromCharon",
- "sig": "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghijklmnoPQRSTUVWxyZ"
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}This endpoint retrieves test results for a specific ENR.
| enr required | string ENR to search for |
[- {
- "data": {
- "charon_peers": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "beacon_node": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "validator_client": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "mev": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}, - "infra": {
- "category_name": "mev",
- "execution_time": "636.089125ms",
- "score": "A",
- "targets": { }
}
}, - "enr": "enr:-IS4QAnExamplePlaceholderReplaceWithRealEnrFromCharon",
- "sig": "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghijklmnoPQRSTUVWxyZ"
}
]This endpoint returns all partial deposit data grouped by amount for a specific validator
| lockHash required | string The cluster lock hash |
| pubkey required | string The validator public key (distributed_public_key) |
{- "lock_hash": "",
- "pubkey": "0xFULL_1",
- "withdrawal_credentials": "0xWITHDRAW_1",
- "amounts": [
- {
- "amount": "32000000000",
- "partials": [
- {
- "partial_public_key": "0xPARTIAL_A",
- "partial_deposit_signature": "0xSIG_A1"
}
]
}
]
}This endpoint saves partial deposit data signed by an operator
| lockHash required | string The lock hash of the cluster |
| share_index required | number The share index (operator index + 1) |
required | Array of objects (PartialDepositDataDto) non-empty | ||||||||
Array (non-empty)
| |||||||||
{- "partial_deposit_data": [
- {
- "pubkey": "0x8b69c67720c909423d7edc5d3a7554e1d1e50f6d7d5f8d18548d68daf424e536afba8b31fbd15df1970ba4af4a7d944c",
- "withdrawal_credentials": "0x010000000000000000000000abcdef1234567890abcdef1234567890abcdef12",
- "amount": "32000000000",
- "signature": "0x1234..."
}
]
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}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.
| lockHash required | string Example: 0x1234abcd... The cluster lock hash. |
| shareIdx required | number Example: 1 The operator share index (1-based). |
required | Array of objects (PartialRegistrationDto) non-empty | ||||
Array (non-empty)
| |||||
{- "partial_registrations": [
- {
- "message": {
- "fee_recipient": "string",
- "gas_limit": "string",
- "timestamp": "string",
- "pubkey": "string"
}, - "signature": "string"
}
]
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}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.
| lockHash required | string Example: 0x1234abcd... The cluster lock hash. |
| pubkeys | Array of strings Optional list of validator pubkeys to filter by. If omitted or empty, returns all validators with registrations. |
{- "pubkeys": [
- "0xdeadbeef...",
- "0xcafebabe..."
]
}{- "statusCode": 404,
- "message": "Cluster not found",
- "error": "Not Found"
}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.
| network required | string Example: mainnet Network name (e.g., mainnet, hoodi) |
| 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. |
{- "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
}Returns all DV clusters where the address (or any additional address) appears as withdrawal_address or fee_recipient. Also checks Lido protocol_fee_splitters.
| network required | string Network name (mainnet, hoodi, etc.) |
| address required | string The address to look up positions for (0x + 40 hex) |
| additionalAddresses | Array of strings <= 100 items Additional addresses to search (e.g. split addresses from getRelatedSplits, DeFi wrapper WA) |
{- "additionalAddresses": [
- "string"
]
}{- "positions": [
- {
- "lock_hash": "string",
- "cluster_name": "string",
- "num_validators_total": 0,
- "validators": [
- {
- "pubkey": "string",
- "withdrawal_address": "string",
- "fee_recipient_address": "string",
- "withdrawal_type": "eoa",
- "fee_recipient_type": "eoa",
- "withdrawal_resolved": {
- "principal_recipient": "string",
- "reward_recipient": "string",
- "threshold": "string",
- "split_recipients": [
- "string"
]
}, - "fee_recipient_resolved": {
- "principal_recipient": "string",
- "reward_recipient": "string",
- "threshold": "string",
- "split_recipients": [
- "string"
]
}
}
], - "total_balance_eth": 0,
- "avg_effectiveness": 0,
- "cluster_apr": 0
}
]
}What our beacon node's head state holds for each pubkey: the validator registry entry (status, balances, activation and exit epochs), every deposit in the pending deposit queue (EIP-6110), each with its own withdrawal credentials, and the total queued in the pending partial withdrawal queue (EIP-7002). Returns one entry per distinct requested pubkey, in request order, including pubkeys with status new. Accepts up to 1000 pubkeys per request (96 hex characters, 0x prefix optional, case-insensitive). Amounts are wei decimal strings. Queued deposit signatures are verified in the background, each queue entry once; a queue-only pubkey whose deposits are not all verified yet has signaturesPending: true (retry for the complete answer). Any upstream failure fails the whole request so a partial answer can never read as new. Entries are cached per pubkey for one slot.
| network required | string Examples:
The network to query validators on |
| pubkeys required | Array of strings non-empty Validator BLS pubkeys (96 hex chars, 0x prefix optional). Max 1000 per request. |
{- "pubkeys": [
- "0x8021d0a2e39c261e29b0aa47a56e21df8a3a11b6bce1bfa621d403c95d3fbe0da4bd1c2a3af0a1b6bd9e0c4a5c2f0e11"
]
}{- "validators": [
- {
- "pubkey": "0x8021d0a2e39c261e29b0aa47a56e21df8a3a11b6bce1bfa621d403c95d3fbe0da4bd1c2a3af0a1b6bd9e0c4a5c2f0e11",
- "status": "active",
- "beaconStatus": "active_ongoing",
- "index": "123456",
- "balance": "32000123456000000000",
- "effectiveBalance": "32000000000000000000",
- "activationEpoch": "12345",
- "exitEpoch": "67890",
- "pendingPartialWithdrawals": "0",
- "withdrawalCredentials": "0x010000000000000000000000abc0000000000000000000000000000000000000",
- "credentialsConflict": false,
- "signaturesPending": false,
- "pendingDeposits": [
- {
- "amount": "32000000000000000000",
- "withdrawalCredentials": "0x010000000000000000000000abc0000000000000000000000000000000000000",
- "signatureValid": true
}
]
}
]
}Provenance (CreateObolValidatorManager from the network OVM factory), state (one Multicall3 read), role holders (RolesUpdated candidates, rolesOf at the same block), the 0xSplits v2 params of its recipients (verified against splitHash) and the validators whose credentials point at it. Every chain read is made at blockNumber. Amounts are wei decimal strings; addresses checksummed. Validators come from the goteth registry snapshot in ClickHouse (daily), the beacon registry past it and the pending deposit queue, with current status from the head state. Roles, splits and validators are only read for a verified Obol OVM (provenance obol); for any other contract they are null and only provenance and state are returned. Sections that could not be read are null and explained in notes. An address without code is 200 with provenance notObol. Complete answers, and answers for notObol addresses, are cached for one slot; answers with a section that could not be read are not cached.
| network required | string Examples:
The network of the OVM |
| address required | string The OVM address |
{- "address": "0x8019384Ddf091154D6cfFA8E7f09542B39E2273f",
- "network": "hoodi",
- "blockNumber": 3854924,
- "provenance": {
- "status": "obol",
- "factoryAddress": "0x5754C8665B7e7BF15E83fCdF6d9636684B782b12",
- "creationTxHash": "0x176d60d40d1825d817941d59811a25c94b98c55a1c7763dccc9635ad6601c0a7",
- "creationBlock": 3807521,
- "reason": "CreateObolValidatorManager event found"
}, - "owner": "string",
- "principalRecipient": "string",
- "rewardRecipient": "string",
- "principalThreshold": "16000000000000000000",
- "amountOfPrincipalStake": "64000000000000000000",
- "fundsPendingWithdrawal": "0",
- "balance": "1250000000000000000",
- "version": "v1.0.0",
- "pullBalances": {
- "principalRecipient": "0",
- "rewardRecipient": "0"
}, - "roles": [
- {
- "address": "0x8a3bE1b1F4e2b6C5bC0dC5Bf1d1e6A1a8D1d5E2F",
- "roles": "33",
- "roleNames": [
- "WITHDRAWAL",
- "DEPOSIT"
], - "isOwner": false,
- "publicForwarder": false,
- "grantedAtBlock": 3807530,
- "grantedAtTimestamp": 1760000000
}
], - "splits": [
- {
- "address": "0x1c5F4E4e2f1D5ab6E1bB0A9c7A4B4D5e6F7a8B9C",
- "kind": "reward",
- "splitHash": "0x9f5a0c0d4c5ea9f4b1c0b1a7a1e2c3d4e5f60718293a4b5c6d7e8f9012345678",
- "recipients": [
- "0x1111111111111111111111111111111111111111"
], - "allocations": [
- "1000000"
], - "totalAllocation": "1000000",
- "distributionIncentive": 0,
- "source": "SplitCreated"
}
], - "validators": [
- {
- "pubkey": "0xabababababababababababababababababababababababababababababababababababababababababababababababab",
- "index": 123456,
- "status": "active",
- "beaconStatus": "active_ongoing",
- "balance": "32001234567000000000",
- "effectiveBalance": "32000000000000000000",
- "withdrawalCredentials": "0x0200000000000000000000008019384ddf091154d6cffa8e7f09542b39e2273f",
- "lockHash": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
- "clusterName": "My Obol Cluster"
}
], - "principalOnBeaconChain": null,
- "notes": [
- "principalOnBeaconChain is null: processed deposits are not indexed"
]
}