{ "openapi": "3.1.1", "info": { "title": "DeFi Liquidation Explorer API", "version": "1.0.0", "summary": "Recent Aave V3 liquidations in USD, who liquidated whom, and a live health-factor check.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://defiliquidationexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Recent Aave V3 liquidations in USD, who liquidated whom, and a live health-factor check.", "description": "Reads Aave V3 LiquidationCall events from the official Pool contract over a recent block window (Ethereum, Base, Arbitrum, OP Mainnet, Polygon, Avalanche, BNB Chain), resolves token symbols and decimals on-chain, values each liquidation at current DefiLlama prices, ranks liquidators and borrowers, and checks any address's current health factor with getUserAccountData — so you can see how close a position is to liquidation.\n\nMethodology:\n- Events: LiquidationCall(address indexed collateralAsset, address indexed debtAsset, address indexed user, uint256 debtToCover, uint256 liquidatedCollateralAmount, address liquidator, bool receiveAToken) from the Aave V3 Pool of the chosen market (addresses from the bgd-labs aave-address-book), read with eth_getLogs over the last N blocks; if the node refuses the range it is halved (down to 100 blocks) and the shrink is reported.\n- Tokens: symbol() and decimals() via eth_call. USD: current DefiLlama coins prices — today's value of the amounts, not the price at liquidation time.\n- Implied bonus = collateral USD ÷ debt USD − 1 at current prices (approximate; Aave's liquidation bonus and protocol fee are reserve parameters).\n- Health factor: Pool.getUserAccountData(user); collateral/debt in the market base currency (BASE_CURRENCY_UNIT read from the price oracle via ADDRESSES_PROVIDER); a health factor below 1 means the position can be liquidated now.", "tags": [ "web3" ], "x-mcp-tool": "defi_liquidation_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefiLiquidationExplorerInput" }, "examples": { "example1": { "summary": "Three Ethereum liquidations (offline logs)", "value": { "mode": "logs", "chain": "ethereum", "logs": "[{\"address\":\"0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2\",\"blockNumber\":\"0x1406f40\",\"transactionHash\":\"0x1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a\",\"topics\":[\"0xe413a321e8681d831f4dbccbca790d2952b56f977908e45be37335533e005286\",\"0x000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"0x000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"0x000000000000000000000000eeee00000000000000000000000000000000eeee\"],\"data\":\"0x000000000000000000000000000000000000000000000000000000012a05f2000000000000000000000000000000000000000000000000001d24b2dfac520000000000000000000000000000dddd00000000000000000000000000000000dddd0000000000000000000000000000000000000000000000000000000000000000\"},{\"address\":\"0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2\",\"blockNumber\":\"0x1406f72\",\"transactionHash\":\"0x2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b\",\"topics\":[\"0xe413a321e8681d831f4dbccbca790d2952b56f977908e45be37335533e005286\",\"0x000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"0x000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7\",\"0x000000000000000000000000ffff00000000000000000000000000000000ffff\"],\"data\":\"0x0000000000000000000000000000000000000000000000000000000047868c000000000000000000000000000000000000000000000000000737693eb3340000000000000000000000000000dddd00000000000000000000000000000000dddd0000000000000000000000000000000000000000000000000000000000000000\"},{\"address\":\"0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2\",\"blockNumber\":\"0x1406f9a\",\"transactionHash\":\"0x3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c\",\"topics\":[\"0xe413a321e8681d831f4dbccbca790d2952b56f977908e45be37335533e005286\",\"0x000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",\"0x000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\",\"0x000000000000000000000000eeee00000000000000000000000000000000eeee\"],\"data\":\"0x00000000000000000000000000000000000000000000000006f05b59d3b20000000000000000000000000000000000000000000000000000000000004a817c8000000000000000000000000077777000000000000000000000000000000777770000000000000000000000000000000000000000000000000000000000000000\"}]" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefiLiquidationExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DefiLiquidationExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "What do you have?", "type": "string", "enum": [ "lookup", "logs" ], "default": "lookup" }, "chain": { "title": "Aave V3 market", "type": "string", "enum": [ "ethereum", "base", "arbitrum", "optimism", "polygon", "avalanche", "bsc" ], "default": "ethereum" }, "blocks": { "title": "Blocks to scan back from the latest", "description": "Ethereum ≈ 12 s/block, Base/OP ≈ 2 s, Arbitrum ≈ 0.25 s. Public nodes cap log ranges; the window shrinks automatically if refused.", "type": "integer", "minimum": 10, "maximum": 20000, "default": 2000 }, "user": { "title": "Check a borrower's health factor (optional)", "description": "Without it, the most recently liquidated borrower is checked.", "type": "string", "maxLength": 42 }, "logs": { "title": "LiquidationCall logs JSON (offline)", "type": "string", "maxLength": 1000000 } }, "required": [] }, "DefiLiquidationExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "mode", "chain", "pool", "window", "liquidations", "totals", "byLiquidator", "byPair", "account", "graph" ], "properties": { "mode": { "type": "string", "enum": [ "lookup", "logs" ] }, "chain": { "type": "string" }, "pool": { "type": "string" }, "window": { "type": "object", "additionalProperties": false, "required": [ "fromBlock", "toBlock", "blocks", "fromTime", "toTime", "shrunk" ], "properties": { "fromBlock": { "type": [ "integer", "null" ] }, "toBlock": { "type": [ "integer", "null" ] }, "blocks": { "type": [ "integer", "null" ] }, "fromTime": { "type": [ "string", "null" ] }, "toTime": { "type": [ "string", "null" ] }, "shrunk": { "type": "boolean" } } }, "liquidations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "block", "time", "tx", "user", "collateralAsset", "collateralSymbol", "collateralAmount", "collateralUsd", "debtAsset", "debtSymbol", "debtAmount", "debtUsd", "liquidator", "receiveAToken", "impliedBonusPct" ], "properties": { "block": { "type": [ "integer", "null" ] }, "time": { "type": [ "string", "null" ] }, "tx": { "type": [ "string", "null" ] }, "user": { "type": "string" }, "collateralAsset": { "type": "string" }, "collateralSymbol": { "type": [ "string", "null" ] }, "collateralAmount": { "type": [ "string", "null" ] }, "collateralUsd": { "type": [ "number", "null" ] }, "debtAsset": { "type": "string" }, "debtSymbol": { "type": [ "string", "null" ] }, "debtAmount": { "type": [ "string", "null" ] }, "debtUsd": { "type": [ "number", "null" ] }, "liquidator": { "type": "string" }, "receiveAToken": { "type": "boolean" }, "impliedBonusPct": { "type": [ "number", "null" ] } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "count", "debtUsd", "collateralUsd", "uniqueUsers", "uniqueLiquidators" ], "properties": { "count": { "type": "integer" }, "debtUsd": { "type": [ "number", "null" ] }, "collateralUsd": { "type": [ "number", "null" ] }, "uniqueUsers": { "type": "integer" }, "uniqueLiquidators": { "type": "integer" } } }, "byLiquidator": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "liquidator", "count", "debtUsd" ], "properties": { "liquidator": { "type": "string" }, "count": { "type": "integer" }, "debtUsd": { "type": [ "number", "null" ] } } } }, "byPair": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "pair", "count", "debtUsd" ], "properties": { "pair": { "type": "string" }, "count": { "type": "integer" }, "debtUsd": { "type": [ "number", "null" ] } } } }, "account": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "user", "checked", "healthFactor", "totalCollateralUsd", "totalDebtUsd", "availableBorrowsUsd", "liquidationThresholdPct", "ltvPct", "liquidatable" ], "properties": { "user": { "type": "string" }, "checked": { "type": "string", "enum": [ "user-input", "latest-liquidated" ] }, "healthFactor": { "type": [ "string", "null" ] }, "totalCollateralUsd": { "type": "number" }, "totalDebtUsd": { "type": "number" }, "availableBorrowsUsd": { "type": "number" }, "liquidationThresholdPct": { "type": "number" }, "ltvPct": { "type": "number" }, "liquidatable": { "type": "boolean" } } }, "graph": { "type": "object", "additionalProperties": false, "required": [ "nodes", "edges" ], "properties": { "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "kind" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" } } } }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "label" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }