# Stakewiz API

## Welcome to Stakewiz API

Stakewiz is an analytics and utility website that serves the Solana ecosystem.

We aim to aggregate information about validators and the Solana network as a whole in order to provide helpful guidance to users seeking to stake their SOL.

As part of this we collate, aggregate and store large volumes of data, not all of which is available on-chain. This includes our Wiz Score which is a unique aggregated scoring system that combines over a dozen metrics into a single percentage score.

This API Reference lists out some of the public APIs we make available for anyone to use. Most of them can be accessed openly via a simple HTTPS GET request.

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:


# API Reference

The Stakewiz API is designed as an extremely simple and efficient RESTful API.

Currently the public API serves only GET requests and we don't yet support filtering and ordering parameters. We are working on adding this as well as improving error and edge case handling.


# Validators

A collection of API methods to get validator related data in JSON format.

## All validators

Receive a JSON object of all current validators, sorted by Wiz Score descending.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validators`

The list includes validators that have voted at least once this epoch or have non-zero active stake.

#### Query Parameters

| Name  | Type   | Description                                                                                               |
| ----- | ------ | --------------------------------------------------------------------------------------------------------- |
| sort  | String | takes most values as sort column, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Returns all validators by default, can be limited                                                         |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        "rank": 144,
        "identity": "LA1NEzryoih6CQW3gwQqJQffK2mKgnXcjSQZSRpM3wc",
        "vote_identity": "GE6atKoWiQ2pt3zL7N13pjNHjdLVys8LinG8qeJLcAiL",
        "last_vote": 140443868,
        "root_slot": 140443835,
        "credits": 39353597,
        "epoch_credits": 33802,
        "activated_stake": 5515852.324715695,
        "version": "1.10.26",
        "delinquent": false,
        "skip_rate": 15.350877192982,
        "updated_at": "2022-07-06 11:16:06.429249+00",
        "first_epoch_with_stake": 216,
        "name": "Laine \u2764\ufe0f stakewiz.com",
        "keybase": "laine_sa",
        "description": "Join our Discord at https:\/\/discord.gg\/3JXdTavv6x. We are a professional high-performance validator running on decentralized enterprise hardware. Available to answer any questions you have.",
        "website": "https:\/\/laine.co.za\/solana",
        "commission": 5,
        "image": "https:\/\/s3.amazonaws.com\/keybase_processed_uploads\/22db82203d02b0d0dd8dbbca00bb9b05_360_360.jpg",
        "ip_latitude": "50.1109221",
        "ip_longitude": "8.6821267",
        "ip_city": "Frankfurt",
        "ip_country": "Germany",
        "ip_asn": "AS54825",
        "ip_org": "Packet Host, Inc.",
        "mod": false,
        "is_jito": true,
        "jito_commission_bps": 800,
        "vote_success": 76.99,
        "vote_success_score": 15.4,
        "skip_rate_score": 2.25,
        "info_score": 10,
        "commission_score": 5,
        "first_epoch_distance": 109,
        "epoch_distance_score": 10,
        "stake_weight": 1.4,
        "above_halt_line": true,
        "stake_weight_score": 0,
        "withdraw_authority_score": 0,
        "asn": "AS54825",
        "asn_concentration": 4.98,
        "asn_concentration_score": -1.01,
        "uptime": 99.88,
        "uptime_score": 13.26,
        "wiz_score": 33.37,
        "version_valid": true,
        "city_concentration": 2.06,
        "city_concentration_score": -0.92,
        "invalid_version_score": 0,
        "superminority_penalty": -20,
        "score_version": 24,
        "no_voting_override": false,
        "epoch": 325,
        "epoch_slot_height": 43744,
        "asncity_concentration": 1.4,
        "asncity_concentration_score": -0.62,
        "stake_ratio": 0.5507,
        "credit_ratio": 77,
        "apy_estimate": 5.46
    },
    [...]
]
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Good to know:** The data is updated every minute and is cached on our side. The total response size ranges between 2.5-3MB. We recommend limiting how frequently you call this method within a page to avoid bad user experience.
{% endhint %}

## Specific validator

Receive a JSON object with data about a single validator.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator/{VOTE_IDENTITY}`

