Integration Guide
Read DeFi risk scores via the free REST API today, with an on-chain oracle coming soon to Base. Scores update every 6 hours from continuous adversarial research. The public tier is free — no API key, no rate limits, no signup. Two tracks are covered: DeFi protocols (12-dimension model) and prediction markets (6-dimension model).
Quick Start
Full guide// Live today: read a protocol's risk score over the free REST API
const res = await fetch("https://oracle.blackhart.io/api/v1/scores/uniswap-v4");
const { bri, stale } = await res.json(); // bri: 300 (highest risk) – 1000 (lowest)
if (stale) throw new Error("Score too old");
// Planned (once the on-chain oracle ships to Base):
// IBROOracle registry = IBROOracle(REGISTRY_ADDRESS);
// (uint16 bri,,, bool stale) = registry.getScore("uniswap-v4");One request. The oracle returns a score between 300 (highest risk) and 1000 (lowest risk). Check the stale flag before making decisions. The Solidity path shown in comments becomes available once the on-chain oracle ships to Base.
Documentation
Quick Start
Get reading scores in under 5 minutes. One import, one function call.
Solidity Interface
The planned IBROOracle interface for on-chain integration, for once the oracle ships to Base.
Integration Examples
Working code in Solidity, TypeScript, Python, and MCP — copy, paste, deploy.
REST API
JSON endpoints for off-chain consumption. No API key required for public tier.
Use Cases
How protocols and institutions use BRO scores for risk management and pricing.
API Plans
Free tier, Developer, and Institutional plans with dimension-level access.
MCP Integration
Query scores from Claude Code, Cursor, or any MCP-compatible development tool.
Contract Interface
Planned contract interface, ABIs, and network configuration for the upcoming Base deployment.
Integration Paths
REST API (TypeScript / Python)
Live today. HTTP GET endpoints returning JSON. Use for dashboards, analytics, portfolio risk overlays, or any off-chain application. No API key required.
GET /api/v1/scores/{slug}On-Chain (Solidity) — planned
Once the oracle ships to Base, import the IBROOracle interface and call getScore() with a slug. For lending collateral gates, insurance pricing, or vault risk filters. Not yet deployed.
registry.getScore("aave-v3") // plannedMCP (AI Development Tools)
Query scores directly from Claude Code, Cursor, or any MCP-compatible tool. Natural language queries against the full score database.
mcp: get_shield_rating("aave-v3")Frequently Asked Questions
How does BlackHart approach vulnerability discovery and disclosure?
BlackHart continuously hunts for critical vulnerabilities across DeFi. When we find issues, we disclose them through official bounty and responsible disclosure channels. No subscription is required to receive or remediate submitted vulnerabilities. The BlackHart Risk Oracle gives protocols and allocators a transparent view of observable risk signals. Protocols cannot pay for a higher score.
Can protocols pay for a higher score?
No. Scores are not for sale. Paying and non-paying protocols are scored identically using the same methodology, tools, and standards. Commercial status determines monitoring coverage and reassessment frequency, not score treatment. Subscribing to continuous monitoring helps protocols reduce real risk — and if those efforts result in verified security improvements, those changes are reflected in future score updates through the normal assessment process.
What does 'BlackHart Monitored' mean?
It means BlackHart has continuous adversarial coverage on the protocol — actively searching for vulnerabilities, monitoring for risk changes, and providing remediation guidance. It does not mean the protocol is safe or has a high score. A monitored protocol can still score poorly if significant risks are identified. Monitoring provides ongoing coverage and faster triage, not favorable scoring.
How are scores calculated?
Every target is evaluated using the same methodology, same tools, and same standards. For DeFi protocols, the BRI is a weighted geometric mean of 12 security dimensions. Prediction markets (e.g. Polymarket) use a separate 6-dimension model tailored to market resolution and oracle risk. Only PoC-validated findings affect a protocol's score. The full methodology is public and versioned.
Do you score prediction markets too?
Yes. Alongside DeFi protocols, BlackHart scores prediction markets using a dedicated 6-dimension model. The two tracks are scored independently — a protocol's 12-dimension BRI and a market's 6-dimension score are not interchangeable. Prediction-market scores are served over the same free REST API.
What if a protocol believes its score is wrong?
Any protocol can submit evidence for review at no cost. We maintain a free correction channel because score accuracy is more important than revenue. If the evidence changes our assessment, the score is updated with full provenance linking to the submitted evidence.