Beacon Validators

Query Ethereum beacon chain data for individual validators by index or BLS pubkey. Mainnet only.

Beacon validator endpoints are an add-on, billed at a set monthly fee separate from your API credit pool. Contact sales to enable beacon access for your account.

Cost: Set monthly fee under the beacon add-on — no per-call credit deduction.

Rate limit: 100 requests/min, on a dedicated beacon bucket (does not count against your portfolio rate limit).

Path parameters

All endpoints accept one of two path-parameter forms:

Parameter	Type	Description
`:index`	integer	Non-negative validator index
`:pubkey`	string	48-byte BLS pubkey, hex-encoded with `0x` prefix (96 hex characters). Case-insensitive

Note: BLS pubkeys are validator identifiers, not wallet addresses.

Validator Details

Get current state, lifecycle epochs, effective balance, and withdrawal credentials for a single validator.

Endpoints

GET https://api.octav.fi/v1/beacon/validators/details/index/:index
GET https://api.octav.fi/v1/beacon/validators/details/pubkey/:pubkey

Response

object

Core validator identity and status.

Show Fields

number

Validator index

string

BLS pubkey (lowercase 0x-prefixed)

boolean

Whether the validator has been slashed

string

object

Epoch-level lifecycle milestones. Fields are null when not yet reached.

Show Fields

number | null

Epoch when the validator became active

number | null

Unix timestamp of activation

number | null

Epoch when the validator exited (or will exit)

number | null

Epoch when withdrawal becomes possible

object

Validator balances as wei strings.

Show Fields

string

Current balance in wei

string

Effective balance in wei (used for reward/penalty calculations)

object

Withdrawal credential info. address is only present for 0x01-prefix validators.

Show Fields

number

Credential prefix byte (0 = BLS, 1 = EVM address)

string

Full credential hex string

string | null

EVM withdrawal address (0x01 only, otherwise null)

Example

curl "https://api.octav.fi/v1/beacon/validators/details/index/123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.octav.fi/v1/beacon/validators/details/index/123456',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const details = await response.json();
console.log(`Status: ${details.validator.status}`);
console.log(`Actual balance: ${details.balance.actual} wei`);

import requests

response = requests.get(
    'https://api.octav.fi/v1/beacon/validators/details/index/123456',
    headers={'Authorization': f'Bearer {api_key}'}
)
details = response.json()
print(f"Status: {details['validator']['status']}")

Example Response

{
  "validator": {
    "index": 123456,
    "pubkey": "0xb03d97937ae39b38a44f90141dcf7f0420c3b9b21caee1a7603046bc9237f5c96b61714474249dafe0a20af583a4fc07",
    "slashed": false,
    "status": "active_ongoing"
  },
  "lifecycle": {
    "activationEpoch": 34567,
    "activationTimestamp": 1672531200,
    "exitEpoch": null,
    "withdrawableEpoch": null
  },
  "balance": {
    "actual": "32045123456789",
    "effective": "32000000000000"
  },
  "withdrawalCredentials": {
    "prefix": 1,
    "credential": "0x0100000000000000000000000a8c8aaa3f2ddf1b22a3f5b2a2e9b7d8c6f4e1a2",
    "address": "0x0a8c8aaa3f2ddf1b22a3f5b2a2e9b7d8c6f4e1a2"
  }
}

Validator Rewards

Paginated reward buckets aggregated by epoch, day, week, or month for a time range. Typical use case: pull daily rewards for a known validator pubkey for portfolio reporting (Lido, Beaver, etc.).

Data availability: Rewards are available from the Merge (epoch 146875, September 15, 2022) onward. If you need data going further back, contact us.

Endpoints

GET https://api.octav.fi/v1/beacon/validators/rewards/index/:index
GET https://api.octav.fi/v1/beacon/validators/rewards/pubkey/:pubkey

Query Parameters

string

required

Determines how rangeFrom / rangeTo are interpreted.

timestamp — values are Unix seconds. Max range: 31,536,000 seconds (1 year).
epoch — values are beacon epoch numbers. Max range: 82,125 epochs (1 year).

integer

required

Start of the range (inclusive). Must be ≥ 0 and ≤ rangeTo. Interpreted as Unix seconds or epoch number per rangeType.

integer

required

End of the range (inclusive). Must be ≥ 0. Interpreted as Unix seconds or epoch number per rangeType.

Maximum 1-year range. Cap is 31,536,000 seconds when rangeType=timestamp, 82,125 epochs when rangeType=epoch. For better performance, keep ranges as small as your use case allows.

