📖

API Reference

DeFi Guardian v1 API — position-level risk intelligence across 23 protocols on 13 chains.

REST APIv1JSON

● Base URL

https://app.defiguardian.fi/api/v1

● Authentication

All v1 API requests require an API key. Pass it via the x-api-key header or Authorization: Bearer dg_...

Example Requestbash

curl -X GET "https://app.defiguardian.fi/api/v1/status" \
  -H "x-api-key: dg_YOUR_API_KEY_HERE"

Granular Scopes

API keys use fine-grained scopes. Each key can have any combination of:

wallets:readwallets:writepositions:readalerts:readalerts:writewebhooks:readwebhooks:writeanalytics:read

● API Product Tiers

API access is a separate product from the consumer dashboard. Each tier unlocks additional endpoints, higher rate limits, and premium features.

Tier	Price	Rate Limit	Daily Limit	API Keys	Webhooks
Guardian Open	Free	10/min	1,000	1	—
Guardian Pro	$199/mo	60/min	100,000	5	5
Guardian Business	$999/mo	300/min	1,000,000	20	20
Guardian Enterprise	Custom	1,000+/min	Unlimited	Unlimited	Unlimited

● Response Headers

Every v1 response includes rate limit and tier information:

X-RateLimit-Limit— Max requests per minute for your tier

X-RateLimit-Remaining— Remaining requests in current window

X-RateLimit-Reset— ISO timestamp when the window resets

X-Guardian-Tier— Your current API tier (open, pro, business, enterprise)

X-Request-Id— Unique request ID for debugging

Guardian Open Endpoints

FREE

GET/v1/statusopen

System health check — confirms the API is operational

Response

{
  "status": "operational",
  "version": "1.0.0",
  "timestamp": "2026-03-21T12:00:00Z"
}

GET/v1/pricesopen

Token prices. Query param: ?symbols=ETH,BTC,AAVE

Parameters

symbols(string)— Comma-separated token symbols

Response

{
  "prices": {
    "ETH": { "usd": 3200.50, "change24h": 2.1 },
    "BTC": { "usd": 65000.00, "change24h": 1.5 }
  },
  "timestamp": "2026-03-21T12:00:00Z"
}

GET/v1/protocolsopen

Supported protocols with TVL and chain data

Response

{
  "protocols": [
    { "id": "aave-v3", "name": "Aave V3", "chains": [1, 42161, 137], "tvl": 12500000000 },
    { "id": "compound-v3", "name": "Compound V3", "chains": [1, 8453], "tvl": 3200000000 }
  ]
}

GET/v1/chainsopen

Supported chains and their health status

Response

{
  "chains": [
    { "id": 1, "name": "Ethereum", "status": "healthy", "blockTime": 12 },
    { "id": 42161, "name": "Arbitrum", "status": "healthy", "blockTime": 0.25 }
  ]
}

GET/v1/risk/market-healthopen

Aggregate DeFi market risk index

Response

{
  "overallRisk": "medium",
  "riskScore": 45,
  "indicators": {
    "volatility": "elevated",
    "liquidationRisk": "moderate",
    "protocolHealth": "stable"
  }
}

GET/v1/risk/indexopen

Guardian Risk Index (GRI) — single 0-100 DeFi market risk score

Response

{
  "gri": 42,
  "label": "Moderate",
  "trend": "improving",
  "components": {
    "volatility": 55,
    "liquidationPressure": 38,
    "protocolStability": 33
  },
  "updatedAt": "2026-03-21T00:00:00Z"
}

GET/v1/positionsopen

List positions for a wallet (up to 3 wallets on Open tier)

Parameters

wallet(string)— Wallet address (0x...)

Response

{
  "positions": [
    {
      "id": "pos_abc123",
      "protocol": "aave-v3",
      "chainId": 1,
      "healthFactor": 1.85,
      "totalCollateralUsd": 10000.00,
      "totalDebtUsd": 5000.00
    }
  ]
}

GET/v1/protocols/:idopen

Protocol detail — category, supported chains, risk tier

Response

