> For the complete documentation index, see [llms.txt](https://docs.luganodes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luganodes.com/apis/ethereum/data-apis.md).

# Data APIs

## Get Validator List

<mark style="color:blue;">`GET`</mark> `/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<mark style="color:red;">\*</mark> | String | API Key provided by Luganodes |

#### Query Params:

| Parameter Name        | Description                                                  | Type    |
| --------------------- | ------------------------------------------------------------ | ------- |
| page                  | Page number                                                  | integer |
| per\_page             | <p>Number of results per page<br>(Default: 10, Max: 100)</p> | integer |
| withdrawal\_addresses | Filter validators by withdrawal addresses                    | array   |
| pubkeys               | Filter validators by an array of pubkeys                     | array   |

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

```json
{
  "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
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The status history tracks the states the validator has transitioned through. An 'ACTIVE' validator will not include a 'WITHDRAWAL\_DONE' status in its history.
{% endhint %}

#### **Sample Request**

```bash
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

<table><thead><tr><th>Field Name</th><th width="249">Description</th><th>Type</th></tr></thead><tbody><tr><td>results</td><td>Array of validator objects</td><td>array</td></tr><tr><td>page</td><td>Current page</td><td>integer</td></tr><tr><td>per_page</td><td>Entries per page</td><td>integer</td></tr><tr><td>total</td><td>Total number of entries</td><td>integer</td></tr><tr><td>pages</td><td>Total number of pages</td><td>integer</td></tr></tbody></table>

#### 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

<mark style="color:blue;">`GET`</mark> `/api/rewards/overview`

Retrieves staking rewards overview data and staking APY statistics.

#### Header

| Name                                      | Type   | Description                   |
| ----------------------------------------- | ------ | ----------------------------- |
| api-key<mark style="color:red;">\*</mark> | String | API Key provided by Luganodes |

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

```json
{
  "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
}
```

{% endtab %}
{% endtabs %}

#### Sample request

```bash
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

<mark style="color:blue;">`GET`</mark> `/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<mark style="color:red;">\*</mark> | String | API Key provided by Luganodes |

#### Query Params

| Parameter Name                                 | Description                                        | Type    |
| ---------------------------------------------- | -------------------------------------------------- | ------- |
| start\_epoch<mark style="color:red;">\*</mark> | Epoch number to start query range                  | integer |
| end\_epoch<mark style="color:red;">\*</mark>   | Epoch number to end query range                    | integer |
| page                                           | Page number                                        | integer |
| per\_page                                      | Number of results per page (Default: 10, Max: 100) | integer |

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

```json
{
  "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
}

```

{% endtab %}
{% endtabs %}

#### Sample Request

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

#### Response Body

<table><thead><tr><th>Field Name</th><th width="249">Description</th><th>Type</th></tr></thead><tbody><tr><td>start_epoch</td><td>Starting epoch for rewards interval</td><td>integer</td></tr><tr><td>end_epoch</td><td>Ending epoch for rewards interval</td><td>integer</td></tr><tr><td>total_cl_rewards</td><td>Total consensus layer rewards earned in Gwei</td><td>string</td></tr><tr><td>total_el_rewards</td><td>Total execution layer rewards earned in Gwei</td><td>string</td></tr><tr><td>interval_summary</td><td>Array of per-epoch reward summary objects</td><td>array</td></tr><tr><td>page</td><td>Current page</td><td>integer</td></tr><tr><td>per_page</td><td>Entries per page</td><td>integer</td></tr><tr><td>total</td><td>Total number of entries</td><td>integer</td></tr><tr><td>pages</td><td>Total number of pages</td><td>integer</td></tr></tbody></table>

#### 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

<mark style="color:blue;">`GET`</mark> `/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<mark style="color:red;">\*</mark> | String | API Key provided by Luganodes |

#### Query Params

| Parameter Name                                | Description                                                  | Type    |
| --------------------------------------------- | ------------------------------------------------------------ | ------- |
| start\_date<mark style="color:red;">\*</mark> | Start date of reward aggregation period (format: YYYY-MM-DD) | string  |
| end\_date<mark style="color:red;">\*</mark>   | 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 |

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

```json
{
  "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
}

```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
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

<mark style="color:blue;">`GET`</mark> `/api/transactions`

Retrieves a list of transactions filtered optionally by validator pubkeys.

***

#### Header

| Name                                      | Type   | Description                   |
| ----------------------------------------- | ------ | ----------------------------- |
| api-key<mark style="color:red;">\*</mark> | 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 |

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

```json
{
  "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
}

```

{% endtab %}
{% endtabs %}

#### Sample Request

```bash
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 |