Stablecoin Yield Aggregator Agent

Production-ready Python agent that scans stablecoin lending APYs across configured protocols/chains, evaluates profitability after gas, executes a rebalance workflow (paper/live modes), and sends notifications.

What is implemented

This repository now includes a complete implementation of the future-oriented architecture:

• Multi-chain protocol scanning from configurable sources
• Decision engine with:
  • APY improvement threshold filtering
  • Gas-cost-aware profitability checks
  • Horizon-based projected gain model
• Rebalance execution pipeline:
  • paper mode simulation (safe default)
  • live mode execution placeholder with transaction flow scaffolding
• Notification system:
  • Console summary
  • Telegram integration
  • Discord webhook integration
• Config-driven behavior via config.yaml
• CLI entrypoint + package script
• Unit tests for config loading and rebalance decision logic

---

Project structure

stablecoin-yield-aggregator-agent/
├── agent.py
├── config.yaml
├── .env.example
├── requirements.txt
├── pyproject.toml
├── src/yield_aggregator/
│   ├── __init__.py
│   ├── cli.py
│   ├── config.py
│   ├── decision.py
│   ├── execution.py
│   ├── models.py
│   ├── notify.py
│   └── protocols.py
└── tests/
    ├── test_config.py
    └── test_decision.py

---

Core workflow

1. Load runtime config
2. Fetch APYs for configured stablecoin (USDC/USDT)
3. Identify current position and best target venue
4. Estimate gas in USD
5. Evaluate rebalance profitability
6. Execute in selected mode (paper or live)
7. Publish report (stdout, Telegram, Discord)

---

Installation

1) Clone and enter project

git clone https://github.com/Rezzecup/stablecoin-yield-aggregator-agent.git
cd stablecoin-yield-aggregator-agent

2) Create virtual environment

python3 -m venv .venv
source .venv/bin/activate

3) Install dependencies

pip install -r requirements.txt
pip install -e .[dev]

4) Prepare environment variables

cp .env.example .env

Set only what you need:

• RPC_URL, PRIVATE_KEY, WALLET_ADDRESS for live transaction integrations
• TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID for Telegram alerts
• DISCORD_WEBHOOK_URL for Discord alerts

---

Configuration

Edit config.yaml to control behavior:

• stablecoin: USDC or USDT
• portfolio: current position and amount
• min_yield_improvement: APY delta threshold
• horizon_days: profit projection window
• gas: gas and ETH pricing assumptions
• protocols: protocol-chain APY inputs
• notifications: stdout / Telegram / Discord toggles

---

Usage

Run once (paper mode)

python3 agent.py --mode paper

Run once (live placeholder)

python3 agent.py --mode live

Emit machine-readable output

python3 agent.py --mode paper --json

Alternative installed CLI

yield-agent --mode paper

---

Testing

Run the test suite:

pytest

---

Important notes

• paper mode is the safe default and should be used first.
• Current live mode intentionally ships as a structured execution placeholder so transaction signing/broadcast adapters can be added safely per protocol.
• The codebase is designed for extension with real on-chain adapters (Aave/Morpho/Compound) while keeping decision logic and risk controls isolated and testable.

---

Roadmap alignment status

Implemented from future-version scope:

• Telegram/Discord alert plumbing
• Multi-chain protocol support through config
• Gas-aware profitability gate
• Professional packaging + tests + CLI

Next recommended upgrades:

• Real protocol adapters (on-chain read/write)
• Scheduler service (cron/systemd/docker)
• Persistent position/state store
• Slippage and bridge-cost models for cross-chain moves
• Integration tests against forked chain environments

---

Security & risk disclaimer

This software is provided "as is" without warranty. DeFi and smart contract interactions carry risk of partial or total loss. Validate behavior in paper mode, use small amounts first, and perform your own security and financial due diligence.

---

Contact

GitHub: Rezzecup