Getting Started

To start using Staking Data API, get an authentication token.

The section provides the examples of how to interact with the API for Ethereum data.

Response format

Every response is a JSON envelope with result and error. On success, result holds the payload and error is empty. On failure, result is null and error contains code, message, name, and type. Error responses also include requestId (the value of the x-request-id header) and timestamp. Quote requestId when contacting support so the request can be found in the server logs.

Error response

{
  "error": {
    "code": 100101,
    "message": "The data provided is not valid. Please check the request parameters and try again.",
    "name": "ValidationException",
    "type": "client"
  },
  "result": null,
  "requestId": "90c16e9e-6e99-4651-a033-60290356df2f",
  "timestamp": "2026-05-20T22:29:03.126Z"
}

Paginated endpoints accept limit (from 1 to 1000, default 50) and offset (default 0). Endpoints that accept startAt and finishAt reject a range longer than 31 days, and finishNumber must not be lower than startNumber. Not every endpoint is available on every network; see the Supported networks line for each method on the Network, Validator, and Delegator pages.

Using curl commands

Request examples are provided using cURL. To demonstrate the API usage scenarios, the examples cover:

retrieving the last staking period,
fetching active stakes for validators,
checking validator states,
obtaining rewards by type.

Get Last Staking Period

To retrieve the last staking period, send a GET request to /api/v1/{network}/data/network/last-staking-period. Example request:

curl --request GET \
    --url https://api.p2p.org/api/v1/ethereum/data/network/last-staking-period \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <token>'

