Aave V3 Lending Protocol CLI

7 commands for lending market data, reserve details, account positions, supply/withdraw, and borrow/repay operations.

Pre-flight Checks

Every time before running any plugin-store command, always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

Confirm installed: Run which plugin-store . If not found, install it:

curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install.sh | sh

If the install script fails, ask the user to install manually following the instructions at: https://github.com/okx/plugin-store

Check for updates: Read ~/.plugin-store/last_check and compare it with the current timestamp:

cached_ts=$(cat ~/.plugin-store/last_check 2>/dev/null || true) now=$(date +%s)

• If cached_ts is non-empty and (now - cached_ts) < 43200 (12 hours), skip the update and proceed.

• Otherwise (file missing or older than 12 hours), run the installer to check for updates: curl -sSL https://raw.githubusercontent.com/purong-huang-1121/skills-store/main/install.sh | sh

If any plugin-store command fails with an unexpected error during this session, try reinstalling before giving up.

Skill Routing

• For token search / analytics → use okx-dex-token

• For DEX swap → use okx-dex-swap

• For token prices / charts → use okx-dex-market

• For wallet balances → use okx-wallet-portfolio

• For transaction broadcasting → use okx-onchain-gateway

• For prediction markets → use okx-dapp-polymarket

Authentication

Data commands (markets, reserve, account): No authentication needed. Work immediately.

Transaction commands (supply, withdraw, borrow, repay): Require an EVM wallet private key:

Add to .env file

EVM_PRIVATE_KEY=0x...

The private key is used to sign supply, withdraw, borrow, and repay transactions on-chain.

Quickstart

Browse and Research

List all Aave V3 markets on Ethereum

plugin-store aave markets --chain ethereum

Get reserve details for USDC

plugin-store aave reserve USDC --chain ethereum

Check account positions

plugin-store aave account 0xYourAddress --chain ethereum

Supply and Withdraw

Supply 100 USDC to Aave on Ethereum

plugin-store aave supply --token USDC --amount 100 --chain ethereum

Withdraw 50 USDC from Aave

plugin-store aave withdraw --token USDC --amount 50 --chain ethereum

Withdraw all USDC (full balance)

plugin-store aave withdraw --token USDC --amount max --chain ethereum

Borrow and Repay

Borrow 500 USDC against your collateral (variable rate)

plugin-store aave borrow --token USDC --amount 500 --chain ethereum

Repay 200 USDC of your debt

plugin-store aave repay --token USDC --amount 200 --chain ethereum

Repay all outstanding USDC debt

plugin-store aave repay --token USDC --amount max --chain ethereum

Command Index

Command Auth Description

1 plugin-store aave markets --chain <chain>

No List all Aave V3 reserve markets on a chain

2 plugin-store aave reserve <symbol> --chain <chain>

No Get detailed reserve data (APY, liquidity, config)

3 plugin-store aave account <address> --chain <chain>

No View account positions, health factor, borrowing power

4 plugin-store aave supply --token <symbol> --amount <n> --chain <chain>

Yes Supply assets to earn yield

5 plugin-store aave withdraw --token <symbol> --amount <n> --chain <chain>

Yes Withdraw supplied assets (use "max" for full withdrawal)

6 plugin-store aave borrow --token <symbol> --amount <n> --chain <chain>

Yes Borrow assets at variable rate against collateral

7 plugin-store aave repay --token <symbol> --amount <n> --chain <chain>

Yes Repay borrowed assets (use "max" for full repayment)

Cross-Skill Workflows

Workflow A: Research and Supply (most common)

User: "What are the best lending rates on Aave right now?"

1. aave markets --chain ethereum → show all reserves with APYs ↓ user picks an asset
2. aave reserve USDC --chain ethereum → show detailed reserve info ↓ user wants to supply
3. Check EVM_PRIVATE_KEY is set ↓ not set → prompt user to add to .env ↓ set → continue
4. aave supply --token USDC --amount 100 --chain ethereum ↓
5. "Supplied 100 USDC to Aave V3. You will receive aUSDC as a receipt token."

Data handoff:

• symbol from markets data → <symbol> for reserve/supply/withdraw commands

• underlyingAsset address is resolved automatically from the symbol

Workflow B: Portfolio Review and Withdrawal