string

required

Bucket size for aggregation. One of: epoch | day | week | month

number

default:"0"

Pagination offset (number of records to skip).

number

default:"10"

Number of records to return. Max 10.

Response

ValidatorRewardSummary[]

Array of reward buckets.

Show ValidatorRewardSummary fields

number

First epoch in this bucket

number

Last epoch in this bucket

number

Unix timestamp of bucket start

number

Unix timestamp of bucket end

string

ISO date string of bucket start

string

ISO date string of bucket end

string

Consensus layer reward in wei

string

Maximum possible consensus reward in wei

number | null

Ratio of actual to potential consensus reward (0–1), or null if not computable

string

Execution layer (MEV + tips) reward in wei

number

Number of attestations included on-chain

number

Number of attestations missed

number

Sync committee participations

number

Sync committee slots missed

number

Blocks proposed

number

Block proposals missed

number

Blocks proposed with MEV

string

Effective balance at the end of the bucket, in wei

number

Current pagination offset

number

Records per page

number

Total number of matching buckets

number

Total number of pages

Example

curl "https://api.octav.fi/v1/beacon/validators/rewards/index/123456?rangeType=timestamp&rangeFrom=1704067200&rangeTo=1706745600&granularity=day&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.octav.fi/v1/beacon/validators/rewards/index/123456?rangeType=epoch&rangeFrom=231200&rangeTo=231424&granularity=epoch&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

// timestamp mode
const params = new URLSearchParams({
  rangeType: 'timestamp',
  rangeFrom: '1704067200',
  rangeTo: '1706745600',
  granularity: 'day',
  limit: '10'
});