Specify the vote account public key of the validator you wish to retrieve.

#### Query Parameters

| Name | Type   | Description                                                                                                      |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| sort | String | takes most return values as sort column, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "rank": 144,
    "identity": "LA1NEzryoih6CQW3gwQqJQffK2mKgnXcjSQZSRpM3wc",
    "vote_identity": "GE6atKoWiQ2pt3zL7N13pjNHjdLVys8LinG8qeJLcAiL",
    "last_vote": 140443868,
    "root_slot": 140443835,
    "credits": 39353597,
    "epoch_credits": 33802,
    "activated_stake": 5515852.324715695,
    "version": "1.10.26",
    "delinquent": false,
    "skip_rate": 15.350877192982,
    "updated_at": "2022-07-06 11:16:06.429249+00",
    "first_epoch_with_stake": 216,
    "name": "Laine \u2764\ufe0f stakewiz.com",
    "keybase": "laine_sa",
    "description": "Join our Discord at https:\/\/discord.gg\/3JXdTavv6x. We are a professional high-performance validator running on decentralized enterprise hardware. Available to answer any questions you have.",
    "website": "https:\/\/laine.co.za\/solana",
    "commission": 5,
    "image": "https:\/\/s3.amazonaws.com\/keybase_processed_uploads\/22db82203d02b0d0dd8dbbca00bb9b05_360_360.jpg",
    "ip_latitude": "50.1109221",
    "ip_longitude": "8.6821267",
    "ip_city": "Frankfurt",
    "ip_country": "Germany",
    "ip_asn": "AS54825",
    "ip_org": "Packet Host, Inc.",
    "mod": false,
    "is_jito": true,
    "jito_commission_bps": 800,
    "vote_success": 76.99,
    "vote_success_score": 15.4,
    "skip_rate_score": 2.25,
    "info_score": 10,
    "commission_score": 5,
    "first_epoch_distance": 109,
    "epoch_distance_score": 10,
    "stake_weight": 1.4,
    "above_halt_line": true,
    "stake_weight_score": 0,
    "withdraw_authority_score": 0,
    "asn": "AS54825",
    "asn_concentration": 4.98,
    "asn_concentration_score": -1.01,
    "uptime": 99.88,
    "uptime_score": 13.26,
    "wiz_score": 33.37,
    "version_valid": true,
    "city_concentration": 2.06,
    "city_concentration_score": -0.92,
    "invalid_version_score": 0,
    "superminority_penalty": -20,
    "score_version": 24,
    "no_voting_override": false,
    "epoch": 325,
    "epoch_slot_height": 43744,
    "asncity_concentration": 1.4,
    "asncity_concentration_score": -0.62,
    "stake_ratio": 0.5507,
    "credit_ratio": 77,
    "apy_estimate": 5.46
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Good to know:** All data on the Stakewiz API is indexed by vote account, not validator identity.
{% endhint %}

## Validator delinquencies

Receive an array of the validator

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_delinquencies/{VOTE_IDENTITY}`

Delinquent minutes are rounded to the nearest full minute and grouped by UTC day.

#### Query Parameters

| Name  | Type   | Description                                                                                                |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------- |
| sort  | String | takes delinquent\_minutes or date, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Default return data is 30 days, can be limited to lower number of days with this parameter                 |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "delinquent_minutes": "17",
        "date": "2022-06-14"
    },
    {
        "delinquent_minutes": "0",
        "date": "2022-06-13"
    },
    {
        "delinquent_minutes": "1",
        "date": "2022-06-12"
    },
    {
        "delinquent_minutes": "1",
        "date": "2022-06-10"
    },
    {
        "delinquent_minutes": "3",
        "date": "2022-06-09"
    },
    {
        "delinquent_minutes": "1",
        "date": "2022-06-08"
    },
    {
        "delinquent_minutes": "1",
        "date": "2022-06-07"
    }
]
```

