Chainstack Ethereum Beacon Chain API

openapi: 3.0.3
info:
  title: Chainstack Ethereum Beacon Chain API
  version: 1.0.0
  description: Chainstack-managed RPC node API for the Ethereum Beacon Chain API blockchain. Endpoints follow the canonical
    JSON-RPC over HTTPS interface for the network. Authenticate against your Chainstack node's per-node URL (e.g. https://nd-XXX-XXX-XXX.p2pify.com/<key>).
    Merged from the Chainstack Developer Portal per-method fragments at https://github.com/chainstack/dev-portal/tree/main/openapi/ethereum_beacon_chain_api.
  contact:
    name: Chainstack API Support
    email: [email protected]
  license:
    name: Chainstack Terms
    url: https://chainstack.com/terms-of-service/
servers:
- url: https://{node_id}.p2pify.com/{api_key}
  description: Chainstack-managed node endpoint
  variables:
    node_id:
      default: nd-000-000-000
      description: Your Chainstack node identifier
    api_key:
      default: <api-key>
      description: Per-node access key
tags:
- name: Configuration Info
- name: Debug
- name: Events
- name: State
- name: Validatiors Info
paths:
  /deposit_contract:
    get:
      summary: Get the Ethereum deposit contract configuration
      operationId: getConfigDepositContract
      responses:
        '200':
          description: Deposit contract configuration successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositContractConfig'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Configuration Info
  /fork_schedule:
    get:
      summary: Get the Ethereum fork schedule
      operationId: getConfigForkSchedule
      responses:
        '200':
          description: Fork schedule successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkScheduleList'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Configuration Info
  /fork_version_by_state_id:
    get:
      summary: Get fork information for a specific state
      operationId: getForkInformation
      tags:
      - Configuration Info
      parameters:
      - name: state_id
        in: path
        required: true
        description: State identifier which can be a slot number, an epoch number, a block root, or special values like  'genesis'
          or 'head'.
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Successful response with fork information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkInformation'
        '400':
          description: Invalid state identifier value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /genesis_data:
    get:
      summary: Genesis
      operationId: getBeaconGenesis
      parameters:
      - name: apiKey
        in: path
        description: Your API key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Beacon genesis information successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Genesis'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Configuration Info
  /node_config:
    get:
      summary: Node configuration
      operationId: getConfigSpec
      responses:
        '200':
          description: Specification configuration successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecConfig'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Configuration Info
  /getDebugBeaconHeadsV2:
    get:
      summary: Get fork choice leaves
      operationId: getDebugBeaconHeadsV2
      description: Retrieves all possible chain heads (leaves of fork choice tree). This endpoint provides insight into the
        current fork choice state by returning all potential chain heads that the beacon node is tracking.
      tags:
      - Debug
      responses:
        '200':
          description: Success - Fork choice leaves retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDebugChainHeadsResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /getDebugBeaconStateV2:
    get:
      summary: Get full BeaconState object
      operationId: getDebugBeaconStateV2
      description: Returns full BeaconState object for given stateId. This is a comprehensive debug endpoint that provides
        the complete state of the beacon chain at a specific point, including all validator information, balances, and other
        state details. Depending on Accept header it can be returned either as JSON or as bytes serialized by SSZ.
      tags:
      - Debug
      parameters:
      - name: state_id
        in: path
        description: 'State identifier. Can be one of: ''head'' (canonical head in node''s view), ''genesis'', ''finalized'',
          ''justified'', <slot>, <hex encoded stateRoot with 0x prefix>.'
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Success - Full BeaconState object retrieved
          headers:
            Eth-Consensus-Version:
              description: The active consensus version to which the data belongs. Required in response so client can deserialize
                returned JSON or SSZ data more effectively.
              required: true
              schema:
                type: string
                enum:
                - phase0
                - altair
                - bellatrix
                - capella
                - deneb
                - electra
                example: deneb
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStateV2Response'
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: SSZ serialized BeaconState object
        '400':
          description: Invalid state ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: State not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /getDebugForkChoice:
    get:
      summary: Get fork choice array
      operationId: getDebugForkChoice
      description: Retrieves all current fork choice context including justified and finalized checkpoints, and the complete
        fork choice tree with all nodes and their weights.
      tags:
      - Debug
      responses:
        '200':
          description: Success - Fork choice data retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetForkChoiceResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /subscribe_to_events:
    get:
      summary: Subscribe to events
      operationId: subscribeToBeaconEvents
      parameters:
      - name: topics
        in: query
        description: Topics to subscribe to, e.g., 'head'
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Successfully subscribed to events
          content:
            text/event-stream:
              schema:
                type: string
                example: 'event: contribution_and_proof

                  data: {"contribution": "...", "proof": "..."}


                  '
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Events
  /getBeaconBlockRootByBlockId:
    get:
      summary: Get the root of the beacon block by block_id
      operationId: getBeaconBlockRootByBlockId
      parameters:
      - name: block_id
        in: path
        description: Block identifier, e.g., 'head', 'genesis', 'finalized', or a specific block root.
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Beacon block root successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconBlockRootItem'
        '404':
          description: Beacon block root not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getBeaconBlocksByBlockId:
    get:
      summary: Get beacon blocks by block_id
      operationId: getBeaconBlocksByBlockId
      parameters:
      - name: block_id
        in: path
        description: Block identifier, e.g., 'head', 'genesis', 'finalized', or a specific block root.
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Beacon block successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconBlockItem'
        '404':
          description: Beacon block not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getBeaconHeadersByBlockId:
    get:
      summary: Get beacon headers by block_id
      operationId: getBeaconHeadersByBlockId
      parameters:
      - name: block_id
        in: path
        description: Block identifier, e.g., 'head', 'genesis', 'finalized', or a specific block root.
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Beacon header successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconHeaderItem'
        '404':
          description: Beacon header not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getBeaconHeadersBySlotAndParentRoot:
    get:
      summary: Get beacon headers by slot and parent root
      operationId: getBeaconHeadersBySlotAndParentRoot
      parameters:
      - name: slot
        in: query
        description: Slot number
        required: false
        schema:
          type: integer
          format: int64
          default: 6215071
      - name: parent_root
        in: query
        description: Parent root hash
        required: false
        schema:
          type: string
          format: byte
      responses:
        '200':
          description: Beacon headers successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconHeaders'
        '404':
          description: Beacon headers not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getBlobsByBlockId:
    get:
      summary: Get blobs by block_id
      operationId: getBlobsByBlockId
      parameters:
      - name: block_id
        in: path
        description: Block identifier, e.g., 'head', 'genesis', 'finalized', or a specific slot number.
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Blobs successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobsResponse'
        '404':
          description: Block not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getCommitteesByStateIdEpochIndexAndSlot:
    get:
      summary: Get committees by state, epoch, index, and slot
      operationId: getCommitteesByStateIdEpochIndexAndSlot
      parameters:
      - name: state_id
        in: path
        description: State identifier, e.g., 'head', 'finalized', 'genesis', or a specific slot number.
        required: true
        schema:
          type: string
          default: head
      - name: epoch
        in: query
        description: Epoch number
        required: false
        schema:
          type: integer
          format: int64
          example: 194213
      - name: index
        in: query
        description: Committee index
        required: false
        schema:
          type: integer
          format: int64
          example: 1
      - name: slot
        in: query
        description: Slot number
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Committee data successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitteeData'
        '404':
          description: Committee data not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getFinalityCheckpoints:
    get:
      summary: Get finality checkpoints for a given state
      operationId: getFinalityCheckpoints
      tags:
      - State
      parameters:
      - name: state_id
        in: path
        required: true
        description: State identifier which can be a slot number, an epoch number, a block root, or 'genesis', 'head'  (default
          is 'head').
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Successful response with finality checkpoints information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinalityCheckpoints'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /getStateRoot:
    get:
      summary: Get the root of a given state
      operationId: getStateRoot
      tags:
      - State
      parameters:
      - name: state_id
        in: path
        required: true
        description: State identifier which can be a slot number, an epoch number, a block root, or 'genesis', 'head'  (default
          is 'head').
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Successful response with state root information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StateRoot'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /getSyncCommitteeContribution:
    get:
      summary: Get sync committee contribution for a given slot, subcommittee index, and beacon block root
      operationId: getSyncCommitteeContribution
      parameters:
      - name: slot
        in: query
        description: Slot for which to retrieve the sync committee contribution
        required: true
        schema:
          type: integer
          format: int64
          default: 6244671
      - name: subcommittee_index
        in: query
        description: Subcommittee index for which to retrieve the sync committee contribution
        required: true
        schema:
          type: integer
          format: int64
          default: 1
      - name: beacon_block_root
        in: query
        description: Beacon block root for which to retrieve the sync committee contribution
        required: true
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          default: '0x19708d7b686e2654656690f3262ff3686b810966839117ae8affd0e757b17544'
      responses:
        '200':
          description: Sync committee contribution successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncCommitteeContribution'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /getSyncCommitteesByStateIdAndEpoch:
    get:
      summary: Get sync committees by state and epoch
      operationId: getSyncCommitteesByStateIdAndEpoch
      parameters:
      - name: state_id
        in: path
        description: State identifier, e.g., 'head', 'finalized', 'genesis', or a specific slot number.
        required: true
        schema:
          type: string
          default: head
      - name: epoch
        in: query
        description: Epoch number
        required: false
        schema:
          type: integer
          format: int64
          example: 194213
      responses:
        '200':
          description: Sync committee data successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncCommitteeData'
        '404':
          description: Sync committee data not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - State
  /attestation_data:
    get:
      summary: Get attestation data
      operationId: getAttestationData
      parameters:
      - name: slot
        in: query
        description: Slot for which to retrieve attestation data
        required: true
        schema:
          type: integer
          format: int64
          default: 6244411
      - name: committee_index
        in: query
        description: Committee index for which to retrieve attestation data
        required: true
        schema:
          type: integer
          format: int64
          default: 5
      responses:
        '200':
          description: Attestation data successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestationData'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /attestation_of_beacon_block_by_block_id:
    get:
      summary: Get attestations of the beacon block by block_id
      operationId: getBeaconBlockAttestationsByBlockId
      parameters:
      - name: block_id
        in: path
        description: Block identifier, e.g., 'head', 'genesis', 'finalized', or a specific block root.
        required: true
        schema:
          type: string
          default: head
      responses:
        '200':
          description: Beacon block attestations successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconBlockAttestationsList'
        '404':
          description: Beacon block attestations not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /attester_slashings:
    get:
      summary: Get attester slashings
      operationId: getBeaconPoolAttesterSlashings
      responses:
        '200':
          description: Beacon pool attester slashings successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconPoolAttesterSlashingsList'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /beacon_pool_attestations:
    get:
      summary: Get attestations from the beacon pool
      operationId: getBeaconPoolAttestationsBySlotAndCommitteeIndex
      parameters:
      - name: slot
        in: query
        description: The slot number to filter attestations
        required: false
        schema:
          type: integer
          format: int64
          default: 6243475
      - name: committee_index
        in: query
        description: The committee index to filter attestations
        required: false
        schema:
          type: integer
          format: int64
          default: 10
      responses:
        '200':
          description: Beacon pool attestations successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconPoolAttestationsList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /produce_unsigned_blinded_block:
    get:
      summary: Produce an unsigned blinded block
      operationId: produceBlindedBlock
      parameters:
      - name: slot
        in: path
        description: Slot for which to produce a new blinded block
        required: true
        schema:
          type: integer
          format: int64
          default: 6244411
      - name: randao_reveal
        in: query
        description: RANDAO reveal for the block
        required: true
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          default: '0x8363f30516d67556dae486c64535e2641293e794ddf21631fe06a32903648e70b606f5461c5f37c13c23f545c1d13e5401ea6a48526e01c9d94ea028e02fec5edc42034fc22b23f3a9dd90621173b2a1141a6ecf409d8bb61c82440e87a5bb25'
      - name: graffiti
        in: query
        description: Graffiti for the block
        required: false
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          example: '0x5374616b65576973650000000000000000000000000000000000000000000000'
      responses:
        '200':
          description: Successfully produced a new blinded block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /produce_unsigned_block:
    get:
      summary: Produce a new block for the given slot
      operationId: produceBlock
      parameters:
      - name: slot
        in: path
        description: Slot for which to produce a new block
        required: true
        schema:
          type: integer
          format: int64
          default: 6244478
      - name: randao_reveal
        in: query
        description: RANDAO reveal for the block
        required: true
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          default: '0xb73a92a633356ed71c3ff8c6a687d6a7b9a10db930f92f3b41a18e2dfc0c41535c522006ae3db8b1cb6fe7b3a93962f413c127de4eba22cb0b2d0065dc120156012e53038c3e29477342f9fac2b4368c054aa0d18c246c1463da03161f902f8e'
      - name: graffiti
        in: query
        description: Graffiti for the block
        required: false
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]+$
          example: '0x4c69676874686f7573652f76342e302e322d72632e302d333564386339380000'
      responses:
        '200':
          description: Successfully produced a new block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /proposer_duties:
    get:
      summary: Get proposer duties
      operationId: getProposerDuties
      parameters:
      - name: epoch
        in: path
        description: Epoch for which to get the proposer duties
        required: true
        schema:
          type: integer
          format: int64
          default: 1
      responses:
        '200':
          description: Successfully retrieved proposer duties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposerDuties'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /proposer_slashings:
    get:
      summary: Get proposer slashings from the beacon pool
      operationId: getBeaconPoolProposerSlashings
      responses:
        '200':
          description: Beacon pool proposer slashings successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeaconPoolProposerSlashingsList'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /validator_balances:
    get:
      summary: Get validator balances by state and ID
      operationId: getValidatorBalancesByStateIdAndValidatorId
      parameters:
      - name: state_id
        in: path
        description: State identifier, e.g., 'head', 'finalized', 'genesis', or a specific slot number.
        required: true
        schema:
          type: string
          default: head
      - name: id
        in: query
        description: Validator ID
        required: true
        schema:
          type: string
          default: 1
      responses:
        '200':
          description: Validator balances successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatorBalances'
        '404':
          description: Validator balances not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Validatiors Info
  /validator_information_by_state_id:
    get:
      summary: Get information about a specific validator in a given state
      operationId: getValidatorInformation
      tags:
      - Validatiors Info
      parameters:
      - name: state_id
        in: path
        required: true
        description: State identifier which can be a slot number, an epoch number, a block root, or 'genesis', 'head'  (default
          is 'head').
        schema:
          type: string
          default: head
      - name: validator_index
        in: path
        required: true
        description: Index of the validator (default is '1').
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Successful response with validator information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatorInformation'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /validator_information_by_state_id_or_public_key:
    get:
      summary: Get validator by state and ID
      operationId: getValidatorByStateIdAndIndex
      parameters:
      - name: state_id
        in: path
        description: State identifier, e.g., 'head', 'finalized', 'genesis', or a specific slot number.
        required: true
        schema:
          type: string
          default: head
      - name: index
        in: path
        description: Validator index
        required: true
        schema:
          type: integer
          format: int64
          default: 1
      responses:
        '200':
          description: Validator successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validator'
        '404':
          description: Validator not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chainstack/refs/heads/main/openapi/chainstack-ethereum-beacon-chain-api-openapi.yml