Getting Started Guide

Quick start guide for installing and running the Wealth Trading Bot

Prerequisites

  • Operating System: Linux, macOS, or Windows
  • Exchange Accounts: Binance Futures, Bybit Perpetuals, or HyperLiquid (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

For developers who want to build from source, see the Development Guide.

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
  • Bybit API Keys - API Key + Secret Key
  • 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
    • See HyperLiquid Integration Guide for authorization details

Step 2: Create Encrypted Credentials

# Create encrypted config
wealth credentials create

# Add exchange credentials
export CREDENTIALS_PASSPHRASE="your_secure_passphrase"
wealth credentials add binance YOUR_API_KEY YOUR_SECRET
wealth credentials add bybit YOUR_API_KEY YOUR_SECRET

# HyperLiquid (choose one mode):

# Direct wallet mode (simplest)
wealth credentials add hyperliquid "" 0xYourPrivateKey

# API wallet (subkey) mode (recommended - better security)
wealth credentials add hyperliquid 0xMasterWallet 0xAPIWalletPrivateKey

# Vault mode (for HyperLiquid vaults)
wealth credentials add hyperliquid 0xVaultAddress 0xAPIWalletPrivateKey --vault-mode

# Verify
wealth credentials verify

Important: If using HyperLiquid subkey mode, you must authorize the API wallet in the HyperLiquid UI. See the detailed HyperLiquid Authorization Guide for step-by-step instructions.

Step 3: Run in Live Mode

export WEALTH__EXECUTION__MODE=live
export CREDENTIALS_PASSPHRASE="your_secure_passphrase"
wealth run

Alternative: Using Environment Variables

For development or testing, you can use environment variables instead of encrypted credentials:

# 1. Copy example configuration
cp .env.example .env

# 2. Edit .env and set exchange credentials
nano .env

# Example .env content:
# BINANCE_API_KEY=your_api_key
# BINANCE_SECRET_KEY=your_secret_key
# BYBIT_API_KEY=your_api_key
# BYBIT_SECRET_KEY=your_secret_key

# 3. Run (no CREDENTIALS_PASSPHRASE needed)
export WEALTH__EXECUTION__MODE=live
wealth run

Note: The bot automatically detects and uses this method when CREDENTIALS_PASSPHRASE is not set.

Basic Commands

# Run the bot
wealth run

# Verify configuration
wealth verify

# Display current config
wealth config

# Manage credentials
wealth credentials create
wealth credentials add binance YOUR_KEY YOUR_SECRET
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: Set CREDENTIALS_PASSPHRASE environment variable

export CREDENTIALS_PASSPHRASE="your_passphrase"

Issue: "Configuration validation failed"

Solution: Check your configuration values

wealth verify

Issue: WebSocket connection failed

Solution: Check internet connection and firewall settings

Next Steps

Once your bot is running:

  1. Monitor Performance: Visit http://localhost:9090/metrics
  2. Set Up AI Monitoring: See Grafana MCP Setup 🤖
  3. View Logs: Check terminal output for trading activity
  4. Configure Strategy: See Configuration Guide
  5. Set Up Dashboards: See Monitoring Guide
  6. 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
export CREDENTIALS_PASSPHRASE="your_passphrase"
wealth run

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.

See Also