mucch.dev/docs
githubnpm

Configuration

mucch uses environment variables for configuration. This guide covers all available settings and how to configure them properly.

Environment Variables

Create a .env file in your project directory with the following configuration:

# Hyperliquid API Configuration
HYPERLIQUID_PRIVATE_KEY=0x1234...
HYPERLIQUID_ACCOUNT_ADDRESS=0xabcd...
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz

# AI Configuration (choose one)
OPENAI_API_KEY=sk-...
# OR
OPENROUTER_API_KEY=sk-or-...

# Trading Configuration
RISK_PERCENTAGE=1.0
MAX_POSITION_SIZE=1000
ENABLE_AI_SUGGESTIONS=true

Required Settings

HYPERLIQUID_PRIVATE_KEYrequired

Your wallet's private key for signing transactions on Hyperliquid. This key must have trading permissions.

Security Warning: Never share your private key. Never commit it to version control. Keep it secure at all times.

HYPERLIQUID_ACCOUNT_ADDRESSrequired

Your Hyperliquid wallet address (starts with 0x). This is your public address visible on the blockchain.

Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

OPENAI_API_KEYone required

Your OpenAI API key for using GPT-5. Get yours from platform.openai.com.

Starts with: sk-proj-...

OPENROUTER_API_KEYone required

Your OpenRouter API key for using Claude 4.5 Sonnet or other models. Get yours from openrouter.ai.

Starts with: sk-or-...

Optional Settings

HYPERLIQUID_API_URLoptional

The Hyperliquid API endpoint. Defaults to mainnet.

Default: https://api.hyperliquid.xyz

Testnet: https://api.hyperliquid-testnet.xyz

RISK_PERCENTAGEoptional

Percentage of your account to risk per trade. Lower values are more conservative.

Default: 1.0 (1% of account)

Range: 0.1 - 5.0

MAX_POSITION_SIZEoptional

Maximum position size in USD. Acts as a hard cap on individual position sizes.

Default: 1000 (USD)

ENABLE_AI_SUGGESTIONSoptional

Enable or disable AI trading suggestions. When disabled, mucch runs in monitor-only mode.

Default: true

Getting Your Hyperliquid Credentials

Step 1: Account Address (Public Key)

This is your wallet address on Hyperliquid. You can find it by:

  1. Go to app.hyperliquid.xyz
  2. Connect your wallet (MetaMask, WalletConnect, etc.)
  3. Your address will be displayed in the top-right corner
  4. Copy the full address (starts with 0x)

Step 2: Private Key

Critical Security Warning: Your private key controls your funds. Never share it with anyone. Never commit it to version control. Store it securely and only use it in trusted environments.

To export your private key from MetaMask:

  1. Open MetaMask extension
  2. Click the three dots menu on your account
  3. Select "Account details"
  4. Click "Show private key"
  5. Enter your MetaMask password
  6. Copy the private key and add it to your .env file

Step 3: API Wallet (Recommended for Security)

For enhanced security, create a dedicated API wallet with limited permissions:

  1. Visit app.hyperliquid.xyz/API
  2. Click "Create API Wallet"
  3. Save the generated private key securely
  4. Grant the API wallet trading permissions from your main wallet
  5. Use the API wallet's private key in your .env
  6. Keep your main wallet address as HYPERLIQUID_ACCOUNT_ADDRESS

Best Practice: Using an API wallet limits exposure. If compromised, you can revoke its permissions without affecting your main wallet.

AI Provider Configuration

mucch supports two AI providers. You only need to configure one.

Option 1: OpenAI (GPT-5)

GPT-5 provides excellent market analysis with consistent reasoning:

  1. Go to platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Name it "mucch Trading Bot"
  4. Copy the key (starts with sk-proj-)
  5. Add to your .env file
OPENAI_API_KEY=sk-proj-abc123...

Option 2: OpenRouter (Claude 4.5 Sonnet)

Claude 4.5 Sonnet offers advanced reasoning and often provides more detailed analysis:

  1. Go to openrouter.ai/keys
  2. Create an account or sign in
  3. Click "Create Key"
  4. Copy the key (starts with sk-or-)
  5. Add to your .env file
OPENROUTER_API_KEY=sk-or-v1-xyz789...

Testing Configuration

To test mucch without risking real funds, use Hyperliquid's testnet:

# Use testnet for safe testing
HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz

# Get testnet funds from the faucet
# Visit: https://app.hyperliquid-testnet.xyz

Complete Configuration Example

Here's a complete example .env file with all settings:

# Hyperliquid Configuration
HYPERLIQUID_PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
HYPERLIQUID_ACCOUNT_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
HYPERLIQUID_API_URL=https://api.hyperliquid.xyz

# AI Provider (choose one)
OPENAI_API_KEY=sk-proj-abc123def456ghi789...
# OPENROUTER_API_KEY=sk-or-v1-xyz789abc123...

# Trading Parameters
RISK_PERCENTAGE=1.0
MAX_POSITION_SIZE=1000
ENABLE_AI_SUGGESTIONS=true

Security Best Practices

Never commit .env files: Add .env to your .gitignore

Use API wallets: Create dedicated API wallets with limited permissions for bot trading

Start small: Test with small amounts first, even on mainnet, before scaling up

Monitor regularly: Keep an eye on your bot's performance and adjust settings as needed

InstallationQuick Start