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 ping-times endpoint will return recent ping times as reported by the participating validators. By default, the most recent 1,000 ping times will be returned. You can include a `limit` parameter to request more or fewer ping times. In the examples below, replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

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

or

$ curl -H "Token: secret-api-token" https://www.validators.app/api/v1/ping-times/:network.json?limit=1

Response:

An Array of response times.

[
  {
    "id":614598,
    "batch_uuid":"baf5c581-7ca3-471f-9a86-17a4f3c904a3",
    "network":"testnet",
    "from_account":"71bhKKL89U3dNHzuZVZ7KarqV6XtHEgjXjvJTsguD11B",
    "from_ip":"165.227.100.142",
    "to_account":"HrTZp96AjUbgxFyaJUcWPLe93441D4TuEN1hC14TNTuJ",
    "to_ip":"95.217.226.153",
    "min_ms":"101.706",
    "avg_ms":"101.778",
    "max_ms":"101.872",
    "mdev":"0.396",
    "observed_at":"2020-06-19T12:54:50.000Z",
    "created_at":"2020-06-19T12:54:50.559Z",
    "updated_at":"2020-06-19T12:54:50.559Z"
  },
  ...
]
    

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'

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

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

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
    }

    

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!