For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

Gnosis Beacon — Config, Debug, Events, Node, Validator (1/3)

API reference for Gnosis Beacon. All methods ->

Part 1 of 3: 1 · 2 · 3

Config​

GET /eth/v1/config/fork_schedule​

Retrieves scheduled upcoming forks.

Retrieve all forks, past present and future, of which this node is aware.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/config/fork_schedule" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": [
    {
      "previous_version": "0x00000000",
      "current_version": "0x00000000",
      "epoch": "1"
    }
  ]
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/config/spec​

Retrieves spec parameters.

Retrieve specification configuration used on this node. The configuration should include:

  • Constants for all hard forks known by the beacon node, for example the phase 0 and altair values.
  • Presets for all hard forks supplied to the beacon node, for example the phase 0 and altair values.
  • Configuration for the beacon node, for example the mainnet values.

Values are returned with the following format:

  • Any value starting with 0x in the spec is returned as a hex string.
  • Numeric values are returned as a quoted integer.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/config/spec" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "DEPOSIT_CONTRACT_ADDRESS": "0x00000000219ab540356cBB839Cbe05303d7705Fa",
  "DEPOSIT_NETWORK_ID": "1",
  "DOMAIN_AGGREGATE_AND_PROOF": "0x06000000",
  "INACTIVITY_PENALTY_QUOTIENT": "67108864",
  "INACTIVITY_PENALTY_QUOTIENT_ALTAIR": "50331648"
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/config/deposit_contract​

Retrieves a deposit contract address.

Retrieve Eth1 deposit contract address and chain ID.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/config/deposit_contract" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": {
    "chain_id": "1",
    "address": "0x1Db3439a222C519ab44bb1144fC28167b4Fa6EE6"
  }
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

Debug​

GET /eth/v2/debug/beacon/states/{state_id}​

Retrieves the full BeaconState object.

Returns full BeaconState object for given stateId. Depending on Accept header it can be returned either as json or as bytes serialized by SSZ.

Parameters​

  • state_id (string; path; required): state identifier. Can be one of: head (canonical head in node's view), genesis, finalized, justified, <slot>, <hex encoded stateRoot with 0x prefix>.
    Example: head.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v2/debug/beacon/states/{state_id}" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.

Note: The Eth-Consensus-Version header is required in response so client can deserialize returned json or ssz data more effectively.

{
  "version": "phase0",
  "execution_optimistic": false,
  "data": {
    "genesis_time": "1",
    "genesis_validators_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "slot": "1",
    "fork": {
      "previous_version": "0x00000000",
      "current_version": "0x00000000",
      "epoch": "1"
    },
    "latest_block_header": {
      "slot": "1",
      "proposer_index": "1",
      "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "body_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
    },
    "block_roots": [],
    "slashings": [],
    "previous_epoch_attestations": [
      {
        "aggregation_bits": "0x2ccfbd524ECbedfc70c91BE08b5668fA4ebdfD773B1fFe1daAbfC912c3cD4b2C93E1",
        "data": {
          "slot": "1",
          "index": "1",
          "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
          "source": {
            "epoch": "1",
            "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
          },
          "target": {
            "epoch": "1",
            "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
          }
        },
        "inclusion_delay": "1",
        "proposer_index": "1"
      }
    ],
    "current_epoch_attestations": [
      {
        "aggregation_bits": "0xF9DD8ABe17ae0baDA640Bb0d8c4e81a349D3a",
        "data": {
          "slot": "1",
          "index": "1",
          "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
          "source": {
            "epoch": "1",
            "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
          },
          "target": {
            "epoch": "1",
            "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
          }
        },
        "inclusion_delay": "1",
        "proposer_index": "1"
      }
    ],
    "justification_bits": "0x01",
    "previous_justified_checkpoint": {
      "epoch": "1",
      "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
    },
    "current_justified_checkpoint": {
      "epoch": "1",
      "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
    },
    "finalized_checkpoint": {
      "epoch": "1",
      "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
    }
  }
}
  • Code 400: Invalid state ID.
{
  "code": 400,
  "message": "Invalid state ID: current"
}
  • Code 404: State not found.
{
  "code": 404,
  "message": "State not found"
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v2/debug/beacon/heads​

Retrieves fork choice leaves.

Retrieves all possible chain heads (leaves of fork choice tree).

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v2/debug/beacon/heads" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": [
    {
      "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "slot": "1",
      "execution_optimistic": false
    }
  ]
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

Events​

GET /eth/v1/events​

Subscribes to Beacon node events.

Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use eventsource implementation to listen on those events.

Servers may send SSE comments beginning with : for any purpose, including to keep the event stream connection alive in the presence of proxy servers.

Parameters​

  • topics (array[string]; query; required): event types to subscribe to; available values : head, block, attestation, voluntary_exit, finalized_checkpoint, chain_reorg, contribution_and_proof.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/events" \
-H "Accept: text/event-stream"

Responses​

  • Code 200: Opened SSE stream.

Head event:

The node has finished processing, resulting in a new head. previous_duty_dependent_root is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) and current_duty_dependent_root is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1). Both dependent roots use the genesis block root in the case of underflow.

