API Routes

Jump to:

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

• GET /staking/ethereum/chains

• GET /staking/ethereum/{chain}/stats

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

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

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

• GET /staking/ethereum/billing/report

• GET /staking/ethereum/regions

• GET /staking/ethereum/validators/report

• POST /staking/ethereum/{chain}/validators

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

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

• Error responses

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": "[e-mail]",
    "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,[e-mail],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,[e-mail],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."
}