openapi: 3.2.0
info:
  title: Bloq Staking API
  version: '2026-09-29'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-09-29: 25 operation(s) read from 6 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; Bloq has published no machine-readable contract that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 30
    documentation: -5
    pages-with-code: 6
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-09-29'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.bloq.com/bloq-services/bloqstake/authenticate-to-bloq-api/api-routes.md
  - https://docs.bloq.com/bloq-services/bloqstake/authenticate-to-bloq-api/authentication.md
  - https://docs.bloq.com/advanced-documentation/technical-reference/nodes-api.md
  - https://docs.bloq.com/advanced-documentation/technical-reference/accounts-api.md
  - https://docs.bloq.com/advanced-documentation/technical-reference/blockchain-node-api.md
  - https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
servers:
- url: https://api.bloq.com
security:
- bearer: []
tags:
- name: Staking
paths:
  /staking/ethereum/{chain}/validators:
    post:
      operationId: post_staking_ethereum_chain_validators
      tags:
      - Staking
      summary: Create a new Ethereum validator
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostStakingEthereumChainValidatorsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostStakingEthereumChainValidatorsResponse'
      x-evidence:
        kind: documentation
  /staking/ethereum/{chain}/validators/{pubkey}:
    delete:
      operationId: delete_staking_ethereum_chain_validators_pubkey
      tags:
      - Staking
      summary: Deletes a validator
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: pubkey
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_staking_ethereum_chain_validators_pubkey
      tags:
      - Staking
      summary: Returns one validator
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: pubkey
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStakingEthereumChainValidatorsPubkeyResponse'
      x-evidence:
        kind: documentation
    put:
      operationId: put_staking_ethereum_chain_validators_pubkey
      tags:
      - Staking
      summary: Updates the fee address of the validator
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: pubkey
        in: path
        required: true
        schema:
          type: string
      - name: feeAddress
        in: query
        required: true
        schema:
          type: string
        description: The new fee address.
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutStakingEthereumChainValidatorsPubkeyRequest'
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /staking/ethereum/{chain}/validators/{pubkey}/performance:
    get:
      operationId: get_staking_ethereum_chain_validators_pubkey_performance
      tags:
      - Staking
      summary: List performance metrics of the validator
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: pubkey
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      - name: includeServiceFee
        in: query
        required: false
        schema:
          type: boolean
        description: Whether to include the service fee or not to calculate the metrics.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStakingEthereumChainValidatorsPubkeyPerformanceResponse'
      x-evidence:
        kind: documentation
  /staking/ethereum/{chain}/validators/{pubkey}/validatorExit:
    post:
      operationId: post_staking_ethereum_chain_validators_pubkey_validatorExit
      tags:
      - Staking
      summary: Initiates the validator exit process to withdraw the staked balance of the…
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: pubkey
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      - name: confirmationDate
        in: query
        required: true
        schema:
          type: string
        description: The date the message was signed.
      - name: confirmationSignature
        in: query
        required: true
        schema:
          type: string
        description: The signature from the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostStakingEthereumChainValidatorsPubkeyValidatorexitRequest'
      responses:
        '204':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /staking/ethereum/{chain}/{id}:
    get:
      operationId: get_staking_ethereum_chain_id
      tags:
      - Staking
      summary: Return stats for a specific chain
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: The authentication token.
      - name: includeServiceFee
        in: query
        required: false
        schema:
          type: boolean
        description: Whether to include the service fee or not to calculate the metrics.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStakingEthereumChainIdResponse'
      x-evidence:
        kind: documentation
        collapsed_from: 2 example path(s) differing only at id
  /staking/ethereum/{ethereumid}:
    get:
      operationId: get_staking_ethereum_ethereumid
      tags:
      - Staking
      summary: GET /staking/ethereum/chains
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: ethereumid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStakingEthereumEthereumidResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X GET https://api.bloq.com/staking/ethereum/chains  -H ''Authorization: Bearer <auth-token>''

          ```'
        collapsed_from: 2 example path(s) differing only at ethereumId
  /staking/ethereum/{ethereumid}/report:
    get:
      operationId: get_staking_ethereum_ethereumid_report
      tags:
      - Staking
      summary: GET /staking/ethereum/billing/report
      x-source: https://docs.bloq.com/bloq-services/bloqstake/ethereum/api-routes.md
      parameters:
      - name: ethereumid
        in: path
        required: true
        schema:
          type: string
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
      - name: toDate
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X GET "https://api.bloq.com/staking/ethereum/billing/report?fromDate=0000-00-00&toDate=0000-00-00"  -H ''Authorization: Bearer <auth_token>''

          ```'
        collapsed_from: 2 example path(s) differing only at ethereumId
