Search…
⌃K

API Routes

Jump to:

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
string | 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
string | 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 (#1), 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.
To create a mainnet validator using the mnemonic and Ethereum 2.0 addresses (#2), the validator keystore and the validator keystore password are required. Those two are created by the user with i.e. the staking_deposit-cli. Note that the deposit of 32 ETH into the Ethereum 2.0 deposit contract should have been done in advance.
If both the withdrawal address and the validator keystore are specified, the request will be considered invalid.

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.
.keystore
body
object
yes (#2)
The validator keystore object.
.password
body
string
yes (#2)
The validator keystore password.
.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"
}'
To use the mnemonic and Ethereum 2.0 addresses (#2) method:
curl -X POST https://api.bloq.com/staking/ethereum/mainnet/validators \
-H 'Authorization: Bearer <auth-token>' \
-H 'Content-Type: application/json' \
-d '{
"keystore": {
"crypto": {...},
"path": "m/12381/3600/0/0/0",
"pubkey": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"version": 4
},
"password": "xxxx"
}'

Response

Status
Description
200
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
string | 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.

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, 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
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 xxxxxx.xxxxxxxxxx.xxxxxx'

Response