{% endtab %}
{% endtabs %}

## Validator total stake per epoch

Receive a JSON object of the validator

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_total_stakes/{VOTE_IDENTITY}`

Values are in SOL, ordered by epoch descending.

#### Query Parameters

| Name  | Type   | Description                                                                                                |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------- |
| sort  | String | takes epoch, stake or created\_at, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Default return data is 30 epochs, can be changed this parameter                                            |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "epoch": 325,
        "stake": 5515852.324715695
    },
    {
        "epoch": 324,
        "stake": 5511295.80789125
    },
    {
        "epoch": 323,
        "stake": 5501722.340971882
    },
    [...]
]
```

{% endtab %}
{% endtabs %}

## Validator stake changes (this epoch)

Receive a JSON Object with the validator

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_epoch_stakes/{VOTE_IDENTITY}`

Return total activating stake, total deactivating stake as well as the number of activating and deactivating stake accounts.

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "activating_stake": "176.200128326",
        "activating_count": 6,
        "deactivating_stake": "337.042753336",
        "deactivating_count": 3
    }
]
```

{% endtab %}
{% endtabs %}

## Validator stake changes with accounts (current epoch)

Receive a JSON Object with changing stake accounts for this epoch.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_epoch_stakes/{VOTE_IDENTITY}`

Returns the total activating and deactivating stake and number of stake accounts as well as the individual stake accounts.

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "activating": {
        "amount": 759.139385877,
        "count": 9,
        "stake_accounts": [
            {
                "pubkey": "HXH6XAJvxdj8enQcjsxLghpB8HiXjicaapVCX77Lznvj",
                "delegated_amount": "1.997717120",
                "activation_epoch": 458,
                "deactivation_epoch": 0
            },
           [...]
        ]
    },
    "deactivating": {
        "amount": 5019.019712812999,
        "count": 6,
        "stake_accounts": [
            {
                "pubkey": "CKf9mwZ3P9TUSLzGTT3uDZcRsDD6xgL7pkB27N6Qc2jr",
                "delegated_amount": "0.000000451",
                "activation_epoch": 220,
                "deactivation_epoch": 458
            },
            [...]
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Validator stake accounts

Get all stake accounts for a validator, includes deactivated stakes.&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_stakes/{VOTE_IDENTITY}`

#### Query Parameters

| Name  | Type   | Description                                                                                                                               |
| ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| sort  | String | takes wiz\_score, avg\_wiz\_score, score\_version or created\_at, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Default return data is 30 days, can be limited to number of values with this parameter                                                    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "pubkey": "...",
        "delegated_to": "...",
        "balance": 125005371,
        "credits_observed": 39319795,
        "delegated_stake": 111722491,
        "activation_epoch": 252,
        "stake_authority": "...",
        "withdraw_authority": "...",
        "rent_exempt_reserve": 2282880,
        "active_stake": 111722491,
        "created_at": "2021-12-14 22:25:51.128813+00",
        "updated_at": "2022-07-06 12:04:06.99867+00",
        "deactivation_epoch": 0
    },
    ...
]
```

{% endtab %}
{% endtabs %}

## Validator historic Wiz Scores (30 days)

Get all validator wiz scores for the past 30 days

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_wiz_scores/{VOTE_IDENTITY}`

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "wiz_score": "0.34105629915025",
        "avg_wiz_score": "0.37400066267243764",
        "created_at": "2022-07-06 12:05:05.35186+00",
        "score_version": 24
    },
    {
        "wiz_score": "0.34139202987286",
        "avg_wiz_score": "0.37413417148884576",
        "created_at": "2022-07-06 12:00:07.409659+00",
        "score_version": 24
    },
    {
        "wiz_score": "0.33584351685902",
        "avg_wiz_score": "0.3742660265227513",
        "created_at": "2022-07-06 11:55:05.392334+00",
        "score_version": 24
    },
    {
        "wiz_score": "0.33565442502329",
        "avg_wiz_score": "0.3744172407367429",
        "created_at": "2022-07-06 11:50:04.848568+00",
        "score_version": 24
    },
    {
        "wiz_score": "0.33737594839354",
        "avg_wiz_score": "0.3745686764086684",
        "created_at": "2022-07-06 11:45:05.344011+00",
        "score_version": 24
    },
    ...
]
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Good to know:** The historic wiz scores include the cluster average for each data point for comparison.
{% endhint %}