components:
  schemas:
    GetStakingEthereumChainValidatorsPubkeyResponse:
      type: object
      properties:
        (root):
          type: object
          description: The response.
        .balance:
          type: string
          description: The ETH balance, expressed in Wei. Returns `null` if there is a failure while retrieving the balance.
        .chain:
          type: string
          description: The validator chain.
        .depositData:
          type: object
          description: The deposit transaction data.
        .feeAddress:
          type: string
          description: The fee address of the validator.
        .id:
          type: string
          description: The validator's id.
        .pubkey:
          type: string
          description: The public address of the validator.
        .region:
          type: string
          description: The region where the validator was created.
        .startedAt:
          type: string
          description: The date the validator was created.
        .status:
          type: string
          description: 'The status: `active_online`, `pending` or `unknown` (when there is a failure getting the status).'
        .user:
          type: string
          description: The user id.
        .withdrawalAddress:
          type: string
          description: The withdrawal address of the validator.
    GetStakingEthereumChainValidatorsPubkeyPerformanceResponse:
      type: object
      properties:
        (root):
          type: object
          description: The response.
        .apr:
          type: number
          description: The APR of the validator, real or annualized if the validator is less than one year. Formatted in 2 decimals.
        .balance:
          type: string
          description: The ETH balance, expressed in Wei.
        .chain:
          type: string
          description: The validator chain.
        .consensusApr:
          type: number
          description: The APR of the validator, considering only consensus rewards.
        .effectiveBalance:
          type: string
          description: The APR of the validator, considering only execution rewards.
        .executionApr:
          type: number
          description: The APR of the validator, real or annualized if the validator is less than one year.
        .pubkey:
          type: string
          description: The public address of the validator.
    PostStakingEthereumChainValidatorsResponse:
      type: object
      properties:
        (root):
          type: object
          description: The validator data.
        .balance:
          type: string
          description: The ETH balance.
        .chain:
          type: string
          description: The validator chain.
        .depositData:
          type: object
          description: 'The deposit transaction data when using method #1.'
        .feeAddress:
          type: string
          description: The fee address of the validator.
        .pubkey:
          type: string
          description: The public address of the validator.
        .region:
          type: string
          description: The validator region.
        .status:
          type: string
          description: 'The status: deposited, pending, active, exited.'
        .withdrawalAddress:
          type: string
          description: The withdrawal address of the validator.
    PostStakingEthereumChainValidatorsPubkeyValidatorexitRequest:
      type: object
      properties:
        confirmationDate:
          type: string
          description: The date the message was signed.
        confirmationSignature:
          type: string
          description: The signature from the user.
      required:
      - confirmationDate
      - confirmationSignature
    PutStakingEthereumChainValidatorsPubkeyRequest:
      type: object
      properties:
        feeAddress:
          type: string
          description: The new fee address.
      required:
      - feeAddress
    GetStakingEthereumChainIdResponse:
      type: object
      properties:
        (root):
          type: object
          description: The response.
        .apr:
          type: string
          description: The APR of the chain. Formatted in 2 decimals
        .chain:
          type: number
          description: The chain.
        .consensusApr:
          type: number
          description: APR of the validator considering only consensus rewards. Formatted in 2 decimals
        .executionApr:
          type: number
          description: APR of the validator considering only execution rewards. Formatted in 2 decimals
    GetStakingEthereumEthereumidResponse:
      type: object
      properties:
        balance:
          type: string
        chain:
          type: string
        feeAddress:
          type: string
        id:
          type: string
        pubkey:
          type: string
        region:
          type: string
        startedAt:
          type: string
          format: date-time
        status:
          type: string
        user:
          type: string
    PostStakingEthereumChainValidatorsRequest:
      type: object
      properties:
        feeAddress:
          type: string
          description: The fee address of the validator.
        region:
          type: string
          description: The AWS region. Defaults to us-east-2.
        withdrawalAddress:
          type: string
          description: The withdrawal address of the validator.
      required:
      - withdrawalAddress
  securitySchemes:
    bearer:
      type: http
      scheme: bearer