LUX Agent System

Autonomous DeFi intelligence platform built on Solana.

Four agents that monitor risk, discover protocols, predict airdrops, and generate publishable content — running 24/7 with real capital on the line.

This repository documents the architecture, methodology, and results of a system managing live leveraged DeFi positions. The agent source code is private.

---

The Problem

Most DeFi tools are broken in ways that cost money:

• Risk monitoring uses fixed LTV thresholds. 88% LTV is "safe" everywhere — but 88% on Aave eMode (liq 97.5%) has a 9.5% buffer, while 88% on Kamino (liq 95%) has only 6.1%. One is fine. The other is one depeg from liquidation.

• Every protocol defines "health" differently. Kamino reports LTV directly. Loopscale and Carrot report price-distance-to-liquidation. If you don't translate between them, your risk classification is wrong from the start.

• Nobody evaluates protocol risk before you enter. DefiLlama shows TVL and APY but doesn't tell you a protocol has no audit, uses a custom oracle, and lost 30% TVL this week. You find out after depositing.

• Airdrop farming is vibes-based. No tool combines tokenless detection + TVL analysis + points program tracking + historical calibration into a quantitative prediction with ROI estimates.

LUX solves all four.

---

Architecture

       DefiLlama API          Protocol APIs
      (pools, protocols)   (on-chain positions)
              |              /      |      \
              |         Kamino  Loopscale  Carrot
              |              \      |      /
              +------+-------+------+
                     |
                apy_scanner
                     |
              live positions
                /         \
      Sentinel              Protocol Radar
   (post-entry)            (pre-entry)
      |                         |
gap-based risk           discovery + scoring
velocity alerts          airdrop prediction
dynamic intervals        TVL-dilution ROI
      |                         |
      +-------+--------+-------+
              |
         lux_data.json
        /       |       \
 LUX Dashboard  |  Thread Assistant
  (frontend)    |  (content pipeline)
      |         |     Grok→Claude→Grok
   browser   LUX Chat    |
           (Claude+Grok)  |
              |        Telegram
           Telegram   + Dashboard

Agent #1 — Sentinel (Risk Engine)

Monitors live leveraged positions after entry. Replaces fixed LTV thresholds with a gap-based system calibrated on real liquidation events.

Key innovation: liq_ltv = ltv / (1 - health / 100)

Every protocol reports health differently. This formula correctly translates Loopscale/Carrot's price-distance metric into actual LTV gap — verified against protocol UIs with screenshots on 6 live positions.

Gap-based classification per asset category:

Category	Safe	Warning	Danger	Critical
Stablecoin Loop (USDC/USDT)	>10%	5-10%	2.5-5%	<2.5%
Correlated (JupSOL/SOL)	>12%	7-12%	3-7%	<3%
Decorrelated (ONYc/USDC)	>20%	12-20%	7-12%	<7%

Dynamic check intervals: SAFE = 30min, WARNING = 5min, DANGER = 1min, CRITICAL = 15sec. The closer to liquidation, the more frequently Sentinel watches.

Calibrated on 6 historical liquidation events: MakerDAO Black Thursday ($8.3M lost), SVB USDC depeg ($24M Aave liquidations), UST death spiral ($40B evaporated), mSOL flash depeg, stETH depeg (post-Merge), USDT 3pool depeg.

Agent #2 — Protocol Radar (Pre-Entry Intelligence)

Evaluates protocols before entry. Three modules:

Module 1 — Discovery: Scans 7,000+ DefiLlama protocols daily. Filters for Solana, core DeFi categories, TVL > $1M, growing TVL. Matches against user's wallet assets.

Module 2 — Risk Pre-Entry Score (1-10):

Five parameters, each 0-2 points:

Parameter	0	1	2
Audit	None	Unknown firm	Trail of Bits, OtterSec, Halborn...
TVL Trend	Dropping >20%/7d	Stable	Growing >5%/7d
Age	<30 days	30-90 days	>90 days
Team	Anonymous	Twitter OR GitHub	Twitter + GitHub + Open Source
Transparency	Closed, no oracle	One of two	Open source + known oracle

Score <5 = AVOID. 5-7 = CAUTION. 8+ = GREEN LIGHT.

Module 3 — Airdrop Radar (1-10):

Calibrated on 4 historical airdrops (HyperLiquid, Jupiter, Jito, Kamino):

Signal	Points	Present in
Tokenless (no gecko_id + blacklist)	+3.0	4/4 airdrops
TVL $50M-$5B	+1.5	4/4
Age 6-24 months	+1.5	4/4
Active points program	+1.5	3/4
Open source	+0.5	4/4
Audited	+0.5	3/4
Core DeFi category	+0.5	4/4
TVL growth >20%/7d	+0.5	variable

Token detection uses gecko_id == null plus a curated KNOWN_TOKEN_SLUGS blacklist to avoid false positives (e.g., Jito LST has no gecko_id but JTO token exists).

Points detection uses a curated ACTIVE_POINTS_SLUGS list of protocols with verified active programs.

ROI Model — TVL Dilution

The original ROI model was flat: deposit x multiplier. $1K in a $50M protocol gave the same result as $1K in a $5B one. Wrong.

New model:

your_return = (deposit / TVL) x FDV_estimate x allocation% x confidence

Your share of the airdrop is proportional to your share of the TVL. Three scenarios calibrated on historical data:

Scenario	FDV/TVL	Alloc %	Reference
Conservative	0.5x	5%	Kamino-tier ($25 per $1K)
Moderate	3.0x	10%	Jito-tier ($497 per $1K)
Optimistic	8.0x	20%	HyperLiquid-tier ($1,750 per $1K)

