Hindenrank API

Quick Start

Check a protocol's risk grade with a single request — no authentication required:

# Get Aave's risk profile
curl "https://hindenrank.com/api/v1/protocols/aave"

Response (truncated):

{
  "data": {
    "slug": "aave",
    "name": "Aave",
    "grade": "B+",
    "rawScore": 22,
    "sector": "Lending",
    "topRisks": ["Oracle dependency on Chainlink..."],
    // ... more fields
  }
}

Authentication

The API supports three access tiers. Pass your key via the X-API-Key header.

# Authenticated request with an API key
curl "https://hindenrank.com/api/v1/protocols/aave" \
  -H "X-API-Key: hr_your_key_here"

Base URL

https://hindenrank.com/api/v1

All endpoints below are relative to this base. Responses are JSON with Content-Type: application/json.

Endpoints

GET/protocols

List all protocols. Supports filtering by sector and grade range, with pagination.

# Top 10 Lending protocols graded B or better
curl "https://hindenrank.com/api/v1/protocols?sector=Lending&maxGrade=B&limit=10"

Response:

{
  "data": [
    { "slug": "aave", "grade": "B+", ... }
  ],
  "meta": {
    "total": 42,
    "count": 10,
    "offset": 0,
    "tier": "anon"
  }
}

GET/protocols/:slug

Get a single protocol by slug. The response fields vary by tier: anonymous gets grades and retail info, free keys add value scores and market data, pro keys get the full mechanism analysis.

curl "https://hindenrank.com/api/v1/protocols/lido"

Response fields by tier:

GET/protocols/search?q=

Fuzzy search protocols by name or slug. Returns basic protocol data.

curl "https://hindenrank.com/api/v1/protocols/search?q=uni&limit=5"

GET/protocols/compare?slugs=

Compare 2–5 protocols side-by-side. Requires an API key (free or pro). Returns full protocol data for each plus a comparison summary.

curl "https://hindenrank.com/api/v1/protocols/compare?slugs=aave,compound,morpho" \
  -H "X-API-Key: hr_your_key_here"

Response includes:

{
  "data": {
    "protocols": {
      "aave": { ... },
      "compound": { ... },
      "morpho": { ... }
    },
    "comparison": {
      "safest": "aave",
      "riskiest": "morpho",
      "bestValue": "compound"
    }
  }
}

GET/protocols/:slug/history

Retrieve the grade history for a protocol over time. Requires an API key (free tier or above). Returns chronological grade snapshots including both risk and value scores with their full breakdowns.

# Get last 30 days of Aave v3 grade history
curl "https://hindenrank.com/api/v1/protocols/aave-v3/history?limit=30" \
  -H "X-API-Key: hr_your_key_here"

Response:

{
  "data": {
    "slug": "aave-v3",
    "history": [
      {
        "date": "2026-03-10",
        "grade": "B+",
        "rawScore": 22,
        "valueGrade": "A-",
        "valueRawScore": 78,
        "gradeBreakdown": { ... },
        "valueBreakdown": { ... }
      }
    ]
  },
  "meta": {
    "count": 30,
    "tier": "free",
    "rateLimit": { ... }
  }
}

GET/sectors

List all sectors with protocol counts and average risk scores.

curl "https://hindenrank.com/api/v1/sectors"

Response:

{
  "data": [
    {
      "name": "DeFi",
      "protocolCount": 187,
      "averageRawScore": 41.3
    }
  ]
}

Vault Endpoints

Access risk ratings for 3,900+ DeFi vaults across Beefy, Hyperliquid, and Morpho. Vault risk is computed using a weakest-link model across underlying protocols.

GET/vaults

List vaults with optional filters. Sorted by TVL descending.

curl "https://hindenrank.com/api/v1/vaults?source=hyperliquid&rated=true&maxGrade=B"

GET/vaults/:vaultId

Get a single vault by ID. Fields returned depend on your API tier.

curl "https://hindenrank.com/api/v1/vaults/hl-0x1234..."

GET/vaults/search

Search vaults by name or asset. Matches vault name, asset symbols, and vault IDs.

curl "https://hindenrank.com/api/v1/vaults/search?q=HYPE"

POST/portfolio/risk

