BloqStakeBloqCloudGitHub

API Routes

Jump to:

DELETE /staking/ethereum/{chain}/validators/{pubkey}

Deletes a validator

Parameters

Name
In
Type
Required
Description

chain

path

string

yes

The validator's chain.

pubkey

path

string

yes

The validator's public key.

Authorization

header

string

yes

The authentication token.

Sample request

curl -X DELETE https://api.bloq.com/staking/ethereum/mainnet/validators/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

204

The validator was deleted.

403

The authorization token is invalid, or the user is not allowed to perform the delete.

404

The validator was not found.

409

The validator has balance or is staking.

Sample response

Successful response: HTTP 204 No content

GET /staking/ethereum/chains

Retrieves all the chains that are enabled for the protocol

Parameters

Name
In
Type
Required
Description

Authorization

header

string

yes

The authentication token.

curl -X GET https://api.bloq.com/staking/ethereum/chains \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The list was retrieved.

401

No authentication header found.

403

The authorization token is invalid.

Property
Type
Description

(root)

array

The response.

[]

string

The name of the chain.

Sample response

["mainnet"]

GET /staking/ethereum/regions

Retrieves all the regions where validators can be created by the user.

Parameters

Name
In
Type
Required
Description

Authorization

header

string

yes

The authentication token.

Sample request

curl -X GET https://api.bloq.com/staking/ethereum/regions \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The list was retrieved.

401

No authentication header found.

403

The authorization token is invalid.

Property
Type
Description

(root)

array

The response.

[]

string

The name of the region.

Sample response

["us-east-2"]

GET /staking/ethereum/{chain}/validators

List all user's Ethereum validators.

Parameters

Name
In
Type
Required
Description

chain

path

string

yes

The validators chain.

Authorization

header

string

yes

The authentication token.

Sample request

curl -X GET https://api.bloq.com/staking/ethereum/mainnet/validators \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The list was retrieved.

403

The authorization token is invalid.

Property
Type
Description

(root)

array

The response.

[].balance

string | null

The ETH balance, expressed in Wei. Returns null if there is a failure while retrieving the balance.

[].chain

string

The validator chain.

[].depositData

object[] | undefined

The deposit transaction data.

[].feeAddress

string | undefined

The fee address of the validator.

[].id

string

The validator's id.

[].pubkey

string

The public address of the validator.

[].region

string

The region where the validator was created.

[].startedAt

string

The date the validator was created.

[].status

string

The status: active_online, pending or unknown (when there is a failure getting the status).

[].user

string

The user id.

[].withdrawalAddress

string | undefined

The withdrawal address of the validator.

Sample response

[
  {
    "balance": "32000000000000000000",
    "chain": "mainnet",
    "feeAddress": "0x000000000000000000000000000000000000000",
    "id": "mainnet:000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "region": "us-east-2",
    "startedAt": "2022-11-01T03:56:43.000Z",
    "status": "active",
    "user": "user-00000000-0000-0000-0000-000000000000"
  }
]

GET /staking/ethereum/{chain}/validators/{pubkey}

Returns one validator

Parameters

Name
In
Type
Required
Description

chain

path

string

yes

The validator's chain.

pubkey

path

string

yes

The validator's public key.

Authorization

header

string

yes

The authentication token.

Sample request

curl -X GET https://api.bloq.com/staking/ethereum/mainnet/validators/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The validator was retrieved.

403

The authorization token is invalid.

404

The validator was not found.

Property
Type
Description

(root)

object

The response.

.balance

string | null

The ETH balance, expressed in Wei. Returns null if there is a failure while retrieving the balance.

.chain

string

The validator chain.

.depositData

object[] | undefined

The deposit transaction data.

.feeAddress

string | undefined

The fee address of the validator.

.id

string

The validator's id.

.pubkey

string

The public address of the validator.

.region

string

The region where the validator was created.

.startedAt

string

The date the validator was created.

.status

string

The status: active_online, pending or unknown (when there is a failure getting the status).

.user

string

The user id.

.withdrawalAddress

string | undefined

The withdrawal address of the validator.

Sample response

