API Documentation

Our API provides several different endpoints to query the validators database. You must have a verified account in order to make requests against the JSON API. Your user account and an API token are used to secure this API. You can create a New Account or Sign In to see your API token.

Pass your API token in as the Token header, like in this curl example:

$ curl -H "Token: secret-api-token" https://www.validators.app/api/v1/ping.json

Examples in this API guide are demonstrated using curl, but you can use an HTTP library of your choice. All responses are JSON.

The ping endpoint will allow you to test your connection to the server.

Request:

$ curl -H "Token: secret-api-token" https://www.validators.app/api/v1/ping.json

Response:

{"answer":"pong"}

The validators endpoint will return a list of validators for the requested network. In the example below, replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validators/:network.json'

Parameter Options:

`order=[score, name, stage]` will sort the results by score descending, name, or stake.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validators/:network.json?order=score'

`limit=NN` will limit the results to NN entries. The default is 9_999.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validators/:network.json?order=score&limit=50'

`page=NN` will return the results from passed page. Works best with limit param.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validators/:network.json?order=score&page=1&limit=50'

`q=query` will limit the results to entries containing query. The query value is compared against validator's name, account and score data center key.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validators/:network.json?order=score&q=query'

Response:

An Array of validators.

[
  {
    "network":"testnet",
    "account":"123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY",
    "name":"Example Name",
    "keybase_id":null,
    "www_url":"https://www.example.com",
    "details":"Example validator located anywhere.",
    "avatar_url":"www.avatar_url.com",
    "created_at":"2020-05-24T19:07:38.222Z",
    "updated_at":"2020-05-24T19:07:38.222Z",
    "total_score":10,
    "root_distance_score:2,
    "vote_distance_score":2,
    "skipped_slot_score":2,
    "software_version":"1.2.3 devbuild",
    "software_version_score":2,
    "stake_concentration_score":0,
    "data_center_concentration_score":0,
    "published_information_score":0,
    "security_report_score":0,
    "active_stake":100000,
    "commission":10,
    "delinquent":false,
    "data_center_key":"24940-FI-Helsinki",
    "data_center_host":"host-name",
    "autonomous_system_number":24940,
    "vote_account":"123JiW1rwJ4JM5BxYqFkBi6wQJ52pt6qUH88JDqrtU9i",
    "epoch_credits": 263538,
    "skipped_slots":664,
    "skipped_slot_percent":"0.5155",
    "ping_time":"205.703",
    "url":"https://www.validators.app/api/v1/validators/testnet/123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY.json"
  },
  ...
]
    

The validators endpoint will return a single validator for the requested network and account. In the example below, replace `:network` with 'testnet' or 'mainnet' as desired. Replace `:account` with the desired account ID.

Request:

curl -H "Token: secret-api-token" https://www.validators.app/api/v1/validators/:network/:account.json

Response:

{
  "network":"testnet",
  "account":"123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY",
  "name":"Example Name",
  "keybase_id":null,
  "www_url":"https://www.example.com",
  "details":"Example validator located anywhere.",
  "avatar_url":"www.avatar_url.com",
  "created_at":"2020-05-24T19:07:38.222Z",
  "updated_at":"2020-05-24T19:07:38.222Z",
  "total_score":10,
  "root_distance_score:2,
  "vote_distance_score":2,
  "skipped_slot_score":2,
  "software_version":"1.2.3 devbuild",
  "software_version_score":2,
  "stake_concentration_score":0,
  "data_center_concentration_score":0,
  "published_information_score":0,
  "security_report_score":0,
  "active_stake":100000,
  "commission":10,
  "delinquent":false,
  "data_center_key":"24940-FI-Helsinki",
  "data_center_host":"host-name",
  "autonomous_system_number":24940,
  "vote_account":"123JiW1rwJ4JM5BxYqFkBi6wQJ52pt6qUH88JDqrtU9i",
  "epoch_credits": 263538,
  "skipped_slots":664,
  "skipped_slot_percent":"0.5155",
  "ping_time":"205.703",
  "url":"https://www.validators.app/api/v1/validators/testnet/123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY.json"
}
    

The validator_block_history endpoint will return a history of block production stats for the requested network and account. In the example below, replace `:network` with 'testnet' or 'mainnet' as desired. Replace `:account` with the desired account ID. You can also include a `limit` parameter to request more or fewer datapoints.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/validator_block_history/:network/:account.json?limit=100'

Response:

[
  {
    "epoch":143,
    "leader_slots":2188,
    "blocks_produced":2036,
    "skipped_slots":152,
    "skipped_slot_percent":"0.0695",
    "created_at":"2021-01-24T17:12:23.098Z",
    "batch_uuid":"015ccead-e713-4412-a1f4-e2365d956809"
  },
  ...
]
    

The Epoch endpoint will return all epoch data. Replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/epochs/:network'

Parameter Options:

`per=NN` number of records per page, defaults to 50

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/epochs/:network?per=50'

`page=NN` page number, defaults to 1

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/epochs/:network?per=50&page=1'

Response:

    {
      epochs: [
        {
          "epoch": 169,
          "starting_slot": 73008000,
          "slots_in_epoch": 432000,
          "network": "mainnet",
          "created_at": "2021-04-12T10:03:52.401Z"
        },
        ...
      ],
      epochs_count: 169
    }

    

The Commission Change endpoint will return all the changes in commission for a given period of time. Replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/commission-changes/:network'

Parameter Options:

`date_from=%year-%month-%dayT%hour:%minute:%second` beginning of a search period. Defaults to 30 days ago

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/commission-changes/:network?date_from=2021-07-01T11:02:12'

`date_to=%year-%month-%dayT%hour:%minute:%second` end of a search period. Defaults to now

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/commission-changes/:network?date_to=2021-07-28T11:02:12'

`query=%account-or-key` returns data only for validators matching by name, pubkey or vote account

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/commission-changes/:network?query=123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY'

Response:

      [
        {
          "created_at": "2021-07-27T08:47:16.803Z",
          "commission_before": 9.0,
          "commission_after": 10.0,
          "epoch": 213,
          "network": "testnet",
          "account": "123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY"
        },
        ...
      ]

    

Active stake is shown in Lamports.

Commision is shown in percent. e.g. 10%.

Our database uses null values when there is no data. You should expect to see `null` as a possible return value for any attribute. If an attribute is missing from the output, then you can also assume the value is null.

Version 1 of this API is still in development. Check back here to see updates!