<span class="translation_missing" title="translation missing: en.home_page_link">Home Page Link</span> mainnet |  testnet |   | 

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.

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

Ping Times

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

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'

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

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!