Aetheros

Demo

About

### Overview **Aetheros** is a comprehensive Model Context Protocol (MCP) server that bridges the gap between AI assistants and the Hedera DeFi ecosystem. It transforms how users interact with decentralized finance by enabling natural language conversations with AI (like Claude) to query data, analyze opportunities, and prepare transactions across multiple DeFi platforms—all without requiring deep technical knowledge or compromising security. ### What It Does - In Detail #### 1. **Unified Multi-Platform DeFi Access** Aetheros provides a single, standardized interface to interact with **5 major Hedera DeFi platforms**, eliminating the need to understand each platform's unique API, smart contract interface, or data format: - **SaucerSwap** (19 tools): Hedera's leading decentralized exchange (DEX) - Access liquidity pools, farming opportunities, and single-sided staking - Get real-time token prices and historical HBAR price data - Query V1 and V2 pool reserves, fees, and trading volumes - Prepare swap transactions with optimal routing - Manage SAUCE staking (SAUCE → xSAUCE) and farm deposits - **Bonzo Finance** (3 tools): Lending and borrowing protocol - View all lending reserves with APYs and utilization rates - Check account positions (supplied, borrowed, collateral) - Identify liquidation opportunities for profitable arbitrage - **Stader Labs** (3 tools): Liquid staking protocol - Get real-time HBAR to HBARX exchange rates - Prepare HBAR staking transactions - Prepare HBARX unstaking transactions - **HeliSwap** (1 tool): Alternative DEX - Query trading pair information and reserves - **Hashport** (10 tools): Cross-chain bridge - List supported assets across 7+ blockchain networks - Get step-by-step bridging instructions - Validate bridge parameters before execution - Track transfer history and asset reserves - Convert transaction ID formats **Total: 36 comprehensive tools** covering every aspect of Hedera DeFi operations. #### 2. **Dual-Mode Security Architecture** Aetheros solves the critical security vs. automation dilemma through an innovative two-mode system: ##### **Prepare Mode (Default - Maximum Security)** - Generates complete, unsigned transaction data - Private keys never loaded into memory - Users can sign with hardware wallets (Ledger, D'CENT, etc.) - Perfect for high-value operations and institutional use - Provides full transparency: contract addresses, function calls, gas limits, payable amounts **Example Output:** ```json { "type": "prepared_transaction", "description": "Swap 10 HBAR for minimum 1,000,000 SAUCE tokens", "from": "0.0.123456", "to": "0x00000000000000000000000000000000002cc9B2", "function": "multicall(bytes[])", "gas": 400000, "value": "1000000000", "unsigned": { "contractId": "0x00000000000000000000000000000000002cc9B2", "functionName": "multicall", "functionParams": ["0xc04b8d59000000..."], "payableAmount": "1000000000" } } ``` ##### **Execute Mode (Advanced - Full Automation)** - Automatically signs and submits transactions to Hedera network - Ideal for automated trading bots and strategies - Returns transaction IDs and confirmation status - Requires explicit environment variable (`EXECUTE_TX=true`) and private key #### 3. **Real-Time DeFi Analytics** Ask questions in plain English and get instant, formatted data: **Examples:** - "What's the current HBAR to HBARX exchange rate?" → `1.0247 (staking rewards accumulated)` - "Show me the best yield farms on SaucerSwap" → Returns sorted farms by APY with TVL and reward rates - "Get SAUCE/USDC pool reserves" → Returns exact token amounts and pool liquidity - "Which Bonzo accounts are eligible for liquidation?" → Lists accounts with health factors below 1.0 #### 4. **Transaction Preparation with AI Guidance** Instead of manually constructing complex smart contract calls, simply describe what you want: **User:** "I want to swap 50 HBAR for SAUCE tokens" **Aetheros:** 1. Fetches current SAUCE token address and pool information 2. Calculates optimal route (direct or multi-hop) 3. Gets price quote with slippage protection 4. Generates complete unsigned transaction with: - Proper function encoding for SaucerSwap Router - HBAR wrapping (HBAR → WHBAR) if needed - Recipient address conversion (Hedera ID → EVM address) - Gas estimation and value amounts - Refund handling for excess HBAR All ready for signing with your preferred wallet. #### 5. **Cross-Chain Bridge Intelligence** Hashport integration enables seamless asset bridging: - Query supported tokens on Ethereum, Polygon, Avalanche, BNB Chain, etc. - Get exact bridging steps with required approvals - Validate amounts and addresses before bridging - Track bridge transaction status - View total value locked across chains ### The Problem It Solves #### Pain Point #1: **Fragmentation & Complexity** Hedera's DeFi ecosystem spans multiple protocols, each with: - Different API structures (REST vs GraphQL vs on-chain queries) - Unique authentication requirements - Varying data formats and units - Complex smart contract interfaces requiring ABI knowledge **Solution:** Aetheros abstracts all complexity into simple, natural language commands. One interface, 36 tools, 5 platforms. #### Pain Point #2: **Manual Monitoring & Analysis** DeFi traders manually: - Check multiple websites for prices and APYs - Calculate optimal routes across DEXs - Monitor liquidation opportunities - Track farming rewards across platforms **Solution:** Ask Aetheros to monitor conditions, compare rates, or identify opportunities—all through conversation. #### Pain Point #3: **Security Risks in Automation** Existing automation tools require: - Exposing private keys to scripts - Trusting third-party services - Running unsafe code from unverified sources **Solution:** Prepare-only mode generates transactions without ever accessing private keys. Sign with your hardware wallet or secure environment. #### Pain Point #4: **No AI Integration** Traditional DeFi tools lack AI capabilities: - No natural language queries - No intelligent routing or optimization - No conversational transaction building **Solution:** Built on MCP, enabling Claude and other AI assistants to safely interact with Hedera DeFi using your natural language. ### Real-World Use Cases 1. **Portfolio Management**: "Show my positions across all Hedera DeFi platforms" 2. **Yield Optimization**: "Find the best HBAR staking rate between Stader and SaucerSwap farms" 3. **Arbitrage Detection**: "Alert me when USDC price differs by >0.5% between SaucerSwap and HeliSwap" 4. **Automated Strategies**: "Stake all my farming rewards back into the highest APY pool" 5. **Bridge Operations**: "How do I bridge 1000 USDC from Ethereum to Hedera?" 6. **Risk Management**: "Show Bonzo accounts near liquidation with >$10k collateral" ### Technical Innovation - **First MCP Server for Hedera DeFi**: Pioneering AI-native DeFi interactions - **100% Success Rate**: All 36 tools tested and working (see TEST_RESULTS.md) - **Type-Safe**: Full TypeScript with Zod schema validation - **Production Ready**: Published on npm as `aetheros` with 1-command installation - **Comprehensive**: Covers data queries, analytics, and transaction preparation ### Installation & Usage ```bash # Install globally npm install -g aetheros # Or use directly with npx npx aetheros ``` **Claude Desktop Integration** (claude_desktop_config.json): ```json { "mcpServers": { "hedera-defi": { "command": "npx", "args": ["-y", "aetheros"] } } } ``` Then simply chat with Claude: - "Get all SaucerSwap tokens" - "Prepare a transaction to stake 100 HBAR" - "Show me the best yield opportunities on Hedera" ### Why It Matters Aetheros democratizes DeFi by removing technical barriers. Whether you're a: - **Beginner**: Ask questions in plain English - **Trader**: Automate strategies without coding - **Developer**: Build on a unified, type-safe API - **Institution**: Prepare transactions with hardware wallet security You can now leverage Hedera's fast, low-cost DeFi ecosystem through the power of AI assistance.