Analyze the aggregate risk of a portfolio of protocol positions. Submit up to 50 positions and receive a composite risk score, grade distribution, concentration warnings, and weakest links. Requires an API key.

Request body:

# Analyze portfolio risk across two positions
curl -X POST "https://hindenrank.com/api/v1/portfolio/risk" \
  -H "X-API-Key: hr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      { "protocol": "aave-v3", "value": 5000 },
      { "protocol": "lido", "value": 3000 }
    ]
  }'

Response:

{
  "data": {
    "riskScore": 28,
    "riskGrade": "B",
    "totalValue": 8000,
    "positionCount": 2,
    "positions": [ ... ],
    "gradeDistribution": {
      "B+": 5000,
      "B": 3000
    },
    "concentrationWarnings": ["62.5% concentrated in aave-v3"],
    "weakestLinks": [ ... ],
    "unmatchedProtocols": []
  },
  "meta": {
    "tier": "free",
    "rateLimit": { ... }
  }
}

GET/account/usage

Check your current rate limit status. Requires an API key.

curl "https://hindenrank.com/api/v1/account/usage" \
  -H "X-API-Key: hr_your_key_here"

Response:

{
  "data": {
    "tier": "free",
    "limit": 2000,
    "used": 142,
    "remaining": 1858,
    "resetsAt": "2026-02-24T00:00:00.000Z"
  }
}

Webhooks

Register webhooks to receive real-time notifications when protocol grades change. All webhook endpoints require an API key.

Event Types

POST/webhooks

Register a new webhook. Provide a URL, a signing secret, and the events you want to subscribe to.

# Register a webhook for grade downgrades
curl -X POST "https://hindenrank.com/api/v1/webhooks" \
  -H "X-API-Key: hr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/hindenrank",
    "secret": "whsec_your_signing_secret",
    "events": ["grade.downgraded", "grade.critical"]
  }'

GET/webhooks

List all webhooks registered under your API key.

curl "https://hindenrank.com/api/v1/webhooks" \
  -H "X-API-Key: hr_your_key_here"

DELETE/webhooks

Delete a webhook by ID. Pass the webhook ID in the request body.

curl -X DELETE "https://hindenrank.com/api/v1/webhooks" \
  -H "X-API-Key: hr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "webhookId": "wh_abc123" }'

Webhook Payload

When an event fires, Hindenrank sends a POST request to your registered URL with this payload:

{
  "event": "grade.downgraded",
  "data": {
    "slug": "terra-luna",
    "name": "Terra Luna",
    "oldGrade": "C",
    "newGrade": "D+",
    "oldRawScore": 52,
    "newRawScore": 61,
    "changedAt": "2026-03-10T14:30:00.000Z"
  },
  "timestamp": "2026-03-10T14:30:05.000Z"
}

Signature Verification

Every webhook request includes an X-Hindenrank-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Always verify this signature before processing the payload.

// Node.js signature verification
const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Rate Limits

Rate limits are enforced per day (24-hour rolling window). Every response includes rate limit headers:

When you exceed your limit, the API returns 429 Too Many Requests with a Retry-After header in seconds.

Response Format

Every successful response follows the same envelope:

{
  "data": // The requested resource(s)
  "meta": {
    "tier": "free",
    "rateLimit": {
      "used": 42,
      "remaining": 1958,
      "resetsAt": "2026-02-24T00:00:00.000Z"
    }
  }
}

Errors follow a consistent structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Protocol not found"
  }
}

Error Codes

MCP Server

Use Hindenrank as a tool in AI coding assistants via the Model Context Protocol. The MCP server exposes 7 tools — protocol lookups, search, compare, and vault risk ratings — that Claude, Cursor, and other MCP-compatible assistants can call directly.

Source: github.com/hindenrank/hindenrank-mcp

Add to your Claude Code or Cursor config:

{
  "mcpServers": {
    "hindenrank": {
      "command": "npx",
      "args": ["hindenrank-mcp@latest"],
      "env": {
        "HINDENRANK_API_KEY": "hr_your_key_here"
      }
    }
  }
}

Available tools:

Get Your API Key

Create a free account to get an API key with 2,000 requests per day. Upgrade to Pro for 50,000 requests and full mechanism data.