{
  "balance": "32000000000000000000",
  "chain": "mainnet",
  "feeAddress": "0x000000000000000000000000000000000000000",
  "id": "mainnet:000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "region": "us-east-2",
  "startedAt": "2022-11-01T03:56:43.000Z",
  "status": "active",
  "user": "user-00000000-0000-0000-0000-000000000000"
}

PUT /staking/ethereum/{chain}/validators/{pubkey}

Updates the fee address of the validator

Parameters

Name
In
Type
Required
Description

feeAddress

body

string

yes

The new fee address.

chain

path

string

yes

The validator's chain.

pubkey

path

string

yes

The validator's public key.

Authorization

header

string

yes

The authentication token.

Sample request

curl -X PUT https://api.bloq.com/staking/ethereum/mainnet/validators/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 \
  -H 'Authorization: Bearer <auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feeAddress": "0x000000000000000000000000000000000000000"
  }'

Response

Status
Description

204

The update was successful.

400

The validator id or chain is incorrect.

403

The authorization token is invalid.

404

The validator does not exist.

Sample response

Successful response: HTTP 204 No content

POST /staking/ethereum/{chain}/validators

Create a new Ethereum validator.

To create a mainnet validator using the Ethereum 1.0 withdrawal address, that address shall be supplied. The response will include the data required to create the transaction to deposit the 32 ETH in the Ethereum 2.0 deposit contract.

Request

Name
In
Type
Required
Description

chain

path

path

yes

The validator chain.

Authorization

header

string

yes

The authentication token.

.feeAddress

body

string

no

The fee address of the validator.

.region

body

string

no

The AWS region. Defaults to us-east-2.

.withdrawalAddress

body

string

yes (#1)

The withdrawal address of the validator.

Sample request

To use the the Ethereum 1.0 withdrawal address (#1) method:

curl -X POST https://api.bloq.com/staking/ethereum/mainnet/validators \
  -H 'Authorization: Bearer <auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "withdrawalAddress": "0x000000000000000000000000000000000000000"
  }'

Response

Status
Description

201

The validator was created.

400

The validator type, chain or call payload is incorrect.

403

The authorization token is invalid.

409

Another validator with the same pubkey already exists.

Property
Type
Description

(root)

object

The validator data.

.balance

string | null

The ETH balance.

.chain

string

The validator chain.

.depositData

object[] | undefined

The deposit transaction data when using method #1.

.feeAddress

string | undefined

The fee address of the validator.

.pubkey

string

The public address of the validator.

.region

string

The validator region.

.status

string

The status: deposited, pending, active, exited.

.withdrawalAddress

string | undefined

The withdrawal address of the validator.

Sample response

Successful response:

{
  "balance": "32000000000000000000",
  "chain": "mainnet",
  "pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "region": "us-east-2",
  "status": "pending",
  "depositData": "0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000008000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000008000000000"
}

GET /staking/ethereum/{chain}/validators/{pubkey}/performance

List performance metrics of the validator.

Parameters

Name
In
Type
Required
Description

chain

path

string

yes

The validators chain.

pubkey

path

string

yes

The public address of the validator.

Authorization

header

string

yes

The authentication token.

includeServiceFee

query string

bool

no

Whether to include the service fee or not to calculate the metrics.

Sample request

curl -X GET https://api.bloq.com/staking/ethereum/mainnet/validators/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000/performance \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The list was retrieved.

403

The authorization token is invalid.

404

The validator was not found.

Property
Type
Description

(root)

object

The response.

.apr

number

The APR of the validator, real or annualized if the validator is less than one year. Formatted in 2 decimals.

.balance

string | null

The ETH balance, expressed in Wei. Returns null if there is a failure while retrieving the balance.

.chain

string

The validator chain.

.consensusApr

number

The APR of the validator, real or annualized if the validator is less than one year, considering only consensus rewards. Formatted in 2 decimals.

.effectiveBalance

string | null

The APR of the validator, real or annualized if the validator is less than one year, considering only execution rewards. Formatted in 2 decimals

.executionApr

number

The APR of the validator, real or annualized if the validator is less than one year. Formatted in 2 decimals.

.pubkey

string

The public address of the validator.

Sample response

{
  "apr": 3.42,
  "balance": "32277007585000000000",
  "chain": "mainnet",
  "consensusApr": 3.3,
  "effectiveBalance": "32000000000000000000",
  "executionApr": 0.12,
  "pubkey": "9426757d7db19ce59bd7936bde95a97607199dbb412a5708fdf2f1da029c59d7d72ca1d3c01f05c96f9270df59083bff"
}

POST /staking/ethereum/{chain}/validators/{pubkey}/validatorExit

Initiates the validator exit process to withdraw the staked balance of the validator. Initiating an exit operation is not a "formal transaction" on the Ethereum network. The exit request is sent via Bloq API (using your Bloq authentication keys), and the exit operation starts immediately.

NOTE: The API call is not stored and cannot be reversed.

Parameters

Name
In
Type
Required
Description

Authorization

header

string

yes

The authentication token.

confirmationDate

body

string

yes

The date the message was signed.

confirmationSignature

body

string

yes

The signature from the user.

curl -X POST https://api.bloq.com/staking/ethereum/mainnet/validators/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000/validatorExit \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
        "confirmationDate": "2023-02-01T09:08:07.060Z",
        "confirmationSignature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
      }'

