# DeFi Liquidation Risk Checker (Aave V3 Multi-Chain) (`gochujang/defi-liquidation-risk-checker`) Actor

On-demand health factor + collateral / debt / LTV for any wallet's Aave V3 positions across Ethereum, Arbitrum, Base, Optimism, Polygon, Avalanche. Direct on-chain via Etherscan eth\_call. Telegram alerts on HF below threshold. $0.02 per wallet checked.

- **URL**: https://apify.com/gochujang/defi-liquidation-risk-checker.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Developer tools, Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## DeFi Liquidation Risk Checker (Aave V3)

> On-demand health factor + collateral / debt / LTV for any wallet's **Aave V3** positions across **Ethereum, Arbitrum, Base, Optimism, Polygon, Avalanche**. Direct on-chain via Etherscan eth_call. **No API key required.**

---

### Why this exists

If you have leveraged positions on Aave, **you need to know your health factor.** A position with HF < 1.0 will be liquidated, costing you the liquidation penalty (5-10% of debt).

Aave's own UI requires you to connect a wallet to check positions. Third-party tools (DeFi Saver, Instadapp) require sign-up or stake.

This actor takes any wallet address and reports HF + collateral + debt for **every Aave V3 market** in one run, with optional Telegram alerts when HF drops below your threshold.

---

### What you get

#### Per-chain row
| Field | Example | Notes |
|---|---|---|
| `chain` | `ethereum` | |
| `risk_level` | `critical` | liquidatable / critical / warning / watch / healthy / no-debt |
| `health_factor` | `1.18` | < 1.0 = liquidatable |
| `total_collateral_usd` | `120,500.50` | |
| `total_debt_usd` | `85,300.00` | |
| `ltv_pct` | `70.84` | current LTV |
| `liquidation_threshold_pct` | `77.50` | LT for this combination of collateral |
| `available_borrows_usd` | `7,420.00` | how much more you can borrow |

#### Risk levels
| Level | Health Factor |
|---|---|
| 🔴 `liquidatable` | < 1.00 |
| 🟠 `critical` | 1.00 – 1.20 |
| 🟡 `warning` | 1.20 – 1.50 |
| 🟢 `watch` | 1.50 – 2.00 |
| ✅ `healthy` | > 2.00 |
| ⚪ `no-debt` | no active debt |

#### Summary row
Aggregates across all chains: total debt, total collateral, worst HF, worst chain.

---

### Quick start