1. aave account 0xYourAddress --chain ethereum → show positions, health factor
2. aave reserve WETH --chain ethereum → check current rates on a position
3. aave withdraw --token WETH --amount max --chain ethereum → withdraw full balance

Workflow C: Multi-Chain Comparison

1. aave markets --chain ethereum → Ethereum rates
2. aave markets --chain polygon → Polygon rates
3. aave markets --chain arbitrum → Arbitrum rates
4. aave supply --token USDC --amount 100 --chain arbitrum → supply on best chain

Workflow D: With OKX Skills

1. okx-wallet-portfolio balance --chain ethereum → check token balances
2. aave markets --chain ethereum → check lending rates
3. aave supply --token USDC --amount 100 --chain ethereum → supply to Aave

Operation Flow

Step 1: Identify Intent

• Browse markets/rates → markets

• Check specific asset details → reserve

• Check account status → account

• Deposit/lend assets → supply

• Withdraw assets → withdraw

• Borrow against collateral → borrow

• Repay debt → repay

Step 2: Collect Parameters

• Missing chain → ask user which chain (ethereum, polygon, or arbitrum)

• Missing symbol for reserve → use markets first, then pick from the list

• Missing address for account → ask user for their wallet address

• Missing amount for supply/withdraw/borrow/repay → ask user how much

• Missing private key (for supply/withdraw/borrow/repay) → prompt to set EVM_PRIVATE_KEY in .env

Step 3: Execute

• Data phase: show market info, rates, positions, let user make informed decision

• Confirmation phase: before any supply/withdraw, display token, amount, chain, estimated APY, and ask for confirmation

• Execution phase: submit transaction, show result with tx hash

Step 4: Suggest Next Steps

Just completed Suggest

markets

1. Check specific reserve details → reserve
2. View account positions → account

reserve

1. Supply assets → supply
2. Compare with other chains → markets on another chain

account

1. Withdraw assets → withdraw
2. Supply more → supply

supply

1. Check updated position → account
2. View reserve APY → reserve

withdraw

1. Check updated position → account
2. View wallet balance → okx-wallet-portfolio

borrow

1. Check health factor → account
2. Monitor borrow rate → reserve

repay

1. Check updated debt → account
2. View wallet balance → okx-wallet-portfolio

Present conversationally — never expose skill names or endpoint paths to the user.

CLI Command Reference

1. plugin-store aave markets

plugin-store aave markets --chain <chain>

Param Required Default Description

--chain

Yes

Chain: ethereum, polygon, arbitrum

Key return fields per reserve:

Field Description

symbol

Asset symbol (e.g. USDC, WETH, DAI)

underlyingAsset

Token contract address

supplyAPY

Current annual supply yield (as decimal, multiply by 100 for %)

borrowAPY

Current annual borrow rate

totalSupply

Total amount supplied

totalBorrow

Total amount borrowed

availableLiquidity

Amount available to borrow

utilizationRate

Ratio of borrowed to supplied

ltv

Loan-to-value ratio for collateral

liquidationThreshold

Threshold at which position can be liquidated

2. plugin-store aave reserve

plugin-store aave reserve <symbol> --chain <chain>

Param Required Default Description

<symbol>

Yes

Asset symbol (e.g. USDC, WETH, DAI)

--chain

Yes

Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

symbol

Asset symbol

supplyAPY

Current supply APY

variableBorrowAPY

Variable borrow rate

stableBorrowAPY

Stable borrow rate (if available)

totalSupply

Total supplied amount

totalBorrow

Total borrowed amount

availableLiquidity

Available to borrow

utilizationRate

Current utilization

ltv

Max loan-to-value for collateral

liquidationThreshold

Liquidation trigger threshold

liquidationBonus

Bonus for liquidators

reserveFactor

Protocol fee on interest

canBeCollateral

Whether asset can be used as collateral

borrowingEnabled

Whether borrowing is enabled

3. plugin-store aave account

plugin-store aave account <address> --chain <chain>

Param Required Default Description

<address>

Yes

Wallet address (0x...)

--chain

Yes

Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

totalSuppliedUSD

Total value of supplied assets in USD

totalBorrowedUSD

Total value of borrowed assets in USD

netWorthUSD

Net position value in USD

healthFactor