const response = await fetch("https://api.p2p.org/api/v1/ethereum/data/network/last-staking-period", {
  headers: {
    "authorization": "Bearer <token>",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.p2p.org/api/v1/ethereum/data/network/last-staking-period",
    headers={
        "authorization": "Bearer <token>",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.p2p.org/api/v1/ethereum/data/network/last-staking-period", nil)
	req.Header.Set("authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response:

{
    "result": {
      "period": 244333,
      "updatedAt": "2023-08-24T08:23:18.830Z"
    },
    "error": {}
  }

period — last staking period.
updatedAt — timestamp of the last update to the queue.

Get Delegator Stake

To fetch the stake of a delegator for each validator, send a GET request to /api/v1/{network}/data/delegator/stakes. Note that there is a list of additional query params. Example request:

curl --request GET \
    --url 'https://api.p2p.org/api/v1/ethereum/data/delegator/stakes?startNumber=298991&finishNumber=298991&limit=1000&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit' \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <token>'

const response = await fetch("https://api.p2p.org/api/v1/ethereum/data/delegator/stakes?startNumber=298991&finishNumber=298991&limit=1000&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit", {
  headers: {
    "authorization": "Bearer <token>",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.p2p.org/api/v1/ethereum/data/delegator/stakes?startNumber=298991&finishNumber=298991&limit=1000&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit",
    headers={
        "authorization": "Bearer <token>",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.p2p.org/api/v1/ethereum/data/delegator/stakes?startNumber=298991&finishNumber=298991&limit=1000&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit", nil)
	req.Header.Set("authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

startNumber — start number of the staking period.
finishNumber — finish number of the staking period. Cannot be lower than startNumber.
limit — number of resources that a single response page contains.
address — delegator address in the required network.
addressType — delegator address type in the required network. If omitted, the default for the network is used:
- deposit — Ethereum (default).
- withdrawal — Ethereum.
- delegator — Solana (default), Sui, Cardano, Celestia.
- stake_account — Solana.
- nominator — Polkadot (default), Kusama (default), TON.
- nominator_reward_account — Polkadot, Kusama.
Passing an addressType that the network does not support returns 400.
validatorAddress — validator address in the required network for this delegator.
groupBy — group the output data: stakingPeriod, day, or all. day cannot be combined with startNumber / finishNumber; use startAt / finishAt instead, otherwise the request returns 400.
skip — set to validator to exclude the breakdown by validator from the report.

Example response:

{
    "result": {
      "limit": 50,
      "offset": 0,
      "list": [
        {
          "stakingPeriod": 298991,
          "stakingPeriodStart": "2023-11-01T06:43:17.000Z",
          "stakingPeriodEnd": "2020-11-01T07:12:27.000Z",
          "stake": 1.82282,
          "validator": "0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17"
        }
      ]
    },
    "error": {}
  }

limit — number of resources that a single response page contains.
offset — number of resources to exclude from the beginning of a response.
list:
- stakingPeriod — number of the staking period.
- stakingPeriodStart — timestamp of the staking period start in the ISO 8601 format.
- stakingPeriodEnd — timestamp of the staking period finish in the ISO 8601 format.
- stake — total stake balance of the delegator. On Ethereum this includes ETH that is still in the deposit or activation queue.
- activeStake — optional; Ethereum only, returned only with groupBy=day. The part of stake that is already active on the Beacon Chain.
- inactiveStake — optional; Ethereum only, returned only with groupBy=day. The part of stake that is still waiting to be activated.
- validator — validator address.

Get Validator State and Statuses

To retrieve validator state, send a GET request to /api/v1/{network}/data/validator/state. Example request:

curl --request GET \
    --url 'https://api.p2p.org/api/v1/ethereum/data/validator/state?address=0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17' \
    --header 'accept: application/json' \
    --header 'authorization: Bearer <token>'

const response = await fetch("https://api.p2p.org/api/v1/ethereum/data/validator/state?address=0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17", {
  headers: {
    "authorization": "Bearer <token>",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.p2p.org/api/v1/ethereum/data/validator/state?address=0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17",
    headers={
        "authorization": "Bearer <token>",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.p2p.org/api/v1/ethereum/data/validator/state?address=0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17", nil)
	req.Header.Set("authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

address — validator address in the required network. For the Ethereum network, it is a public validator key.

Example response:

{
    "result": {
      "state": "string",
      "activatedAt": "string",
      "activatedStakingPeriodNum": 0
    },
    "error": {}
  }

state — validator state.
activatedAt — timestamp of the validator activated date in the ISO 8601 format.
activatedStakingPeriodNum — timestamp of the validator activated staking period.

You can also retrieve the information about validator statuses by sending a GET request to /api/v1/{network}/data/validator/statuses . Example request:

curl --request GET \
     --url https://api.p2p.org/api/v1/ethereum/data/validator/statuses \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'

const response = await fetch("https://api.p2p.org/api/v1/ethereum/data/validator/statuses", {
  headers: {
    "authorization": "Bearer <token>",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.p2p.org/api/v1/ethereum/data/validator/statuses",
    headers={
        "authorization": "Bearer <token>",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.p2p.org/api/v1/ethereum/data/validator/statuses", nil)
	req.Header.Set("authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response:

{
    "result": {
      "total": 3,
      "by_status": [
        {
          "pending_initialized": 0,
          "pending_queued": 0,
          "active_ongoing": 2,
          "active_slashed": 0,
          "exited_unslashed": 0,
          "exited_slashed": 0,
          "withdrawal_possible": 1,
          "withdrawal_done": 0
        }
      ]
    },
    "error": {}
  }

total — total count of validators.
by_status:
- pending_initialized — number of validators which are initialized but not yet in the queue for activation.
- pending_queued — number of validators that entered a queue for activation.
- active_ongoing — number of validators that were activated and currently participate in attesting and proposing blocks.
- active_slashed — number of validators that were slashed due to misbehaviors.
- exited_unslashed — number of validators that have exited the network without being slashed and are no longer acting as validators.
- exited_slashed — number of validators that have exited the network after being slashed and are no longer acting as validators.
- withdrawal_possible — number of validators having a non-zero balance.
- withdrawal_done — number of validators completed the withdrawal process.

Get Delegator Rewards

To fetch a list of delegators rewards by type, send a GET request to /api/v1/{network}/data/delegator/rewards. Note that there is a list of additional query params, e.g., grouping the data by date. Example request:

curl --request GET \
     --url 'https://api.p2p.org/api/v1/ethereum/data/delegator/rewards?startAt=2024-07-01T00%3A00%3A00&finishAt=2024-07-23T00%3A00%3A00&limit=100&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit&groupBy=day' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>'

const response = await fetch("https://api.p2p.org/api/v1/ethereum/data/delegator/rewards?startAt=2024-07-01T00%3A00%3A00&finishAt=2024-07-23T00%3A00%3A00&limit=100&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit&groupBy=day", {
  headers: {
    "authorization": "Bearer <token>",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://api.p2p.org/api/v1/ethereum/data/delegator/rewards?startAt=2024-07-01T00%3A00%3A00&finishAt=2024-07-23T00%3A00%3A00&limit=100&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit&groupBy=day",
    headers={
        "authorization": "Bearer <token>",
    },
)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.p2p.org/api/v1/ethereum/data/delegator/rewards?startAt=2024-07-01T00%3A00%3A00&finishAt=2024-07-23T00%3A00%3A00&limit=100&address=0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb&addressType=deposit&groupBy=day", nil)
	req.Header.Set("authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

startAt — timestamp of the report data period start in the ISO 8601 format. If not specified, the default value is the one month ago.
finishAt — timestamp of the report data period finish in the ISO 8601 format. If not specified, the default value is the current date.
limit — number of resources that a single response page contains.
address — delegator address in the required network.
addressType — delegator address type in the required network. If omitted, the default for the network is used:
- deposit — Ethereum (default).
- withdrawal — Ethereum.
- delegator — Solana (default), Sui, Cardano, Celestia.
- stake_account — Solana.
- nominator — Polkadot (default), Kusama (default), TON.
- nominator_reward_account — Polkadot, Kusama.
Passing an addressType that the network does not support returns 400.
validatorAddress — validator address in the required network for this delegator.
groupBy — group the output data:
- stakingPeriod — aggregate the results by epoch.
- day — aggregate the results by days.
- all — aggregate the results over the entire period.
skip — set to validator to exclude the breakdown by validator from the report.
rewardTypes — filter rewards by type. Pass a single value or repeat the key (?rewardTypes=consensus&rewardTypes=execution). Some networks exclude certain reward types by default; pass rewardTypes=all to return every type.

Example response:

{
    "result": {
      "limit": 50,
      "offset": 0,
      "list": [
        {
          "stakingPeriod": 298991,
          "stakingPeriodStart": "2023-11-01T06:43:17.000Z",
          "stakingPeriodEnd": "2020-11-01T07:12:27.000Z",
          "rewards": [
            {
              "type": "consensus",
              "amount": 0.63722,
              "currency": "ETH",
              "recipient": "string"
            }
          ]
        }
      ]
    },
    "error": {}
  }

limit — number of resources that a single response page contains.
offset — number of resources to exclude from the beginning of a response.
list:
- stakingPeriod — number of the staking period.
- stakingPeriodStart — timestamp of the staking period start in the ISO 8601 format.
- stakingPeriodEnd — timestamp of the staking period finish in the ISO 8601 format.
- rewards:
  - type — rewards type: consensus or execution.
  - amount — amount of tokens in the stake.
  - currency — currency of the tokens.
  - recipient — rewards recipient address.

Using Python code

This section demonstrates how to use Python with the Staking Data API. The examples for Ethereum data cover:

fetching the delegator daily rewards,
retrieving the summary for a delegator and validator.

Get Delegator Rewards

To fetch the daily rewards for a delegator, use the following code with the API endpoint /api/v1/{network}/data/delegator/rewards:

import requests
import datetime
import pickle

# API endpoint.
API_URL = 'https://api.p2p.org/api/v1/ethereum/data/delegator/rewards'

# Include your Bearer token for authentication and specify the delegator address.
ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'
DELEGATOR_ADDRESS = 'DELEGATOR_ADDRESS'

def fetch_rewards_for_date(session, date, address):
    """Fetch rewards for a specific date."""
    params = {
        'startAt': date.strftime('%Y-%m-%dT00:00:00') ,# Start time in the ISO 8601 format for each day.
        'finishAt': (date + datetime.timedelta(days=1)).strftime('%Y-%m-%dT00:00:00'), # Finish time in the ISO 8601 format for the next day.
        'limit': 1000, # Number of resources per page.
        'offset': 0, # Number of resources to exclude from the beginning; the default value is 0.
        'address': address, # Delegator address in the Ethereum network.
        'addressType': 'deposit', # Delegator address type in the required network. For Ethereum it can be `deposit` or `withdrawal`.
        'skip': 'validator', # Excludes breakdown by validator from the data report. To include validator, specify the empty value.
        'groupBy': 'stakingPeriod' # Group the results by `stakingPeriod`, `day` or `all` (the entire period).
    }

    rewards = []
    while True:
        try:
            response = session.get(API_URL, params=params)
            response.raise_for_status()
            result = response.json()
            new_rows = result.get('result', {}).get('list', [])

            if new_rows:
                rewards.extend(new_rows)
                params['offset'] += 1000
            else:
                break

        except requests.RequestException as e:
            print(f"An error occurred: {e}")
            break

    return rewards

def main():
    # Setup session
    session = requests.Session()
    session.headers.update({'Authorization': f'Bearer {ACCESS_TOKEN}'})

    # Define date range
    start_date = datetime.date(year=2024, month=1, day=1)
    end_date = datetime.date.today()
    date_range = (start_date + datetime.timedelta(days=d) for d in range((end_date - start_date).days + 1))

    all_rewards = []

    # Fetch rewards for each date
    for date in date_range:
        print(f"Fetching rewards for {date}")
        daily_rewards = fetch_rewards_for_date(session, date, DELEGATOR_ADDRESS)
        all_rewards.extend(daily_rewards)

    # Save rewards to file
    with open('dump.pkl', 'wb') as file:
        pickle.dump(all_rewards, file)

    # Calculate total amount
    total_amount = sum(reward['amount'] for epoch in all_rewards for reward in epoch.get('rewards', []))

    print(f"Total Amount: {total_amount}")

if __name__ == '__main__':
    main()

This script gathers daily rewards data from a start date to the current date, saves the data to a file, and calculates the total rewards amount.

Get Delegator Summary

To fetch the lifetime stake, rewards, and APY for a delegator, use the following code with the API endpoint /api/v1/{network}/data/delegator/summary:

import requests

# API endpoint.
url = "https://api.p2p.org/api/v1/{network}/data/delegator/summary"

# Include your Bearer token for authentication.
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

# Specify the following parameters:
params = {
    "address": "0x338EF19fA2eC0fc4d1277B1307a613fA1FBbc0cb", # Delegator address.
    "addressType": "deposit", # Delegator address type in the required network. For Ethereum it can be `deposit` or `withdrawal`.
    "network": "ethereum",  # Network name.
    "startAt": "2024-04-17T15:00:00.000Z",  # Report data start time in the ISO 8601 format.
    "finishAt": "2024-04-19T15:00:00.000Z",  # Report data finish time in the ISO 8601 format.
    "groupBy": "all",  # Aggregate the results by `stakingPeriod` or `day`. To aggregate the results for the entire period, set `all`.
    "skip": "validator"  # Exclude breakdown by validator from the report. To include validators in the output, remove the parameter or pass an empty value.
}

try:
    # Make the request.
    response = requests.get(url.format(network=params["network"]), headers=headers, params=params)

    # Check the response status.
    response.raise_for_status()

    # Parse the JSON response.
    data = response.json()

    # Check if the response contains data.
    if data and "result" in data:
        print("Delegator Summary:")
        print("Gross APY:", data["result"]["list"][0]["grossApy"])
        print("Net APY:", data["result"]["list"][0]["netApy"])
        print("Stake:", data["result"]["list"][0]["stake"], data["result"]["list"][0]["currency"])
        print("Rewards:")
        for reward in data["result"]["list"][0]["rewards"]:
            print("Type:", reward["type"])
            print("Amount:", reward["amount"], reward["currency"])
            print("---")
    else:
        print("Empty response received.")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except requests.exceptions.RequestException as req_err:
    print(f"Request exception occurred: {req_err}")
except ValueError as val_err:
    print(f"Value error occurred: {val_err}")
except Exception as err:
    print(f"Other error occurred: {err}")

Example output (with breaking down the result by validators):

Gross APY: 0.0312
Net APY: 0.0287
Stake: 1411 ETH
Rewards: 
  Type: consensus
  Amount: 5.195236601009028 ETH
  ---
  Type: execution
  Amount: 1.188704036616951 ETH
  ---

Gross APY — delegator annual percentage yield (APY) before the validator fee (grossApy).
Net APY — delegator APY after the validator fee (netApy).
Stake — total stake balance of the delegator.
Rewards:
- Type — rewards type: consensus or execution.
- Amount — amount of tokens in the stake.

Get Validator Summary

To retrieve the validator summary, use the following code with the API endpoint /api/v1/{network}/data/validator/summary:

import requests

# API endpoint.
url = "https://api.p2p.org/api/v1/{network}/data/validator/summary"

# Include your Bearer token for authentication.
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

# Specify the following parameters:
params = {
    "address": "0x39D02C253dA1d9F85ddbEB3B6Dc30bc1EcBbFA17",  # Validator address in the required network. For the Ethereum network, it is a public validator key.
    "network": "ethereum",  # Network name.
    "startAt": "2024-04-17T15:00:00.000Z",  # Report data start time in the ISO 8601 format.
    "finishAt": "2024-04-19T15:00:00.000Z",  # Report data finish time in the ISO 8601 format.
    "limit": 50,  # Number of resources that a single response page contains.
    "offset": 0  # Number of resources to exclude from the beginning of a response.
}

try:
    # Make the request.
    response = requests.get(url.format(network=params["network"]), headers=headers, params=params)

    # Check the response status.
    response.raise_for_status()

    # Parse the JSON response.
    data = response.json()

    # Check if the response contains data.
    if data and "result" in data:
        validator_summary = data["result"]

        # Print the validator summary information.
        print("Validator Summary:")
        print("---")

        # Iterate over each item in the list.
        for item in validator_summary["list"]:
            print("Staking Period:", item["stakingPeriod"])
            print("Start:", item["stakingPeriodStart"])
            print("End:", item["stakingPeriodEnd"])
            print("APY:", item["apy"])
            print("Stake:", item["stake"], "ETH")

            # Print the rewards information.
            print("Rewards:")
            for reward in item["rewards"]:
                print("Amount:", reward["amount"], reward["currency"])
            print("---")

    else:
        print("Empty response received.")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except requests.exceptions.RequestException as req_err:
    print(f"Request exception occurred: {req_err}")
except ValueError as val_err:
    print(f"Value error occurred: {val_err}")
except Exception as err:
    print(f"Other error occurred: {err}")

Example output (without breaking down the results by validators):

Validator Summary:
---
Staking Period: 277903
Start: 2024-04-19 14:59:35
End: 2024-04-19 15:05:59
APY: 0.024850512
Stake: 32.01709 ETH
Rewards:
  Amount: 9.683e-06 ETH
  ---
  Staking Period: 277902
  Start: 2024-04-19 14:53:11
  End: 2024-04-19 14:59:35
  APY: 0.024770953
  Stake: 32.01708 ETH
  Rewards:
  Amount: 9.652e-06 ETH
  ---

Staking Period — number of the staking period.
Start and End — timestamp of the staking period start and finish in the ISO 8601 format.
APY — validator annual percentage yield (APY).
Stake — total stake balance of the validator.
Rewards:
- Amount — amount of tokens in the stake.

Introduction

Using AI Tools

API Products

Widget

Syncro Products

SDK Products

Deep Dive

Support

Getting Started

Response format

Using curl commands

Get Last Staking Period

Get Delegator Stake

Get Validator State and Statuses

Get Delegator Rewards

Using Python code

Get Delegator Rewards

Get Delegator Summary

Get Validator Summary

​Response format

​Using curl commands

​Get Last Staking Period

​Get Delegator Stake

​Get Validator State and Statuses

​Get Delegator Rewards

​Using Python code

​Get Delegator Rewards

​Get Delegator Summary

​Get Validator Summary

Response format

Using curl commands

Get Last Staking Period

Get Delegator Stake

Get Validator State and Statuses

Get Delegator Rewards

Using Python code

Get Delegator Rewards

Get Delegator Summary

Get Validator Summary