API Reference

Complete reference documentation for mucch's TypeScript API. Use these classes and methods to build custom trading strategies or integrate mucch into your applications.

Core Classes

TradingBot

Main orchestrator that coordinates trading operations, AI analysis, and dashboard display.

Constructor

new TradingBot(config: BotConfig)

Methods

start(): Promise<void>

Initialize bot and start monitoring

stop(): Promise<void>

Gracefully shut down bot

requestAnalysis(): Promise<AISignal>

Request immediate AI market analysis

HyperLiquidTrader

Handles all Hyperliquid API interactions including market data, orders, and account information.

Constructor

new HyperLiquidTrader(
  privateKey: string,
  testnet?: boolean
)

Methods

getMarketData(asset: string): Promise<MarketData>

Fetch current market data for an asset

getAccountInfo(): Promise<AccountInfo>

Get account balance and positions

placeOrder(order: Order): Promise<OrderResult>

Execute a trade order

cancelOrder(orderId: string): Promise<void>

Cancel an existing order

getOpenPositions(): Promise<Position[]>

Retrieve all open positions

AIStrategy

AI-powered market analysis using GPT-5 or Claude 4.5 Sonnet to generate trading signals.

Constructor

new AIStrategy(config: AIConfig)

Methods

analyze(marketData: MarketData): Promise<AISignal>

Generate trading signal from market data

setProvider(provider: 'openai' | 'openrouter'): void

Switch AI provider

setModel(model: string): void

Change AI model (gpt-5, claude-4.5-sonnet)

Type Definitions

BotConfig

interface BotConfig {
  hyperliquid: {
    privateKey: string;
    testnet: boolean;
  };
  ai: {
    provider: 'openai' | 'openrouter';
    apiKey: string;
    model: string;
  };
  trading: {
    assets: string[];
    riskPercentage: number;
    maxPositions: number;
    checkInterval: number;
  };
}

MarketData

interface MarketData {
  asset: string;
  price: number;
  high24h: number;
  low24h: number;
  volume24h: number;
  change24h: number;
  timestamp: number;
}

AISignal

interface AISignal {
  action: 'BUY' | 'SELL' | 'HOLD';
  asset: string;
  confidence: number;
  reasoning: string;
  entry: number;
  stopLoss: number;
  takeProfit: number;
  positionSize: number;
  timestamp: number;
}

AccountInfo

interface AccountInfo {
  balance: number;
  equity: number;
  pnl: number;
  marginUsed: number;
  marginFree: number;
  positions: Position[];
}

Example Usage

Here's a complete example of using mucch programmatically:

import { TradingBot } from 'mucch';

const bot = new TradingBot({
  hyperliquid: {
    privateKey: process.env.HYPERLIQUID_PRIVATE_KEY!,
    testnet: false
  },
  ai: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-5'
  },
  trading: {
    assets: ['BTC', 'ETH'],
    riskPercentage: 1,
    maxPositions: 2,
    checkInterval: 300000 // 5 minutes
  }
});

// Start the bot
await bot.start();

// Request immediate analysis
const signal = await bot.requestAnalysis();
console.log('AI Signal:', signal);

// Graceful shutdown
process.on('SIGINT', async () => {
  await bot.stop();
  process.exit(0);
});

Hyperliquid API Integration

mucch directly integrates with Hyperliquid's REST and WebSocket APIs:

Market Data Endpoints

/info - Asset information and metadata
/clearinghouseState - Account balances and positions
/l2Book - Order book depth
/candleSnapshot - OHLCV candle data

Trading Endpoints

/order - Place market/limit orders
/cancel - Cancel orders
/batchModify - Batch order modifications
/usdTransfer - Transfer USDC

Authentication

All trading requests are signed using your Ethereum private key:

const wallet = new ethers.Wallet(privateKey);
const signature = await wallet.signMessage(message);

AI Provider APIs

OpenAI (GPT-5)

Uses OpenAI's Chat Completions API:

POST https://api.openai.com/v1/chat/completions
{
  "model": "gpt-5",
  "messages": [...],
  "temperature": 0.3,
  "max_tokens": 500,
  "response_format": { "type": "json_object" }
}

API Key: Set OPENAI_API_KEY environment variable

OpenRouter (Claude 4.5 Sonnet)

Uses OpenRouter's unified API:

POST https://openrouter.ai/api/v1/chat/completions
{
  "model": "anthropic/claude-4.5-sonnet",
  "messages": [...],
  "temperature": 0.3,
  "max_tokens": 500
}

API Key: Set OPENROUTER_API_KEY environment variable

Error Handling

All methods can throw errors that should be handled:

try {
  const signal = await bot.requestAnalysis();
  console.log('Signal received:', signal);
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Invalid AI API key');
  } else if (error.message.includes('Hyperliquid')) {
    console.error('Hyperliquid connection failed');
  } else {
    console.error('Unknown error:', error);
  }
}

Advanced Usage

Custom Trading Logic

Extend the bot with custom logic:

class CustomBot extends TradingBot {
  async onSignal(signal: AISignal) {
    // Custom logic before executing signal
    if (signal.confidence > 80) {
      await this.executeTrade(signal);
    }
  }
}

Event Listeners

Subscribe to bot events:

bot.on('signal', (signal) => {
  console.log('New signal:', signal);
});

bot.on('trade', (trade) => {
  console.log('Trade executed:', trade);
});

bot.on('error', (error) => {
  console.error('Bot error:', error);
});

Need Help? For additional examples and community support, check the GitHub repository or join our Discord server.

Dashboard Supported Assets