## Validator historic vote success (30 days)

Get vote success rates for the past 30 days

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_vote_success/{VOTE_IDENTITY}`

#### Query Parameters

| Name  | Type   | Description                                                                                                 |
| ----- | ------ | ----------------------------------------------------------------------------------------------------------- |
| sort  | String | takes vote\_success or created\_at, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Default return data is 30 days, can be limited to number of values with this parameter                      |

{% tabs %}
{% tab title="200: OK " %}

```json
[
    {
        "vote_success": "0.94580298364118",
        "created_at": "2023-06-07 11:35:27.434722+00"
    },
    {
        "vote_success": "0.9457769685846",
        "created_at": "2023-06-07 11:30:29.726574+00"
    },
    {
        "vote_success": "0.94589480254896",
        "created_at": "2023-06-07 11:25:25.463367+00"
    },
    [...]
]
```

{% endtab %}
{% endtabs %}

## Validator historic skip rate (30 days)

Get skip rate for the past 30 days

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/validator_skip_rate/{VOTE_IDENTITY}`

#### Query Parameters

| Name  | Type   | Description                                                                                              |
| ----- | ------ | -------------------------------------------------------------------------------------------------------- |
| sort  | String | takes skip\_rate or created\_at, sorts ascending, prepend a minus to sort descending (e.g. -created\_at) |
| limit | String | Default return data is 30 days, can be limited to number of values with this parameter                   |

{% tabs %}
{% tab title="200: OK " %}

```json
[
    {
        "skip_rate": "0.95238095238095",
        "created_at": "2023-06-07 11:40:31.453009+00"
    },
    {
        "skip_rate": "0.95238095238095",
        "created_at": "2023-06-07 11:35:27.434722+00"
    },
    {
        "skip_rate": "0.95238095238095",
        "created_at": "2023-06-07 11:30:29.726574+00"
    },
    [...]
]
```

{% endtab %}
{% endtabs %}


# Cluster statistics

## Cluster statistics

Get latest cluster statistics, these are averages of key metrics used by stakewiz.com

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/cluster_stats`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "avg_credit_ratio": 70.83,
    "avg_activated_stake": 133033,
    "avg_commission": 9.5,
    "avg_skip_rate": 18.4,
    "avg_apy": 5.14
}
```

{% endtab %}
{% endtabs %}


# Wiz Score

## Wiz Score weightings

Get the current score and its weightings

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/wiz_score`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "vote_success_weight": 0.2,
    "skip_rate_weight": 0.2,
    "skip_rate_cutoff_multiplier": 1,
    "min_versions": [
        "1.10.25"
    ],
    "invalid_version_penalty": -0.2,
    "info_weight": 0.1,
    "max_commission": 10,
    "commission_weight": 0.10,
    "epoch_distance_max": 30,
    "epoch_distance_weight": 0.1,
    "stake_weight_threshold": 0.1,
    "stake_weight_weight": 0.15,
    "withdraw_authority_penalty": -0.2,
    "asn_concentration_weight": -0.066,
    "city_concentration_weight": -0.066,
    "asn_city_concentration_weight": -0.066,
    "uptime_weight": 0.15,
    "uptime_cutoff": 0.99,
    "superminority_penalty": -0.2,
    "score_version": 24
}
```