Health factor (< 1.0 = liquidatable)

availableBorrowsUSD

Remaining borrowing capacity in USD

currentLTV

Current loan-to-value ratio

supplies

List of supplied positions [{symbol, amount, amountUSD, apy}]

borrows

List of borrow positions [{symbol, amount, amountUSD, apy}]

4. plugin-store aave supply

plugin-store aave supply --token <symbol> --amount <amount> --chain <chain>

Param Required Default Description

--token

Yes

Asset symbol (e.g. USDC, WETH)

--amount

Yes

Amount to supply (in token units)

--chain

Yes

Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

txHash

Transaction hash

status

Transaction status (pending, confirmed, failed)

supplied

Amount supplied

token

Token symbol

chain

Chain used

5. plugin-store aave withdraw

plugin-store aave withdraw --token <symbol> --amount <amount> --chain <chain>

Param Required Default Description

--token

Yes

Asset symbol (e.g. USDC, WETH)

--amount

Yes

Amount to withdraw (in token units, or "max" for full withdrawal)

--chain

Yes

Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

txHash

Transaction hash

status

Transaction status (pending, confirmed, failed)

withdrawn

Amount withdrawn

token

Token symbol

chain

Chain used

6. plugin-store aave borrow

plugin-store aave borrow --token <symbol> --amount <amount> --chain <chain>

Param Required Default Description

--token

Yes

Asset symbol to borrow (e.g. USDC, WETH)

--amount

Yes

Amount to borrow (in token units)

--chain

No ethereum Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

txHash

Transaction hash

status

Transaction status (success, reverted)

borrowed

Amount borrowed

token

Token symbol

chain

Chain used

7. plugin-store aave repay

plugin-store aave repay --token <symbol> --amount <amount> --chain <chain>

Param Required Default Description

--token

Yes

Asset symbol to repay (e.g. USDC, WETH)

--amount

Yes

Amount to repay (in token units, or "max" for full repayment)

--chain

No ethereum Chain: ethereum, polygon, arbitrum

Return fields:

Field Description

txHash

Transaction hash

status

Transaction status (success, reverted)

repaid

Amount repaid

token

Token symbol

chain

Chain used

Key Concepts

• Supply APY: Annual percentage yield earned by supplying assets. Rates are variable and change based on utilization.

• Health Factor: Ratio indicating position safety. Above 1.0 is safe; below 1.0 means the position can be liquidated. Keep it well above 1.0 (recommended > 1.5).

• aTokens: Receipt tokens received when supplying (e.g. supply USDC, receive aUSDC). aTokens accrue interest automatically — their balance grows over time.

• RAY: Aave uses 27-decimal fixed-point numbers (1 RAY = 10^27) for rate calculations internally. The CLI converts these to human-readable percentages.

• LTV (Loan-to-Value): Maximum percentage of collateral value that can be borrowed. E.g. 80% LTV means you can borrow up to 80% of your collateral value.

• Liquidation Threshold: The LTV level at which a position becomes eligible for liquidation. Always higher than the max LTV.

• Utilization Rate: Ratio of total borrowed to total supplied. Higher utilization = higher rates for both suppliers and borrowers.

Edge Cases

• Insufficient balance: If the user tries to supply more than their wallet balance, the transaction will fail. Check balance first via okx-wallet-portfolio .

• Health factor risk: When withdrawing collateral or borrowing, warn if the resulting health factor would drop below 1.5. Withdrawing/borrowing too much can trigger liquidation.

• Borrow capacity: User must have sufficient collateral before borrowing. Check available borrows via account command.

• Max repay: Use --amount max to repay the full outstanding debt including accrued interest.

• Max withdrawal: Use --amount max to withdraw the full supplied balance including accrued interest. This uses type(uint256).max internally.

• Token approval: First-time supply of a token requires an ERC-20 approval transaction. The CLI handles this automatically but it will use additional gas.

• Private key not set: For supply/withdraw commands, show clear error: "Set EVM_PRIVATE_KEY in your .env file"

• Unsupported chain: Only ethereum, polygon, and arbitrum are supported. Other chains will return an error.

• Asset not listed: If a token symbol is not recognized as an Aave V3 reserve, suggest using markets to see available assets.

• Rate limiting: OKX API has rate limits. Use retry with backoff.