Aetheros

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:

{
  "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

# Install globally
npm install -g aetheros

# Or use directly with npx
npx aetheros

Claude Desktop Integration (claude_desktop_config.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.

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

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

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

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

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

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:

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:

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:

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:

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

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

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

{
  "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)

{
  "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

{
  "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:

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:

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:

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:

// 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