{
  "protocol": {
    "id": "aave_v3",
    "name": "Aave V3",
    "category": "lending",
    "chains": [1, 42161, 137, 10, 8453, 43114],
    "riskTier": "low",
    "tvlBracket": "$10B+"
  }
}

GET/v1/chains/:idopen

Chain detail — native currency, block explorer, block time

Response

{
  "chain": {
    "id": 1,
    "name": "Ethereum",
    "nativeCurrency": "ETH",
    "blockExplorer": "etherscan.io",
    "avgBlockTime": 12,
    "status": "operational"
  }
}

POST/v1/prices/batchopen

Batch price lookup for multiple tokens

Request Body

{ "symbols": ["ethereum", "bitcoin", "aave", "uniswap"] }

Response

{
  "prices": {
    "ethereum": { "usd": 3200.50, "usd_24h_change": 2.1, "usd_market_cap": 384000000000 },
    "bitcoin": { "usd": 65000.00, "usd_24h_change": 1.5, "usd_market_cap": 1260000000000 }
  },
  "count": 2
}

Guardian Pro Endpoints

$199/mo

All Open endpoints plus:

GET/v1/positions/:idpro

Get detailed position with collateral/debt breakdown

Response

{
  "id": "pos_abc123",
  "protocol": "aave-v3",
  "chainId": 1,
  "healthFactor": 1.85,
  "totalCollateralUsd": 10000.00,
  "totalDebtUsd": 5000.00,
  "collateralAssets": [
    { "asset": "WETH", "amount": 5.0, "usdValue": 10000.00 }
  ],
  "debtAssets": [
    { "asset": "USDC", "amount": 5000, "usdValue": 5000.00 }
  ]
}

GET/v1/positions/:id/risk-scorepro

0-100 risk score with breakdown factors

Response

{
  "riskScore": 35,
  "label": "Moderate",
  "factors": {
    "healthFactor": 15,
    "collateralVolatility": 10,
    "debtConcentration": 5,
    "protocolRisk": 5
  }
}

POST/v1/positions/scanpro

Scan a wallet across all supported protocols

Request Body

{ "wallet": "0x1234...abcd", "chains": [1, 42161] }

Response

{
  "positions": [...],
  "totalCollateralUsd": 50000,
  "totalDebtUsd": 20000,
  "protocols": ["aave-v3", "compound-v3"]
}

POST/v1/simulate/what-ifpro

Simulate price changes and their effect on positions

Request Body

{
  "positionId": "pos_abc123",
  "scenarios": [
    { "asset": "ETH", "priceChangePercent": -30 }
  ]
}

Response

{
  "results": [
    {
      "scenario": "ETH -30%",
      "newHealthFactor": 1.12,
      "liquidationRisk": "high",
      "estimatedLoss": 3000
    }
  ]
}

POST/v1/simulate/monte-carlopro

Monte Carlo simulation (1K iterations on Pro, 5K on Business)

Request Body

{
  "positionId": "pos_abc123",
  "iterations": 1000,
  "horizonDays": 30
}

Response

{
  "iterations": 1000,
  "liquidationProbability": 0.12,
  "percentiles": {
    "p5": { "healthFactor": 0.95 },
    "p50": { "healthFactor": 1.65 },
    "p95": { "healthFactor": 2.40 }
  }
}

GET/v1/risk/metricspro

VaR, CVaR, volatility, and advanced risk metrics

Response

{
  "var95": 12500,
  "cvar95": 18000,
  "portfolioVolatility": 0.45,
  "sharpeRatio": 1.2
}

GET/v1/whales/clusterspro

Whale wallet clusters and their aggregate positions

Response

{
  "clusters": [
    {
      "id": "wc_001",
      "walletCount": 12,
      "totalValueUsd": 450000000,
      "dominantProtocol": "aave-v3"
    }
  ]
}

POST/v1/ai/risk-qapro

Ask AI about risk in natural language

Request Body

{ "question": "What is my liquidation risk if ETH drops 40%?" }

Response

{
  "answer": "If ETH drops 40%, your Aave V3 position would...",
  "confidence": 0.92,
  "sources": ["position_analysis", "market_data"]
}

GET/v1/alertspro

List alerts for the authenticated user

Parameters

