REST API

JSON API for off-chain consumption. Base URL:

https://oracle.blackhart.io/api/v1

Endpoints

GET/api/v1/scores

List all scored protocols with current BRI and Forge Scale.

GET/api/v1/scores/:slug

Full score breakdown including all 12 dimensions and evidence hash.

POST/api/v1/scores/batchComing Soon

Batch fetch up to 50 protocols. Body: { "slugs": [...] }

GET/api/v1/scores/:slug/historyComing SoonDeveloper

Score history over time. 7-day history with Developer tier ($49/mo).

GET/api/v1/scores/:slug/dimensionsComing SoonDeveloper

Detailed dimension breakdown with individual scores.

GET/api/v1/markets/historicalAegis

Resolved prediction-market archive with the full per-dimension risk signals + evidence. Aegis plan.

WS/api/v1/ws/scoresComing SoonDeveloper

Real-time WebSocket feed of score changes.

Response Format

Single protocol response from GET /api/v1/scores/:slug:

Response

{
  "slug": "uniswap-v4",
  "bri": 913,
  "forgeScale": "MITHRIL",
  "forgeScaleNum": 6,
  "confidence": 67,
  "delta": -3,
  "updatedAt": "2026-05-05T14:00:00Z",
  "evidenceHash": "QmX7b2...",
  "dimensions": {
    "access_control": 95,
    "economic_soundness": 92,
    "oracle_integrity": 98,
    "compositional_risk": 91,
    "governance": 92,
    "maturity": 89,
    "adversarial_resilience": 62,
    "supply_chain": 88,
    "liquidity": 0,
    "cross_chain": 0,
    "opsec": 82,
    "cascade_exposure": 100
  },
  "cascade": {
    "blastRadius": 0,
    "upstreamDeps": 1
  },
  "findings": {
    "critical": 10,
    "high": 15,
    "medium": 48
  },
  "metadata": {
    "category": "DEX / AMM",
    "chain": "Multi-chain",
    "tvl": "$3.5B",
    "contracts": 8,
    "zFactor": 0.744
  }
}

Batch Request

Terminal

curl -X POST https://oracle.blackhart.io/api/v1/scores/batch \
  -H "Content-Type: application/json" \
  -d '{
    "slugs": ["aave-v3", "sky", "lido", "uniswap-v4"]
  }'

Historical Markets

Aegis

The resolved prediction-market archive as a programmatic feed. Each row carries the final outcome, dispute flag, the composite + Forge tier, and the full per-dimension breakdown with the underlying evidence that the score was built from while the market was still live. Returned newest-resolved first.

GET/api/v1/markets/historicalAegis

Auth: a bh_live_ key on the Aegis plan (enterprise/partner). Lower tiers receive 403 { code: "AEGIS_REQUIRED" }. Send the key as Authorization: Bearer … or x-api-key. Rate limits are reported via the X-RateLimit-* response headers.

Query Parameters

Param	Type	Description
category	string	Filter by market category (case-insensitive exact match).
tier	ForgeTier	RAW · CAST · FORGED · TEMPERED · DAMASCUS · MITHRIL · ADAMANTINE.
outcome	string	Filter by resolved outcome label (e.g. Yes / No).
disputed	boolean	true / false — whether the resolution was disputed.
from / to	ISO date	resolved_at range (inclusive).
min_composite / max_composite	300-1000	Composite score bounds.
min_<dim> / max_<dim>	0-100	Per-dimension thresholds: informed, integrity, oracle, catalyst, design, counterparty.
page / pageSize	int (≤500)	Page paging, newest-resolved first.
cursor	string	Keyset cursor (use nextCursor from the prior page) — preferred for large pulls.

Example Request

Terminal

curl -H "Authorization: Bearer bh_live_YOUR_AEGIS_KEY" \
  "https://oracle.blackhart.io/api/v1/markets/historical?\
category=Politics&disputed=true&min_composite=300&max_integrity=50&pageSize=100"

Example Response

Use nextCursor from each page as the cursor param of the next request to walk the whole archive deterministically (preferred over page for bulk pulls).

Response

{
  "version": "bri-pm-v0.1",
  "tier": "enterprise",
  "count": 100,
  "total": 1342,
  "page": 1,
  "pageSize": 100,
  "nextCursor": "MjAyNi0wNS0xMC4uLnxhYmM=",
  "timestamp": "2026-05-30T14:00:00Z",
  "markets": [
    {
      "id": "f3c1...uuid",
      "slug": "us-recession-2026",
      "question": "Will the US enter a recession in 2026?",
      "category": "Economics",
      "composite": 612,
      "tier": "FORGED",
      "status": "resolved",
      "resolvedOutcome": "No",
      "resolvedAt": "2026-04-30T23:59:00Z",
      "resolutionSource": "https://www.bea.gov/...",
      "disputed": false,
      "topRiskDriver": "Elevated informed-trading signal",
      "flaggedCount": 3,
      "formulaVersion": "bri-pm-v0.1",
      "weightVersion": "bri-pm-w-v0.1",
      "dimensions": [
        {
          "key": "informed",
          "name": "Information Fairness",
          "score": 41,
          "weight": 0.35,
          "description": "How level the playing field is ...",
          "evidence": [
            {
              "type": "wallet_signal",
              "label": "18% of recent volume matches informed-trading patterns.",
              "pattern": "Pre-event informed positioning",
              "reference": { "label": "Polymarket", "url": "https://polymarket.com/profile/0x...", "kind": "profile" }
            }
          ],
          "references": [],
          "computation": { "baseline": 100, "raises": [], "lowers": [ ... ] }
        }
        // ...integrity, oracle, catalyst, design, counterparty
      ]
    }
  ]
}

Rate Limits

Free (no key)1,000 req/day, 15,000/month

Developer ($49/mo)50,000 req/day

← Examples Use Cases