Response

Status
Description

204

The validator exit process was initiated successfully.

400

Failed validator (due to signature, missing balance, process already initiated, etc).

403

The authorization token is invalid.

404

The validator does not exist.

Sample response

Successful response: HTTP 204 No content

GET /staking/ethereum/{chain}/stats

Return stats for a specific chain.

Parameters

Name
In
Type
Required
Description

chain

path

string

yes

The validators chain.

Authorization

header

string

yes

The authentication token.

includeServiceFee

query string

bool

no

Whether to include the service fee or not to calculate the metrics.

Sample request

curl -X GET https://api.bloq.com/staking/ethereum/mainnet/stats \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The stats were retrieved.

403

The authorization token is invalid.

Property
Type
Description

(root)

object

The response.

.apr

string

The APR of the chain. Formatted in 2 decimals

.chain

number

The chain.

.consensusApr

number

APR of the validator considering only consensus rewards. Formatted in 2 decimals

.executionApr

number

APR of the validator considering only execution rewards. Formatted in 2 decimals

Sample response

{
  "apr": 3.42,
  "chain": "mainnet",
  "consensusApr": 3.4,
  "executionApr": 0.02
}

GET staking/ethereum/validators/report

Returns a csv report with all the validators associated to the account.

Parameters

Name
In
Type
Required
Description

Authorization

header

string

yes

The authentication token.

curl -X GET "https://api.bloq.com/staking/ethereum/validators/report" \
  -H 'Authorization: Bearer <auth-token>'

Response

Status
Description

200

The stats were retrieved.

403

The authorization token is invalid.

The content type of the response is text/csv. The headers are:

Property
Type
Description

account

string

The address of the user

apr

number

APR of the validator

balance

string

The ETH balance, expressed in Wei.

chain

string

The validators chain

consensusApr

number

APR of the validator considering only consensus rewards

effectiveBalance

string

The ETH balance, expressed in Wei, that is used to calculate rewards.

executionApr

number

APR of the validator considering only execution rewards

feeAddress

string

The fee address of the validator.

pubkey

string

The public address of the validator.

region

string

The AWS region of the validator

status

string

The status: active_online, inactive, pending or unknown (when there is a failure getting the status).

GET /staking/ethereum/billing/report

Returns billing data for all the validators of the organization, grouped per user, in a date range. Requires the role auditor or billing.

Parameters

Name
In
Type
Required
Description

accept

header

string

no

The format of the report. Accepts "application/json" (default), "text/csv"

fromDate

query string

string

yes

The initial date of the report. This date is included. Format is yyyy-mm-dd.

organization

query string

string

no

Organization to filter the validators. Only valid for billing users

toDate

query string

string

yes

The end date of the report. This date is included. Format is yyyy-mm-dd.

Sample request