limit(number)— Max results (default: 50)

status(string)— Filter: active, resolved

Response

{
  "alerts": [
    {
      "id": "alt_001",
      "type": "health_factor_warning",
      "severity": "high",
      "message": "Health factor dropped below 1.5",
      "createdAt": "2026-03-21T10:30:00Z"
    }
  ]
}

GET/v1/analytics/portfoliopro

Portfolio analytics — allocation, performance, risk distribution

Response

{
  "portfolio": {
    "totalPositions": 5,
    "totalCollateralUsd": 150000,
    "totalDebtUsd": 60000,
    "netWorthUsd": 90000,
    "avgHealthFactor": 2.15,
    "positionsAtRisk": 0
  }
}

POST/v1/ai/suggestionspro

AI-generated risk suggestions for your portfolio

Response

{
  "suggestions": [
    {
      "type": "add_collateral",
      "severity": "warning",
      "title": "Warning: Aave V3 position at elevated risk",
      "description": "Health factor is 1.35. Consider adding collateral.",
      "positionId": "pos_abc123",
      "protocol": "aave_v3"
    }
  ],
  "count": 1,
  "positionsAnalyzed": 5
}

GET/v1/webhookspro

List your webhook endpoints

Response

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://example.com/webhook",
      "events": ["alert.created", "position.updated"],
      "isEnabled": true,
      "deliveryCount": 42,
      "createdAt": "2026-03-21T10:00:00Z"
    }
  ],
  "count": 1
}

POST/v1/webhookspro

Create a webhook endpoint

Request Body

{
  "url": "https://example.com/webhook",
  "events": ["alert.created", "alert.resolved", "position.updated"]
}

Response

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://example.com/webhook",
    "events": ["alert.created", "alert.resolved", "position.updated"],
    "secret": "whsec_a1b2c3...",
    "isEnabled": true
  }
}

DELETE/v1/webhooks/:idpro

Delete a webhook endpoint

Response

{ "success": true, "deleted": "wh_abc123" }

POST/v1/webhooks/:id/testpro

Send a test ping to a webhook endpoint

Response

{
  "success": true,
  "statusCode": 200,
  "responseTime": 145,
  "deliveryId": "del_abc123"
}

Guardian Business Endpoints

$999/mo

All Pro endpoints plus:

POST/v1/simulate/stress-testbusiness

Multi-scenario stress testing

Request Body

{
  "positionId": "pos_abc123",
  "scenarios": ["eth_crash_50", "usdc_depeg", "aave_exploit"]
}

Response

{
  "results": [
    { "scenario": "eth_crash_50", "healthFactor": 0.82, "liquidated": true },
    { "scenario": "usdc_depeg", "healthFactor": 1.55, "liquidated": false },
    { "scenario": "aave_exploit", "healthFactor": 0.00, "liquidated": true }
  ]
}

GET/v1/whales/activitybusiness

Real-time whale activity feed with protocol action decoding

Response

{
  "activity": [
    {
      "wallet": "0xwhale...",
      "action": "withdraw",
      "protocol": "aave-v3",
      "asset": "WETH",
      "amount": 500,
      "usdValue": 1600000,
      "timestamp": "2026-03-21T12:05:00Z"
    }
  ]
}

POST/v1/ai/briefingbusiness

AI-generated daily risk briefing

Request Body

{ "timeframe": "24h" }

Response

{
  "briefing": "## Market Overview\nDeFi markets showed elevated volatility...",
  "alerts": 12,
  "topRisks": ["ETH volatility", "AAVE governance proposal"],
  "generatedAt": "2026-03-21T06:00:00Z"
}

POST/v1/ai/postmortembusiness

AI incident postmortem analysis

Request Body

{ "incidentId": "inc_001" }

Response

{
  "summary": "A cascading liquidation event triggered by...",
  "timeline": [...],
  "rootCause": "Sudden oracle price drop of 15% in 2 blocks",
  "recommendations": [...]
}

POST/v1/positions/:id/forecastbusiness

Liquidation distance forecast

Response

{
  "currentHealthFactor": 1.85,
  "liquidationPrice": { "ETH": 1800 },
  "distancePercent": 42,
  "daysToLiquidation": null
}

