Getting Started Guide

Quick start guide for installing and running the Wealth Trading Bot

⏱️ Estimated time: 10-15 minutes for paper trading, 20-30 minutes for live trading

Quick Start Flow

flowchart TB
    subgraph Setup["🔧 Initial Setup"]
        A[Download Binary] --> B[Create Config]
        B --> C{Paper or Live?}
    end
    
    subgraph Paper["📄 Paper Trading"]
        C -->|Paper| D[Run: wealth run]
        D --> E[Monitor at :9090]
    end
    
    subgraph Live["💰 Live Trading"]
        C -->|Live| F[Get API Keys]
        F --> G[Create Encrypted Credentials]
        G --> H[wealth credentials add]
        H --> I[Set WEALTH__EXECUTION__MODE=live]
        I --> J[Run: wealth run]
        J --> K[Enter Passphrase]
        K --> L[Monitor at :9090]
    end
    
    style Setup fill:#e3f2fd
    style Paper fill:#e8f5e9
    style Live fill:#fff3e0

Architecture Overview

flowchart LR
    subgraph Exchanges["Supported Exchanges"]
        BIN[Binance Futures]
        BYB[Bybit Perpetuals]
        HL[HyperLiquid]
        AST[Aster Futures]
    end
    
    subgraph Bot["Wealth Bot"]
        WS[WebSocket Streams]
        API[REST APIs]
        STRAT[Strategy Engine]
    end
    
    subgraph Outputs["Monitoring"]
        METRICS[Metrics :9090]
        LOGS[Structured Logs]
        HEALTH[Health Endpoint]
    end
    
    BIN & BYB & HL & AST <--> WS
    BIN & BYB & HL & AST <--> API
    WS --> STRAT
    API --> STRAT
    STRAT --> METRICS
    STRAT --> LOGS
    STRAT --> HEALTH

Prerequisites

  • Operating System: Linux, macOS, or Windows
  • Exchange Accounts: Binance Futures, Bybit Perpetuals, HyperLiquid, or Aster Futures (optional for paper trading)

Installation

Download the latest release for your platform:

# Linux (x86_64)
curl -LO https://github.com/thiras/wealth/releases/latest/download/wealth-linux-x86_64.tar.gz
tar -xzf wealth-linux-x86_64.tar.gz
chmod +x wealth
sudo mv wealth /usr/local/bin/

# macOS (Apple Silicon)
curl -LO https://github.com/thiras/wealth/releases/latest/download/wealth-darwin-arm64.tar.gz
tar -xzf wealth-darwin-arm64.tar.gz
chmod +x wealth
sudo mv wealth /usr/local/bin/

# macOS (Intel)
curl -LO https://github.com/thiras/wealth/releases/latest/download/wealth-darwin-x86_64.tar.gz
tar -xzf wealth-darwin-x86_64.tar.gz
chmod +x wealth
sudo mv wealth /usr/local/bin/

Verify installation:

wealth --version

# Pull the latest image
docker pull ghcr.io/thiras/wealth:latest

# Run with Docker Compose (recommended)
curl -LO https://raw.githubusercontent.com/thiras/wealth/main/compose.yml
docker compose up -d

# Or run directly
docker run -d --name wealth \
  -v $(pwd)/config.toml:/app/config.toml \
  -v $(pwd)/credentials.encrypted.json:/app/credentials.encrypted.json \
  -e CREDENTIALS_PASSPHRASE="your_passphrase" \
  ghcr.io/thiras/wealth:latest

Option 3: Build from Source

Building from source requires Rust toolchain and development dependencies.

First Run (Paper Trading)

The bot runs in paper trading mode by default, which is safe for testing without real money.

# Run with defaults (paper trading)
wealth run

# Show help and available commands
wealth --help

You should see output like:

INFO  Initializing bot | mode=paper_trading
INFO  Starting WebSocket price streams
INFO  Binance WebSocket connected
INFO  Bybit WebSocket connected
INFO  Bot running | metrics_port=9090

Check Health

In another terminal:

# Health endpoint
curl http://localhost:9090/health | jq

# Metrics endpoint (JSON info about OTLP config)
curl http://localhost:9090/metrics | jq
# Query actual metrics in Grafana/Prometheus backend

Configuration

Paper Trading (Default)

No credentials needed! Just run:

wealth run

Live Trading Setup

The bot supports two methods for providing credentials, and automatically chooses the right one:

  1. Encrypted Credentials (Recommended for production)

    • Set CREDENTIALS_PASSPHRASE in .env
    • Use wealth credentials commands to manage
    • Credentials stored in AES-256-GCM encrypted file

  2. Environment Variables (For development/testing)

    • Set exchange-specific variables in .env
    • Simpler but less secure
    • Bot automatically falls back to this if no encrypted file

No configuration needed - just set up one method and the bot handles the rest!