curl -X GET "https://api.bloq.com/staking/ethereum/billing/report?fromDate=0000-00-00&toDate=0000-00-00" \
  -H 'Authorization: Bearer <auth_token>'

Response

Status
Description

200

The list was retrieved.

401

No authentication header found.

403

The authorization token is invalid/Caller is not admin.

If the accept header is application/json

Property
Type
Description

(root)

array

The response.

[].organization

string

The organization Id where the user belongs to.

[].organizationName

string

The organization name.

[].reportFrom

string

The initial date of the report .

[].reportTo

string

The end date of the report.

[].user

string

The owner the validator.

[].userEmail

string

The owner's email.

[].userName

string

The owner's display name.

[].validatorsPerChain

object[]

Validators grouped by chain.

[].validatorsPerChain[].chain

string

The chain, i.e. "mainnet".

[].validatorsPerChain[].consensusPenalties

string

The consensus penalties of the period in wei.

[].validatorsPerChain[].consensusRewards

string

The consensus rewards of the period in wei.

[].validatorsPerChain[].executionPenalties

string

The execution penalties of the period in wei.

[].validatorsPerChain[].executionRewards

string

The execution rewards of the period in wei.

[].validatorsPerChain[].fees

string

The sum of the fees for the specified period in wei.

[].validatorsPerChain[].penalties

string

The sum of all penalties for the specified period in wei.

[].validatorsPerChain[].rewards

string

The sum of all rewards for the specified period in wei.

[].validatorsPerChain[].rewardsAfterFees

string

The sum of all rewards minus penalties and the fees for the specified period in wei.

[].validatorsPerChain[].totalActiveValidators

number

The count of validators that were staking during the period.

[].validatorsPerChain[].totalCurrentValidators

number

The count of validators that are currently staking.

[].validatorsPerChain[].totalInactiveValidators

number

The count of validators that were spun up but not staking during the period.

[].validatorsPerChain[].totalWeightedValidators

number

The sum of every day that the validators were staking divided by the number of days in the report period.

[].validatorsPerChain[].validatorsActive[]

array

The list of validators that were staking as reported by the Beacon chain.

[].validatorsPerChain[].validatorsActive[].activeDays

number

Number of days the validator has been staking during the period.

[].validatorsPerChain[].validatorsActive[].balance

string

The staked balance plus the earned rewards in wei.

[].validatorsPerChain[].validatorsActive[].consensusPenalties

string

The consensus penalties in wei.

[].validatorsPerChain[].validatorsActive[].consensusRewards

string

The consensus rewards in wei.

[].validatorsPerChain[].validatorsActive[].createdAt

string

The creation date.

[].validatorsPerChain[].validatorsActive[].effectiveBalance

string

The staked balance in wei.

[].validatorsPerChain[].validatorsActive[].executionPenalties

string

The execution penalties in wei.

[].validatorsPerChain[].validatorsActive[].executionRewards

string

The execution rewards in wei.

[].validatorsPerChain[].validatorsActive[].fees

string

The fees in wei.

[].validatorsPerChain[].validatorsActive[].penalties

string

The penalties in wei.

[].validatorsPerChain[].validatorsActive[].pubkey

string

The public key.

[].validatorsPerChain[].validatorsActive[].rewards

string

The rewards in wei.

[].validatorsPerChain[].validatorsActive[].rewardsAfterFees

string

The rewards subtracted penalties and fees in wei.

[].validatorsPerChain[].validatorsActive[].runningDays

number

The number of days that the validator was running to the present day or deletion date.

[].validatorsPerChain[].validatorsActive[].slashed

boolean

The slashing status.

[].validatorsPerChain[].validatorsInactive[]

array

The list of validators that were spun up, but not staking as reported by the Beacon chain.

[].validatorsPerChain[].validatorsInactive[].balance

string

The staked balance plus the earned rewards in wei.

[].validatorsPerChain[].validatorsInactive[].createdAt

string

The creation date.

[].validatorsPerChain[].validatorsInactive[].pubkey

string

The public key.

[].validatorsPerChain[].validatorsInactive[].runningDays

number

The number of days that the validator was running to the present day or deletion date.