const response = await fetch(
  `https://api.octav.fi/v1/beacon/validators/rewards/index/123456?${params}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const rewards = await response.json();
rewards.data.forEach(bucket => {
  console.log(`${bucket.dateStart}: consensus ${bucket.consensusReward} wei`);
});

import requests

# epoch mode
response = requests.get(
    'https://api.octav.fi/v1/beacon/validators/rewards/index/123456',
    params={
        'rangeType': 'epoch',
        'rangeFrom': 231200,
        'rangeTo': 231424,
        'granularity': 'epoch',
        'limit': 10
    },
    headers={'Authorization': f'Bearer {api_key}'}
)
data = response.json()
for bucket in data['data']:
    print(f"{bucket['dateStart']}: {bucket['consensusReward']} wei")

Example Response

{
  "data": [
    {
      "epochStart": 231200,
      "epochEnd": 231424,
      "timestampStart": 1704067200,
      "timestampEnd": 1704153600,
      "dateStart": "2024-01-01",
      "dateEnd": "2024-01-02",
      "consensusReward": "2450000000000",
      "consensusPotentialReward": "2500000000000",
      "consensusEfficiency": 0.98,
      "executionReward": "125000000000",
      "attestationsIncluded": 224,
      "attestationsMissed": 0,
      "syncParticipations": 0,
      "syncMissed": 0,
      "proposedBlocks": 0,
      "missedBlocks": 0,
      "mevBlocks": 0,
      "endEffectiveBalance": "32000000000000"
    }
  ],
  "offset": 0,
  "limit": 10,
  "totalRows": 31,
  "pages": 4
}

Validator Withdrawals

Paginated list of withdrawals processed for a validator.

Endpoints

GET https://api.octav.fi/v1/beacon/validators/withdrawals/index/:index
GET https://api.octav.fi/v1/beacon/validators/withdrawals/pubkey/:pubkey

Query Parameters

number

default:"0"

Pagination offset.

number

default:"10"

Number of records to return. Max 10.

Response

ValidatorWithdrawal[]

Array of withdrawal events.

Show ValidatorWithdrawal fields

number

Slot in which the withdrawal was processed

number

Epoch containing the slot

number

Unix timestamp of the withdrawal

string

Withdrawn amount in wei

string

EVM address that received the withdrawal

number

Validator index

number

Current pagination offset

number

Records per page

number

Total number of withdrawals

number

Total number of pages

Example

curl "https://api.octav.fi/v1/beacon/validators/withdrawals/index/123456?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.octav.fi/v1/beacon/validators/withdrawals/index/123456?limit=10&offset=0',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const withdrawals = await response.json();
console.log(`Total withdrawals: ${withdrawals.totalRows}`);

Example Response

{
  "data": [
    {
      "slot": 8901234,
      "epoch": 278163,
      "timestamp": 1706745600,
      "amount": "32000000000000",
      "address": "0x0a8c8aaa3f2ddf1b22a3f5b2a2e9b7d8c6f4e1a2",
      "index": 123456
    }
  ],
  "offset": 0,
  "limit": 10,
  "totalRows": 3,
  "pages": 1
}

Validator Deposits

Paginated list of deposits made to a validator.

Endpoints

GET https://api.octav.fi/v1/beacon/validators/deposits/index/:index
GET https://api.octav.fi/v1/beacon/validators/deposits/pubkey/:pubkey

Query Parameters

number

default:"0"

Pagination offset.

number

default:"10"

Number of records to return. Max 10.

Response

ValidatorDeposit[]

Array of deposit events.

Show ValidatorDeposit fields

number

Slot in which the deposit was included

number

Epoch containing the slot

number

Unix timestamp of the deposit

string

Deposited amount in wei

number

Global deposit contract index

string

Full withdrawal credential hex string

string | null

EVM withdrawal address (0x01 prefix only, otherwise null)

number

Current pagination offset

number

Records per page

number

Total number of deposits

number

Total number of pages

Example

curl "https://api.octav.fi/v1/beacon/validators/deposits/pubkey/0xb03d97937ae39b38a44f90141dcf7f0420c3b9b21caee1a7603046bc9237f5c96b61714474249dafe0a20af583a4fc07?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

const pubkey = '0xb03d97937ae39b38a44f90141dcf7f0420c3b9b21caee1a7603046bc9237f5c96b61714474249dafe0a20af583a4fc07';

const response = await fetch(
  `https://api.octav.fi/v1/beacon/validators/deposits/pubkey/${pubkey}?limit=10`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const deposits = await response.json();
console.log(`Total deposits: ${deposits.totalRows}`);

Example Response

{
  "data": [
    {
      "slot": 1234567,
      "epoch": 38579,
      "timestamp": 1634567890,
      "amount": "32000000000000000000",
      "depositIndex": 456789,
      "withdrawalCredentials": "0x0100000000000000000000000a8c8aaa3f2ddf1b22a3f5b2a2e9b7d8c6f4e1a2",
      "withdrawalAddress": "0x0a8c8aaa3f2ddf1b22a3f5b2a2e9b7d8c6f4e1a2"
    }
  ],
  "offset": 0,
  "limit": 10,
  "totalRows": 1,
  "pages": 1
}

Error Responses

400 Bad Request

Input validation failed (Joi structured error).

{ "error": "\"index\" must be a non-negative integer" }

Common causes: invalid :index or :pubkey format, missing required query params, rangeFrom > rangeTo, range exceeding 1-year cap, invalid rangeType or granularity value.

401 Unauthorized

Missing or invalid Bearer token.

{ "message": "Unauthorized" }

403 Forbidden

Valid token but account does not have enterprise beacon access.

{ "error": "Beacon access requires enterprise subscription. Contact sales." }

404 Validator Not Found

Validator does not exist on mainnet.

{ "error": "Validator not found for index 99999999" }

500 Internal Server Error

Upstream beacon data error.

Error fetching validator details

Use Cases

Staking Yield in Portfolio
Validator Status
Withdrawals by Address

Aggregate daily rewards across a set of validators and convert wei to ETH for portfolio reporting.

async function getDailyStakingYield(pubkeys, fromTs, toTs) {
  const buckets = {};

  for (const pubkey of pubkeys) {
    const params = new URLSearchParams({
      rangeType: 'timestamp',
      rangeFrom: String(fromTs),
      rangeTo: String(toTs),
      granularity: 'day',
      limit: '10'
    });

    const response = await fetch(
      `https://api.octav.fi/v1/beacon/validators/rewards/pubkey/${pubkey}?${params}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data } = await response.json();

    data.forEach(b => {
      const total = BigInt(b.consensusReward) + BigInt(b.executionReward);
      buckets[b.dateStart] = (buckets[b.dateStart] ?? 0n) + total;
    });
  }

  return Object.entries(buckets).map(([date, wei]) => ({
    date,
    eth: Number(wei) / 1e18
  }));
}

Read the canonical validator.status value to drive lifecycle UI or alerting.

export const ValidatorStatus = {
  Pending: 'pending',
  ActiveOngoing: 'active_ongoing',
  ActiveExiting: 'active_exiting',
  ActiveSlashed: 'active_slashed',
  ExitedUnslashed: 'exited_unslashed',
  ExitedSlashed: 'exited_slashed',
  WithdrawalPossible: 'withdrawal_possible',
  WithdrawalDone: 'withdrawal_done',
} as const;

async function getValidatorStatus(index) {
  const response = await fetch(
    `https://api.octav.fi/v1/beacon/validators/details/index/${index}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const { validator } = await response.json();

  if (validator.status === ValidatorStatus.ActiveSlashed ||
      validator.status === ValidatorStatus.ExitedSlashed) {
    alert(`Validator ${validator.index} has been slashed`);
  }

  return validator.status;
}

Paginate every withdrawal for a validator and bucket totals by recipient address (useful for tax reporting and proof-of-reserves).

async function getWithdrawalsByAddress(index) {
  const totals = {};
  let offset = 0;

  while (true) {
    const response = await fetch(
      `https://api.octav.fi/v1/beacon/validators/withdrawals/index/${index}?limit=10&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data, totalRows } = await response.json();

    data.forEach(w => {
      totals[w.address] = (totals[w.address] ?? 0n) + BigInt(w.amount);
    });

    offset += data.length;
    if (offset >= totalRows || data.length === 0) break;
  }

  return Object.entries(totals).map(([address, wei]) => ({
    address,
    eth: Number(wei) / 1e18
  }));
}

Best Practices

Cache Validator Details Client-Side

validator.status, lifecycle.*, and withdrawalCredentials.* change on the order of minutes-to-hours, not seconds. Cache details responses for several minutes to cut latency and load.

const detailsCache = new Map(); // index -> { value, expiresAt }
const TTL_MS = 5 * 60 * 1000;

async function getValidatorDetails(index) {
  const cached = detailsCache.get(index);
  if (cached && cached.expiresAt > Date.now()) return cached.value;

  const response = await fetch(
    `https://api.octav.fi/v1/beacon/validators/details/index/${index}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const value = await response.json();

  detailsCache.set(index, { value, expiresAt: Date.now() + TTL_MS });
  return value;
}

Pick Granularity to Match Range

Reward buckets at granularity=epoch over a one-year range can yield ~82,000 rows. Match the granularity to the range so a single query returns a meaningful page.

Range	Suggested granularity
< 1 day	`epoch`
1–30 days	`day`
1–6 months	`week`
6 months – 1 year	`month`

Going finer than this still works, but you’ll need to paginate (limit is capped at 10) and stitch results together.

Convert Wei With BigInt

Reward and balance fields are returned as decimal strings in wei. Summing across long ranges or many validators can exceed Number.MAX_SAFE_INTEGER — parse with BigInt, divide by 10^18 only at the display step.

const totalWei = rewards.data.reduce(
  (sum, b) => sum + BigInt(b.consensusReward) + BigInt(b.executionReward),
  0n
);
const totalEth = Number(totalWei) / 1e18;

Paginate to Fetch All Records

limit is capped at 10 for rewards, withdrawals, and deposits. Loop on offset until you’ve consumed totalRows.

async function fetchAll(url) {
  const all = [];
  let offset = 0;

  while (true) {
    const sep = url.includes('?') ? '&' : '?';
    const response = await fetch(
      `${url}${sep}limit=10&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { data, totalRows } = await response.json();

    all.push(...data);
    offset += data.length;
    if (offset >= totalRows || data.length === 0) break;
  }

  return all;
}

Portfolio

Get full portfolio holdings for a wallet address

Transactions

View on-chain transaction history

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Path parameters

Validator Details

Endpoints

Response

Example

Validator Rewards

Endpoints

Query Parameters

Response

Example

Validator Withdrawals

Endpoints

Query Parameters

Response

Example

Validator Deposits

Endpoints

Query Parameters

Response

Example

Error Responses

Use Cases

Best Practices

Portfolio

Transactions

​Path parameters

​Validator Details

​Endpoints

​Response

​Example

​Validator Rewards

​Endpoints

​Query Parameters

​Response

​Example

​Validator Withdrawals

​Endpoints

​Query Parameters

​Response

​Example

​Validator Deposits

​Endpoints

​Query Parameters

​Response

​Example

​Error Responses

​Use Cases

​Best Practices

​Related Endpoints

Portfolio

Transactions

Path parameters

Validator Details

Endpoints

Response

Example

Validator Rewards

Endpoints

Query Parameters

Response

Example

Validator Withdrawals

Endpoints

Query Parameters

Response

Example

Validator Deposits

Endpoints

Query Parameters

Response

Example

Error Responses

Use Cases

Best Practices

Related Endpoints