> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn how to authenticate, make your first request, and understand responses using the beaconcha.in V2 API — the recommended API for all new integrations.

The **V2 API** is the recommended API for all new integrations. It offers richer data, flexible validator selectors, cursor-based pagination, and exclusive features like [BeaconScore](/use-cases/performance-introduction) and [entity benchmarking](/use-cases/rank-and-compare-entities). The [V1 API](/api/v1-overview) remains available but no new features will be added to V1.

## Pricing

| Plan       | Price                                                        | Features       | Ratelimit                                                    | Requests  |
| ---------- | ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ | --------- |
| Free Trial | 0€ (30 days)                                                 | Basic          | 1/sec                                                        | 1000      |
| Hobbyist   | 59€/mo\*                                                     | Basic          | 1/sec                                                        | Unlimited |
| Business   | 99€/mo\*                                                     | Basic          | 2/sec                                                        | Unlimited |
| Scale      | 399€/mo\*                                                    | Basic & Pro 💎 | 5/sec                                                        | Unlimited |
| Enterprise | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Basic & Pro 💎 | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Unlimited |

\*Prices shown are for annual billing, excluding VAT

* **Free Trial:** Test the API with a 30-day free trial. The trial does not auto-renew; access ends after 30 days unless you upgrade. [Start your free trial and create an API key](https://beaconcha.in/user/api-key-management).
* **Access:** API endpoints require an API key. Free Trial and paid users have access to both V1 and V2 APIs.
* **Pro 💎 features:** available for users on the Scale and Enterprise plans.
* **Attribution:** See [API Terms and Conditions](/legal/api-terms) for details.

<Tip>
  **Building with AI?** Connect your AI assistant to our documentation via [AI Integration](/api/ai-integration). Get accurate, up-to-date answers about the beaconcha.in API directly in your development environment.
</Tip>

## Attribution Requirements

If you use beaconcha.in API data in your application or website, please follow these attribution guidelines:

### BeaconScore

After an agreement the BeaconScore badge may be required. See [API Terms and Conditions](/legal/api-terms) for details.

<Frame>
  <img src="https://mintcdn.com/bitflyexplorergmbh/u4FDQLNfRccMj2Kg/images/license-materials/beaconscore_black.svg?fit=max&auto=format&n=u4FDQLNfRccMj2Kg&q=85&s=af3f46de08814ba4df3fdea7290973a5" alt="BeaconScore" width="186" height="56" data-path="images/license-materials/beaconscore_black.svg" />
</Frame>

### Powered by beaconcha.in

After an agreement the "Powered by beaconcha.in" logo may be required. See [API Terms and Conditions](/legal/api-terms) for details.

<Frame>
  <img src="https://mintcdn.com/bitflyexplorergmbh/wvIFUZajcQb_cYrx/images/license-materials/poweredby_black.svg?fit=max&auto=format&n=wvIFUZajcQb_cYrx&q=85&s=9a3d6d39c5b4f1b1bf509fdf84a0040d" alt="Powered by beaconcha.in" width="277" height="56" data-path="images/license-materials/poweredby_black.svg" />
</Frame>

<Card title="License Materials" icon="download" href="/legal/license-materials">
  Download official BeaconScore and "Powered by beaconcha.in" badges in SVG and PNG formats
</Card>

For full terms and conditions, see our [BeaconScore License](/legal/beaconscore-license).

## API Keys

API keys can be obtained in the [user portal](https://beaconcha.in/user/api-key-management) and must be included in requests either as a query string parameter or in the request header.

<Note>
  V1 and V2 APIs use the same authentication method. A single API key is valid for all endpoints.
</Note>

## Quick Start — Your First Request

The simplest V2 API call is the [Chain State](/api-reference/ethereum/state) endpoint, which returns the current state of the Ethereum network with a single field in the request body:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST 'https://beaconcha.in/api/v2/ethereum/state' \
      -H 'Authorization: Bearer <YOUR_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{"chain": "mainnet"}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://beaconcha.in/api/v2/ethereum/state",
        headers={
            "Authorization": "Bearer <YOUR_API_KEY>",
            "Content-Type": "application/json"
        },
        json={"chain": "mainnet"}
    )
    print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await fetch("https://beaconcha.in/api/v2/ethereum/state", {
      method: "POST",
      headers: {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ chain: "mainnet" })
    });
    const data: { data: { current_epoch: number; total_validators: number } } = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch("https://beaconcha.in/api/v2/ethereum/state", {
      method: "POST",
      headers: {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ chain: "mainnet" })
    });
    const data = await response.json();
    console.log(data);
    ```
  </Tab>
</Tabs>

<Note>
  All V2 API endpoints use the `POST` method with a JSON request body. The `chain` field (`"mainnet"` or `"hoodi"`) is required in every request.
</Note>

## Full Example — Validator Rewards

This example uses the [Rewards](/api-reference/ethereum/validators/rewards-list) endpoint to get validator rewards data.

### Request

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators/rewards-list' \
      -H 'Authorization: Bearer <YOUR_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "validator": {
          "validator_identifiers": [1]
        },
        "chain": "mainnet",
        "page_size": 10,
        "epoch": 347566
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "<YOUR_API_KEY>"
    BASE_URL = "https://beaconcha.in"

    response = requests.post(
        f"{BASE_URL}/api/v2/ethereum/validators/rewards-list",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "validator": {"validator_identifiers": [1]},
            "chain": "mainnet",
            "page_size": 10,
            "epoch": 347566
        }
    )

    if response.status_code == 200:
        data = response.json()
        print(data)
    else:
        print(f"Error {response.status_code}: {response.json()}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const API_KEY = "<YOUR_API_KEY>";
    const BASE_URL = "https://beaconcha.in";

    interface RewardsResponse {
      data: Array<{
        validator: { index: number; public_key: string };
        total: string;
        total_reward: string;
        total_penalty: string;
      }>;
      paging: { next_cursor?: string };
    }

    async function getValidatorRewards(): Promise<RewardsResponse> {
      const response = await fetch(
        `${BASE_URL}/api/v2/ethereum/validators/rewards-list`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            validator: { validator_identifiers: [1] },
            chain: "mainnet",
            page_size: 10,
            epoch: 347566
          })
        }
      );

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API error ${response.status}: ${error.error}`);
      }

      return response.json();
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const API_KEY = "<YOUR_API_KEY>";
    const BASE_URL = "https://beaconcha.in";

    async function getValidatorRewards() {
      const response = await fetch(
        `${BASE_URL}/api/v2/ethereum/validators/rewards-list`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            validator: { validator_identifiers: [1] },
            chain: "mainnet",
            page_size: 10,
            epoch: 347566
          })
        }
      );

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API error ${response.status}: ${error.error}`);
      }

      return response.json();
    }
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "data": [
    {
      "total": "80660680222696592",
      "validator": {
        "index": 1,
        "public_key": "0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c"
      },
      "total_reward": "80660680222696592",
      "total_penalty": "0",
      "total_missed": "132644000000000",
      "attestation": {
        "total": "9371000000000",
        "head": {
          "total": "2408000000000",
          "reward": "2408000000000",
          "penalty": "0",
          "missed_reward": "0"
        },
        "source": {
          "total": "2437000000000",
          "reward": "2437000000000",
          "penalty": "0",
          "missed_reward": "0"
        },
        "target": {
          "total": "4526000000000",
          "reward": "4526000000000",
          "penalty": "0",
          "missed_reward": "0"
        },
        "inactivity_leak_penalty": "0",
        "inclusion_delay": null
      },
      "sync_committee": {
        "total": "0",
        "reward": "0",
        "penalty": "0",
        "missed_reward": "0"
      },
      "proposal": {
        "total": "80651309222696592",
        "execution_layer_reward": "35087332222696592",
        "attestation_inclusion_reward": "43946801000000000",
        "sync_inclusion_reward": "1617176000000000",
        "slashing_inclusion_reward": "0",
        "missed_cl_reward": "132644000000000",
        "missed_el_reward": "0"
      },
      "finality": "finalized"
    }
  ],
  "paging": {},
  "range": {
    "slot": {
      "start": 11122112,
      "end": 11122143
    },
    "epoch": {
      "start": 347566,
      "end": 347566
    },
    "timestamp": {
      "start": 1740289367,
      "end": 1740289750
    }
  }
}
```

<Card title="View Full API Documentation" icon="arrow-right" href="/api-reference/ethereum/validators/rewards-list">
  See all parameters, response fields, and try the Rewards endpoint
</Card>