Architecture Overview

System Diagram

User
 |
 v
Dashboard (apps/dashboard)
 |  - Authentication (Google/GitHub/email)
 |  - LP wallet scanning configuration
 |  - Bot strategy configuration
 |  - Execution wallet (API key) management
 |
 v
Bot Runtime (apps/bot)
 |  - On-chain LP position scanner
 |  - Bot FSM per strategy instance
 |  - Hedge executor
 |
 +---> DEX / On-chain (Uniswap V3/V4, PancakeSwap V3)
 |       LP position scanning (read-only via public address)
 |
 +---> CEX / Futures Exchange (Binance Futures, HyperLiquid)
         Futures order execution (via user-provided API key)

Self-Custody and Auto-Custody Model

LP wallet (self-custody, read-only). The LP wallet is identified by a public address. Aegis uses this address only to scan on-chain LP positions. The bot does not hold LP funds, does not require a private key or seed phrase, and does not request any approval or signature from the LP wallet. LP capital stays in the user’s wallet at all times.

CEX execution wallet (user-controlled). Futures hedges execute using an API key that the user creates on their centralized exchange account. The API key grants trading permissions only. Funds stay in the user’s exchange account. Aegis holds no custody over exchange funds.

API Key Encryption

API keys are encrypted at rest using AES-256-GCM inside the Aegis infrastructure (apps/bot/src/shared/infrastructure/credentials/). Keys are never displayed back in the dashboard after saving. For the required permission set and security model, see API Keys — Overview and FAQ — Security.

LP Concentration Model

Uniswap V3/V4 and PancakeSwap V3 use concentrated liquidity: the LP sets a price range [P_lower, P_upper]. When the market price is inside the range, the position earns fees proportional to the depth of liquidity. When price exits the range, the position is fully single-sided and earns no fees.

Aegis models the delta exposure of the LP position based on the current price relative to the range. Hedging bots open and close perpetual futures positions to offset this exposure according to each bot’s strategy logic.

Bot FSM Lifecycle

Each active bot instance runs a finite state machine with the following high-level states:

• Idle — no active LP position matched.
• Monitoring — LP position detected; bot is watching price relative to the configured trigger conditions.
• Active Hedge — trigger condition met; one or more futures legs are open.
• Closing — position is being closed (take-profit, stop-loss, or range re-entry).
• Error — execution failure; bot is in error state until the operator resolves the issue.

Bot Orchestration

The runtime manages multiple bot instances concurrently. Each bot instance is bound to exactly one execution wallet and one trading pair (perpetual symbol). Running multiple bot types (for example, Bastion and Vanguard on the same exchange) requires separate execution wallets — one per bot type.

Live bots: Bastion (short protection), Vanguard (breakout long), Orbit (mean-reversion long/short). Each bot interacts with LP range edges differently. See the individual bot pages for strategy details.