Eyrium API

A read-only REST API for your own validators: current on-chain state, every alert event Eyrium detected, and per-epoch attestation rewards with ideal-reward comparison. Included on the free tier and Pro — no separate API subscription.

Scope note: this is not a chain explorer API. It returns data about validators on your account only.

Authentication

Create a key in Settings → API (sign in first). Keys look like eyk_… and are shown once. Send the key as a bearer token:

curl -H "Authorization: Bearer eyk_YOUR_KEY" https://api.eyrium.app/v1/validators

Limits: 5 active keys per account, 60 requests per minute per key (HTTP 429 with Retry-After beyond that). Errors use a uniform envelope: {"error":{"code":"…","message":"…"}} with codes unauthorized, not_found, invalid_request, rate_limited.

GET /v1/validators

Every validator on your account with its latest known on-chain state. No parameters.

curl -H "Authorization: Bearer eyk_YOUR_KEY" https://api.eyrium.app/v1/validators

{
  "validators": [
    {
      "id": "0b892948-9d0e-4a04-bd0e-3a59aa7f9c1a",
      "pubkey": "0x86fd…549c",
      "validator_index": 123456,
      "label": "home-validator",
      "created_at": "2026-07-01T09:00:00+00:00",
      "state": {
        "status": "active_ongoing",
        "balance_gwei": 32004120345,
        "effective_balance_gwei": 32000000000,
        "fee_recipient": "0xabc…def",
        "withdrawal_credentials": "0x01…",
        "last_attestation_epoch": 371204,
        "last_proposal_slot": 11877211,
        "updated_at": "2026-07-22T10:04:11+00:00"
      }
    }
  ]
}

state is null for a just-added validator that hasn't been polled yet.

GET /v1/events

Everything Eyrium detected for your validators — missed attestations and proposals, balance drops, status changes (slashing, exit, withdrawal), credential changes, proposed blocks, processed withdrawals. Newest first, cursor-paginated.

• type — filter to one event type: balance_drop, block_proposed, missed_attestation, missed_proposal, state_change, status_change, withdrawal_processed
• validator_id — filter to one of your validators (UUID from /v1/validators)
• since — ISO 8601 timestamp — only events at or after this time
• limit — page size, 1–100 (default 50)
• cursor — opaque cursor from the previous response's next_cursor

curl -H "Authorization: Bearer eyk_YOUR_KEY" \
  "https://api.eyrium.app/v1/events?type=missed_attestation&limit=2"

{
  "events": [
    {
      "id": "8f6f7f4e-…",
      "validator_id": "0b892948-…",
      "type": "missed_attestation",
      "epoch": 371190,
      "slot": null,
      "payload": { "streak": 1, "head_reward": 0, "ideal_head_reward": 3021 },
      "created_at": "2026-07-22T08:11:32+00:00"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0…"
}

GET /v1/rewards

Per-epoch attestation rewards for your validators, including the ideal (maximum attainable) reward for the same duty — the delta is what a miss actually cost. Newest epoch first, cursor-paginated.

• validator_id — filter to one of your validators
• from_epoch — inclusive lower epoch bound
• to_epoch — inclusive upper epoch bound
• limit — page size, 1–1000 (default 500)
• cursor — opaque cursor from the previous response's next_cursor
• format — json (default) or csv

curl -H "Authorization: Bearer eyk_YOUR_KEY" \
  "https://api.eyrium.app/v1/rewards?from_epoch=371000&to_epoch=371010"

{
  "rewards": [
    {
      "validator_id": "0b892948-…",
      "epoch": 371010,
      "head_reward": 3021,
      "target_reward": 5814,
      "source_reward": 3130,
      "ideal_head_reward": 3021,
      "ideal_target_reward": 5814,
      "ideal_source_reward": 3130,
      "effective_balance_gwei": 32000000000,
      "recorded_at": "2026-07-22T10:04:11+00:00"
    }
  ],
  "next_cursor": null
}

CSV export

format=csv streams your full reward history (respecting validator_id, from_epoch, and to_epoch) in one response — limit and cursor are ignored. Columns, in order: validator_id, epoch, head_reward, target_reward, source_reward, ideal_head_reward, ideal_target_reward, ideal_source_reward, effective_balance_gwei, recorded_at. Reward values are gwei. Exports past 499,500 rows end with a # TRUNCATED line — narrow the epoch range and request the remainder.

curl -H "Authorization: Bearer eyk_YOUR_KEY" \
  -o rewards.csv "https://api.eyrium.app/v1/rewards?format=csv"

GET /v1/effectiveness

Attestation effectiveness — the share of the maximum attainable reward your validators actually earned over the window — per validator plus an account rollup. The rollup is gwei-weighted (total actual ÷ total ideal), and missed_gwei is what the gap cost you.

• window — 7d (default) or 30d, anchored to your newest recorded epoch

curl -H "Authorization: Bearer eyk_YOUR_KEY" \
  "https://api.eyrium.app/v1/effectiveness?window=7d"

{
  "window": "7d",
  "validators": [
    {
      "validator_id": "0b892948-…",
      "actual_gwei": "18803155",
      "ideal_gwei": "18871420",
      "effectiveness_pct": 99.64
    }
  ],
  "totals": {
    "actual_gwei": "93417072",
    "ideal_gwei": "94112830",
    "missed_gwei": "695758",
    "effectiveness_pct": 99.26
  }
}

Coming later

Webhooks (push instead of poll) are on the roadmap. If you need an endpoint that isn't here, say so: support@eyrium.app.