Eclipse Agent

Autonomous DeFi execution agent for Virtuals ACP. Handles swaps, yield analysis, Morpho deposits, and DCA on Base chain.

Services

Service	Type	Description
swap-quote	Info	3-tier quote: 0x Protocol → CDP → OpenOcean
execute-swap	Fund Transfer	Execute swap with buyer's funds via 0x AllowanceHolder
defi-yield	Info	Multi-protocol yield discovery via DefiLlama
morpho-vaults	Info	List Morpho USDC vaults on Base
morpho-deposit	Fund Transfer	Deposit USDC into Morpho (user owns position)
dca-setup	Fund Transfer	Create DCA order (dollar cost averaging)
dca-status	Info	Check DCA order progress

Quick Start

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your keys

# Run
npm start

# Typecheck
npm run typecheck

Configuration

Required

Variable	Description
ECLIPSE_ENTITY_ID	Virtuals ACP entity ID
ECLIPSE_WALLET_ADDRESS	Smart account address
ECLIPSE_PRIVATE_KEY	Wallet private key
API_KEY	GAME framework API key

Swap Providers (at least one)

Variable	Description
ZEROX_API_KEY	0x Protocol — primary, best prices
CDP_API_KEY + CDP_API_SECRET	Coinbase CDP — fallback

OpenOcean is always available as a final fallback (no key needed).

Optional

Variable	Default	Description
ECLIPSE_SWAP_WALLET	Same as wallet	EOA for swap execution
BASE_RPC_URL	https://mainnet.base.org	Base RPC endpoint
ECLIPSE_CLUSTER	defi	ACP cluster name
DATABASE_URL	—	PostgreSQL for persistent DCA

Architecture

src/
├── index.ts              # ACP init, job routing
├── standalone.ts         # Polling loop, entry point
├── config.ts             # Env vars, constants, token map
├── services/
│   ├── token-resolver.ts # Symbol → address resolution
│   ├── swap-quote.ts     # 3-tier swap quoting
│   ├── swap-execute.ts   # Swap execution with funds
│   ├── yield-analysis.ts # DefiLlama yield discovery
│   ├── morpho-vaults.ts  # Morpho vault list + deposit
│   └── dca.ts            # DCA order management
└── utils/
    ├── provider.ts       # Base RPC provider singleton
    └── timeout.ts        # Async timeout helper

Swap Quote Tiers

1. 0x Protocol (primary) — Best prices, AllowanceHolder pattern
2. Coinbase CDP (fallback) — Permit2 signing
3. OpenOcean (last resort) — Always available, no API key needed

DCA Orders

DCA orders are stored in-memory by default. Each poll cycle checks for due executions. Orders specify:

• Token pair, amount per swap, interval (hours), total swaps
• Buyer sends full budget upfront
• Each scheduled swap calls execute-swap internally

ACP Job Flow

1. Buyer creates job on Virtuals ACP
2. Eclipse accepts (REQUEST phase)
   - Fund transfer jobs: request tokens from buyer
   - Service-only jobs: accept immediately
3. Eclipse executes (TRANSACTION phase)
   - Runs service handler
   - Delivers result to buyer
   - Transfers output tokens (for swaps)

License

MIT