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.

Quick Reference


Authentication

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.


Ping

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"}

Validators List

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.",
    "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",
    "skipped_slots":664,
    "skipped_slot_percent":"0.5155",
    "ping_time":"205.703",
    "url":"https://www.validators.app/api/v1/validators/testnet/123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY.json"
  },
  ...
]
    

Validator Detail

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.",
  "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",
  "skipped_slots":664,
  "skipped_slot_percent":"0.5155",
  "ping_time":"205.703",
  "url":"https://www.validators.app/api/v1/validators/testnet/123vij84ecQEKUvQ7gYMKxKwKF6PbYSzCzzURYA4xULY.json"
}
    

Validator Block Production History

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"
  },
  ...
]
    

Epoch Index

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
    }

    

Error Codes:

400
Parameter Missing
401
Unauthorized
404
Record Not Found
500
Server Error (Admin has been notified)

NOTES:

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!