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.

Server 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 List 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, defaults to 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, defaults to 1. Can be combined 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,
    "consensus_mods_score":0,
    "data_center_concentration_score":0,
    "published_information_score":0,
    "security_report_score":0,
    "admin_warning":"This validator has open RPC ports",
    "active_stake":100000,
    "commission":10,
    "delinquent":false,
    "data_center_key":"24940-FI-Helsinki",
    "data_center_host":"host-name",
    "autonomous_system_number":24940,
    "latitude": "48.8582",
    "longitude": "2.3387",
    "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"
  },
  ...
]

Validator Details

The Validator Details 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

Parameter Options:

`with_history=true` will return history fields for validator (root_distance_history, vote_distance_history, skipped_slot_history, skipped_vote_history, skipped_slot_moving_average_history, stake_concentration and software_version). 

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

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,
  "consensus_mods_score":0,
  "data_center_concentration_score":0,
  "published_information_score":0,
  "security_report_score":0,
  "admin_warning":"This validator has open RPC ports",
  "active_stake":100000,
  "commission":10,
  "delinquent":false,
  "data_center_key":"24940-FI-Helsinki",
  "data_center_host":"host-name",
  "autonomous_system_number":24940,
  "latitude": "48.8582",
  "longitude": "2.3387",
  "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"
}

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

Epochs

