# /v1/beacon/states/{state_id}/validator_balances

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

GET https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/{state_id}/validator_balances

Returns a filterable list of validator balances.   Balances will be returned for all indices or public keys that match known validators.   If an index or public key does not match any known validator, no balance will be returned,   but this will not cause an error.   The response does not guarantee ordering, so the `index` should be used to match inputs.


Reference: https://www.alchemy.com/docs/chains/ethereum/ethereum-beacon-api-endpoints/ethereum-beacon-api-endpoints/v-1-beacon-states-state-id-validator-balances

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| state_id | string | Yes | State identifier.   Can be one of:   `head` (canonical head in node's view),   `genesis`,   `finalized`,   `justified`,   `<slot>`,   `<hex encoded stateRoot with 0x prefix>`.  |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string[] | No | Optional filter: hex-encoded validator public key (`bytes48` with 0x prefix)   or validator index. Multiple values can be provided.  |

## Code Examples

### cURL

```bash
curl --request GET \
  --url https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances
```

### JavaScript

```javascript
const options = {method: 'GET'};

fetch('https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances"

response = requests.get(url)

print(response.text)
```

### Go

```go
package main

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

func main() {

	url := "https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

### Java

```java
HttpResponse<String> response = Unirest.get("https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances")
  .asString();
```

### C#

```csharp
using RestSharp;


var options = new RestClientOptions("https://eth-mainnetbeacon.g.alchemy.com/v2/docs-demo/eth/v1/beacon/states/head/validator_balances");
var client = new RestClient(options);
var request = new RestRequest("");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

```


## Operation Specification

```yaml
path: /eth/v1/beacon/states/{state_id}/validator_balances
method: GET
operation:
  summary: /v1/beacon/states/{state_id}/validator_balances
  description: |
    Returns a filterable list of validator balances.   Balances will be returned for all indices or public keys that match known validators.   If an index or public key does not match any known validator, no balance will be returned,   but this will not cause an error.   The response does not guarantee ordering, so the `index` should be used to match inputs.
  tags:
    - Ethereum Beacon API Endpoints
  security:
    - apiKey: []
  parameters:
    - name: state_id
      in: path
      required: true
      schema:
        type: string
        example: head
      description: |
        State identifier.   Can be one of:   `head` (canonical head in node's view),   `genesis`,   `finalized`,   `justified`,   `<slot>`,   `<hex encoded stateRoot with 0x prefix>`.
    - name: id
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          example: '0x8c5a8efa6e472c358dd7024fae6f6569cd60af754591ddc78ef9e9db287aa68c'
      description: |
        Optional filter: hex-encoded validator public key (`bytes48` with 0x prefix)   or validator index. Multiple values can be provided.
  responses:
    '200':
      description: Validator balances for the given state.
      content:
        application/json:
          schema:
            type: object
            properties:
              execution_optimistic:
                type: boolean
                description: Whether the execution payload is optimistic.
              finalized:
                type: boolean
                description: Whether the state is finalized.
              data:
                type: array
                description: List of validator balances.
                items:
                  type: object
                  properties:
                    index:
                      type: string
                      description: Validator index.
                      example: '1'
                    balance:
                      type: string
                      description: Validator balance in Gwei.
                      example: '32000000000'
          examples:
            response:
              summary: Example response
              value:
                execution_optimistic: false
                finalized: false
                data:
                  - index: '1'
                    balance: '32000000000'
                  - index: '2'
                    balance: '31950000000'
```