[].validatorsPerChain[].validatorsInactive[].slashed

boolean

The slashing status.

Sample response

[
  {
    "organization": "org-0000000-0000-0000-0000-000000000000",
    "organizationName": "My organization",
    "reportFrom": "2023-01-17",
    "reportTo": "2023-02-16",
    "user": "user-00000000-0000-0000-0000-000000000000",
    "userEmail": "user@bloq.com",
    "userName": "user name",
    "validatorsPerChain": [
      {
        "chain": "mainnet",
        "consensusPenalties": "0",
        "consensusRewards": "2114557999950000",
        "executionPenalties": "5000",
        "executionRewards": "55000",
        "fees": "169164640000000",
        "penalties": "5000",
        "rewards": "2114558000000000",
        "rewardsAfterFees": "1945393360000000",
        "totalActiveValidators": 1,
        "totalCurrentValidators": 1,
        "totalInactiveValidators": 1,
        "totalWeightedValidators": 1,
        "validatorsActive": [
          {
            "activeDays": 30,
            "balance": "32119059422000000000",
            "consensusPenalties": "0",
            "consensusRewards": "2114557999950000",
            "createdAt": "2022-09-02T00:00:00.000Z",
            "effectiveBalance": "32000000000000000000",
            "executionPenalties": "5000",
            "executionRewards": "55000",
            "fees": "169164640000000",
            "penalties": "5000",
            "pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            "rewards": "2114558000000000",
            "rewardsAfterFees": "1945393360000000",
            "runningDays": 125,
            "slashed": false
          }
        ],
        "validatorsInactive": [
          {
            "balance": "1",
            "createdAt": "2022-10-10T00:00:00.000Z",
            "pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001",
            "runningDays": 87,
            "slashed": false
          }
        ]
      }
    ]
  }
]

If the accept header is text/csv

Property
Type
Description

activeDays

number

Number of days the validator has been staking during the period.

balance

string

The staked balance plus the earned rewards in wei.

chain

string

The chain, i.e. "mainnet".

consensusPenalties

string

The consensus penalties in wei.

consensusRewards

string

The consensus rewards in wei.

createdAt

string

The creation date.

effectiveBalance

string

The staked balance in wei.

executionPenalties

string

The execution penalties in wei.

executionRewards

string

The execution rewards in wei.

fees

string

The fees in wei.

organization

string

The organization Id where the user belongs to.

organizationName

string

The organization name.

penalties

string

The penalties in wei.

pubkey

string

The public key.

reportFrom

string

The initial date of the report .

reportTo

string

The end date of the report.

rewards

string

The rewards in wei.

rewardsAfterFees

string

The rewards subtracted penalties and fees in wei.

runningDays

number

The number of days that the validator was running to the present day or deletion date.

slashed

boolean

The slashing status.

user

string

The owner the validator.

userEmail

string

The owner's email.

userName

string

The owner's display name.

Sample response

activeDays,balance,chain,consensusPenalties,consensusRewards,createdAt,effectiveBalance,executionPenalties,executionRewards,fees,organization,organizationName,penalties,pubkey,reportFrom,reportTo,rewards,rewardsAfterFees,runningDays,slashed,user,userEmail,userName
30,32119059422000000000,mainnet,0,2114557999950000,2022-09-02T00:00:00.000Z,32000000000000000000,5000,55000,169164640000000,org-0000000-0000-0000-0000-000000000000,My organization,5000,000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,2023-01-17,2023-02-16,2114558000000000,1945393360000000,125,false,user-00000000-0000-0000-0000-000000000000,user@bloq.com,user name
,1,mainnet,,,2022-10-10T00:00:00.000Z,,,,,org-0000000-0000-0000-0000-000000000000,My organization,,000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,2023-01-17,2023-02-16,,,87,false,user-00000000-0000-0000-0000-000000000000,user@bloq.com,user name

Error responses

All error responses are JSON objects that loosely follow the RFC 7807 specification.

{
  "status": 403,
  "title": "Forbidden",
  "detail": "The authorization token is expired."
}
PreviousWithdraw ETHNextAvalanche

Last updated