POST/v1/positions/:id/deleveragebusiness

Calculate optimal deleverage strategy

Request Body

{ "targetHealthFactor": 2.5 }

Response

{
  "positionId": "pos_abc123",
  "currentHealthFactor": 1.85,
  "targetHealthFactor": 2.5,
  "requiredRepayUsd": 2000.00,
  "protocol": "aave_v3",
  "strategy": "repay_debt"
}

POST/v1/positions/batchbusiness

Batch position lookup across multiple wallets (up to 100 per request)

Request Body

{ "wallets": ["0x1234...abcd", "0x5678...efgh"] }

Response

{
  "positions": [...],
  "count": 12,
  "walletsQueried": 2
}

GET/v1/automation/rulesbusiness

List automation rules for your account

Response

{
  "rules": [
    {
      "id": "rule_001",
      "name": "Low Health Alert",
      "conditionType": "health_factor_below",
      "conditionValue": 1.5,
      "actionType": "alert",
      "isActive": true
    }
  ],
  "count": 1
}

POST/v1/automation/rulesbusiness

Create an automation rule

Request Body

{
  "name": "Low Health Alert",
  "conditionType": "health_factor_below",
  "conditionValue": 1.5,
  "actionType": "alert",
  "positionId": "pos_abc123"
}

Response

{
  "rule": {
    "id": "rule_002",
    "name": "Low Health Alert",
    "conditionType": "health_factor_below",
    "conditionValue": 1.5,
    "actionType": "alert",
    "isActive": true,
    "createdAt": "2026-03-21T12:00:00Z"
  }
}

GET/v1/automation/executionsbusiness

Automation execution history

Response

{
  "executions": [
    {
      "id": "exec_001",
      "ruleId": "rule_001",
      "status": "completed",
      "triggeredAt": "2026-03-21T10:00:00Z",
      "result": "Alert sent via email and webhook"
    }
  ],
  "count": 1
}

GET/v1/analytics/historicalbusiness

Historical position snapshots (up to 90 days on Business)

Parameters

days(number)— Lookback period in days (default: 30, max: tier limit)

Response

{
  "snapshots": [
    {
      "positionId": "pos_abc123",
      "healthFactor": 2.10,
      "collateralUsd": 10000,
      "debtUsd": 4800,
      "createdAt": "2026-03-20T00:00:00Z"
    }
  ],
  "count": 30,
  "days": 30,
  "maxDays": 90
}

Guardian Enterprise

Custom

All Business endpoints plus WebSocket streams, on-chain execution API, dedicated infra, SSO, white-label.

WS /v1/streams/positions — Real-time position updates

WS /v1/streams/alerts — Real-time alert stream

WS /v1/streams/whales — Real-time whale activity

POST /v1/execution/deleverage — On-chain auto-execution

GET /v1/execution/status — Execution status tracking

Contact Sales

Enterprise plans include dedicated infrastructure, SLAs, named account manager, and custom integrations. Contact us at sales@defiguardian.fi

● Error Codes

400Bad Request— Invalid request parameters

401Unauthorized— Missing or invalid API key

403Forbidden— Endpoint requires a higher API tier, or scope not granted

404Not Found— Resource not found

429Too Many Requests— Rate limit exceeded — check X-RateLimit-Reset header

500Server Error— Internal server error — include X-Request-Id when reporting

● Official SDKs

🟨

API Reference

● Base URL

● Authentication

● API Product Tiers

● Response Headers

Guardian Open Endpoints

Response

Parameters

Response

Response

Response

Response

Response

Parameters

Response

Response

Response

Request Body

Response

Guardian Pro Endpoints

Response

Response

Request Body

Response

Request Body

Response

Request Body

Response

Response

Response

Request Body

Response

Parameters

Response

Response

Response

Response

Request Body

Response

Response

Response

Guardian Business Endpoints

Request Body

Response

Response

Request Body

Response

Request Body

Response

Response

Request Body

Response

Request Body

Response

Response

Request Body

Response

Response

Parameters

Response

Guardian Enterprise

● Error Codes

● Official SDKs

TypeScript

Python

Go

Rust