Developer Documentation

Risk Intelligence API

Programmatic access to protocol risk scores, findings, and real-time alerts. Designed for direct integration into underwriting platforms and pricing models.

Authentication

All API requests require authentication via Bearer token.

HTTP Header

Authorization: Bearer bhr_live_sk_...

keyAPI Keys

API keys are provisioned upon enrollment. Each key is scoped to your organization and the protocols included in your subscription tier. Contact your account manager or request access to get started.

Base URL

https://api.research.blackhart.io

Endpoints

GET/api/v1/protocols

List all monitored protocols with current risk scores

Response — JSON200 OK

{
  "data": [
    {
      "id": "aave-v3",
      "name": "Aave V3",
      "chain": "ethereum",
      "tvl": 12400000000,
      "risk_score": 87,
      "risk_level": "low",
      "findings_count": {
        "critical": 0,
        "high": 1,
        "medium": 3,
        "low": 7
      },
      "last_updated": "2026-04-29T14:23:00Z"
    }
  ],
  "meta": {
    "total": 4,
    "page": 1,
    "per_page": 25
  }
}

GET/api/v1/protocols/:id/findings

Active findings for a specific protocol with severity, impact, and validation status

Response — JSON200 OK

{
  "data": [
    {
      "id": "BHR-2026-0042",
      "protocol_id": "euler-v2",
      "title": "Cross-vault liquidation chain",
      "severity": "critical",
      "exploit_value": 15200000,
      "tvl_at_risk": 680000000,
      "likelihood": 0.73,
      "status": "confirmed",
      "poc_validated": true,
      "discovered_at": "2026-04-29T12:15:00Z",
      "chain_length": 4,
      "attack_primitives": [
        "flash_loan",
        "oracle_manipulation",
        "reentrancy",
        "liquidation_cascade"
      ]
    }
  ],
  "meta": {
    "total": 11,
    "protocol": "euler-v2"
  }
}

GET/api/v1/protocols/:id/risk-score

Current risk score with dimensional breakdown and historical trend

Response — JSON200 OK

{
  "protocol_id": "compound-v3",
  "risk_score": 72,
  "risk_level": "moderate",
  "dimensions": {
    "severity_score": 65,
    "likelihood_score": 78,
    "exposure_score": 74
  },
  "trend": {
    "7d": -3.2,
    "30d": -8.1,
    "90d": +2.4
  },
  "factors": [
    {
      "factor": "Unpatched HIGH finding in USDC market",
      "impact": -12
    },
    {
      "factor": "Recent governance upgrade verified",
      "impact": +4
    }
  ],
  "computed_at": "2026-04-29T14:30:00Z"
}

WSS/api/v1/alerts

Real-time alert stream via WebSocket. Pushes finding discoveries, score changes, and protocol events as they happen

Event Payload — JSON200 OK

{
  "type": "finding_discovered",
  "timestamp": "2026-04-29T12:15:00Z",
  "data": {
    "id": "BHR-2026-0042",
    "protocol_id": "euler-v2",
    "severity": "critical",
    "title": "Cross-vault liquidation chain",
    "exploit_value": 15200000,
    "risk_score_impact": -8
  }
}

// Score change event:
{
  "type": "score_change",
  "timestamp": "2026-04-29T12:16:00Z",
  "data": {
    "protocol_id": "euler-v2",
    "previous_score": 72,
    "new_score": 64,
    "reason": "New critical finding confirmed"
  }
}

Rate Limits & SLAs

Observatory

Rate Limit100 req/min

Uptime SLA99.5%

P99 Latency< 2s

Command Center

Rate Limit1,000 req/min

Uptime SLA99.9%

P99 Latency< 500ms

War Room

Rate LimitUnlimited

Uptime SLA99.99%

P99 Latency< 200ms