xerberus.scanner

Documentation for eth_defi.xerberus.scanner Python module.

Xerberus risk scanner with DuckDB storage.

Orchestrates fetching registry scores and optional vault lists from the Xerberus public REST API and storing them in XerberusDatabase.

HTTP is serial and paced (see session rate limits). Do not fan out parallel authenticated calls under the public 10 requests / 60 s quota.

Example:

import os

from eth_defi.xerberus.session import create_xerberus_session
from eth_defi.xerberus.scanner import scan_xerberus

# Pass api_email explicitly when known; never invent the registered email.
session = create_xerberus_session(
    api_key=os.environ["XERBERUS_API_KEY"],
    api_email=os.environ["XERBERUS_API_EMAIL"],
)
db = scan_xerberus(session=session)
try:
    print(db.get_entity_counts())
finally:
    db.close()

Functions

scan_xerberus(session[, db_path, ...])

Scan Xerberus registry (and optional vault lists) into DuckDB.
scan_xerberus(session, db_path=PosixPath('/home/runner/.tradingstrategy/vaults/xerberus/xerberus.duckdb'), fetch_vault_lists=True, fetch_reports=True, report_limit=50, registry_types=('pool', 'protocol'), timeout=60.0, dry_run=False)

Scan Xerberus registry (and optional vault lists) into DuckDB.

  1. Soft pre-flight registry healthcheck

  2. Fetch registry scores for pool + protocol

  3. Insert snapshots and upsert score_daily

  4. Optionally fetch per-platform vault lists

  5. Optionally backfill a capped number of report URLs

Caller must close() the returned database (unless dry_run).

Parameters

  • session (eth_defi.xerberus.session.XerberusSession) – Authenticated Xerberus session.

  • db_path (pathlib.Path) – DuckDB path.

  • fetch_vault_lists (bool) – When True, poll /vault/list for each known platform.

  • fetch_reports (bool) – When True, fetch dendrogram URLs for a capped set of pools.

  • report_limit (int) – Max report download calls this run.

  • registry_types (tuple[str, ...]) – Entity types passed to /registry/scores.

  • timeout (float) – HTTP timeout seconds.

  • dry_run (bool) – When True, log the plan and return None without writing.

Returns

Open XerberusDatabase, or None on dry run.

Return type

Optional[eth_defi.xerberus.database.XerberusDatabase]