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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.luganodes.com/apis/ethereum/data-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.