Example: $1K in a protocol with $86M TVL and airdrop score 8.9:

• Conservative: $22
• Moderate: $267
• Optimistic: $1,424

Same $1K in a $5B TVL protocol (score 7.0):

• Conservative: $17
• Moderate: $210
• Optimistic: $1,120

Smaller TVL = bigger slice of the pool.

LUX Chat Agent (Dual-LLM Architecture)

Conversational AI with real tool use — not a chatbot wrapper.

• Claude (backend): on-chain data analysis, risk assessment, memory management, tool execution
• Grok (frontend): X/Twitter sentiment, web search, narrative analysis, personality layer

Tools available to the agent:

• refresh_positions — live data from Kamino, Loopscale, Carrot
• get_token_prices — real-time from Raydium
• check_risk — Sentinel risk assessment on demand
• save_memory / recall_memory — persistent user context
• update_personality — evolving communication style

Agent #3 — Thread Assistant (Content Pipeline)

Transforms on-chain data + news into publishable content using a Grok→Claude→Grok sandwich architecture:

1. Grok (Research): scrapes X/Twitter for news, sentiment, context
2. Claude (Analysis): cross-references with live portfolio data, structures narrative, assigns media
3. Grok (Writing): applies λ Forensics personality, adapts per platform (X/LinkedIn/YouTube)

5 operating modes:

• reactive_news — automated morning scan, scores relevance ≥7 → draft
• portfolio_report — monthly performance report from yield history
• repo_publish — topic → 6-tweet thread + LinkedIn + YouTube script
• reply_engine — comment analysis with 2 reply strategies (safe vs bold)
• session_recap — building-in-public recap

Output is a complete operational package (tweets, LinkedIn text, YouTube script, media suggestions, checklist) saved to the dashboard Content tab for live editing via LUX Chat.

LUX Dashboard

Single-file HTML dashboard with 7 tabs:

• Positions — carousel + grid view of all leveraged positions
• Analytics — gap analysis, wave visualizer, LUX narrative
• Yield — pure yield vs price impact breakdown, historical charts
• LUX — chat interface connected to the dual-LLM agent
• Vault — wallet holdings, best yields, best move, compound projections
• Radar — protocol cards with risk/airdrop badges, interactive ROI calculator, filter pills
• Content — Thread Assistant drafts with platform toggle, status cycling, and live chat editing with Apply button

---

Validation Results

Sentinel was tested against 6 live leveraged positions. The old system had critical errors on 3 of 6:

Position	Category	LTV	Liq LTV	Gap	Old System	Sentinel	Source
stKESOL→SOL	Correlated	89.93%	95.0%	5.07%	DANGER	DANGER	Loopscale UI
USDG→PYUSD	Stablecoin	88.86%	95.0%	6.14%	SAFE	WARNING	Kamino API
ONyc→USDC	Decorrelated	74.58%	90.0%	15.42%	CRITICAL	WARNING	Loopscale UI
ONYC/USDC	Decorrelated	70.75%	86.3%	15.55%	DANGER	WARNING	Carrot UI

• USDG→PYUSD: Old system said SAFE (88.86% < 90% threshold). Gap is only 6.14% — Sentinel correctly flags WARNING.
• ONyc→USDC: Old system used hardcoded liq 80% → gap 5.46% → CRITICAL. Real liq is 90% (verified on Loopscale) → gap 15.42% → WARNING. Would have triggered an unnecessary emergency repay.

Protocol Radar current scan: 60 protocols on Solana, 5 with airdrop score >=7.

---

Tech Stack

Component	Technology
Agent runtime	Python 3.13
Risk engine	Custom gap-based model
Data source	DefiLlama API (free tier)
On-chain	Kamino, Loopscale, Carrot APIs
AI backend	Claude (Anthropic API)
AI frontend	Grok (xAI API)
Dashboard	Vanilla HTML/JS (single file, no build step)
Alerts	Telegram Bot API
Scheduling	cron + bot listener
Charts	matplotlib (headless)

---

Reports

Detailed methodology reports with full derivations, historical analysis, and validation data.

View all reports →

Agent	Report	Type
Sentinel	Methodology Report	Full derivation + validation
Sentinel	Architecture Overview	Visual summary
Protocol Radar	Methodology Report	Airdrop model + ROI
Protocol Radar	Architecture Overview	Visual summary
Thread Assistant	Methodology Report	Sandwich architecture + modes
Thread Assistant	Architecture Overview	Visual system diagram
ROI Model	TVL Dilution	Formula derivation

All reports are bilingual (EN/IT) and rendered as interactive pages via GitHub Pages.

---

Pipeline

Daily (08:00 UTC):
  apy_scanner.py        →  fetch pools, protocols, live positions
  protocol_radar.py     →  score 60+ Solana protocols
  export_to_dashboard   →  merge into lux_data.json
  thread_assistant.py   →  morning news scan (reactive_news)
  sentinel.py           →  continuous monitoring loop (15s-30min)

On demand (via Telegram or LUX Chat):
  lux_chat_api.py       →  Claude analyzes, Grok responds
  thread_assistant.py   →  content generation (post/portfolio/reply/recap)

---

Codebase

~10,500 lines of Python + HTML across 10 core files. The source code is private. This repository contains the methodology, architecture documentation, and validated results.

If you're interested in the system, the methodology, or collaboration:

X: @alex_lamports GitHub: alex-lamport

---

_{Built by a DeFi user who got tired of getting liquidated by tools that don't understand the difference between protocols.}