#### Check a wallet across all 6 Aave V3 markets
```json
{
  "walletAddress": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503"
}
````

#### Check only Ethereum + Arbitrum

```json
{
  "walletAddress": "0x...",
  "chains": ["ethereum", "arbitrum"]
}
```

#### Alert when HF drops below 1.5

```json
{
  "walletAddress": "0x...",
  "alertHealthFactorBelow": 1.5,
  "telegramBotToken": "YOUR_BOT_TOKEN",
  "telegramChatId": "YOUR_CHAT_ID"
}
```

#### Schedule every 15 minutes during volatile markets

Configure Apify schedule → cron `*/15 * * * *` → input with `alertHealthFactorBelow: 1.3`. Sleeps until next 15-min boundary, costs $0.02 per check ($1.92/day for round-the-clock monitoring).

***

### Pricing

**Pay-Per-Event**: `$0.02 per wallet checked.`

Flat fee regardless of how many chains you query. Vs:

- DeFi Saver: free dashboard, paid automation ($2-5 / tx)
- Instadapp DSA: gas + deposit required
- Hypernative: $99-$2000/mo

***

### Risk explanation

Aave V3's **health factor** is calculated as:

```
HF = Σ(collateral_i × liquidationThreshold_i) / Σ(debt_j)
```

When HF drops to 1.0 or below, **liquidators can repay your debt and seize collateral** at a 5-10% discount.

Common triggers for HF drop:

1. **Collateral price drops** — e.g. ETH drops 20%, your wstETH collateral worth drops
2. **Borrowed asset price rises** — e.g. you borrowed USDC and ETH dumps, your debt value in ETH rises
3. **Rates compounding** — variable rate debt accrues interest

This actor takes a snapshot at the moment of the call. For continuous monitoring, schedule it.

***

### Supported markets

All canonical Aave V3 deployments:

- Ethereum mainnet (Pool: `0x8787...4fA4E2`)
- Arbitrum (Pool: `0x794a...4814aD`)
- Optimism (Pool: same)
- Base (Pool: `0xA238...8d1c5`)
- Polygon (Pool: same as Arb/Op)
- Avalanche C-Chain (Pool: same as Arb/Op)

Other markets (BNB, Metis, Gnosis, Scroll, ZkSync) coming if there's demand.

***

### Limitations

- **Aave V3 only.** Compound V3, Morpho, Spark, Maker — not yet covered (v0.2).
- **No isolation-mode logic.** HF returned by the contract already accounts for it, but per-asset detail is not exposed.
- **Etherscan free-tier rate limits.** Default Etherscan V2 key is shared and rate-limited to 5 req/s. Pass your own `etherscanApiKey` for production use.

***

### Related actors (same author)

- [Wallet PnL Analyzer](https://apify.com/gochujang/wallet-pnl-analyzer) — Full token portfolio for the same wallet
- [DeFi Liquidation Tracker](https://apify.com/gochujang/defi-liquidation-tracker) — Track liquidation events across protocols
- [Lending Rate Tracker](https://apify.com/gochujang/lending-rate-tracker) — Current borrow APYs
- [LST Health Tracker](https://apify.com/gochujang/lst-health-tracker) — If you collateralize wstETH/rETH

***

### Feedback

A short review helps DeFi power users find it: [Leave a review on Apify Store](https://apify.com/gochujang/defi-liquidation-risk-checker#reviews)

# Actor input Schema

## `walletAddress` (type: `string`):

EVM wallet address (0x...).

## `chains` (type: `array`):

Aave V3 markets to check. Empty = all 6 supported.

## `alertHealthFactorBelow` (type: `number`):

Send Telegram alert if any active position has health factor ≤ this value. 0 = disabled. 1.5 = warning, 1.2 = critical, 1.0 = liquidatable.

## `etherscanApiKey` (type: `string`):

Bring your own Etherscan V2 key for higher rate limits. Default works for low volume.

## `telegramBotToken` (type: `string`):

Telegram bot token.

## `telegramChatId` (type: `string`):

Chat ID.

## Actor input object example

```json
{
  "walletAddress": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
  "chains": [
    "ethereum",
    "arbitrum",
    "base",
    "optimism",
    "polygon",
    "avalanche"
  ],
  "alertHealthFactorBelow": 0,
  "telegramChatId": ""
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "walletAddress": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
    "chains": [
        "ethereum",
        "arbitrum",
        "base",
        "optimism",
        "polygon",
        "avalanche"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/defi-liquidation-risk-checker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "walletAddress": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
    "chains": [
        "ethereum",
        "arbitrum",
        "base",
        "optimism",
        "polygon",
        "avalanche",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/defi-liquidation-risk-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "walletAddress": "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503",
  "chains": [
    "ethereum",
    "arbitrum",
    "base",
    "optimism",
    "polygon",
    "avalanche"
  ]
}' |
apify call gochujang/defi-liquidation-risk-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=gochujang/defi-liquidation-risk-checker",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "DeFi Liquidation Risk Checker (Aave V3 Multi-Chain)",
        "description": "On-demand health factor + collateral / debt / LTV for any wallet's Aave V3 positions across Ethereum, Arbitrum, Base, Optimism, Polygon, Avalanche. Direct on-chain via Etherscan eth_call. Telegram alerts on HF below threshold. $0.02 per wallet checked.",
        "version": "0.1",
        "x-build-id": "Dmt6KpsCwdDZL63zi"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/gochujang~defi-liquidation-risk-checker/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-gochujang-defi-liquidation-risk-checker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/gochujang~defi-liquidation-risk-checker/runs": {
            "post": {
                "operationId": "runs-sync-gochujang-defi-liquidation-risk-checker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/gochujang~defi-liquidation-risk-checker/run-sync": {
            "post": {
                "operationId": "run-sync-gochujang-defi-liquidation-risk-checker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "walletAddress"
                ],
                "properties": {
                    "walletAddress": {
                        "title": "Wallet address",
                        "pattern": "^0x[a-fA-F0-9]{40}$",
                        "type": "string",
                        "description": "EVM wallet address (0x...)."
                    },
                    "chains": {
                        "title": "Chains",
                        "type": "array",
                        "description": "Aave V3 markets to check. Empty = all 6 supported.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "alertHealthFactorBelow": {
                        "title": "Alert on HF below",
                        "minimum": 0,
                        "type": "number",
                        "description": "Send Telegram alert if any active position has health factor ≤ this value. 0 = disabled. 1.5 = warning, 1.2 = critical, 1.0 = liquidatable.",
                        "default": 0
                    },
                    "etherscanApiKey": {
                        "title": "Etherscan API key (optional)",
                        "type": "string",
                        "description": "Bring your own Etherscan V2 key for higher rate limits. Default works for low volume."
                    },
                    "telegramBotToken": {
                        "title": "Telegram Bot Token",
                        "type": "string",
                        "description": "Telegram bot token."
                    },
                    "telegramChatId": {
                        "title": "Telegram Chat ID",
                        "type": "string",
                        "description": "Chat ID.",
                        "default": ""
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```