openapi: 3.0.0
info:
  title: Obol Address State API
  description: "## What is this API?\n\nThis API is for creating and managing [Distributed Validators](https://docs.obol.tech/docs/int/key-concepts#distributed-validator). This API works in tandem with Obol's [Distributed Validator Launchpad](https://hoodi.launchpad.obol.org), a dapp designed to allow people to authenticate their counterparties and agree to the terms of a Distributed Validator Cluster. This API will be made more easy for code-only interaction in the coming quarters with the release of the Obol-SDK. \n\nRead more about Obol and how to use the [launchpad](https://hoodi.launchpad.obol.org) on our [docs site](https://docs.obol.tech/). \n\nFor enquiries:"
  version: v1.0.0-local
  contact:
    name: Obol Labs
    url: https://obol.tech
    email: support@obol.tech
servers:
- url: https://api.obol.tech
  description: Production environment
- url: http://localhost:3000
  description: Local development server
- url: https://localhost:3000
  description: HTTPS Local development server
tags:
- name: State
paths:
  /v1/state/{lockHash}:
    get:
      description: This endpoint is used to retrieve the states of all validators in a DV Cluster
      operationId: StateController_getDistributedValidatorStatesByLockHash_v1
      parameters:
      - name: lockHash
        required: true
        in: path
        description: The `lock_hash` calculated for a cluster lock.
        schema:
          type: string
      responses:
        '200':
          description: A map of pubkeys to DVState
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/DistributedValidatorStateResponse'
                example:
                  '0x000000000000000000000000000000':
                    index: '0'
                    status: active_ongoing
                    balance: '32'
        '400':
          description: Bad request received
        '404':
          description: Lock Hash not found
        '500':
          description: An unknown error occurred
      summary: Retrieve the Validator states for a cluster
      tags:
      - State
components:
  schemas:
    DistributedValidatorStateResponse:
      type: object
      properties:
        index:
          type: string
          example: '12345'
        status:
          type: string
          example: active_ongoing
        balance:
          type: string
          example: '32'
        effective_balance:
          type: string
          example: '32'
        withdrawal_credentials:
          type: string
          example: '0x01000000000000000000000086b8145c98e5bd25ba722645b15ed65f024a87ec'
        pending_partial_withdrawals:
          type: string
          example: '3'
        pending_partial_deposits:
          type: string
          example: '3'
        is_not_within_committee:
          type: boolean
          example: true
          description: Indicates if validator has been active for at least 256 epochs and is not within the committee period
      required:
      - index
      - status
      - balance
      - effective_balance
      - withdrawal_credentials
      - pending_partial_withdrawals
      - pending_partial_deposits
      - is_not_within_committee
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http