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 either 'testnet', 'mainnet' or 'pythnet' 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":"12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX",
    "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",
    "jito":false,
    "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/12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX.json",
    "stake_pools_list":["Jito", "Marinade"]

  },
  ...
]

Validator Details

The Validator Details endpoint will return a single validator for the requested network and account. In the example below, replace `:network` with either 'testnet', 'mainnet' or 'pythnet' 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":"12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX",
  "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/12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX.json",
  "stake_pools_list":["Jito", "Marinade"]
}

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 either 'testnet', 'mainnet' or 'pythnet' 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 either 'testnet', 'mainnet' or 'pythnet' as desired.

Request:

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

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.json?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.json?per=50&page=1'

Response:

{
  epochs: [
    {
      "epoch": 472,
      "starting_slot": 203904008,
      "slots_in_epoch": 432000,
      "network": "mainnet",
      "created_at": "2023-07-07T07:44:56.000Z",
      "total_rewards": 181321548661377,
      "total_active_stake": 390383623782551636
    },
    ...
  ],
  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 either 'testnet', 'mainnet' or 'pythnet' as desired.

Request:

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

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.json?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.json?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.json?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.json?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.json?query=12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX'

Response:

[
  {
    "created_at": "2023-01-31T22:27:13.791Z",
    "commission_before": 100.0,
    "commission_after": 10.0,
    "epoch": 406,
    "network": "mainnet",
    "epoch_completion": 0.05,
    "batch_uuid": "18d35532-7b13-4696-baec-269ac4e0cc9f",
    "account": "12345j84ecQEKUvQ7gYMKxKwKF6PbYXxXxxXXXXXxXXX",
    "name": "Example Name",
    "source_from_rewards": true
  },
  ...
]

Stake Pools

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

Request:

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

Response:

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

Stake Accounts

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

Request:

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

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.json?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.json?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.json?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.json?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.json

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 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.json

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 either 'testnet', 'mainnet' or 'pythnet' as desired.

Request:

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

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.json?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.json?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 either 'testnet', 'mainnet' or 'pythnet' as desired.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/ping-thing-stats/:network.json?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 endpoint will return prices.

Request:

curl -H "Token: secret-api-token" 'https://www.validators.app/api/v1/sol-prices.json'

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.json?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.json?to=2022-01-01T00:00:00'

Response:

[
  {
    "id": 631,
    "currency": "usd",
    "epoch_mainnet": null,
    "epoch_testnet": 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.json'

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

Authorities Changes

Authorities Changes endpoint will return changes in authorities for validators in a given network.

Request:

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

Parameter Options:

`validator=identity` will return results only for a given validator.

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

`vote_account=account` will return results only for a given vote account.

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

`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/account-authorities/:network.json?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/account-authorities/:network.json?per=50&page=1'

Response:

[
  {
    "authority_changes": {
      "authorized_withdrawer_before": null,
      "authorized_withdrawer_after": "4hEF3wqsyr1NxXf2SYec3Qs8yk24vWsT7o7Cw7HsTLej",
      "authorized_voters_before": null,
      "authorized_voters_after": {
        "432": "DDnAqxJVFo2GVTujibHt5cjevHMSE9bo8HJaydHoshdp"
      },
      "network": "mainnet",
      "created_at": "2023-04-05T11:24:51.593Z",
      "vote_account_address": "9GJmEHGom9eWo4np4L5vC6b6ri1Df2xN8KFoWixvD1Bs"
    },
    "total_count": 100
  }
]

Error Codes:

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

Requests Limits:

Requests limit to our API is 60 or 30 requests per 5 minutes, depending on the endpoint. Higher limit is available for data that changes more often: Ping Thing, Ping Thing Stats and Commission Changes endpoints.

After exceeding the limit, your will get 429 Too Many Requests error.

Limits are automatically reset after 5 minutes. See RateLimit-Reset header to check how much time is left (in seconds) until the limit resets.

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.

Besides JSON format, our API provides CSV format as well. For this case please change .json suffix into .csv in url when making up a request call. E.g: 'https://www.validators.app/api/v1/ping.csv'.

Version 1 of this API is still in development. Check back here to see updates!