Step 1: Get API Keys

  • Binance API Keys - API Key + Secret Key
    • Enable Futures trading permission
    • IP whitelist recommended for production
  • Bybit API Keys - API Key + Secret Key
    • Requires Unified Trading Account (UTA)
    • Enable Contract trading permission
  • Aster API Keys - API Key + Secret Key (Binance-compatible format)
    • Variable funding intervals: Aster uses 4h or 8h funding intervals per symbol (fetched automatically by the bot)
    • API compatibility: Uses Binance-compatible endpoints, so credential setup is identical
  • HyperLiquid: Use your Ethereum wallet private key (0x... format)
    • Direct mode: Just the private key
    • Subkey mode (recommended): Master wallet address + API wallet private key
    • Vault mode: Vault address + API wallet private key

Step 2: Create Encrypted Credentials

# Create encrypted config and add credentials (interactive mode)
export CREDENTIALS_PASSPHRASE="your_secure_passphrase"
wealth credentials create
wealth credentials add binance
wealth credentials add bybit
wealth credentials add hyperliquid

# Verify setup
wealth credentials verify

📖 For detailed credential setup including HyperLiquid wallet modes (direct, subkey, vault), see Security Guide - Credential Setup.

Step 3: Run in Live Mode

export WEALTH__EXECUTION__MODE=live
wealth run
# You'll be prompted: 🔐 Enter credentials passphrase:

Note: The bot will automatically prompt for your passphrase if CREDENTIALS_PASSPHRASE is not set. For automation or scripts, set the env var to skip the prompt:

export CREDENTIALS_PASSPHRASE="your_secure_passphrase"
wealth run  # No prompt

Basic Commands

# Initialize configuration file
wealth init

# Run the bot
wealth run

# Verify configuration
wealth verify

# Display current config
wealth config

# Manage credentials
wealth credentials create
wealth credentials add binance  # Interactive mode
wealth credentials verify

# Generate shell completions
wealth completions bash > ~/.local/share/bash-completion/completions/wealth

💡 Tip: Once running, you can edit config.toml and changes will apply automatically within 500ms without restart. See Configuration Hot-Reload for details.

Testing the Setup

1. Verify Configuration

wealth verify --encrypted

2. Check Exchange Connectivity

wealth health --all

3. View Current Config

wealth config

4. Monitor Metrics

# In your browser
open http://localhost:9090/metrics

Common First-Run Issues

Issue: "Failed to decrypt credentials"

Solution: Enter the correct passphrase when prompted, or set the environment variable:

# Option 1: Just run and enter passphrase when prompted
wealth run
# 🔐 Enter credentials passphrase: ********

# Option 2: Set environment variable
export CREDENTIALS_PASSPHRASE="your_passphrase"
wealth run

Issue: "Configuration validation failed"

Solution: Check your configuration values

wealth verify

Issue: WebSocket connection failed

Solution: Check internet connection and firewall settings. Ensure your network allows outbound connections to:

  • Binance: stream.binance.com:443
  • Bybit: stream.bybit.com:443
  • HyperLiquid: api.hyperliquid.xyz:443

Issue: "Exchange rate limit exceeded"

Solution: The bot has built-in rate limiting, but if you see this:

  1. Wait 1-2 minutes before retrying
  2. Check if you have other tools using the same API keys
  3. Consider using different API keys for different tools

Issue: "Insufficient balance" in paper trading

Solution: Paper trading simulates with virtual balances. If you see balance issues:

  1. Check your config.toml for position sizing settings
  2. Ensure max_position_usd is reasonable for simulated balance

📖 More issues? See Troubleshooting Guide for comprehensive problem-solving.

Next Steps

Once your bot is running:

  1. Monitor Performance: Visit http://localhost:9090/metrics
  2. View Logs: Check terminal output for trading activity
  3. Configure Strategy: See Configuration Guide
  4. Set Up Dashboards: See Monitoring Guide
  5. Deploy to Production: See Deployment Guide

Quick Reference

Paper Trading (Safe):

wealth run  # That's it!

Live Trading (Requires credentials):

export WEALTH__EXECUTION__MODE=live
wealth run
# Enter passphrase when prompted, or set CREDENTIALS_PASSPHRASE env var

Custom Configuration:

# Use environment variables or config.toml for customization
export WEALTH__OBSERVABILITY__METRICS_PORT=8080
wealth run --verbose

AI-Powered Monitoring (After setup):

# Ask AI natural language questions like:
# "What's my current P&L?"
# "Show funding rates for BTCUSDT"
# "Are there any firing alerts?"

Stop the Bot: Press Ctrl+C for graceful shutdown (takes ~6-8 seconds to close all positions safely)

Note: Shutdown is fast thanks to shutdown-aware background tasks that respond instantly to signals.

TopicGuide
Command referenceCLI Reference
All config optionsConfiguration Guide
Secure credentialsSecurity Guide
Cloud monitoringGrafana Cloud Setup
Production deployDeployment Guide
Common issuesTroubleshooting