Skip to main content

​
Overview

BeaconScore provides an independent, trusted metric for validator performance. By embedding BeaconScore in your product, you can offer your users transparent performance data while keeping them in your ecosystem.
API Endpoint: This guide uses /api/v2/ethereum/validators/performance-aggregate to fetch BeaconScore metrics.
BeaconScore is a proprietary metric developed by beaconcha.in. Attribution is required when displaying BeaconScore publicly. Enterprise plan users may be exempt from attribution requirements.

​
Why Embed BeaconScore?

Independent Validation

Provide users with trusted, third-party performance metrics that validate your operational quality.

Skip Backend Work

Use our robust API to build real-time visualizations without building your own indexing infrastructure.

Ecosystem Retention

Keep customers in your platform by offering independent data within your UI.

Competitive Advantage

Differentiate your product with transparent performance reporting.

​
Quick Start

​
1. Fetch BeaconScore Data

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "validator_identifiers": [1, 2, 3]
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'

​
2. Display in Your UI

{
  "data": {
    "beaconscore": {
      "total": 0.9945,
      "attestation": 0.9952,
      "proposal": 0.9876,
      "sync_committee": 0.9991
    },
    "duties": {
      "proposal": { "successful": 3, "missed": 0 }
    }
  }
}

​
3. Add Attribution

Include the BeaconScore badge when displaying the metric publicly:
BeaconScore

​
Attribution Requirements

Required: When displaying BeaconScore data publicly in your application, website, or reports, you must include appropriate attribution using our official badges.

​
BeaconScore Badge

Use when displaying BeaconScore/Efficiency metrics:
FormatLight ModeDark Mode
SVGbeaconscore_black.svgbeaconscore_white.svg
PNGbeaconscore_black.pngbeaconscore_white.png

​
Powered by beaconcha.in Badge

Use when your product uses any beaconcha.in API data:
FormatLight ModeDark Mode
SVGpoweredby_black.svgpoweredby_white.svg
PNGpoweredby_black.pngpoweredby_white.png

Download License Materials

Download official badges in SVG and PNG formats
Enterprise Exemption: Enterprise API plan users are exempt from attribution requirements. Contact sales for details.

​
Integration Patterns

​
Pattern 1: Dashboard Widget

Display a performance summary widget in your staking dashboard: 
async function fetchBeaconScore(validatorIndices) {
  const response = await fetch(
    'https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        chain: 'mainnet',
        validator: { validator_identifiers: validatorIndices },
        range: { evaluation_window: '30d' }
      })
    }
  );
  return response.json();
}

function renderPerformanceWidget(data) {
  const score = (data.data.beaconscore?.total || 0) * 100;
  const rating = score >= 99.5 ? 'Excellent' : 
                 score >= 99.0 ? 'Good' : 
                 score >= 98.0 ? 'Fair' : 'Needs Attention';
  
  return `
    <div class="performance-widget">
      <div class="score">${score.toFixed(2)}%</div>
      <div class="rating ${rating.toLowerCase()}">${rating}</div>
      <div class="details">
        <span>Attestations: ${((data.data.beaconscore?.attestation || 0) * 100).toFixed(2)}%</span>
        <span>Proposals: ${data.data.duties?.proposal?.successful || 0} (${data.data.duties?.proposal?.missed || 0} missed)</span>
      </div>
      <img src="/badges/beaconscore_black.svg" alt="BeaconScore" class="badge" />
    </div>
  `;
}

​
Pattern 2: Customer Reports

Generate performance reports for your staking customers: 
import requests
from datetime import datetime

API_KEY = "<YOUR_API_KEY>"

def generate_customer_report(customer_validators: list, customer_name: str):
    """Generate a performance report for a customer."""
    
    # Fetch performance data
    response = requests.post(
        "https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "chain": "mainnet",
            "validator": {"validator_identifiers": customer_validators},
            "range": {"evaluation_window": "30d"}
        }
    )
    data = response.json()
    
    # Fetch rewards data
    rewards_response = requests.post(
        "https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "chain": "mainnet",
            "validator": {"validator_identifiers": customer_validators},
            "range": {"evaluation_window": "30d"}
        }
    )
    rewards = rewards_response.json()
    
    # Generate report
    beaconscore = data.get("data", {}).get("beaconscore", {})
    duties = data.get("data", {}).get("duties", {})
    
    report = {
        "customer": customer_name,
        "generated_at": datetime.utcnow().isoformat(),
        "period": "30 days",
        "validators": len(customer_validators),
        "performance": {
            "beaconscore": beaconscore.get("total", 0) * 100,
            "attestation_efficiency": beaconscore.get("attestation", 0) * 100,
            "proposals": {
                "successful": duties.get("proposal", {}).get("successful", 0),
                "missed": duties.get("proposal", {}).get("missed", 0)
            }
        },
        "rewards": {
            "total_eth": int(rewards.get("data", {}).get("total", 0)) / 1e18,
            "net_rewards_eth": int(rewards.get("data", {}).get("total_reward", 0)) / 1e18,
            "penalties_eth": int(rewards.get("data", {}).get("total_penalty", 0)) / 1e18
        },
        "attribution": "Performance data powered by beaconcha.in BeaconScore"
    }
    
    return report

# Example usage
report = generate_customer_report(
    customer_validators=[123456, 123457, 123458],
    customer_name="Acme Staking"
)
print(f"Customer: {report['customer']}")
print(f"BeaconScore: {report['performance']['beaconscore']:.2f}%")
print(f"Total Rewards: {report['rewards']['total_eth']:.4f} ETH")

​
Pattern 3: Comparison Tool

Let users compare your validators against network averages: 
def compare_to_network(dashboard_id: int):
    """Compare dashboard performance to network average."""
    
    # Get your validators' performance
    my_perf = requests.post(
        "https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "chain": "mainnet",
            "validator": {"dashboard_id": dashboard_id},
            "range": {"evaluation_window": "30d"}
        }
    ).json()
    
    # Get network average (all validators)
    network_perf = requests.post(
        "https://beaconcha.in/api/v2/ethereum/performance-aggregate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "chain": "mainnet",
            "range": {"evaluation_window": "30d"}
        }
    ).json()
    
    my_score = my_perf.get("data", {}).get("beaconscore", {}).get("total", 0) * 100
    network_score = network_perf.get("data", {}).get("beaconscore", {}).get("total", 0) * 100
    
    diff = my_score - network_score
    
    return {
        "your_score": my_score,
        "network_average": network_score,
        "difference": diff,
        "percentile": "top 10%" if diff > 0.5 else "above average" if diff > 0 else "below average"
    }

​
API Plans for Integration

PlanBest ForBeaconScore Access
ScaleProduction integrationsFull access, attribution required
EnterpriseWhite-label solutionsFull access, attribution optional
For high-volume integrations or white-label requirements, contact our sales team.