{% endtab %}
{% endtabs %}


# Epoch

## Epoch Info (current epoch)

Receive a JSON object with information for the current epoch

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/epoch_info`

Includes start time and slot, current slot height, epoch duration in seconds as well as seconds elapsed and remaining in the epoch, and the estimated epochs per year based on this epoch's current estimated duration.

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "epoch": 353,
    "start_slot": 152496000,
    "start_time": "2022-09-26 15:13:55.35934+00",
    "slot_height": 127916,
    "duration_seconds": 236696,
    "elapsed_seconds": 70157,
    "remaining_seconds": 166539,
    "epochs_per_year": 133.32544698685234
}
```

{% endtab %}
{% endtabs %}

## Epoch history (any epoch)

Receive a JSON object with information on a past epoch.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/epoch_history/{EPOCH}`

Includes start and end times as well as its duration in seconds.\
\
If the epoch passed is the current epoch the end time and duration are estimates based on average slot times in the current epoch.

Returns false if the epoch isn't found (HTTP 200 OK with payload of false). Some historical epochs don't have block times available to provide start and end times.&#x20;

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "epoch": 340,
    "start_time": "2022-08-20 19:30:01.763991+00",
    "end_time": "2022-08-23 15:53:01.337229+00",
    "duration_seconds": 246180
}
```

{% endtab %}
{% endtabs %}

## Epoch history (all epochs)

Receive a JSON object with all available historical epochs.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/all_epochs_history`

Returns all available historical epochs with their start and end times as well as duration in seconds.

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "epoch": 353,
        "start": "2022-09-26 15:13:55.35934+00",
        "end": "2022-09-29 08:54:20+00",
        "duration_seconds": 236425
    },
    {
        "epoch": 352,
        "start": "2022-09-24 00:22:01.95102+00",
        "end": "2022-09-26 15:13:02+00",
        "duration_seconds": 226261
    },
    {
        "epoch": 351,
        "start": "2022-09-21 04:41:01.679778+00",
        "end": "2022-09-24 00:21:01.973181+00",
        "duration_seconds": 243600
    },
    [...]
]
```

{% endtab %}
{% endtabs %}


# Other

## Stakes by withdraw authority

Get all validators that a particular wallet (withdraw authority of a stake account) has active delegations to.

<mark style="color:blue;">`GET`</mark> `https://api.stakewiz.com/stake_validators_by_withdraw_authority/{PUBLIC_KEY}`

Returns the vote accounts of the validators, only considers active stakes.

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    "1234LB7uvDC23rdCQoK8C3jNwnovUNyeKxz8wC3dghJ5",
    "12pVREJSt8d5AV4aBzGFf3QZn3qo8DWmwBQu3wQ5RAZ9",
    "13fUogQP3K8jAWgSW5gji5NyqHFprwoW3xVRs9MpLqdp"
    ...
]
```

{% endtab %}
{% endtabs %}


# Usage & Attribution

### Usage & rate limits

This API is open to the public and does not require any authentication, tokens or registration.

While we don't currently enforce rate-limits and have done our best to cache relevant data server-side, please don't abuse the API. If we notice performance degradation due to increased usage we may need to implement rate limits.

The API was built first and foremost to serve the needs of stakewiz.com. As such it might not always serve the intuitive objective use case for a particular method. Over time our goal is to make the API more neutral, offer additional filters and sort options and provide a robust and generic window into our data.

{% hint style="info" %}
We may introduce token-based authentication in future, we recommend you reach out and let us know that you're using our API so we can communicate any future changes with you.
{% endhint %}

### Attribution

If you are building a dapp, tool, website etc that uses our API we would appreciate if you would reference this on your site.

This can be a note in your footer or "Powered by Stakewiz", feel free to use these logos as well:

<figure><img src="/files/9HjGAlZMxjpLyV8umGSS" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/ZBp7MZHPAlFaLtNS2y7E" alt=""><figcaption></figcaption></figure>