Solana Validators | www.validators.app

Quick Reference

Authentication
Server Ping
Validators List
Validator Details
Validator Block Production History
Epochs
Commission Changes
Stake Pools
Stake Accounts
Ping Thing Post
Ping Thing Batch
Ping Thing List
Ping Thing Stats
Sol Prices
Gossip Nodes
Error Codes
Requests Limits
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.

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":"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",
    "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/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 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":"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 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'

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 either 'testnet', 'mainnet' or 'pythnet' 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": "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": "GkxhyfXtiiwXgy51UcmJrXxv5Rrbf9vVgFCPVqkA5cdV",
    "name": "jasonmason67",
    "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'

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 either 'testnet', 'mainnet' or 'pythnet' 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":"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

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'

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 either 'testnet', 'mainnet' or 'pythnet' 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 endpoint will return prices.

Request:

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

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'

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'

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
429: Too Many Requests
500: Server Error (Admin has been notified)

Requests Limits:

Requests limit to our API is 40 or 25 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.

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!

API Documentation

Quick Reference

Authentication

Server Ping

Request:

Response:

Validators List

Request:

Parameter Options:

Response:

Validator Details

Request:

Parameter Options:

Response:

Validator Block Production History

Request:

Response:

Epochs

Request:

Parameter Options:

Response:

Commission Changes

Request:

Parameter Options:

Response:

Stake Pools

Request:

Response:

Stake Accounts

Request:

Parameter Options:

Response:

Ping Thing Post

Request:

Parameter Options:

Response:

Ping Thing Post Batch

Request:

Parameter Options:

Response:

Ping Thing List

Request:

Parameter Options:

Response:

Ping Thing Stats

Request:

Parameter Options:

Response:

Sol Prices

Request:

Parameter Options:

Response:

Gossip Nodes

Request:

Parameter Options:

Response:

Error Codes:

Requests Limits:

NOTES: