Skip to main content

Validators


warning

These docs reflect the Validator Mainnet API. If you would like to use the Testnet API, please use the following base url:

https://testnet-api.helium.wtf/v1/

List Validators

GET https://api.helium.io/v1/validators

List known validators as registered on the blockchain. The results are paged. If a cursor field is present in the response, more results are available.

Query Parameters

paramTypeNote
cursor (optional)stringCursor for the page to fetch

Validator for Address

GET https://api.helium.io/v1/validators/:address

Fetch a validator with a given address.

Path Parameters

paramTypeNote
addressstringAddress of validator to fetch

Validators for Name

GET https://api.helium.io/v1/validators/name/:name

Fetch the validators which map to the given 3-word animal name. The name must be all lower-case with dashes between the words, e.g. tall-plum-griffin. Because of collisions in the Angry Purple Tiger algorithm, the given name might map to more than one validator.

Path Parameters

paramTypeNote
namestringName of validator(s) to fetch

GET https://api.helium.io/v1/validators/name?search=<term>

Fetch the validators which match a search term in the given search term query parameter. The search parameter needs to be at least one character, with 3 or more recommended.

Query Parameters

paramTypeNote
searchstringThe name fragment to search for

Validator Activity

GET https://api.helium.io/v1/validators/:address/activity
caution

The /activity route will be deprecated on May 1, 2022 and will be replaced by /roles, described below

Lists all blockchain transactions that the given validator was involved in. This route is paged using a cursor.

Path Parameters

paramTypeNote
address (optional)stringB58 address of the validator

Query Parameters

paramTypeNote
cursor (optional)stringCursor for page of results to fetch
filter_types (optional)stringComma separated list of transaction types
min_time (optional)stringFirst time to include data for
max_time (optional)stringLast time to include data for
limit (optional)numberMaximum number of items to return

Validator Roles

GET https://api.helium.io/v1/validators/:address/roles

Lists all blockchain transactions that the given validator was involved in. This route is paged using a cursor.

Path Parameters

paramTypeNote
address (optional)stringB58 address of the validator

Query Parameters

paramTypeNote
cursor (optional)stringCursor for page of results to fetch
filter_types (optional)stringComma separated list of transaction types
min_time (optional)stringFirst time to include data for
max_time (optional)stringLast time to include data for
limit (optional)numberMaximum number of items to return

Validator Roles Counts

GET https://api.helium.io/v1/validators/:address/roles/count

Count transactions that indicate activity for a validator.

The results are a map keyed by the given filter_types and the count of transaction of that type.

Path Parameters

paramTypeNote
address (required)stringHotspot B58 address to fetch counts for

Query Parameters

paramTypeNote
filter_typesstringComma separated list of transaction types

Stats for Validators


GET https://api.helium.io/v1/validators/stats

Returns stats for validators


Currently Elected Validators

GET https://api.helium.io/v1/validators/elected

Returns the list of validators that are currently elected to the consensus group.

No Parameters

Elected Validators at a Block

GET https://api.helium.io/v1/validators/elected/:height

Returns the list of validators that were in the consensus group at a given block height

Path Parameters

paramTypeNote
height (required)numberBlockchain Height

Elected Validators in an Election


GET https://api.helium.io/v1/validators/elected/hash/:hash

Returns the list of validators that were elected in the consensus group transcation indicated by the given transaction hash.

Path Parameters

paramTypeNote
hash (required)numberTransaction Hash

Rewards for a Validator

GET https://api.helium.io/v1/validators/:address/rewards

Returns rewards for a given validator per reward block the validator is in, for a given timeframe. Timestamps are given in ISO 8601 format, or in relative time. The block that contains the max_time timestamp is excluded from the result.

This route is paged using a cursor.

Path Parameters

paramTypeNote
address (required)stringB58 address of the validator

Query Parameters

paramTypeNote
cursor (optional)stringCursor for page of rewards to fetch
max_time (required)stringLast timestamp to include rewards for
min_time (required)stringFirst timestamp to include rewards for

Reward Total for a Validator

GET https://api.helium.io/v1/validators/:address/rewards/sum

Returns the total rewards earned for a given validator over a given time range. Timestamps are given in ISO 8601 format or in relative time. The block that includes the max_time timestamp is excluded from the result.

The optional bucket parameter buckets the results in the given bucket size (hour, day, week).

Path Parameters

paramTypeNote
address (required)stringB58 address of the validator

Query Parameters

paramTypeNote
max_time (required)stringLast timestamp to include rewards for
min_time (required)stringFirst timestamp to include rewards for
bucket (optional)stringBucket size (defaults to entire range)

Reward Total for all Validators

GET https://api.helium.io/v1/validators/:rewards/sum

Returns the total rewards earned for all validators over a given time range. Timestamps are given in ISO 8601 format or in relative time. The block that includes the max_time timestamp is excluded from the result.

Path Parameters

paramTypeNote
address (required)stringB58 address of the validator

Query Parameters

paramTypeNote
max_time (required)stringLast timestamp to include rewards for
min_time (required)stringFirst timestamp to include rewards for