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
- Ping
- Ping Times
- Validators List
- Validator Detail
- Validator Block Production History
- Error Codes
- Notes
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, "data_center_key":"24940-FI-Helsinki", "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", "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" }, ... ]
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!