How it's made

### Architecture Overview Aetheros is built using a **modular client-based architecture** where each DeFi platform has its own dedicated client class, all exposed through a unified MCP server interface. This design enables independent platform updates without breaking other integrations. ``` ┌─────────────────────────────────────────────────────┐ │ MCP Server (src/index.ts) │ │ - Tool registration & schema validation │ │ - Request routing & response formatting │ └─────────────────────────────────────────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ │SaucerSwap│ │ Bonzo │ │ Stader │ ... │ Client │ │ Client │ │ Client │ └──────────┘ └────────┘ └────────┘ │ │ │ ┌────▼───────┐ ┌───▼──────┐ ┌────▼────────┐ │ REST APIs │ │Smart │ │ @hashgraph/ │ │ + Contracts│ │Contracts │ │ sdk │ └────────────┘ └──────────┘ └─────────────┘ ``` ### Core Technology Stack #### 1. **Runtime & Language** **TypeScript 5.3+** (`typescript@^5.3.0`) - Strict type checking with `strict: true` in tsconfig.json - ESM modules for modern JavaScript compatibility - Interfaces for all platform responses and transaction types **Node.js 18+** - ESM module system (`"type": "module"` in package.json) - Native async/await support for all API calls - Environment variable management via `dotenv@^16.3.1` **tsx** (`tsx@^4.6.0`) - Development hot-reloading with `npm run dev` - Direct TypeScript execution without compilation step #### 2. **MCP Protocol Implementation** **@modelcontextprotocol/sdk** (`@modelcontextprotocol/sdk@^0.5.0`) - `Server` class for MCP server initialization - `StdioServerTransport` for stdio-based communication with Claude Desktop - Tool registration with JSON schemas generated from Zod ```typescript import { Server, StdioServerTransport } from "@modelcontextprotocol/sdk/server/index.js"; import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"; const server = new Server( { name: "aetheros", version: "1.0.6" }, { capabilities: { tools: {} } } ); // Register 36 tools with schemas server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "saucerswap_get_tokens", description: "Get all available tokens on SaucerSwap", inputSchema: zodToJsonSchema(GetTokensSchema) }, // ... 35 more tools ] })); ``` #### 3. **Schema Validation** **Zod** (`zod@^3.22.0`) + **zod-to-json-schema** (`zod-to-json-schema@^3.24.6`) - Runtime validation of all tool inputs - Automatic JSON Schema generation for MCP - Type inference for TypeScript compiler ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; // Example: SaucerSwap swap schema const SwapHbarForTokensSchema = z.object({ accountId: z.string().describe("Hedera account ID (0.0.xxxxx)"), tokenOut: z.string().describe("Output token address"), amountIn: z.string().describe("HBAR amount in tinybars"), fee: z.number().describe("Pool fee tier (500, 3000, 10000)"), slippage: z.number().min(0).max(100).default(0.5) }); type SwapParams = z.infer<typeof SwapHbarForTokensSchema>; ``` #### 4. **Hedera Blockchain Integration** **@hashgraph/sdk** (`@hashgraph/sdk@^2.45.0`) - `Client` for Hedera network connections (mainnet/testnet) - `AccountId` for Hedera address handling - `PrivateKey` for transaction signing in execute mode - `ContractExecuteTransaction` for smart contract interactions - `ContractCallQuery` for read-only contract queries ```typescript import { Client, AccountId, PrivateKey, ContractExecuteTransaction, ContractFunctionParameters } from "@hashgraph/sdk"; // Initialize Hedera client const client = Client.forMainnet(); client.setOperator( AccountId.fromString(process.env.MAINNET_HEDERA_OPERATOR_ID!), PrivateKey.fromString(process.env.MAINNET_HEDERA_OPERATOR_KEY!) ); // Execute contract transaction const tx = await new ContractExecuteTransaction() .setContractId("0.0.2917554") .setGas(400000) .setFunction("stake", params) .setPayableAmount(amountInHbar) .execute(client); ``` #### 5. **Smart Contract Interactions** **Ethers.js v6** (`ethers@^6.9.0`) - `Interface` for ABI encoding/decoding - `solidityPacked` for parameter encoding - `Contract` class for type-safe contract calls - BigNumber handling for precise token amounts ```typescript import { ethers } from "ethers"; // Encode SaucerSwap multicall const routerInterface = new ethers.Interface([ "function multicall(bytes[] calldata data) external payable returns (bytes[] memory)", "function exactInputSingle((address,address,uint24,address,uint256,uint256,uint256)) external payable returns (uint256)" ]); const swapParams = { tokenIn: WHBAR_ADDRESS, tokenOut: tokenOutAddress, fee: feeAmount, recipient: evmAddress, deadline: BigInt(Math.floor(Date.now() / 1000) + 300), amountIn: BigInt(amountIn), amountOutMinimum: BigInt(minAmountOut) }; const encodedSwap = routerInterface.encodeFunctionData("exactInputSingle", [swapParams]); ``` #### 6. **HTTP Client & API Integration** **Axios** (`axios@^1.6.0`) - REST API calls to SaucerSwap, Bonzo, Hashport - Automatic JSON parsing and error handling - Request/response interceptors for logging - Timeout management for rate-limited endpoints ```typescript import axios from "axios"; // SaucerSwap API with authentication const saucerswapApi = axios.create({ baseURL: "https://api.saucerswap.finance", headers: { "Authorization": `Bearer ${process.env.SAUCERSWAP_API_KEY}`, "Content-Type": "application/json" }, timeout: 30000 }); // Bonzo Finance API (public) const bonzoApi = axios.create({ baseURL: "https://mainnet-api.bonzo.finance/api/v1", timeout: 15000 }); ``` ### Platform-Specific Implementation Details #### **SaucerSwap Client** (`src/clients/saucerswap.ts`) **Challenges:** 1. **API Rate Limiting**: SaucerSwap's public API has strict rate limits - Solution: Implemented graceful degradation and retry logic - Cache responses where appropriate 2. **V1 vs V2 Pools**: Different contract interfaces for Uniswap V2 and V3 style pools - Solution: Separate tool implementations with proper ABI handling 3. **Transaction Complexity**: Swaps require multicall with WHBAR wrapping/unwrapping - Solution: Built helper functions to construct multicall arrays **Key Implementation:** ```typescript export class SaucerSwapClient { private apiKey?: string; private client?: Client; private routerAddress: string; private quoterAddress: string; // 19 methods for data queries and transaction preparation async swapHbarForTokens(params: SwapParams) { // 1. Convert Hedera account ID to EVM address const evmAddress = this.accountIdToEvmAddress(params.accountId); // 2. Encode exactInputSingle call const swapCall = this.encodeSwapCall(params, evmAddress); // 3. Encode refundETH call (for excess HBAR) const refundCall = routerInterface.encodeFunctionData("refundETH"); // 4. Construct multicall const multicallData = routerInterface.encodeFunctionData("multicall", [ [swapCall, refundCall] ]); // 5. Return unsigned transaction return { type: "prepared_transaction", contractId: this.routerAddress, functionName: "multicall", functionParams: multicallData, gas: 400000, payableAmount: params.amountIn }; } } ``` #### **Stader Client** (`src/clients/stader.ts`) **Challenges:** 1. **Mainnet Only**: Stader contracts only deployed on mainnet - Solution: Network detection and graceful error messages on testnet 2. **Exchange Rate Precision**: HBARX rate requires high-precision decimal handling - Solution: Use BigInt for all calculations, format for display **Key Implementation:** ```typescript export class StaderClient { private stakePoolAddress = "0.0.2917554"; async stakeHbar(accountId: string, amount: string) { // Prepare ContractExecuteTransaction const params = new ContractFunctionParameters() .addUint256(BigInt(amount)); return { type: "prepared_transaction", description: `Stake ${amount} tinybars HBAR for HBARX`, contractId: this.stakePoolAddress, functionName: "stake", functionParams: params, gas: 300000, payableAmount: amount }; } } ``` #### **Bonzo Client** (`src/clients/bonzo.ts`) **Challenges:** 1. **Complex Reserve Data**: Multiple nested objects with protocol-specific calculations - Solution: Strong TypeScript interfaces for type safety 2. **Health Factor Calculation**: Liquidation logic requires precise decimal math - Solution: Use reserve decimals for accurate calculations **Key Implementation:** ```typescript export class BonzoClient { async getReserves() { const response = await axios.get( "https://mainnet-api.bonzo.finance/api/v1/reserves" ); // Transform API response to user-friendly format return response.data.map((reserve: any) => ({ symbol: reserve.symbol, supplyAPY: (reserve.liquidityRate / 1e27 * 100).toFixed(2), borrowAPY: (reserve.variableBorrowRate / 1e27 * 100).toFixed(2), utilizationRate: (reserve.utilizationRate / 1e27 * 100).toFixed(2), totalSupplied: (BigInt(reserve.totalLiquidity) / BigInt(10 ** reserve.decimals)).toString(), availableLiquidity: (BigInt(reserve.availableLiquidity) / BigInt(10 ** reserve.decimals)).toString() })); } } ``` #### **Hashport Client** (`src/clients/hashport.ts`) **Challenges:** 1. **Multi-Network Support**: 7+ different blockchain networks - Solution: Network ID mapping and validation 2. **Asset ID Formats**: Different formats across chains (ERC20 addresses vs Hedera token IDs) - Solution: Flexible string handling with validation **Key Implementation:** ```typescript export class HashportClient { private baseUrl = "https://mainnet.hashport.network/api/v1"; async getSupportedAssets() { const response = await axios.get(`${this.baseUrl}/assets`); return response.data.map((asset: any) => ({ symbol: asset.symbol, name: asset.name, networks: asset.supportedNetworks.map((net: any) => ({ networkId: net.networkId, networkName: net.networkName, assetId: net.assetId, isNative: net.isNative })) })); } async getBridgeSteps(sourceNetwork: string, targetNetwork: string, assetId: string) { // Query bridge contract for step-by-step instructions // Includes: approvals, lock/burn, mint/unlock steps } } ``` ### Security Implementation #### **1. Environment-Based Mode Selection** ```typescript const EXECUTE_TX = process.env.EXECUTE_TX === "true"; const network = process.env.HEDERA_NETWORK || "mainnet"; // Only load private key if execute mode enabled let operatorKey: PrivateKey | undefined; if (EXECUTE_TX) { const keyEnvVar = network === "mainnet" ? "MAINNET_HEDERA_OPERATOR_KEY" : "TESTNET_HEDERA_OPERATOR_KEY"; operatorKey = PrivateKey.fromString(process.env[keyEnvVar]!); } ``` #### **2. Transaction Preparation vs Execution** ```typescript async function handleTransactionTool(params: any) { const unsignedTx = await prepareTransaction(params); if (!EXECUTE_TX) { // Return unsigned transaction for external signing return { type: "prepared_transaction", ...unsignedTx, instructions: "Sign this transaction with your wallet or dApp" }; } // Execute mode: sign and submit const tx = buildTransaction(unsignedTx); const signedTx = await tx.sign(operatorKey!); const receipt = await signedTx.execute(client); return { type: "executed_transaction", transactionId: receipt.transactionId.toString(), status: receipt.status.toString() }; } ``` ### Build & Distribution #### **Development Workflow** ```json { "scripts": { "dev": "tsx src/index.ts", // Hot reload development "build": "tsc", // Compile TypeScript to dist/ "start": "node dist/index.js", // Run production build "watch": "tsx watch src/index.ts", // Watch mode "prepublishOnly": "npm run build" // Auto-build before publish } } ``` #### **TypeScript Configuration** (tsconfig.json) ```json { "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "node", "outDir": "./dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "declaration": true, // Generate .d.ts files "declarationMap": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] } ``` #### **NPM Package Configuration** ```json { "name": "aetheros", "version": "1.0.6", "type": "module", "main": "dist/index.js", "bin": { "aetheros": "dist/index.js" // CLI command }, "files": [ "dist/**/*", // Include compiled files "README.md", "LICENSE", ".env.example" ], "engines": { "node": ">=18.0.0" // Require Node 18+ } } ``` ### Particularly Hacky/Notable Implementations #### **1. Hedera Account ID to EVM Address Conversion** Hedera uses account IDs (0.0.xxxxx) but smart contracts need EVM addresses (0x...). We convert by: ```typescript function accountIdToEvmAddress(accountId: string): string { const parts = accountId.split('.'); const num = parseInt(parts[2]); // Hedera's EVM address: 0x0000000000000000000000000000000000{accountNum in hex} return '0x' + num.toString(16).padStart(40, '0'); } ``` #### **2. Multicall Transaction Builder** SaucerSwap swaps require multiple steps (swap + refund). We encode them into a single multicall: ```typescript function buildMulticallSwap(params: SwapParams) { const calls: string[] = []; // 1. Wrap HBAR to WHBAR (if needed) if (params.tokenIn === HBAR) { calls.push(encodeWrapHbar(params.amountIn)); } // 2. Execute swap calls.push(encodeExactInputSingle(params)); // 3. Unwrap WHBAR back to HBAR (if output is HBAR) if (params.tokenOut === HBAR) { calls.push(encodeUnwrapWHBAR(params.amountOut)); } // 4. Refund excess HBAR calls.push(routerInterface.encodeFunctionData("refundETH")); return routerInterface.encodeFunctionData("multicall", [calls]); } ``` #### **3. Graceful API Degradation** SaucerSwap API requires authentication, but we still work without it: ```typescript async getTokens() { try { if (this.apiKey) { // Use authenticated endpoint (more reliable) return await this.authenticatedApi.get('/tokens'); } } catch (error) { console.warn("Authenticated API failed, falling back to public endpoint"); } // Fallback to public endpoint (rate limited) return await this.publicApi.get('/tokens'); } ``` #### **4. BigInt JSON Serialization** JavaScript's JSON.stringify() doesn't support BigInt, causing errors. We patch it: ```typescript // Monkey patch BigInt serialization (BigInt.prototype as any).toJSON = function() { return this.toString(); }; ``` ### Testing & Verification **Test Coverage**: 36/36 tools tested (100% success rate) **Testing Methodology**: 1. Manual testing via Claude Desktop integration 2. Programmatic testing with test-mcp-tools.js 3. Network-specific testing (mainnet vs testnet) 4. Rate limit and timeout handling verification **Results**: See TEST_RESULTS.md for comprehensive results including: - Response sizes and performance metrics - Known API limitations and workarounds - Platform availability by network ### Why These Technologies? 1. **TypeScript**: Type safety prevents runtime errors in financial operations 2. **MCP**: First-class AI integration, future-proof protocol 3. **Zod**: Runtime validation ensures user inputs are safe before blockchain submission 4. **@hashgraph/sdk**: Official SDK, optimized for Hedera's unique consensus 5. **Ethers.js**: Industry standard for EVM contract interactions 6. **Axios**: Robust HTTP client with excellent error handling ### Future Enhancements **Immediate**: - Add Bonzo transaction preparation (lend/borrow/repay) - Implement intelligent swap routing across multiple DEXs - Add WebSocket support for real-time price updates **Advanced**: - Flash loan support for arbitrage strategies - Batch transaction builder for complex DeFi operations - Position monitoring with customizable alerts - Integration with additional Hedera DeFi platforms **Long-term**: - Become the standard MCP server for Hedera DeFi - Enable AI-driven yield optimization strategies - Support for other blockchain ecosystems