> For the complete documentation index, see [llms.txt](https://triggerx.gitbook.io/triggerx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://triggerx.gitbook.io/triggerx-docs/developer-hub/aave-triggerx-automation-system.md).

# Aave TriggerX Automation System

Automated collateral protection for Aave V3 positions using the TriggerX Automation SDK and Safe Wallet.\
This system continuously monitors your health factor and automatically tops up collateral whenever it drops below your specified threshold, protecting your position from liquidation 24/7.

## **Overview**

The Aave TriggerX Automation System enables:

* **Real-time monitoring** of your Aave V3 health factor
* **Automatic collateral top-ups** when HF ≤ threshold
* **Secure execution** via Safe Wallet
* **Decentralized automation** using TriggerX
* **Public health-monitoring API** (locally served, exposed via ngrok)

This system is ideal for users who want non-custodial, programmable protection for leveraged Aave strategies.

## **Prerequisites**

Before getting started, ensure you have:

#### **Software**

* Node.js v16+
* npm or yarn
* ngrok (for exposing local API)

#### **Wallet Requirements**

* Wallet with:
  * **ETH** for gas
  * **WETH** for collateral top-ups
* Active Aave V3 position (Optimism Sepolia recommended for testing)
* TriggerX API Key → <https://triggerx.network/>

## **Project Structure**

```
aave-triggerX/
├── src/
│   ├── contracts/               # ABIs and contract addresses
│   ├── services/
│   │   ├── aave.service.ts      # Aave contract interactions
│   │   ├── health-monitor.service.ts  # API exposing health factor
│   │   └── triggerx.service.ts  # TriggerX SDK wrapper
│   ├── utils/config.ts          # Global config values
│   └── main.ts                  # App entry point
├── scripts/
│   ├── create-safe-wallet.ts
│   ├── prepare-safe-wallet.ts
│   ├── approve-weth-for-aave.ts
│   └── deploy-ngrok-job.ts
├── .env
├── package.json
├── tsconfig.json
└── README.md
```

***

## **How the System Works**

1. **Health Monitoring API**\
   Runs locally and exposes:

   ```
   GET /health-factor/:wallet
   ```
2. **ngrok** exposes the local API publicly so TriggerX can call it.
3. **TriggerX Job** polls the API every \~90 seconds.
4. **Condition Logic**\
   If `healthFactor ≤ threshold`TriggerX executes the job.
5. **Safe Wallet Execution**\
   TriggerX triggers a Safe transaction that:
   * Approves WETH (if not approved)
   * Supplies WETH to the Aave Pool
6. **Aave Position Strengthened**\
   Health Factor increases, reducing liquidation risk.

## **Quick Start**

### **1. Install the Repository**

```bash
git clone https://github.com/trigg3rX/aave-triggerX.git
cd aave-triggerX
npm install
```

### **2. Configure Environment Variables**

Create a `.env` file:

```env
# Private key of wallet with Aave position
PRIVATE_KEY=your_private_key_here

# TriggerX API Key
TRIGGERX_API_KEY=your_triggerx_api_key_here

# RPC + Chain
SEPOLIA_RPC_URL=https://sepolia.optimism.io
CHAIN_ID=11155420

# User + Safe Wallet
USER_ADDRESS=0xYourWalletAddress
SAFE_WALLET_ADDRESS=0xYourSafeWalletAddress

# Aave Contracts (Optimism Sepolia)
AAVE_POOL_ADDRESS=0xb50201558B00496A145fE76f7424749556E326D8
AAVE_POOL_DATA_PROVIDER=0x9991e51345F8E60Ec76d5AF29D910B93dcC05620

# Public API URL (updated after ngrok runs)
PUBLIC_URL=https://your-ngrok-url.ngrok-free.dev
```

### **3. Start the Health Monitoring API**

```bash
npm start
```

This launches an API server at <http://localhost:3000>, which TriggerX uses to fetch your health factor.

### **4. Expose API Using ngrok**

```bash
ngrok http 3000
```

Copy the tunnel URL and update `.env`:

```
PUBLIC_URL=https://abc123.ngrok-free.dev
```

### **5. Create Safe Wallet**

```bash
npm run create-safe
```

Save the generated address in `.env` under `SAFE_WALLET_ADDRESS`.

### **6. Fund the Safe Wallet**

Send:

* **WETH** → for collateral supply
* **ETH** → for gas

Example:

* 0.1 WETH
* 0.01 ETH

### **7. Approve WETH for Aave**

```bash
npm run approve-weth
```

### **8. Deploy TriggerX Automation Job**

```bash
npm run deploy-ngrok
```

Your Aave position is now monitored and automatically protected by TriggerX.

## **Customization Guide**

### **1. Using Different Chains**

Update `.env`:

#### Ethereum Mainnet:

```env
SEPOLIA_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key
CHAIN_ID=1
```

#### Arbitrum:

```env
SEPOLIA_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/your-api-key
CHAIN_ID=42161
```

Update Aave V3 contract addresses accordingly:\
→ <https://docs.aave.com/developers/deployed-contracts/v3-mainnet>

Update WETH address in `abis.ts`.

### **2. Monitoring a Different Wallet**

Update:

```env
USER_ADDRESS=0xNewWallet
```

(Optional) Create a new Safe:

```bash
npm run create-safe
```

Then re-fund, re-approve, and re-deploy the job.

### **3. Customizing Threshold & Top-Up Amount**

Edit `src/utils/config.ts`:

```ts
export const config = {
  healthFactorThreshold: 1.5,
  topUpAmount: '50000000000000000', // 0.05 ETH
  jobDuration: 3600,                // 1 hour
};
```

### **4. Using Your Own API Instead of Built-In**

Your API must:

* Return pure number format
* Content-Type: `text/plain`
* Respond within 5 seconds
* Publicly accessible

Example:

```
1.42
```

Update `deploy-ngrok-job.ts`:

```ts
valueSourceUrl: `https://your-api.com/health-factor/${config.userAddress}`,
```

Then deploy:

```bash
npm run deploy-ngrok
```

### **5. Customizing Safe Transactions**

You can supply a different token:

```ts
const YOUR_TOKEN_ADDRESS = '0x...';
```

Or add multiple Safe actions:

```ts
safeTransactions: [
  { to: WETH, data: approveData },
  { to: AAVE_POOL, data: supplyData },
  { to: AAVE_POOL, data: enableCollateralData },
]
```

## **Available Commands**

| Command                | Description               |
| ---------------------- | ------------------------- |
| `npm start`            | Start local API server    |
| `npm run deploy-ngrok` | Deploy TriggerX job       |
| `npm run create-safe`  | Create Safe wallet        |
| `npm run prepare-safe` | Check Safe status         |
| `npm run approve-weth` | Approve WETH for Aave     |
| `npm run dev`          | Start in development mode |
| `npm run build`        | Compile TS → JS           |
| `npm run clean`        | Clear build artifacts     |

## **Security**

* Never share `.env` or your private key
* Only fund Safe with the required amounts
* Use testnets for all initial testing
* ngrok exposes your API publicly → Avoid exposing wallet balances, keys, internal logs

## **Troubleshooting**

#### **Job Not Triggering**

* Health factor not below threshold
* Wrong ngrok URL
* Safe wallet lacks WETH or ETH
* WETH not approved
* Job expired (non-recurring jobs run once)

#### **API Timeout**

* Slow RPC → use Alchemy/Infura
* ngrok not running
* Network filtering on your machine

#### **Transaction Reverts**

* Not enough WETH
* Not enough gas in Safe
* Aave supply reverted because HF is already high

## **Advanced Options**

#### **Recurring Jobs**

In `deploy-ngrok-job.ts`:

```ts
recurring: true,
timeFrame: 86400, // 1 day
```

#### **Monitor Multiple Wallets**

1. Create multiple `.env` files
2. Run multiple API instances
3. Create separate ngrok tunnels
4. Deploy multiple jobs

#### **Trigger Conditions Supported**

```ts
less_equal
greater_equal
equal
between
```

## **Useful Links**

* Aave V3 Docs → <https://docs.aave.com/developers>
* TriggerX Docs → <https://triggerx.gitbook.io/triggerx-docs>
* Safe Docs → <https://docs.safe.global/>
* Ethers.js → <https://docs.ethers.org/>