Data APIs

Data APIs for Ethereum

Get Validator List

GET /api/validators/list

Retrieves a list of validators optionally filtered by withdrawal address, or list of pubkeys. Returns an array of validator objects detailing balances, lifecycle, and validator info.

Header:

Name	Type	Description
api-key*	String	API Key provided by Luganodes

Query Params:

Parameter Name	Description	Type
page	Page number	integer
per_page	Number of results per page (Default: 10, Max: 100)	integer
withdrawal_addresses	Filter validators by withdrawal addresses	array
pubkeys	Filter validators by an array of pubkeys	array

200: OK

{
  "results": [
    {
      "validator": {
        "fee_recipient": "0xaaa112...",
        "network": "HOODI",
        "pubkey": "0xaaa113...",
        "beacon_status": "active_ongoing",
        "withdrawal_address": "0xaaa114...",
        "withdrawal_credentials": "0x020000...",
        "index": 118324,
        "balances": {
          "current_staked": "32000000000"
        },
        "lifecycle": {
          "status_history": [
            { "status": "CREATED", "time": "2025-10-17T18:17:11Z" },
            { "status": "DEPOSITED", "time": "2025-10-17T20:51:36Z" },
            { "status": "PENDING", "time": "2025-10-18T13:29:36Z" },
            { "status": "ACTIVE", "time": "2025-10-19T06:27:12Z" },
            { "status": "EXIT_REQUESTED", "time": "2025-10-20T17:26:24Z" },
            { "status": "EXITED", "time": "2025-10-21T21:10:24Z" },
            { "status": "WITHDRAWAL_DONE", "time": "2025-10-23T06:08:00Z" }
          ]
        }
      }
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 1,
  "pages": 1
}

The status history tracks the states the validator has transitioned through. An 'ACTIVE' validator will not include a 'WITHDRAWAL_DONE' status in its history.

Sample Request

curl --location '{{url}}/api/validators/list?page=1&per_page=5&withdrawal_addresses=["address1","address2"]&pubkeys=["pubkey1","pubkey2"]' \
--header 'api-key: --your-api-key--'

Response Body

Field Name	Description	Type
results	Array of validator objects	array
page	Current page	integer
per_page	Entries per page	integer
total	Total number of entries	integer
pages	Total number of pages	integer

Types:

Validator Object

Field Path	Description	Type
validator.fee_recipient	Address set for receiving rewards	string
validator.network	The blockchain network (e.g., "HOODI", "MAINNET")	string
validator.pubkey	Validator public key	string
validator.beacon_status	Current Beacon Status of the validator	string (enum)
validator.withdrawal_address	Withdrawal address	string
validator.withdrawal_credentials	Withdrawal credentials	string
validator.index	Validator Index	integer
validator.balances.current_staked	Validator’s current stake in Gwei	string
validator.lifecycle.status_history	Array of status objects with time stamps	array

Status History

Field Name	Description	Type
status	Validator status string	string (enum)
time	Timestamp of status entry	string (ISO8601)

Validator Status History Enum

Status	Description
CREATED	Validator was provisioned through Luganodes API
DEPOSITED	Deposit waiting to be seen by the blockchain
PENDING	Validator is in the queue waiting to go live
ACTIVE	Validator is participating and earning rewards
EXIT_REQUESTED	Exit has been requested by the client
EXITED	Validator has exited from the network
WITHDRAWAL_DONE	Withdrawal was successfully completed

Beacon Status Enum

Status	Description
pending_initialized	Validator is recognized but hasn’t met the deposit requirements
pending_queued	Validator has met deposit requirements and is waiting in the activation queue to become active
active_ongoing	Validator is actively participating in block and attestation duties on the Beacon Chain
active_exiting	Validator has requested to exit (via voluntary exit) and is waiting for the exit to process
active_slashed	Validator has been slashed for protocol violations but is still active until forced exit completes
exited_unslashed	Validator has successfully exited without being slashed and is no longer participating
exited_slashed	Validator has exited after being slashed for misconduct. No longer participates and may lose stake
withdrawal_possible	All withdrawals are now available; validator can move funds from the beacon chain to the execution layer
withdrawal_done	Validator’s funds have been fully withdrawn

Rewards Overview

GET /api/rewards/overview

Retrieves staking rewards overview data and staking APY statistics.

Header

Name	Type	Description
api-key*	String	API Key provided by Luganodes

200: OK

{
  "network": "MAINNET",
  "provider": "Luganodes",
  "total_active_stake": "30421572100000",
  "total_cl_rewards": "381412000",
  "total_el_rewards": "119607000",
  "apy_7d": 3.16,
  "apy_30d": 3.09,
  "apy_365d": 3.27
}

Sample request

curl --location '{{url}}/api/rewards/overview' \
--header 'api-key: --your-api-key--'

Response Body

Field Name	Description	Type
network	The blockchain network (e.g., "HOODI", "MAINNET")	string
provider	Name of staking provider	string
total_active_stake	Total ETH actively staked in Gwei	string
total_cl_rewards	Total consensus layer rewards in Gwei	string
total_el_rewards	Total execution layer rewards in Gwei	string
apy_7d	Annualized % yield across past 7 days (%)	number
apy_30d	Annualized % yield across past 30 days (%)	number
apy_365d	Annualized % yield across past 365 days (%)	number

Rewards: Epoch Wise

GET /api/rewards/epoch

Retrieves staking rewards for a range of epochs specified by start_epoch and end_epoch query parameters. Returns aggregated rewards and detailed validator reward breakdown per epoch.

Header

Name	Type	Description
api-key*	String	API Key provided by Luganodes

Query Params

Parameter Name	Description	Type
start_epoch*	Epoch number to start query range	integer
end_epoch*	Epoch number to end query range	integer
page	Page number	integer
per_page	Number of results per page (Default: 10, Max: 100)	integer

200: OK

{
  "start_epoch": 990011,
  "end_epoch": 990014,
  "total_cl_rewards": "16000000",
  "total_el_rewards": "32000000",
  "interval_summary": [
    {
      "epoch": 990011,
      "timestamp": "2025-10-20T06:08:00Z",
      "validators": [
        {
          "pubkey": "0xd85f01ef...",
          "index": 84312,
          "cl_reward": "31000000",
          "el_reward": "8000000"
        },
        {
          "pubkey": "0xab77a17c...",
          "index": 84313,
          "cl_reward": "29000000",
          "el_reward": "6000000"
        }
      ]
    }
  ],
  "page": 1,
  "per_page": 100,
  "total": 1,
  "pages": 1
}

Sample Request

curl --location '{{url}}/api/rewards/epoch?start_epoch=990011&end_epoch=990014' \
--header 'api-key: --your-api-key--'

Response Body

Field Name	Description	Type
start_epoch	Starting epoch for rewards interval	integer
end_epoch	Ending epoch for rewards interval	integer
total_cl_rewards	Total consensus layer rewards earned in Gwei	string
total_el_rewards	Total execution layer rewards earned in Gwei	string
interval_summary	Array of per-epoch reward summary objects	array
page	Current page	integer
per_page	Entries per page	integer
total	Total number of entries	integer
pages	Total number of pages	integer

Interval Summary Table

Field Name	Description	Type
epoch	Epoch number	integer
timestamp	UTC timestamp of the epoch	string(ISO 8601)
validators	Array of validator reward breakdown	array

Validator Reward Object

Field Name	Description	Type
pubkey	Validator public key	string
cl_reward	Consensus layer reward earned by validator in Gwei	string
el_reward	Execution layer reward earned by validator in Gwei	string
index	Validator index	integer

Rewards: Date Wise

GET /api/rewards/date

Retrieves staking rewards aggregated by date intervals. Supports aggregation intervals: 1d, 7d, 30d, filtered by start_date and end_date parameters.

Header

Name	Type	Description
api-key*	String	API Key provided by Luganodes

Query Params

Parameter Name	Description	Type
start_date*	Start date of reward aggregation period (format: YYYY-MM-DD)	string
end_date*	End date of reward aggregation period (format: YYYY-MM-DD)	string
interval*	Aggregation frequency: "1d", "7d", or "30d"	string
page	Page number	integer
per_page	Number of results per page (Default: 10, Max: 100)	integer

200: OK

{
  "start_date": "2025-10-20T00:00:00Z",
  "end_date": "2025-10-22T00:00:00Z",
  "total_cl_rewards": "402000000",
  "total_el_rewards": "93000000",
  "interval_summary": [
    {
      "date": "2025-10-20",
      "validators": [
        {
          "pubkey": "0xd85f01ef...",
          "index": 84312,
          "cl_reward": "21000000",
          "el_reward": "4000000"
        },
        {
          "pubkey": "0xab77a17c...",
          "index": 84313,
          "cl_reward": "19000000",
          "el_reward": "3000000"
        }
      ]
    }
  ],
  "page": 1,
  "per_page": 100,
  "total": 1,
  "pages": 1
}

Sample Request

curl --location '{{url}}/api/rewards/date?start_date=2025-10-02&end_date=2025-10-04&interval=1d' \
--header 'api-key: --your-api-key--'

Response Body

Field Name	Description	Type
start_date	Start date/time of aggregation window (ISO 8601)	string
end_date	End date/time of aggregation window (ISO 8601)	string
total_cl_rewards	Total consensus layer rewards in aggregation window in Gwei	string
total_el_rewards	Total execution layer rewards in aggregation window in Gwei	string
interval_summary	Array of intervals (daily, weekly, monthly) reward summaries	array
page	Current page	integer
per_page	Entries per page	integer
total	Total number of entries	integer
pages	Total number of pages	integer

Interval Summary Table

Field Name	Description	Type
date	Date representing the interval (YYYY-MM-DD)	string
validators	Array of validator reward objects for the interval	array

Validator Reward Object

Field Name	Description	Type
pubkey	Validator public key	string
cl_reward	Consensus layer reward earned by validator in Gwei	string
el_reward	Execution layer reward earned by validator in Gwei	string
index	Validator index	integer

Transactions

GET /api/transactions

Retrieves a list of transactions filtered optionally by validator pubkeys.

---

Header

Name	Type	Description
api-key*	String	API Key provided by Luganodes

Query Params

Parameter Name	Description	Type
pubkeys	Filter transactions by validator pubkeys (array)	array
page	Page number	integer
per_page	Number of results per page (Default: 10, Max: 100)	integer

200: OK

{
  "results": [
    {
      "transactionHash": "0xaaa...",
      "blockNumber": 662122,
      "blockTimestamp": 1750689480,
      "data": "0xaaa...",
      "fee": "102894",
      "from": "0xaaa...",
      "layer": "EXECUTION_LAYER",
      "type": "CONSOLIDATE",
      "pubkey": null,
      "sourcePubkey": "0xaaa...",
      "targetPubkey": "0xaaa...",
      "amount": null,
      "withdrawalAddress": "0xaaa...",
      "withdrawalCredentials": null,
      "to": "0xaaa..."
    },
    {
      "transactionHash": "0xbbb...",
      "blockNumber": 594779,
      "blockTimestamp": 1749816804,
      "data": "0xaaa...",
      "fee": "86157",
      "from": "0xaaa...",
      "layer": "EXECUTION_LAYER",
      "type": "PARTIAL_EXIT",
      "pubkey": "0xaaa...",
      "sourcePubkey": null,
      "targetPubkey": null,
      "amount": "10000000000",
      "withdrawalAddress": null,
      "withdrawalCredentials": null,
      "to": "0xaaa..."
    },
    {
      "transactionHash": "0xccc...",
      "blockNumber": 594641,
      "blockTimestamp": 1749815040,
      "data": "0xaaa...",
      "fee": "89400",
      "from": "0xaaa...",
      "layer": "EXECUTION_LAYER",
      "type": "PARTIAL_EXIT",
      "pubkey": "0xaaa...",
      "sourcePubkey": null,
      "targetPubkey": null,
      "amount": "120000000",
      "withdrawalAddress": null,
      "withdrawalCredentials": null,
      "to": "0xaaa..."
    },
    {
      "transactionHash": "0xddd...",
      "blockNumber": 2025644,
      "blockTimestamp": 1768336188,
      "data": "0xaaa...",
      "fee": "138609",
      "from": "0xaaa...",
      "layer": "EXECUTION_LAYER",
      "type": "FULL_WITHDRAWAL",
      "pubkey": "0xaaa...",
      "sourcePubkey": null,
      "targetPubkey": null,
      "amount": null,
      "withdrawalAddress": null,
      "withdrawalCredentials": null,
      "to": "0xaaa..."
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 6,
  "pages": 1
}

Sample Request

curl --location '{{url}}/api/transactions?pubkeys=["0xabc123","0xdef456"]&page=1&per_page=10' \
--header 'api-key: --your-api-key--'

Response Body

Field Name	Description	Type
results	Array of transaction objects	array
page	Current page	integer
per_page	Entries per page	integer
total	Total number of entries	integer
pages	Total number of pages	integer

Transaction Object

Field Name	Description	Type
transactionHash	Unique transaction hash	string
blockNumber	Block number for the transaction	integer
blockTimestamp	Timestamp of the block (Unix timestamp)	integer
data	Transaction data	string
fee	Transaction fee in gwei	string
from	Sender address	string
layer	Layer that the transaction was done on	string (enum)
type	Type of transaction	string (enum)
pubkey	Validator pubkey	string
sourcePubkey	Consolidation/Switch source validator pubkey	string
targetPubkey	Consolidation/Switch target validator pubkey	string
amount	Amount in Gwei	string
withdrawalAddress	Execution-layer withdrawal address for this validator	string
withdrawalCredentials	Consensus-layer withdrawal credentials (32‑byte value)	string
to	Recipient address	string

Transaction Types

Enum Value	Description
DEPOSIT	Initial or subsequent deposit of ETH to validator staking contract
PARTIAL_EXIT	Partial withdrawal of funds from the validator
FULL_WITHDRAWAL	Full withdrawal of all funds from the validator
CONSOLIDATE	Consolidation of two validators into a single 0x02 validator
SWITCH	Upgrade of validator withdrawal credentials to 0x02

Transaction Layers

Enum Value	Description
EXECUTION_LAYER	Transaction was done on the Execution Layer, or EL
CONSENSUS_LAYER	Transaction was done on the Consensus Layer, or CL