event: head
data: {"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch_transition":false, "previous_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "current_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "execution_optimistic": false}

Block event:

The node has received a valid block (from P2P or API).

event: block
data: {"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "execution_optimistic": false}

Attestation event:

The node has received a valid attestation (from P2P or API).

event: attestation
data: {"aggregation_bits":"0x01", "signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505", "data":{"slot":"1", "index":"1", "beacon_block_root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "source":{"epoch":"1", "root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "target":{"epoch":"1", "root":"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}}}

Voluntary exit event:

The node has received a valid voluntary exit (from P2P or API).

event: voluntary_exit
data: {"message":{"epoch":"1", "validator_index":"1"}, "signature":"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}

Finalized checkpoint event:

Finalized checkpoint has been updated.

event: finalized_checkpoint
data: {"block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch":"2", "execution_optimistic": false }

Chain reorg event:

The node has reorganized its chain.

event: chain_reorg
data: {"slot":"200", "depth":"50", "old_head_block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "new_head_block":"0x76262e91970d375a19bfe8a867288d7b9cde43c8635f598d93d39d041706fc76", "old_head_state":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "new_head_state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch":"2", "execution_optimistic": false}

Contribution and proof event:

The node has received a valid sync committee SignedContributionAndProof (from P2P or API).

event: contribution_and_proof
data: {"message": {"aggregator_index": "997", "contribution": {"slot": "168097", "beacon_block_root": "0x56f1fd4262c08fa81e27621c370e187e621a67fc80fe42340b07519f84b42ea1", "subcommittee_index": "0", "aggregation_bits": "0xffffffffffffffffffffffffffffffff", "signature": "0x85ab9018e14963026476fdf784cc674da144b3dbdb47516185438768774f077d882087b90ad642469902e782a8b43eed0cfc1b862aa9a473b54c98d860424a702297b4b648f3f30bdaae8a8b7627d10d04cb96a2cc8376af3e54a9aa0c8145e3"}, "selection_proof": "0x87c305f04bfe5db27c2b19fc23e00d7ac496ec7d3e759cbfdd1035cb8cf6caaa17a36a95a08ba78c282725e7b66a76820ca4eb333822bd399ceeb9807a0f2926c67ce67cfe06a0b0006838203b493505a8457eb79913ce1a3bcd1cc8e4ef30ed"}, "signature": "0xac118511474a94f857300b315c50585c32a713e4452e26a6bb98cdb619936370f126ed3b6bb64469259ee92e69791d9e12d324ce6fd90081680ce72f39d85d50b0ff977260a8667465e613362c6d6e6e745e1f9323ec1d6f16041c4e358839ac"}

Node​

GET /eth/v1/node/peers​

Retrieves node network peers.

Retrieves data about the node's network peers. By default, this returns all peers. Multiple query params are combined using AND conditions.

Parameters​

  • state (array[string]; query): available values : disconnected, connecting, connected, disconnecting.
  • direction (array[string]; query): available values : inbound, outbound.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/peers" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": [
    {
      "peer_id": "QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N",
      "enr": "enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8",
      "last_seen_p2p_address": "/ip4/7.7.7.7/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N",
      "state": "disconnected",
      "direction": "inbound"
    }
  ],
  "meta": {
    "count": 1
  }
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/node/peers/{peer_id}​

Retrieves a peer.

Retrieves data about the given peer.

Parameters​

  • peer_id (string; path; required): a peer ID; example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/peers/{peer_id}" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": {
    "peer_id": "QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N",
    "enr": "enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8",
    "last_seen_p2p_address": "/ip4/7.7.7.7/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N",
    "state": "disconnected",
    "direction": "inbound"
  }
}
  • Code 400: The peer ID supplied could not be parsed.
{
  "code": 400,
  "message": "Invalid peer ID: localhost"
}
  • Code 404: Peer not found.
{
  "code": 404,
  "message": "Peer not found"
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/node/peer_count​

Retrieves peer count.

Retrieves number of known peers.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/peer_count" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": {
    "disconnected": "12",
    "connecting": "34",
    "connected": "56",
    "disconnecting": "5"
  }
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/node/version​

Retrieves a version string of the running Beacon node.

Requests that the beacon node identify information about its implementation in a format similar to an HTTP User-Agent field.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/version" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": {
    "version": "Lighthouse/v0.1.5 (Linux x86_64)"
  }
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/node/syncing​

Retrieves a node syncing status.

Requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/syncing" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "data": {
    "head_slot": "1",
    "sync_distance": "1",
    "is_syncing": true,
    "is_optimistic": true
  }
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}

GET /eth/v1/node/health​

Retrieves health check.

Returns node health status in http status codes. Useful for load balancers.

Parameters​

None.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/node/health"

Responses​

  • Code 200: Node is ready.
  • Code 206: Node is syncing but can serve incomplete data.
  • Code 503: Node not initialized or having issues.

Validator​

POST /eth/v1/validator/duties/attester/{epoch}​

Retrieves attester duties.

Requests the beacon node to provide a set of attestation duties, which should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.previous_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) + 1 == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) or the genesis block root in the case of underflow.

Parameters​

  • epoch (string; path; required): should only be allowed one epoch ahead.
  • <request body> (required): an array of the validator indices for which to obtain the duties:
[
  "1"
]

Request example​

curl -X POST "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/validator/duties/attester/{epoch}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{request body}'

Responses​

  • Code 200: Success.
{
  "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  "execution_optimistic": false,
  "data": [
    {
      "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
      "validator_index": "1",
      "committee_index": "1",
      "committee_length": "1",
      "committees_at_slot": "1",
      "validator_committee_index": "1",
      "slot": "1"
    }
  ]
}
  • Code 400: Invalid epoch or index.
{
  "code": 400,
  "message": "Invalid epoch: -2"
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}
  • Code 503: Beacon node is currently syncing, try again later.
{
  "code": 503,
  "message": "Beacon node is currently syncing and not serving request on that endpoint"
}

GET /eth/v1/validator/duties/proposer/{epoch}​

Retrieves block proposer duties.

Request beacon node to provide all validators that are scheduled to propose a block in the given epoch. Duties should only need to be checked once per epoch, however a chain reorganization could occur that results in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1) or the genesis block root in the case of underflow.

Parameters​

  • epoch (string; path; required); an epoch.

Request example​

curl -X GET "https://rpc.ankr.com/premium-http/gnosis_beacon/YOUR_ANKR_API_KEY/eth/v1/validator/duties/proposer/{epoch}" \
-H "Accept: application/json"

Responses​

  • Code 200: Success.
{
  "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  "execution_optimistic": false,
  "data": [
    {
      "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
      "validator_index": "1",
      "slot": "1"
    }
  ]
}
  • Code 400: Invalid epoch.
{
  "code": 400,
  "message": "Invalid epoch: -2"
}
  • Code 500: Beacon node internal error.
{
  "code": 500,
  "message": "Internal server error"
}
  • Code 503: Beacon node is currently syncing, try again later.
{
  "code": 503,
  "message": "Beacon node is currently syncing and not serving request on that endpoint"
}