The Epochs 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` will limit the results to NN entries per page, defaults to 50.

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

`page=NN` will return the results from passed page, 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
}

Commission Changes

The Commission Changes 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'

`per=NN` will limit the results to NN entries per page, defaults to 25.

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

`page=NN` will return the results from passed page, defaults to 1.

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

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

Stake Pools

The Stake Pools endpoint will return all the stake pools. Replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

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

Response:

{ "stake_pools":
  [
    {
    "id": 72,
    "authority": "authority",
    "average_apy": 12,
    "average_delinquent": 1,
    "average_lifetime": 22,
    "average_score": 7,
    "average_skipped_slots": 12,
    "average_uptime": 1,
    "average_validators_commission": 2,
    "manager_fee": 0,
    "name": "TestName",
    "network": "testnet",
    "ticker": 'ticker',
    "validators_count": 0
    },
    ...
  ]
}

Stake Accounts

The Stake Accounts endpoint will return all the stake accounts grouped by vote accounts. Replace `:network` with 'testnet' or 'mainnet' as desired.

Request:

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

Parameter Options:

`filter_[account|staker|withdrawer|validator]=` filters by chosen value. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/stake-accounts/:network?filter_account=7hTEVqbQmt3UPQQKcavaxzzakt1FWbwVXyE8MZGadhW6'

`sort_by=[epoch_|withdrawer_|staker_|stake_]` will sort the results by epoch, withdrawer, staker or stake. NOTE: after underscore add `asc` or `desc`, example below. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/stake-accounts/:network?sort_by=epoch_desc'

`per=NN` will limit the results to NN entries per page, defaults to 25.

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

`page=NN` will return the results from passed page, defaults to 1.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/stake-accounts/:network?page=1'

Response:

{
  "stake_accounts": [
    {
      "3X6FsQ8awkcU4iXTF82T4RtnTJx9LTY5D3dHK6zDE1Tp": [
        {
          "created_at": "2021-11-17T15:53:25.266Z",
          "activation_epoch": 232,
          "active_stake": 2000001000000,
          "delegated_stake": 2000001000000,
          "network": "testnet",
          "delegated_vote_account_address": "5HNvXiPTUKPtPxz1Y4cUj9BMDbhupi5Bd6mp7AqJhSGN",
          "id": 16,
          "stake_pubkey": "5eJuknGqijkJJzR3Yt35Kr71WrHqDivEhtSeSm3tTYCy",
          "batch_uuid": "4aac4a2c-3312-4189-9433-d535d1908754",
          "stake_pool_id": 5,
          "staker": "25jjjw9kBPoHtCLEoWu2zx6ZdXEYKPUbZ6zweJ561rbT",
          "withdrawer": "25jjjw9kBPoHtCLEoWu2zx6ZdXEYKPUbZ6zweJ561rbT",
          "pool_name": "Jpool",
          "validator_name": "linap",
          "validator_account": "3X6FsQ8awkcU4iXTF82T4RtnTJx9LTY5D3dHK6zDE1Tp"
        }
      ]
    },
  ...
}

Ping Thing Post

The Ping Thing Post endpoint allows you to push information about transaction times.

Request:

curl -X POST -H "Token: secret-api-token" -H "Content-Type: application/json" -d '{"application": "mango",  "commitment_level": "finalized", "signature": "signature", "success": true, "time": "NN", "transaction_type": "transfer", "slot_sent": "NN", "slot_landed": "NN", "reported_at": "2021-07-01T11:02:12"}' https://www.validators.app/api/v1/ping-thing/:network

Parameter Options:

`application: string` Application type.

`commitment_level: string` Possible values: 'processed' OR 'confirmed' OR 'finalized'.

`signature: string` Transaction signature.

`reported_at: %year-%month-%dayT%hour:%minute:%second` Transaction creation time.

`success: boolean` Optional, true or false, default true, if empty success will be set to true. Only false value sets `success` field to false.

`time: NN` Confirmation time in miliseconds.

`transaction_type: string` A string to describe the type of transaction, e.g. 'transfer', 'defi-swap', 'nft-mint', or anything meaningful to the sender.

`slot_sent: NN` Number of slot in which transaction has been started.

`slot_landed: NN` Number of slot in which transaction has been finished.

Response:

{"status":"ok"}

Ping Thing Post Batch

The Ping Thing Batch endpoint allows you to push multiple transaction informations at once.

Request:

curl -X POST -H "Token: secret-api-token" -H "Content-Type: application/json" -d '{"transactions": [{"time": "NN", "signature": "signature", "transaction_type": "transfer", "slot_sent": "NN", "slot_landed": "NN", "reported_at": "2021-07-01T11:02:12"}, { ... }, ...]}' https://www.validators.app/api/v1/ping-thing-batch/:network

Parameter Options:

`application: string` Application type.

`commitment_level: string` Possible values: 'processed' OR 'confirmed' OR 'finalized'.

`signature: string` Transaction signature.

`reported_at: %year-%month-%dayT%hour:%minute:%second` Transaction creation time.

`success: boolean` Optional, true or false, default true, if empty success will be set to true. Only false value sets `success` field to false.

`time: NN` Confirmation time in miliseconds.

`transaction_type: string` A string to describe the type of transaction, e.g. 'transfer', 'defi-swap', 'nft-mint', or anything meaningful to the sender.

`slot_sent: NN` Number of slot in which transaction has been started.

`slot_landed: NN` Number of slot in which transaction has been finished.

Response:

{"status":"created"}

Ping Thing List

This Ping Thing List endpoint will return a list of pings 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/ping-thing/:network'

Parameter Options:

`limit=NN` will limit the results to NN entries, defaults to 240. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/ping-thing/:network?limit=10'

`page=NN` will return the results from passed page, defaults to 1. Can be combined with limit param. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/ping-thing/:network?page=1'

Response:

[
  {
    "application": "mango",
    "commitment_level": "finalized",
    "created_at": "2022-02-10T13:37:42.097Z",
    "network": "testnet",
    "response_time": 396,
    "signature": "0d7f418e4d1a3f80dc8a266cd867f766b73d9c80feea36524dfd074068bdef9221e356c192ac6ac71b71404d",
    "success": true,
    "transaction_type": "transfer",
    "slot_sent": 120,
    "slot_landed": 123,
    "reported_at": "2022-02-10T13:31:55.000Z"
    "username": "sample_user"
  },
  ...
]

Ping Thing Stats

This Ping Thing Stats endpoint will return a ping thing stats. 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/ping-thing-stats/:network?interval=1'

Parameter Options:

`interval=NN` Possible values: 1, 3, 12, 24. Will return stats with passed interval.

Response:

[
  {
    "interval"=>1,
    "max"=>120.0,
    "median"=>82.0,
    "min"=>50.0,
    "network"=>"testnet",
    "num_of_records"=>10,
    "time_from"=>"2022-04-21T13:41:00.000Z",
    "average_slot_latency":2
  },
  ...
]

Sol Prices

The Sol Prices endpoind will return prices gathered from multiple exchanges.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/sol-prices?exchange=coin_gecko'

Parameter Options:

`from=%year-%month-%dayT%hour:%minute:%second` will return results starting from a given time, defaults to 30 days ago. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/sol-prices?from=2022-01-01T00:00:00'

`to=%year-%month-%dayT%hour:%minute:%second` will return results until a given time, defaults to today. 

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/sol-prices?to=2022-01-01T00:00:00'

`exchange=(ftx | coin_gecko)` will return results from a given exchange.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/sol-prices?exchange=ftx'

Response:

[
  {
    "id": 631,
    "exchange": "coin_gecko",
    "currency": "usd",
    "epoch_mainnet": null,
    "epoch_testnet": null,
    "open": null,
    "close": null,
    "high": null,
    "low": null,
    "volume": "1380634374.482357",
    "datetime_from_exchange": "2022-01-01T00:00:00.000Z",
    "created_at": "2022-03-08T07:33:01.426Z",
    "updated_at": "2022-03-08T07:33:01.426Z",
    "average_price": "170.1966082645718"
  },
  ...
]

Gossip Nodes

Gossip Nodes endpoint will return all nodes visible in Gossip, including RPC nodes, with basic information & geo coordinates for mapping.

Request:

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

Parameter Options:

`staked=(true | false)` will limit the results only to staked / unstaked nodes. Omit this parameter for all nodes.

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/gossip-nodes/:network?staked=true'

`per=NN` will limit the results to NN entries per page, defaults to 100.

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

`page=NN` will return the results from provided page, defaults to 1.

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

Response:

[
  {
    "account": "DDnAqxJVFo2GVTujibHt5cjevHMSE9bo8HJaydHoshdp",
    "ip": "74.118.139.6",
    "network": "mainnet",
    "staked": true,
    "software_version": "1.10.35",
    "created_at": "2022-08-22T06:47:57.008Z",
    "updated_at": "2022-08-24T12:04:21.546Z",
    "avatar_url": "https://s3.amazonaws.com/keybase_processed_uploads/3af995d21a8fe4cec4d6e83104f87205_360_360.jpg",
    "details": "Experienced validator located in Boulder, CO. Creator/Maintainer of www.validators.app",
    "keybase_id": "brianlong",
    "name": "Block Logic | BL",
    "www_url": "https://www.blocklogic.net",
    "admin_warning": null,
    "country_name": "Netherlands",
    "data_center_key": "20326-NL-Amsterdam",
    "latitude": "52.3716",
    "longitude": "4.8883"
  },
  ...
]

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!