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

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
}

Coming later

Webhooks (push instead of poll) are on the roadmap. If you need an endpoint that isn't here, say so: [email protected].