Wealth Trading System - User Guide

Your guide to automated funding rate arbitrage trading

Welcome to the Wealth Trading System! This documentation will help you get started and make the most of the platform.

Quick Navigation

Supported Exchanges

Strategy & Trading

• Trading Strategy - How the bot generates profits
• Strategy Formulas - Mathematical models and calculations

Getting Started

• Quick Start Guide - Installation, setup, and first run
• Practical Examples - Real-world workflows and use cases
• Configuration Guide - Settings and environment variables
• CLI Reference - Command-line interface documentation
• HTTP API Reference - REST API for automation
• TUI Dashboard - Interactive terminal interface

Monitoring & Operations

• Monitoring & Metrics - Prometheus, Grafana, and observability
• Grafana Cloud Setup - Cloud monitoring configuration
• Log Collection - Centralized logging with Loki
• Hot-Reload - Live configuration updates

Deployment & Security

• Deployment Guide - Production deployment and Docker
• Security & Credentials - Keeping your system secure

Help & Support

• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions
• Licensing - License information

Quick Reference

Core Features

• Real-time funding rate monitoring across multiple exchanges
• WebSocket market data streaming with automatic reconnection
• Atomic order execution with automatic rollback on failure
• Automatic max leverage detection with symmetric resolution for hedged positions
• Slippage protection with adaptive limit orders
• Paper trading mode for safe testing
• Encrypted credentials (AES-256-GCM)
• OpenTelemetry metrics & Grafana dashboards
• Docker containerization with compose support
• Fast graceful shutdown

Support

• GitHub Issues: https://github.com/thiras/wealth/issues
• Repository: https://github.com/thiras/wealth

License & Disclaimer

License: Proprietary License - See LICENSE file for details

⚠️ Disclaimer: Cryptocurrency trading involves substantial risk. Use at your own risk. The authors assume no responsibility for financial losses.

Trading Strategy Guide

Understanding how the Wealth bot generates profits through funding rate arbitrage

Overview

The Wealth bot implements a funding rate arbitrage strategy that profits from differences in funding rates across cryptocurrency exchanges while maintaining delta-neutral positions (no exposure to price movements).

Strategy Flow

stateDiagram-v2
    [*] --> Monitoring: Start Bot
    
    Monitoring --> Evaluating: Found Opportunity
    Evaluating --> Monitoring: Below Threshold
    Evaluating --> Executing: Meets Criteria
    
    state Executing {
        [*] --> PlacingLong
        PlacingLong --> PlacingShort
        PlacingShort --> Hedging
        Hedging --> Completed
        PlacingLong --> RollingBack: Failure
        PlacingShort --> RollingBack: Failure
        RollingBack --> RolledBack
    }
    
    Executing --> Active: Completed
    Executing --> Monitoring: RolledBack
    
    Active --> Closing: Exit Trigger
    Closing --> Monitoring: Position Closed
    
    note right of Active
        Exit Triggers:
        - Target profit reached
        - Spread reversal
        - Trailing stop
        - Max duration
    end note

What Are Funding Rates?

Funding rates are periodic payments exchanged between traders holding long and short positions in perpetual futures contracts. They keep the perpetual futures price aligned with the spot price.

• Positive funding rate: Longs pay shorts
• Negative funding rate: Shorts pay longs
• Payment frequency: Varies by exchange:
  • Binance/Bybit: Every 8 hours (3× daily)
  • HyperLiquid: Every 1 hour (24× daily)
  • Aster: Every 4-8 hours depending on symbol (fetched automatically)

How the Strategy Works

The Arbitrage Opportunity

flowchart TB
    subgraph Funding["Funding Rate Arbitrage"]
        direction TB
        A[Exchange A<br/>Low Funding Rate] 
        B[Exchange B<br/>High Funding Rate]
        
        A -->|"LONG Position<br/>(Pay low funding)"| POS[Delta-Neutral<br/>Position]
        B -->|"SHORT Position<br/>(Receive high funding)"| POS
        
        POS -->|"Net Profit"| PROFIT["Spread = High Rate - Low Rate"]
    end
    
    style A fill:#c8e6c9
    style B fill:#ffcdd2
    style POS fill:#e3f2fd
    style PROFIT fill:#fff9c4

Different exchanges often have different funding rates for the same asset. The bot exploits this by:

1. Opening a LONG position on the exchange with the lower (or negative) funding rate
2. Opening a SHORT position on the exchange with the higher funding rate
3. Collecting the spread between the two rates every funding period

Delta-Neutral = Market-Neutral

Because you hold equal and opposite positions:

• If BTC price goes up: Your long profits, your short loses → net zero
• If BTC price goes down: Your long loses, your short profits → net zero
• Your only P&L comes from the funding rate difference

Visual Example

Exchange A (Binance):    Funding Rate = +0.01%  → You go LONG  (receive 0.01%)
Exchange B (HyperLiquid): Funding Rate = +0.05% → You go SHORT (pay 0.05%)

Your position:
┌─────────────────────────────────────────────────────────────┐
│  LONG 0.1 BTC on Binance    ←→    SHORT 0.1 BTC on HyperLiquid  │
│  (Receive funding)                (Pay funding)                 │
└─────────────────────────────────────────────────────────────┘

Net result per 8-hour period:
  Receive: +0.01% on Binance
  Pay:     -0.05% on HyperLiquid
  ────────────────────────────
  Wait... that's negative!

Actually, you want the OPPOSITE - go SHORT where rates are HIGH:
  Pay:     -0.01% on Binance (you're long, you pay positive funding)
  Receive: +0.05% on HyperLiquid (you're short, you receive positive funding)
  ────────────────────────────
  Net: +0.04% profit per 8 hours

Profit Calculation Example

Position size: $10,000 per side
Funding spread: 0.04% (4 basis points)
Leverage: 10x

Per funding period (every 8 hours):
  Profit = $10,000 × 0.0004 = $4.00

Daily (3 funding periods):
  Profit = $4.00 × 3 = $12.00

Monthly:
  Profit = $12.00 × 30 = $360.00

Annualized APY:
  APY = 0.04% × 3 × 365 = 43.8%

When Does the Bot Open Positions?

The bot continuously monitors funding rates and opens positions when:

1. Spread exceeds threshold: The funding rate difference meets your configured minimum (default: 0.04%)
2. Sufficient balance: You have enough collateral on both exchanges
3. Position limits not reached: You haven't hit your maximum concurrent positions
4. Positive expected value: After accounting for fees and slippage, the trade is profitable

When Does the Bot Close Positions?

Positions are closed automatically when:

1. Target profit reached: Default 5% profit on position
2. Spread reverses: The funding rate advantage disappears or reverses
3. Trailing stop triggered: Profit retraces too much from peak (protects gains)
4. Manual shutdown: You stop the bot gracefully

Risk Management Features

Delta-Neutral Protection

• Equal position sizes on both exchanges
• No exposure to price movements
• Profit comes only from funding rate spread

Slippage Protection

• Uses limit orders with timeout
• Falls back to market orders if needed
• Configurable maximum slippage tolerance

Trailing Stop Loss

• Activates after reaching profit threshold (default: 3%)
• Locks in minimum profit (default: 2%)
• Closes if profit retraces too much from peak

Atomic Execution

• Opens both legs simultaneously
• If one leg fails, the other is rolled back
• Prevents unhedged (risky) positions

Position Size Limits

• Maximum position size cap (USD)
• Maximum percentage of balance per trade
• Maximum concurrent positions

Configuring the Strategy

Key parameters in config.toml:

[trading]
# Minimum spread to open a position (0.04% = 4 basis points)
min_funding_spread = 0.04

# Position sizing
position_size_percent = 0.30    # Use 30% of available balance
max_position_usd = 10000        # Cap at $10,000 per position
max_concurrent_positions = 5    # Maximum open positions

# Profit targets
target_profit_percent = 0.05    # Close at 5% profit

[risk]
# Trailing stop configuration
trailing_stops_enabled = true
trailing_stop_activation = 0.03  # Activate at 3% profit
trailing_stop_distance = 0.40    # Allow 40% retracement
trailing_stop_min_lock = 0.02    # Lock in minimum 2%

# Slippage protection
max_slippage_bps = 50           # Maximum 0.5% slippage

Understanding Expected Value (EV)

Before opening a position, the bot calculates the expected value - whether the trade will be profitable after costs:

flowchart LR
    subgraph EV["Expected Value Calculation"]
        SPREAD[Funding Spread] --> GROSS[Gross EV]
        TIME[Time Weight] --> GROSS
        
        GROSS --> NET[Net EV]
        FEES[Entry + Exit Fees] --> NET
        SLIP[Slippage Estimate] --> NET
        
        NET --> DECISION{EV > Threshold?}
        DECISION -->|Yes| TRADE[Execute Trade]
        DECISION -->|No| SKIP[Skip Opportunity]
    end
    
    style GROSS fill:#e8f5e9
    style NET fill:#fff3e0
    style TRADE fill:#c8e6c9
    style SKIP fill:#ffcdd2

Expected Value = (Funding Spread × Time Weight) - (Entry Fees + Exit Fees + Slippage)

• Funding Spread: The rate difference between exchanges
• Time Weight: Reduced value if close to next funding payment
• Fees: Trading fees on both exchanges (entry and exit)
• Slippage: Expected price impact

The bot only opens positions with positive expected value.

Pair Selection Strategies

The bot supports multiple strategies for selecting which trading pairs to monitor:

Arbitrage-Based Selection (Recommended)

Sort pairs by their current funding rate spread to find the best arbitrage opportunities:

[instrument_discovery]
enabled = true
use_loris_rankings = true
loris_sort_by = "arbitrage"    # Sort by funding spread (default)

How it works:

• For each symbol, finds the exchange with the lowest rate (go long) and highest rate (go short)
• Calculates the spread: short_rate - long_rate
• Ranks symbols by spread size (highest first)
• Prioritizes pairs with immediate profit potential

Best for: Active traders seeking maximum returns

Liquidity-Based Selection

Sort pairs by open interest rank to prioritize the most liquid markets:

[instrument_discovery]
enabled = true
use_loris_rankings = true
loris_sort_by = "oi_rank"      # Sort by liquidity

How it works:

• Uses Binance open interest rankings as a proxy for liquidity
• Lower rank = more liquid (BTC is usually rank 1)
• Prioritizes easy entry/exit with minimal slippage

Best for: Conservative traders, larger position sizes

Volume-Based Selection

Sort pairs by 24h trading volume using direct exchange APIs:

[instrument_discovery]
enabled = true
use_loris_rankings = false     # Use exchange APIs

How it works:

• Fetches 24h volume from each exchange directly
• Ranks pairs by trading activity
• No third-party data dependency

Best for: Traders who prefer direct data sources

Supported Exchanges

*Bybit and Aster funding intervals vary per symbol. The bot automatically fetches per-symbol intervals via API at startup, refreshes every 4 hours, and receives real-time updates from WebSocket streams.

Note: HyperLiquid's hourly funding means more frequent profit collection but requires different EV calculations.

Frequently Asked Questions

What happens if one exchange goes down?

The bot monitors connectivity and will:

• Alert you to connection issues
• Prevent new positions from opening
• Existing positions remain open (both legs on different exchanges)

Can I lose money?

While the strategy is market-neutral, risks include:

• Fee costs: If spread narrows before covering fees
• Liquidation: If leverage is too high and price moves sharply
• Exchange risk: Counterparty risk on centralized exchanges
• Execution risk: Slippage during entry/exit

How much capital do I need?

Minimum recommended: $1,000 per exchange ($2,000 total)

With leverage, you can control larger positions:

• $1,000 at 10x = $10,000 position size
• Required margin = Position / Leverage + Safety Buffer

What's a good minimum spread to trade?

• Conservative: 0.05% (5 basis points) - fewer trades, higher quality
• Moderate: 0.04% (4 basis points) - balanced approach
• Aggressive: 0.03% (3 basis points) - more trades, lower margins

How often are there opportunities?

This varies by market conditions:

• High volatility: More funding rate divergence = more opportunities
• Low volatility: Rates converge = fewer opportunities
• Typical: 2-5 high-quality opportunities per day

See Also

• Configuration Guide - Detailed parameter reference
• Getting Started - Initial setup
• Monitoring Guide - Track your positions
• Troubleshooting - Common issues

Strategy Calculation Formulas

Mathematical reference for funding rate arbitrage calculations, position sizing, and profitability analysis

Table of Contents

• Funding Rate Arbitrage
• Expected Value (EV) Calculation
• Position Sizing
• Fee Calculations
• Profit & Loss
• Risk Metrics
• Configuration Reference

Funding Rate Arbitrage

Core Concept

Funding rate arbitrage exploits differences in funding rates across exchanges while maintaining delta-neutral positions.

Funding Rate Spread

$$\text{spread}=|{\text{rate}}_{\text{short}}-{\text{rate}}_{\text{long}}|$$

Where:

• rate_short = funding rate on high-rate exchange (short position)
• rate_long = funding rate on low-rate exchange (long position)

Example:

Binance BTCUSDT: +0.0001 (1 basis point)
HyperLiquid BTCUSDT: +0.0006 (6 basis points)

spread = |0.0006 - 0.0001| = 0.0005 = 5 basis points = 0.05%

Annual Percentage Yield (APY)

$$\text{APY}=\text{spread}\times \text{funding\_intervals\_per\_year}$$

Where:

• funding_intervals_per_year depends on exchange funding frequency
• Spread is expressed as a decimal (e.g., 0.0005)

APY by Exchange Interval:

Example (8-hour interval):

spread = 0.0005 (5 basis points)
APY = 0.0005 × 1,095 = 0.5475 = 54.75%

Example (1-hour interval - HyperLiquid):

spread = 0.0001 (1 basis point per hour)
APY = 0.0001 × 8,760 = 0.876 = 87.6%

Expected Value (EV) Calculation

The bot uses risk-adjusted expected value to filter opportunities and ensure trades are profitable after all costs.

Funding Intervals by Exchange

*Bybit and Aster funding intervals vary by symbol. The bot automatically fetches per-symbol intervals via REST API at startup (refreshed every 4h) and from WebSocket streams in real-time.

Cross-Exchange Yield Normalization

When trading across exchanges with different funding intervals (e.g., HyperLiquid + Binance), the bot normalizes yields to a common 8-hour reference period. This is important because HyperLiquid pays funding 8x more frequently than Binance/Bybit.

How It Works:

Key Benefit: A 9 bps simple spread becomes 79 bps normalized yield when HyperLiquid's 8x payment frequency is properly accounted for.

Time Weighting

$$\text{time\_weight}=\min \left(\frac{\text{minutes\_to\_funding}}{\text{min\_interval}},1\right)$$

Where:

• min_interval = minimum of both exchange intervals (determines next funding)
• Weight approaches 1 as funding time approaches
• Weight approaches 0 immediately after funding

Gross Expected Value

$$\text{gross\_ev}=\text{normalized\_spread}\times \text{time\_weight}$$

Transaction Costs

$$\text{costs}={\text{fee}}_{\text{long\_entry}}+{\text{fee}}_{\text{long\_exit}}+{\text{fee}}_{\text{short\_entry}}+{\text{fee}}_{\text{short\_exit}}+\text{slippage}$$

For limit orders (maker fees): $$\text{costs}=2\times ({\text{maker}}_{\text{long}}+{\text{maker}}_{\text{short}})$$

For market orders (taker fees + slippage): $$\text{costs}=2\times ({\text{taker}}_{\text{long}}+{\text{taker}}_{\text{short}})+\text{slippage\_estimate}$$

Staleness Haircut

$$\text{staleness}=\{\begin{array}{ll}\text{haircut}& \text{if data age}>4\text{ minutes}\\ 0& \text{otherwise}\end{array}$$

Default: haircut = 0.03 (3 basis points = 0.03%)

Adjusted Expected Value

$$\text{adjusted\_ev}=\text{gross\_ev}-\text{costs}-\text{staleness}$$

Qualification Criteria

An opportunity qualifies if:

$$\text{adjusted\_ev}\ge \text{min\_ev\_bps}\text{AND}\text{spread}\ge \text{min\_spread\_threshold}$$

Default thresholds (percentage form):

• min_ev_bps = 0.05 (5 basis points = 0.05%)
• min_spread_threshold = 0.04 (4 basis points = 0.04%)

Complete EV Example

Scenario:

• Binance BTCUSDT: +0.01% (long position, 8h interval)
• HyperLiquid BTCUSDT: +0.10% (short position, 1h interval)
• Time to funding: 60 minutes (HyperLiquid's next funding)
• Order type: Limit (maker fees)

Step 1: Calculate normalized spread

Long Binance: -0.01% × (480/480) = -0.01% (pay 1 payment)
Short HyperLiquid: +0.10% × (480/60) = +0.80% (receive 8 payments)
Normalized spread = -0.01% + 0.80% = +0.79% (79 bps)

Step 2: Time weighting (using minimum interval = 60 min) $$\text{time\_weight}=\frac{60}{60}=1.0$$

Step 3: Gross EV $$\text{gross\_ev}=0.79\%\times 1.0=0.79\%=79\text{ bps}$$

Step 4: Calculate costs

Binance fees: 0.02% maker (entry) + 0.02% maker (exit) = 0.04%
HyperLiquid fees: 0.0144% maker (entry) + 0.0144% maker (exit) = 0.0288%
Total costs: ~7 bps

Step 5: Staleness haircut

Data age: < 4 minutes
Staleness: 0

Step 6: Adjusted EV $$\text{adjusted\_ev}=79-7-0=72\text{ bps}$$

Step 7: Qualification check

adjusted_ev (72 bps) >= min_ev (5 bps) ✅
raw_spread (9 bps) >= min_spread (4 bps) ✅

Result: QUALIFIES

Expected profit per $10,000 position (over 8h reference): $$\text{profit}=\$10,000\times 0.0072=\$72$$

Note: The normalized EV (72 bps after costs) is much higher than what you'd calculate from the simple 9 bps spread because HyperLiquid pays funding 8 times per Binance cycle.

Position Sizing

Conservative Sizing Formula

The bot reserves margin for both opening AND closing positions:

$$\text{position\_size}=\left(\frac{\text{balance}\times \text{percentage}}{2}\right)\times \text{leverage}$$

Where:

• balance = available balance on exchange (USDT)
• percentage = position size percentage (default: 0.30 = 30%)
• leverage = configured leverage (default: 10x)
• Division by 2 reserves margin for closing

Example:

balance = $1,000 USDT
percentage = 0.30 (30%)
leverage = 10x

position_size = (1,000 × 0.30 / 2) × 10
              = (300 / 2) × 10
              = 150 × 10
              = $1,500 USD notional

Quantity Calculation

$$\text{quantity}=\frac{\text{position\_size}}{\text{price}}$$

Must be rounded to exchange precision:

$$\text{quantity\_rounded}=\lfloor \frac{\text{quantity}}{10^{-\text{precision}}}\rfloor \times 10^{-\text{precision}}$$

Example:

position_size = $1,500
BTC price = $50,000
precision = 3 decimals (0.001 BTC minimum)

quantity = 1,500 / 50,000 = 0.030 BTC
quantity_rounded = floor(0.030 / 0.001) × 0.001 = 0.030 BTC ✅

Kelly Criterion Sizing

The bot supports two position sizing modes:

Mode 1: Kelly Criterion (Dynamic)

Enabled when use_kelly_criterion = true (default). Sizes positions based on expected value and variance:

$$\text{kelly\_fraction}=\frac{\text{EV}}{\text{variance}}$$

$$\text{raw\_kelly\_size}=\text{kelly\_fraction}\times \text{reference\_capital}\times \text{leverage}$$

With safety caps:

$$\text{final\_size}=\min \left(\text{raw\_kelly\_size}\times \text{kelly\_cap},\text{max\_notional},\text{balance}\times \text{max\_utilization}\right)$$

Where:

• kelly_cap = 0.25 (quarter-Kelly, default)
• max_notional = $10,000 (per-symbol cap, default)
• max_utilization = 0.50 (50% of balance, default)

Use when: You want dynamic sizing that increases with edge quality and decreases with variance.

Mode 2: Fixed Percentage (Simple)

Enabled when use_kelly_criterion = false. Uses fixed percentage of available capital:

$$\text{reference\_capital}=\min (\text{long\_balance},\text{short\_balance})$$

$$\text{fixed\_size}=\text{reference\_capital}\times \text{max\_utilization}\times \text{leverage}$$

With safety cap:

$$\text{final\_size}=\min (\text{fixed\_size},\text{max\_notional})$$

Use when: You want predictable, consistent position sizing regardless of opportunity quality.

Configuration:

[trading]
use_kelly_criterion = true    # Toggle between Kelly and fixed modes
kelly_fraction = 0.25          # Only used in Kelly mode
max_exchange_utilization = 0.5 # Used in both modes
max_notional_per_symbol = 10000 # Hard cap for both modes

Fee Calculations

Exchange Fee Structure

*Bybit and Aster funding intervals vary per symbol (4h or 8h), fetched dynamically via API and WebSocket **HyperLiquid has 24 funding payments per day (hourly)

Order Fee Calculation

$$\text{fee}=\text{notional\_value}\times \text{fee\_rate}$$

$$\text{notional\_value}=\text{quantity}\times \text{price}$$

Example:

quantity = 0.1 BTC
price = $50,000
fee_rate = 0.0004 (0.04% taker)

notional = 0.1 × 50,000 = $5,000
fee = 5,000 × 0.0004 = $2.00

Round-Trip Cost

For entering and exiting a position:

$$\text{round\_trip\_cost}=2\times ({\text{fee}}_{\text{long}}+{\text{fee}}_{\text{short}})+\text{slippage}$$

Example (limit orders):

Binance maker: 0.02%
HyperLiquid maker: 0.00%

Entry cost: (0.0002 + 0.0000) = 0.0002 = 0.02%
Exit cost: (0.0002 + 0.0000) = 0.0002 = 0.02%
Total: 0.0004 = 0.04% = 4 basis points

On $10,000 position: $10,000 × 0.0004 = $4.00

Breakeven Spread

Minimum spread needed to be profitable:

$$\text{breakeven\_spread}=\frac{\text{round\_trip\_cost}}{\text{holding\_periods}}$$

Example (3 funding periods = 24 hours):

round_trip_cost = 0.0004 (4 bps)
holding_periods = 3

breakeven = 0.0004 / 3 = 0.000133 = 1.33 bps per period

Profit & Loss

Funding Payment Calculation

$$\text{funding\_payment}=\text{position\_size}\times \text{funding\_rate}$$

For long position:

• Positive rate: pay funding
• Negative rate: receive funding

For short position:

• Positive rate: receive funding
• Negative rate: pay funding

Arbitrage Profit Per Period

$$\text{profit}=\text{position\_size}\times ({\text{rate}}_{\text{short}}-{\text{rate}}_{\text{long}})$$

Example:

position_size = $10,000
Binance rate (long): +0.0001
HyperLiquid rate (short): +0.0006

profit = 10,000 × (0.0006 - 0.0001)
       = 10,000 × 0.0005
       = $5.00 per funding period

Net Profit After Fees

$$\text{net\_profit}=\text{gross\_profit}-\text{entry\_fees}-\text{exit\_fees}$$

Example:

gross_profit = $5.00 per period × 3 periods = $15.00
entry_fees = $4.00
exit_fees = $4.00

net_profit = 15.00 - 4.00 - 4.00 = $7.00 per day
monthly = $7.00 × 30 = $210.00

Return on Capital

$$\text{ROC}=\frac{\text{net\_profit}}{\text{margin\_used}}$$

$$\text{margin\_used}=\frac{\text{position\_size}}{\text{leverage}}$$

Example:

position_size = $10,000
leverage = 10x
margin_used = 10,000 / 10 = $1,000

daily_profit = $7.00
daily_ROC = 7.00 / 1,000 = 0.007 = 0.7%
annual_ROC = 0.007 × 365 = 2.555 = 255.5%

ROI (Return on Investment)

The ROI displayed in the TUI is calculated as:

$$\text{ROI}=\frac{\text{funding\_collected}-\text{trading\_fees}}{\text{position\_size}}\times 100\%$$

Where:

• funding_collected = total funding payments received since position opened
• trading_fees = trading fees for both legs (entry + exit). Note: as of now, the fee tracker only captures entry fees; exit fees are included in the formula but are effectively $0 until exit-fee tracking is implemented.
• position_size = notional value of the position

ROI Display States:

Fee Estimation Fallback:

When exchange API calls fail or timeout (2 minutes), fees are estimated: $$\text{estimated\_fees}=\text{position\_size}\times 0.0005\times 2$$

This uses a default taker fee rate of 0.05% (5 basis points) per leg.

Example:

position_size = $1,000
funding_collected = $5.00
entry_fee_long = $0.50
entry_fee_short = $0.35

ROI = (5.00 - 0.50 - 0.35) / 1,000 × 100%
    = 4.15 / 1,000 × 100%
    = 0.415%

Unrealized P&L (Price Spread)

Added in v0.58: The TUI and metrics now display unrealized P&L from price spread movements, not just funding collected.

While funding rate arbitrage is theoretically delta-neutral, price divergence between exchanges creates real P&L that must be tracked. This is especially important when exchanges have different liquidity or when prices move during entry/exit.

Formula:

$$\text{unrealized\_price\_pnl}=\text{long\_leg\_pnl}+\text{short\_leg\_pnl}$$

Where:

$$\text{long\_leg\_pnl}=(\text{current\_price}-\text{long\_entry\_price})\times \text{quantity}$$

$$\text{short\_leg\_pnl}=(\text{short\_entry\_price}-\text{current\_price})\times \text{quantity}$$

Example (Spread Reversal - Loss):

# Position entered with 0.1 BTC
long_entry_price = $40,000 (Binance)
short_entry_price = $40,000 (Aster)
current_price = $40,100 (price moved up)

long_leg_pnl  = (40,100 - 40,000) × 0.1 = +$10.00 (profit)
short_leg_pnl = (40,000 - 40,100) × 0.1 = -$10.00 (loss)

# In theory, should net to $0 if hedged properly
# But with slippage or different prices on each exchange:

long_entry_price = $40,000 (Binance)
short_entry_price = $39,950 (Aster - worse fill)
current_price = $40,100

long_leg_pnl  = (40,100 - 40,000) × 0.1 = +$10.00
short_leg_pnl = (39,950 - 40,100) × 0.1 = -$15.00
total_price_pnl = 10.00 - 15.00 = -$5.00 (loss from spread)

Total Unrealized P&L:

$$\text{total\_unrealized\_pnl}=\text{funding\_collected}+\text{price\_spread\_pnl}$$

Important: A position can show positive funding collected but still be losing money overall if the price spread moved against you.

Risk Metrics

Maximum Position Size

$$\text{max\_size}=\min \left(\text{config\_max},\frac{\text{balance}\times \text{utilization}}{\text{margin\_rate}}\right)$$

Where:

• config_max = $10,000 (default per-symbol cap)
• utilization = 0.50 (50% of balance usage)
• margin_rate = 1 / leverage

Example:

balance = $5,000
utilization = 0.50
leverage = 10x
margin_rate = 0.1

balance_limit = (5,000 × 0.50) / 0.1 = 25,000
max_size = min(10,000, 25,000) = $10,000

Margin Requirement

$$\text{margin\_required}=\frac{\text{position\_size}}{\text{leverage}}\times 1.2$$

The 1.2 factor provides a 20% safety buffer.

Example:

position_size = $10,000
leverage = 10x

margin = (10,000 / 10) × 1.2 = 1,000 × 1.2 = $1,200

Liquidation Distance

$$\text{liq\_distance}=\frac{\text{margin}-\text{maintenance\_margin}}{\text{position\_size}}$$

Example:

margin = $1,000
maintenance = $100 (10% of margin)
position_size = $10,000

liq_distance = (1,000 - 100) / 10,000 = 0.09 = 9%

Position liquidates at 9% adverse price move

Sharpe Ratio

$$\text{Sharpe}=\frac{\text{mean\_return}-\text{risk\_free\_rate}}{\text{std\_deviation}}$$

Calculated over historical trades for strategy performance evaluation.

Maximum Drawdown

$$\text{max\_drawdown}=\max \left(\frac{\text{peak\_equity}-\text{current\_equity}}{\text{peak\_equity}}\right)$$

Tracks the largest peak-to-trough decline in account equity.

Configuration Reference

Default Values

Exchange Fee Rates

Example Configuration

[trading]
# Spread thresholds
min_funding_spread = 0.04        # 4 basis points
min_ev_bps = 0.05                # 5 basis points

# Position sizing
position_size_percent = 0.30       # 30% of balance
max_position_usd = 10000           # $10,000 cap
leverage = 10                      # 10x leverage

# Kelly criterion settings
use_kelly_criterion = true
kelly_fraction = 0.25              # Quarter-Kelly
max_exchange_utilization = 0.50    # 50% max usage

[risk]
# Slippage
max_slippage_bps = 50              # 0.5% maximum
estimated_slippage = 0.001         # 0.1% estimate

Quick Reference Card

Profit Estimation

APY by Spread

Minimum Capital Requirements

See Also

• Trading Strategy - Strategy overview and concepts
• Configuration Guide - Detailed parameter reference
• Getting Started - Initial setup
• Monitoring Guide - Track your positions

Note: All formulas use decimal representation (e.g., 0.0005 = 5 basis points = 0.05%). The bot maintains high precision using Rust's Decimal type (96-bit precision) for all calculations.

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

Option 1: Download Binary (Recommended)

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

Option 2: Docker (Recommended for Production)

# 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.

Related Documentation

Practical Examples & Common Workflows

This guide provides practical, real-world examples for using the Wealth trading bot. All examples assume you've completed the Getting Started guide.

Table of Contents

• Quick Start Example
• Opening Your First Position
• Monitoring Active Positions
• Closing Positions
• Alert Integration
• Troubleshooting Common Issues

Quick Start Example

Complete Workflow from Scratch

This example shows the complete workflow from installation to your first trade:

# 1. Download and install (or use Docker)
# See Getting Started guide for installation options

# 2. Set up credentials
export CREDENTIALS_PASSPHRASE="your-secure-passphrase-here"
wealth credentials create
wealth credentials add binance   # Interactive prompts
wealth credentials add hyperliquid

# 3. Verify setup
wealth verify

# 4. Run the bot (paper trading by default)
wealth run

📖 For detailed setup instructions, see:

• Getting Started - First Run
• Security Guide - Credential Setup

Expected Output:

2025-11-07T10:30:00Z INFO  Wealth Trading Bot
2025-11-07T10:30:00Z INFO  Mode: PAPER TRADING (no real orders)
2025-11-07T10:30:01Z INFO  Initialized leverage: BTCUSDT = 15x
2025-11-07T10:30:02Z INFO  WebSocket connected: Binance ticker stream
2025-11-07T10:30:03Z INFO  WebSocket connected: HyperLiquid ticker stream
2025-11-07T10:30:04Z INFO  Fetching funding rates...
2025-11-07T10:30:05Z INFO  Binance BTCUSDT: 0.0100%
2025-11-07T10:30:05Z INFO  HyperLiquid BTC: 0.0500%
2025-11-07T10:30:05Z INFO  Spread detected: 0.0400% (above 0.0300% threshold)
2025-11-07T10:30:05Z INFO  Opening arbitrage position...

Opening Your First Position

Manual Position Opening (Development/Testing)

# Check current funding rates
wealth funding

# Output:
# Exchange      Symbol      Rate        Next Payment
# binance       BTCUSDT     0.0100%     2025-11-07 12:00:00 UTC
# hyperliquid   BTC         0.0500%     2025-11-07 11:00:00 UTC
# Spread: 0.0400% ✓ (above 0.0300% threshold)

# Check available balance
wealth balance

# Output:
# Exchange      Asset    Free         Total        Reserved
# binance       USDT     10000.00     10000.00     0.00
# hyperliquid   USDT     10000.00     10000.00     0.00

# Start the bot (it will auto-open positions when spreads are found)
wealth run

Understanding Position Logic

The bot opens positions automatically when:

1. Spread Check: funding_rate_high - funding_rate_low >= 0.0300% (configurable)
2. Balance Validation: Sufficient collateral with 20% safety buffer
3. Leverage Validation: Within exchange limits (1-125x Binance/Aster, 1-100x Bybit, 1-50x HyperLiquid)
4. Position Limits: Under max concurrent pairs (default: 3)

Example Calculation:

Given:
- Position size: $1,000
- Leverage: 10x
- Safety buffer: 20%

Required collateral = ($1,000 / 10) * 1.2 = $120 per exchange
Total required = $120 + $120 = $240

If available balance >= $240, position opens

Monitoring Active Positions

Check Current Positions

# View all open positions
wealth positions

# Output:
# ID    Symbol      Long Exchange  Short Exchange  Size       Entry Spread  Current Spread  Funding Collected  P&L      Age
# 1     BTCUSDT     binance       hyperliquid     0.1 BTC    0.0400%      0.0350%         $2.40             $12.50   2h 15m
# 2     ETHUSDT     bybit         binance         2.0 ETH    0.0380%      0.0420%         $1.80             $8.30    1h 45m

Real-Time Monitoring with OpenTelemetry

The bot exports metrics via OTLP to your observability backend. Check configuration:

# View OTLP configuration (JSON response)
curl -s localhost:9090/metrics | jq

# Output:
# {
#   "status": "operational",
#   "backend": "OpenTelemetry OTLP",
#   "endpoint": "http://localhost:4317",
#   "protocol": "gRPC"
# }

# Query actual metrics in Grafana or your OTLP-compatible backend:
# wealth_funding_rate{exchange="binance",symbol="BTCUSDT"}
# wealth_positions_active
# wealth_profit_loss_usd

Using Grafana (Optional)

# Start Grafana with docker-compose
docker-compose up -d grafana

# Access dashboard at http://localhost:3000
# Default credentials: admin/admin
# Pre-configured dashboard shows:
# - Active positions
# - Funding rate spreads
# - P&L over time
# - WebSocket health
# - API latency

Closing Positions

Automatic Closing (Normal Operation)

Positions close automatically when any condition is met:

1. Target Profit Reached: 5% profit (configurable via target_profit)
2. Spread Reversal: Spread drops below 50% of entry spread
3. Emergency: Critical errors or shutdown signal

Example Auto-Close:

2025-11-07T14:30:00Z INFO  Position #1 BTCUSDT reached target profit (5.2%)
2025-11-07T14:30:01Z INFO  Closing position atomically...
2025-11-07T14:30:02Z INFO  Close order placed: Binance (sell 0.1 BTC)
2025-11-07T14:30:03Z INFO  Close order placed: HyperLiquid (buy 0.1 BTC)
2025-11-07T14:30:04Z INFO  Position closed successfully. Final P&L: $52.40

Manual Emergency Close

# Close positions on specific exchange
wealth close --exchange binance --confirm

# Close positions for specific symbol
wealth close --symbol BTCUSDT --confirm

# Emergency close ALL positions (requires confirmation)
wealth close --all --confirm

# Graceful shutdown (closes all non-held positions cleanly)
# Press Ctrl+C once and wait (~6-8 seconds typical)
# Note: Held positions (marked with 🔒 in TUI) are preserved
^C
2025-11-07T14:35:00Z INFO  Shutdown signal received
2025-11-07T14:35:01Z INFO  Closing all positions gracefully...
2025-11-07T14:35:01Z INFO  Skipping held position ETHUSDT (will persist)
2025-11-07T14:35:05Z INFO  All non-held positions closed. Exiting.

Note: All close commands require --confirm flag for safety.

Verifying Position Closure

# Check positions after close
wealth positions

# Output should be empty:
# 📊 Current Positions
#
#   No active positions

# Check balances are back to normal
wealth balance

Alert Integration

Discord Notifications

Set up Discord alerts for important events:

# Set your Discord webhook URL
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# The bot will send notifications for:
# - Position opened/closed
# - Target profit reached
# - Errors or warnings

Slack Notifications

# Set your Slack webhook URL
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

Dynamic Pair Discovery Examples

Using Loris.tools Arbitrage Mode (Recommended)

The bot can automatically discover trading pairs using Loris.tools API, sorted by arbitrage opportunity:

# config.toml - Maximum arbitrage opportunities
[instrument_discovery]
enabled = true
use_loris_rankings = true         # Use Loris.tools API
loris_sort_by = "arbitrage"       # Sort by funding spread (default)
min_24h_volume_usd = 1_000_000    # $1M minimum liquidity
quote_asset = "USDT"
max_symbols = 20
min_exchanges = 2
exclude = ["BULL", "BEAR", "UP", "DOWN"]
refresh_interval_hours = 6        # Refresh pairs every 6 hours

# Run with discovery enabled
wealth run --enable-discovery

# Output shows arbitrage-sorted pairs:
# INFO Pair discovery using Loris rankings (sort: arbitrage)
# INFO Top arbitrage opportunities:
#   1. DOGE: spread=0.12% (Binance: -0.05%, Bybit: 0.07%)
#   2. SOL:  spread=0.08% (Binance: 0.01%, HyperLiquid: 0.09%)
#   3. BTC:  spread=0.04% (Binance: 0.01%, Bybit: 0.05%)

Using Loris.tools OI Rank Mode (Liquidity-Focused)

For conservative strategies prioritizing liquidity:

# config.toml - Most liquid pairs
[instrument_discovery]
enabled = true
use_loris_rankings = true
loris_sort_by = "oi_rank"         # Sort by open interest (liquidity)
min_24h_volume_usd = 1_000_000
quote_asset = "USDT"
max_symbols = 10                   # Fewer, more liquid pairs
min_exchanges = 2
exclude = ["BULL", "BEAR", "UP", "DOWN"]
refresh_interval_hours = 6         # Refresh pairs every 6 hours

# Output shows OI-sorted pairs:
# INFO Pair discovery using Loris rankings (sort: oi_rank)
# INFO Top pairs by liquidity:
#   1. BTC:  OI rank=1
#   2. ETH:  OI rank=2
#   3. SOL:  OI rank=5

Using Exchange Volume Data (Direct)

For maximum control without third-party APIs:

# config.toml - Direct exchange data
[instrument_discovery]
enabled = true
use_loris_rankings = false        # Use exchange APIs directly
min_24h_volume_usd = 5_000_000    # Higher threshold
quote_asset = "USDT"
max_symbols = 20
min_exchanges = 2
exchanges = ["binance_futures", "bybit_perpetuals_usd"]
refresh_interval_hours = 0        # No periodic refresh (runs at startup only)

Troubleshooting Common Issues

Issue: "Insufficient balance" error

Solution:

# Check current balance
wealth balance

# If balance is low, deposit more funds or reduce position size
# Edit config.toml:
[trading]
position_size_percentage = 0.1  # Reduce from 30% to 10%
max_position_usd = 5000.0       # Reduce cap

Issue: Position not opening despite good spread

Possible causes:

1. Balance too low

   # Check required collateral
   # For $1000 position at 10x leverage with 20% buffer:
   # Required = ($1000 / 10) * 1.2 = $120 per exchange
   

2. Leverage not initialized

   # Check logs for:
   grep "Initialized leverage" logs/wealth.log
   
   # If missing, verify config.toml has leverage section
   

3. Max concurrent positions reached

   # Check current count
   wealth positions | wc -l
   
   # Increase in config if needed:
   "max_concurrent_pairs": 5
   

Issue: WebSocket keeps disconnecting

Automatic Recovery (v0.54.0+):

The bot now includes automatic per-exchange health monitoring and restart:

• Health checks every 30 seconds using ping/pong heartbeats
• Only unhealthy exchanges are restarted (not all)
• 90-second threshold before considering a stream unhealthy
• 60-second grace period for newly restarted streams

Manual troubleshooting:

# Check network connectivity
curl -I https://fstream.binance.com
curl -I https://stream.bybit.com

# Enable detailed logging to see health check status
export RUST_LOG=wealth::market_data=debug
wealth run

# Look for these log patterns:
# "All WebSocket streams healthy" - system is working
# "Exchange binance unhealthy: No activity for 95s" - single exchange restart
# "Restarting single exchange stream" - per-exchange recovery in progress

Persistent disconnection issues:

1. Network instability: Check your connection quality
2. Exchange rate limiting: The bot uses exponential backoff; wait for recovery
3. Firewall/proxy: Ensure WebSocket connections (wss://) are allowed

Issue: Orders rejected by exchange

Common reasons:

1. Quantity too small

   # Binance minimum: 0.001 BTC
   # HyperLiquid minimum: 0.01 BTC (varies by symbol)
   
   # Increase position size or use different symbol
   

2. Insufficient margin

   # Check exchange-specific requirements:
   wealth verify --check-margin
   

3. Position mode not set (Binance)

   # Bot auto-initializes hedge mode, but if it fails:
   # Manually set in Binance UI: Futures > Preferences > Position Mode > Hedge Mode
   

Related Documentation

• Getting Started - Initial setup
• Configuration Guide - Detailed config options
• CLI Reference - All commands
• API Reference - Programmatic usage
• Troubleshooting - Detailed problem solving

Next Steps

1. Test in Paper Trading Mode: Run with WEALTH__EXECUTION__MODE=paper for 1-2 weeks
2. Monitor Metrics: Set up Grafana dashboard for visualization
3. Set Up Alerts: Configure Discord/Slack notifications for important events
4. Gradual Scaling: Start with small position sizes, increase gradually
5. Review Performance: Use wealth stats to analyze historical performance

Questions? See Troubleshooting or check the logs in logs/wealth.log.

Configuration Guide

Complete reference for configuration settings

Overview

The bot uses a unified configuration system with support for TOML configuration files and environment variables. All variables have sensible defaults and are validated on startup.

Configuration Loading Flow

flowchart TD
    subgraph Priority["Configuration Loading Priority"]
        direction TB
        ENV["🔴 Environment Variables<br/>WEALTH__SECTION__FIELD<br/>(Highest Priority)"]
        TOML["🟡 TOML/JSON Config File<br/>config.toml or config.json"]
        DEF["🟢 Default Values<br/>(Fallback)"]
    end
    
    ENV --> TOML --> DEF
    
    style ENV fill:#ffcdd2
    style TOML fill:#fff9c4
    style DEF fill:#c8e6c9

Configuration Structure

flowchart LR
    subgraph Config["AppConfig Structure"]
        direction TB
        APP[AppConfig]
        APP --> INST[instruments]
        APP --> DISC[instrument_discovery]
        APP --> LEV[leverage]
        APP --> TRADE[trading]
        APP --> RISK[risk]
        APP --> EXEC[execution]
        APP --> OBS[observability]
        APP --> LIC[licensing]
    end
    
    style APP fill:#e3f2fd
    style TRADE fill:#fff3e0
    style RISK fill:#ffcdd2

Current Version: The bot uses a simplified configuration structure with direct field access.

Configuration Files:

• config.toml - Main configuration file (instruments, leverage, trading params) - Preferred
• config.json - Legacy JSON format (still supported for backward compatibility)
• .env - Local environment configuration for sensitive values

Hot-Reload Support: The bot supports runtime configuration updates for safe parameters without requiring a restart. See Configuration Hot-Reload for details on which parameters can be hot-reloaded.

Configuration Architecture:

• AppConfig - Single unified configuration structure
• Direct field access: config.trading.*, config.risk.*, config.leverage.*
• Environment variables with WEALTH__ prefix override TOML/JSON settings

Loading Priority:

1. Environment variables with WEALTH__ prefix (highest priority)
2. TOML/JSON configuration file (config.toml or config.json)
3. Default values (fallback)

Configuration Sections

The configuration is organized into clear sections:

Environment Variable Overrides:

• All configuration can be overridden via environment variables
• Prefix pattern: WEALTH__SECTION__FIELD (e.g., WEALTH__TRADING__MIN_FUNDING_SPREAD)

Trading Configuration

WEALTH__TRADING__MIN_FUNDING_SPREAD

Minimum funding rate spread required to open a position.

• Type: Decimal (0.0-1.0)
• Default: 0.04 (0.04% = 4 bps)
• TOML Path: trading.min_funding_spread
• Example: WEALTH__TRADING__MIN_FUNDING_SPREAD=0.05

WEALTH__TRADING__MAX_POSITION_USD

Maximum position size cap in USD (safety limit).

• Type: Decimal
• Default: 10000 ($10,000)
• TOML Path: trading.max_position_usd
• Example: WEALTH__TRADING__MAX_POSITION_USD=20000

WEALTH__TRADING__POSITION_SIZE_PERCENT

Percentage of available balance to use per position.

• Type: Decimal (0.0 - 1.0)
• Default: 0.3 (30%)
• TOML Path: trading.position_size_percent
• Example: WEALTH__TRADING__POSITION_SIZE_PERCENT=0.25

WEALTH__TRADING__TARGET_PROFIT_PERCENT

Target profit percentage per position.

• Type: Decimal (0.0 - 1.0)
• Default: 0.05 (5%)
• TOML Path: trading.target_profit_percent
• Example: WEALTH__TRADING__TARGET_PROFIT_PERCENT=0.08

WEALTH__TRADING__MAX_POSITION_DURATION_HOURS

Maximum position duration in hours before forced exit. Prevents capital from being tied up indefinitely.

• Type: Integer
• Default: 168 (7 days)
• TOML Path: trading.max_position_duration_hours
• Example: WEALTH__TRADING__MAX_POSITION_DURATION_HOURS=336
• Note: Set to 0 to disable duration-based exits

WEALTH__TRADING__NARROW_SPREAD_EXIT_PERIODS

Number of consecutive narrow spread periods (8-hour intervals) before closing position.

• Type: Integer
• Default: 3 (24 hours of narrow spread)
• TOML Path: trading.narrow_spread_exit_periods
• Example: WEALTH__TRADING__NARROW_SPREAD_EXIT_PERIODS=2
• Note: Set to 0 for immediate spread narrowing exit

WEALTH__TRADING__MAX_CONCURRENT_POSITIONS

Maximum number of concurrent arbitrage pairs.

• Type: Integer
• Default: 5
• TOML Path: trading.max_concurrent_positions
• Example: WEALTH__TRADING__MAX_CONCURRENT_POSITIONS=3

WEALTH__TRADING__UPDATE_INTERVAL_SECS

Funding rate update interval in seconds.

• Type: Integer
• Default: 60
• TOML Path: trading.update_interval_secs
• Example: WEALTH__TRADING__UPDATE_INTERVAL_SECS=30

WEALTH__TRADING__MAX_HEDGE_ATTEMPTS

Maximum number of hedging attempts for partial fills.

• Type: Integer
• Default: 5
• TOML Path: trading.max_hedge_attempts
• Example: WEALTH__TRADING__MAX_HEDGE_ATTEMPTS=3
• Purpose: Prevents infinite hedging loops when orders partially fill

WEALTH__TRADING__HEDGE_TOLERANCE_PERCENT

Hedging tolerance as percentage (when to stop hedging).

• Type: Decimal (0.0-1.0)
• Default: 0.001 (0.1%)
• TOML Path: trading.hedge_tolerance_percent
• Example: WEALTH__TRADING__HEDGE_TOLERANCE_PERCENT=0.0005
• Purpose: Allows small quantity mismatches without additional hedging orders

WEALTH__TRADING__FALLBACK_PRICE_USD

Fallback price in USD used when real-time price data is unavailable.

• Type: Decimal
• Default: 100000 ($100,000)
• TOML Path: trading.fallback_price_usd
• Example: WEALTH__TRADING__FALLBACK_PRICE_USD=95000
• Purpose: Last-resort value for position sizing calculations when WebSocket price feeds fail
• Note: Set to approximately current BTC price for reasonable position sizing. An error is logged when fallback is used.

WEALTH__TRADING__SYMBOL_FALLBACK_PRICES

Per-symbol fallback prices when real-time data is unavailable.

• Type: Map<String, Decimal>
• Default: Empty (uses global fallback_price_usd)
• TOML Path: trading.symbol_fallback_prices
• Purpose: Provides accurate fallback prices for non-BTC symbols, improving position sizing accuracy

Example TOML Configuration:

[trading.symbol_fallback_prices]
BTCUSDT = 100000
ETHUSDT = 3500
SOLUSDT = 200
XRPUSDT = 2.5

Note: Symbol-specific fallback prices take precedence over the global fallback_price_usd. Only configure symbols you actively trade.

Note: Leverage is configured per-symbol in the [leverage] section, not as a global trading parameter.

Expected Value (EV) Gating

The bot uses expected value analysis to filter opportunities before execution. Only opportunities with positive risk-adjusted EV after costs are considered.

WEALTH__TRADING__MIN_EXPECTED_VALUE

Minimum expected value threshold (net profit after costs).

• Type: Decimal (0.0-1.0)
• Default: 0.05 (0.05% = 5 bps)
• TOML Path: trading.min_expected_value
• Example: WEALTH__TRADING__MIN_EXPECTED_VALUE=0.08
• Purpose: Filters out low-quality opportunities with insufficient edge
• Formula: EV = (time_weighted_spread × 3 funding payments) - (entry_fees + exit_fees + slippage)
• Note: Time weighting applies linear decay based on minutes until next funding payment

WEALTH__TRADING__STALENESS_PENALTY

Discount applied to EV calculation when data age exceeds staleness haircut threshold.

• Type: Decimal (0.0-1.0)
• Default: 0.03 (0.03% = 3 bps)
• TOML Path: trading.staleness_penalty
• Example: WEALTH__TRADING__STALENESS_PENALTY=0.05
• Purpose: Conservative adjustment for potential data lag
• When Applied: Reduces gross EV when funding rate data age exceeds staleness_haircut_threshold_secs (default: 120s)

WEALTH__TRADING__STALENESS_HAIRCUT_THRESHOLD_SECS

Data age threshold (in seconds) for applying staleness penalty.

• Type: Integer (seconds)
• Default: 120 (2 minutes)
• TOML Path: trading.staleness_haircut_threshold_secs
• Example: WEALTH__TRADING__STALENESS_HAIRCUT_THRESHOLD_SECS=180
• Purpose: Defines when funding rate data is considered "semi-stale" and warrants a penalty
• Note: Distinct from data rejection threshold - data older than 5 minutes is rejected entirely

Example EV Calculation:

Funding spread: 90 bps (0.0090)
Time to funding: 240 minutes (50% of 8h period)
Time weight: 0.5
Gross EV: 90 bps × 0.5 = 45 bps

Entry fees (both sides): 4 bps
Exit fees (both sides): 4 bps
Estimated slippage: 10 bps
Total costs: 18 bps

Adjusted EV: 45 - 18 = 27 bps
Passes threshold: 27 bps > 5 bps ✅

Kelly Position Sizing

The bot supports two position sizing modes: Kelly Criterion (dynamic, risk-adjusted) or Fixed Percentage (simple, predictable).

WEALTH__TRADING__USE_KELLY_CRITERION

Enable or disable Kelly Criterion for position sizing.

• Type: Boolean
• Default: true
• TOML Path: trading.use_kelly_criterion
• Example: WEALTH__TRADING__USE_KELLY_CRITERION=false
• When true: Uses Kelly Criterion formula for dynamic sizing based on EV and variance
• When false: Uses fixed percentage sizing: size = min(balance) × max_exchange_utilization × leverage
• Recommendation: true for optimal capital allocation, false for simpler, predictable sizing

WEALTH__TRADING__KELLY_FRACTION

Fraction of full Kelly size to use (0.0 - 1.0).

• Type: Decimal
• Default: 0.25 (quarter-Kelly for conservative sizing)
• TOML Path: trading.kelly_fraction
• Example: WEALTH__TRADING__KELLY_FRACTION=0.5
• Purpose: Reduces risk by using only a fraction of the mathematically optimal Kelly size
• Recommendation: Keep at 0.25 or lower for funding rate arbitrage

WEALTH__TRADING__MAX_NOTIONAL_PER_SYMBOL

Maximum notional value per symbol across all exchanges in USD.

• Type: Decimal
• Default: 10000 ($10,000)
• TOML Path: trading.max_notional_per_symbol
• Example: WEALTH__TRADING__MAX_NOTIONAL_PER_SYMBOL=20000
• Purpose: Hard cap on position size regardless of Kelly calculation
• Applied: Per symbol across all exchanges (e.g., total BTC exposure)

WEALTH__TRADING__MAX_EXCHANGE_UTILIZATION

Maximum percentage of free balance to use for a single position (0.0 - 1.0).

• Type: Decimal
• Default: 0.5 (50%)
• TOML Path: trading.max_exchange_utilization
• Example: WEALTH__TRADING__MAX_EXCHANGE_UTILIZATION=0.3
• Purpose: Prevents over-concentration on one exchange
• Reference Capital: Uses min(long_exchange_balance, short_exchange_balance) for sizing

Example Kelly Sizing:

EV: 30 bps per 8h (0.003)
Variance: 0.0001 (estimated spread volatility)
Kelly fraction: EV / variance = 0.003 / 0.0001 = 30
Reference capital: min($50,000, $80,000) = $50,000
Leverage: 10x
Full Kelly size: $50,000 × 30 × 10 = $15,000,000 (unrealistic)

Apply kelly_cap (0.25): $15,000,000 × 0.25 = $3,750,000
Apply max_notional cap: min($3,750,000, $10,000) = $10,000
Apply utilization cap: min($10,000, $50,000 × 0.5) = $10,000

Final position size: $10,000 (binding constraint: notional cap)

Leverage Configuration

Leverage multiplies your position size relative to margin. Higher leverage means higher potential returns AND higher risk of liquidation.

WEALTH__LEVERAGE__DEFAULT

Default leverage for all symbols.

• Type: Integer OR "max"
• Default: 3
• TOML Path: leverage.default
• Example: WEALTH__LEVERAGE__DEFAULT=10 or WEALTH__LEVERAGE__DEFAULT=max

Supported Values:

• Numbers: Fixed leverage (e.g., 3, 5, 10, 20)
• "max": Automatically use the maximum leverage allowed by each exchange

Per-Symbol Overrides

You can configure different leverage for specific symbols using the [leverage.overrides] section:

[leverage]
default = 10  # Default 10x for most symbols

[leverage.overrides]
BTCUSDT = 5       # Lower leverage for BTC (less volatile)
ETHUSDT = 8       # Medium leverage for ETH
SOLUSDT = "max"   # Use max allowed for SOL

Symmetric Leverage for Hedged Positions

When trading hedged positions across exchanges, the bot automatically ensures consistent leverage:

1. If config is a fixed number: Uses that value (clamped to exchange max if needed)
2. If config is "max": Uses min(max_exchange_A, max_exchange_B)

Example:

• Config: SOLUSDT = "max"
• Binance max for SOL: 75x
• HyperLiquid max for SOL: 50x
• Result: Bot uses 50x on both exchanges

This ensures the hedge ratio remains balanced regardless of differing exchange limits.

Max Leverage Caching

When using "max" leverage:

• Max leverage is fetched from exchange APIs on startup
• Results are cached to avoid API rate limits
• Cache is refreshed when bot restarts

Exchange API Sources:

• Binance: /fapi/v1/leverageBracket (uses first tier max)
• Bybit: /v5/market/instruments-info (leverageFilter.maxLeverage)
• HyperLiquid: /info meta endpoint (universe[].maxLeverage)
• Aster: Binance-compatible API

Recommended Settings

Note: Higher leverage increases both potential gains and liquidation risk. The bot does NOT automatically manage position size based on leverage—that's controlled by position_size_percent and max_position_usd.

Slippage Protection Configuration

WEALTH__RISK__MAX_SLIPPAGE_BPS

Maximum allowed slippage in basis points.

• Type: Integer
• Default: 50 (0.5%)
• TOML Path: risk.max_slippage_bps
• Example: WEALTH__RISK__MAX_SLIPPAGE_BPS=30

WEALTH__RISK__MIN_SLIPPAGE_BPS

Minimum slippage buffer in basis points (always applied).

• Type: Integer
• Default: 10 (0.1%)
• TOML Path: risk.min_slippage_bps
• Example: WEALTH__RISK__MIN_SLIPPAGE_BPS=5

WEALTH__RISK__MARKET_ORDER_FALLBACK_ENABLED

Whether to fall back to MARKET orders if LIMIT order doesn't fill.

• Type: Boolean
• Default: true
• TOML Path: risk.market_order_fallback_enabled
• Values: true | false
• Example: WEALTH__RISK__MARKET_ORDER_FALLBACK_ENABLED=false

WEALTH__RISK__LIMIT_ORDER_TIMEOUT_SECS

Timeout before falling back to MARKET order (seconds).

• Type: Integer
• Default: 5
• TOML Path: risk.limit_order_timeout_secs
• Example: WEALTH__RISK__LIMIT_ORDER_TIMEOUT_SECS=10

WEALTH__RISK__SLIPPAGE_VOLATILITY_MULTIPLIER

Multiplier to increase slippage tolerance in volatile markets.

• Type: Float
• Default: 1.5 (50% wider)
• TOML Path: risk.slippage_volatility_multiplier
• Example: WEALTH__RISK__SLIPPAGE_VOLATILITY_MULTIPLIER=2.0

Post-Only (Maker) Order Configuration

Post-only orders ensure you always pay maker fees instead of taker fees, significantly reducing execution costs.

WEALTH__RISK__USE_POST_ONLY

Enable post-only (maker) order execution.

• Type: Boolean
• Default: false
• TOML Path: risk.use_post_only
• Values: true | false
• Example: WEALTH__RISK__USE_POST_ONLY=true

Exchange-Specific Order Types:

WEALTH__RISK__LIMIT_PRICE_OFFSET_BPS

Price offset from market for post-only orders (basis points).

• Type: Integer
• Default: 10 (0.10%)
• TOML Path: risk.limit_price_offset_bps
• Example: WEALTH__RISK__LIMIT_PRICE_OFFSET_BPS=15

How it works:

• Buy orders: Place at market_price × (1 - offset_bps/10000)
• Sell orders: Place at market_price × (1 + offset_bps/10000)

WEALTH__RISK__POST_ONLY_RETRY_COUNT

Number of retry attempts when post-only order is rejected.

• Type: Integer
• Default: 3
• TOML Path: risk.post_only_retry_count
• Example: WEALTH__RISK__POST_ONLY_RETRY_COUNT=5

Retry Logic:

1. Post-only order placed at calculated price
2. If rejected (would cross spread), price adjusted deeper into book
3. Repeat up to post_only_retry_count times
4. If all retries fail and market_order_fallback_enabled=true, fall back to market order

Fee Savings Example:

Trailing Stop Configuration

Note: Trailing stop configuration is defined in config.toml or via environment variables below.

WEALTH__RISK__TRAILING_STOPS_ENABLED

Enable trailing stop loss functionality.

• Type: Boolean
• Default: true
• TOML Path: risk.trailing_stops_enabled
• Values: true | false
• Example: WEALTH__RISK__TRAILING_STOPS_ENABLED=true

WEALTH__RISK__TRAILING_STOP_ACTIVATION

Profit threshold to activate trailing stop (as decimal percentage).

• Type: Decimal (0.0-1.0)
• Default: 0.03 (3%)
• TOML Path: risk.trailing_stop_activation
• Example: WEALTH__RISK__TRAILING_STOP_ACTIVATION=0.05

WEALTH__RISK__TRAILING_STOP_DISTANCE

Maximum allowed profit retracement before exit (as decimal percentage).

• Type: Decimal (0.0-1.0)
• Default: 0.40 (40% from peak)
• TOML Path: risk.trailing_stop_distance
• Example: WEALTH__RISK__TRAILING_STOP_DISTANCE=0.3

WEALTH__RISK__TRAILING_STOP_MIN_LOCK

Minimum profit to lock in (prevents exit below this level).

• Type: Decimal (0.0-1.0)
• Default: 0.02 (2%)
• TOML Path: risk.trailing_stop_min_lock
• Example: WEALTH__RISK__TRAILING_STOP_MIN_LOCK=0.015

WEALTH__RISK__SLIPPAGE_AWARE_EXITS

Consider estimated slippage cost in exit decisions. When enabled, positions with remaining potential profit less than expected closing costs may be held for one more funding period.

• Type: Boolean
• Default: true
• TOML Path: risk.slippage_aware_exits
• Example: WEALTH__RISK__SLIPPAGE_AWARE_EXITS=false

Fee Configuration

WEALTH__RISK__FEES__ESTIMATED_SLIPPAGE

Estimated slippage for market orders (as decimal).

• Type: Decimal (0.0-1.0)
• Default: 0.001 (0.1%)
• TOML Path: risk.fees.estimated_slippage
• Example: WEALTH__RISK__FEES__ESTIMATED_SLIPPAGE=0.002

Exchange Fee Overrides

Override default exchange fee rates in config.toml under [risk.fees.<exchange>]:

Binance

[risk.fees.binance]
maker = 0.0002  # 0.02% - Maker fee
taker = 0.0004  # 0.04% - Taker fee
funding_interval_hours = 8

Bybit

[risk.fees.bybit]
maker = 0.0001  # 0.01% - Maker fee
taker = 0.0006  # 0.06% - Taker fee
funding_interval_hours = 8

HyperLiquid

[risk.fees.hyperliquid]
maker = 0.0000   # 0.00% - Maker rebate
taker = 0.00035  # 0.035% - Taker fee
funding_interval_hours = 1  # HyperLiquid uses hourly funding (24x daily)

Note: HyperLiquid processes funding every hour, unlike most CEXes which use 8-hour intervals. This affects EV calculations and provides more frequent profit collection opportunities.

Aster

[risk.fees.aster]
maker = 0.0002   # 0.02% - Maker fee
taker = 0.0005   # 0.05% - Taker fee
funding_interval_hours = 4  # Aster uses 4h or 8h per-symbol (fetched dynamically)

Note: Aster funding intervals vary by symbol (4h or 8h). The bot automatically fetches per-symbol intervals via the API and caches them. The config value is a fallback only.

Instrument Discovery Configuration

Dynamic pair discovery settings for automatic symbol detection (v0.30+). These settings control how the bot discovers and manages trading pairs from external sources like Loris.tools.

WEALTH__INSTRUMENT_DISCOVERY__USE_LORIS_RANKINGS

Enable Loris.tools-based pair discovery for top funding rate opportunities.

• Type: Boolean
• Default: false
• TOML Path: instrument_discovery.use_loris_rankings
• Example: WEALTH__INSTRUMENT_DISCOVERY__USE_LORIS_RANKINGS=true
• Prerequisite: Requires enabled = true or --discover CLI flag

WEALTH__INSTRUMENT_DISCOVERY__REFRESH_INTERVAL_HOURS

Periodic refresh interval for Loris.tools pair discovery (hours, 0 = disabled).

• Type: Integer (hours)
• Default: 0 (disabled - discovery runs only at startup)
• TOML Path: instrument_discovery.refresh_interval_hours
• Example: WEALTH__INSTRUMENT_DISCOVERY__REFRESH_INTERVAL_HOURS=6
• Prerequisite: Requires use_loris_rankings = true and discovery enabled

Behavior:

• When > 0: Periodically queries Loris.tools API to discover new high-opportunity pairs
• Add-only strategy: New pairs are added automatically; pairs with active positions are never removed
• Jitter protection: Random 0-30 minute delay added to prevent synchronized API requests across multiple bot instances
• WebSocket integration: Automatically registers new pairs with price and funding rate streams

When to Enable:

Note: The instrument list may grow over time with add-only logic. Use hot-reload config changes to manually prune symbols if needed.

WEALTH__INSTRUMENT_DISCOVERY__MAX_SYMBOLS

Maximum number of symbols to discover from Loris.tools rankings.

• Type: Integer
• Default: 20
• TOML Path: instrument_discovery.max_symbols
• Example: WEALTH__INSTRUMENT_DISCOVERY__MAX_SYMBOLS=30

WEALTH__INSTRUMENT_DISCOVERY__ENABLED

Enable dynamic pair discovery (requires both config and CLI flag for safety).

• Type: Boolean
• Default: false
• TOML Path: instrument_discovery.enabled
• Example: WEALTH__INSTRUMENT_DISCOVERY__ENABLED=true

When enabled, the bot discovers trading pairs automatically instead of using static [[instruments]] configuration. Requires double opt-in: set enabled = true in config AND use --enable-discovery CLI flag.

WEALTH__INSTRUMENT_DISCOVERY__EXCHANGES

Exchanges to use for pair discovery. If empty, all exchanges with credentials are used.

• Type: Array of strings
• Default: [] (all available exchanges)
• TOML Path: instrument_discovery.exchanges
• Example: WEALTH__INSTRUMENT_DISCOVERY__EXCHANGES=binance_futures,hyper_liquid

Options: binance_futures, bybit_perpetuals_usd, hyper_liquid

WEALTH__INSTRUMENT_DISCOVERY__MIN_24H_VOLUME_USD

Minimum 24-hour trading volume in USD for discovered pairs.

• Type: Integer (USD)
• Default: 1000000 ($1M)
• TOML Path: instrument_discovery.min_24h_volume_usd
• Example: WEALTH__INSTRUMENT_DISCOVERY__MIN_24H_VOLUME_USD=5000000

Higher values select more liquid pairs with lower slippage. Recommended range: $1M-$10M depending on position sizes.

WEALTH__INSTRUMENT_DISCOVERY__QUOTE_ASSET

Quote asset filter for discovered pairs.

• Type: String
• Default: USDT
• TOML Path: instrument_discovery.quote_asset
• Example: WEALTH__INSTRUMENT_DISCOVERY__QUOTE_ASSET=USDC

Options: USDT, USDC, BUSD

WEALTH__INSTRUMENT_DISCOVERY__EXCLUDE

Symbols to exclude from discovery (substring matching, case-sensitive).

• Type: Array of strings
• Default: ["BULL", "BEAR", "UP", "DOWN", "HEDGE", "DEFI"]
• TOML Path: instrument_discovery.exclude
• Example: WEALTH__INSTRUMENT_DISCOVERY__EXCLUDE=BULL,BEAR,SHIB

Use to manually block leveraged tokens, sector baskets, or specific pairs. Example: "BULL" matches "BULLISH", "BULLUSDT", "ETHBULL".

WEALTH__INSTRUMENT_DISCOVERY__MIN_EXCHANGES

Minimum number of exchanges that must support a symbol for it to be discovered.

• Type: Integer
• Default: 2
• TOML Path: instrument_discovery.min_exchanges
• Example: WEALTH__INSTRUMENT_DISCOVERY__MIN_EXCHANGES=3

Ensures arbitrage is possible (need at least 2 exchanges). Set higher to only trade pairs available on 3+ exchanges.

WEALTH__INSTRUMENT_DISCOVERY__LORIS_SORT_BY

Sorting strategy when using Loris.tools API for discovery.

• Type: String
• Default: arbitrage
• TOML Path: instrument_discovery.loris_sort_by
• Example: WEALTH__INSTRUMENT_DISCOVERY__LORIS_SORT_BY=oi_rank

Options:

• arbitrage - Sort by funding rate spread (highest arbitrage opportunity first)
• oi_rank - Sort by Binance open interest ranking (most liquid first)

Only applies when use_loris_rankings = true.

WEALTH__INSTRUMENT_DISCOVERY__FORCE_REMOVE_PAIRS

Force removal of pairs during hot-reload even if they have pending orders.

• Type: Boolean
• Default: false
• TOML Path: instrument_discovery.force_remove_pairs
• Example: WEALTH__INSTRUMENT_DISCOVERY__FORCE_REMOVE_PAIRS=true

Behavior:

• When true: Auto-cancels all pending orders for removed symbols
• When false: Blocks removal if symbol has pending orders or active positions

⚠️ Use with caution - may result in unhedged positions if orders are cancelled mid-execution.

Example Configuration

[instrument_discovery]
enabled = true
use_loris_rankings = true
loris_sort_by = "arbitrage"
refresh_interval_hours = 6
max_symbols = 20
min_24h_volume_usd = 1000000
quote_asset = "USDT"
min_exchanges = 2
exclude = ["BULL", "BEAR", "UP", "DOWN", "HEDGE", "DEFI"]
force_remove_pairs = false
# exchanges = ["binance_futures", "hyper_liquid"]  # Optional: limit to specific exchanges

Metrics Server Configuration

WEALTH__OBSERVABILITY__METRICS_PORT

Port for metrics and health check server.

• Type: Integer
• Default: 9090
• TOML Path: observability.metrics_port
• Example: WEALTH__OBSERVABILITY__METRICS_PORT=8080

WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS

Bind address for metrics server.

• Type: String (IP address)
• Default: 0.0.0.0 (all interfaces)
• TOML Path: observability.metrics_bind_address
• Example: WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS=127.0.0.1

Execution Mode

WEALTH__EXECUTION__MODE

Execution mode for order placement.

• Type: String ("paper" | "live" | "dryrun")
• Default: paper
• TOML Path: execution.mode
• Example: WEALTH__EXECUTION__MODE=live

Modes:

• paper - Simulated trading with mock order fills
• live - Real trading with actual exchange orders
• dryrun - Logs order intent but doesn't execute (useful for testing strategy logic)

Note: The old PAPER_TRADING and DRY_RUN boolean flags have been replaced with WEALTH__EXECUTION__MODE in v0.33.0 for clearer semantics.

Exchange Credentials

Credential Loading Strategy

The bot automatically tries to load credentials in the following order:

1. Encrypted Credentials File (if CREDENTIALS_PASSPHRASE is set)

   • Uses credentials.encrypted.json and .credentials.salt
   • Most secure, recommended for production
   • Managed via wealth credentials CLI commands

2. Environment Variables (fallback)

   • Exchange-specific variables documented below
   • Simpler for development and testing

No configuration needed - the bot seamlessly uses whichever method you set up.

Setup Option 1: Encrypted Credentials (Recommended)

Initial Setup:

# 1. Set passphrase in .env
echo "CREDENTIALS_PASSPHRASE=your-secure-passphrase" >> .env

# 2. Create encrypted credentials file
wealth credentials create

# 3. Add exchange credentials (interactive mode - recommended)
wealth credentials add binance
# Or with flags (less secure - visible in shell history)
wealth credentials add binance --api-key YOUR_API_KEY --secret-key YOUR_SECRET_KEY
wealth credentials add bybit --api-key YOUR_API_KEY --secret-key YOUR_SECRET_KEY
wealth credentials add hyperliquid --api-key 0xWALLET_ADDRESS --secret-key 0xPRIVATE_KEY

# 4. Verify
wealth verify --encrypted

Advantages:

• AES-256-GCM encryption
• Credentials never stored in plaintext
• Secure key derivation from passphrase (PBKDF2 with 100,000 iterations)
• Isolated from source code and version control

Security:

• Never commit credentials.encrypted.json or .credentials.salt to version control
• Use a strong passphrase (12+ characters, mix of types)
• Store passphrase securely (password manager, secrets vault)

CREDENTIALS_PASSPHRASE

Passphrase for encrypting/decrypting the credentials file.

• Type: String
• Default: None (not set)
• Example: CREDENTIALS_PASSPHRASE=my-super-secure-passphrase-2024
• Required for: Encrypted credentials (Option 1)
• Not needed for: Direct environment variables (Option 2)

When set: Bot loads credentials from credentials.encrypted.json
When not set: Bot will fail to start (encrypted credentials are required since v0.21.0)

Note: Direct exchange credential environment variables (e.g., BINANCE_API_KEY) were deprecated in v0.21.0 and have been removed. Use encrypted credentials for all deployments. See Security Guide for setup instructions.

Resilience Configuration

WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_FAILURES

Number of failures before circuit breaker opens.

• Type: Integer
• Default: 5
• TOML Path: execution.resilience.circuit_breaker_failures
• Example: WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_FAILURES=10

WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_TIMEOUT_SECS

Time to wait before testing recovery.

• Type: Integer
• Default: 60
• TOML Path: execution.resilience.circuit_breaker_timeout_secs
• Example: WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_TIMEOUT_SECS=120

WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_SUCCESS_THRESHOLD

Number of successful calls needed to close circuit breaker.

• Type: Integer
• Default: 2
• TOML Path: execution.resilience.circuit_breaker_success_threshold
• Example: WEALTH__EXECUTION__RESILIENCE__CIRCUIT_BREAKER_SUCCESS_THRESHOLD=3

WEALTH__EXECUTION__RESILIENCE__MAX_RETRIES

Maximum retry attempts for API calls.

• Type: Integer
• Default: 3
• TOML Path: execution.resilience.max_retries
• Example: WEALTH__EXECUTION__RESILIENCE__MAX_RETRIES=5

WEALTH__EXECUTION__RESILIENCE__RETRY_INITIAL_BACKOFF_MS

Initial retry backoff in milliseconds.

• Type: Integer
• Default: 100
• TOML Path: execution.resilience.retry_initial_backoff_ms
• Example: WEALTH__EXECUTION__RESILIENCE__RETRY_INITIAL_BACKOFF_MS=200

WEALTH__EXECUTION__RESILIENCE__RETRY_MAX_BACKOFF_SECS

Maximum retry backoff in seconds.

• Type: Integer
• Default: 10
• TOML Path: execution.resilience.retry_max_backoff_secs
• Example: WEALTH__EXECUTION__RESILIENCE__RETRY_MAX_BACKOFF_SECS=30

WEALTH__EXECUTION__RESILIENCE__WEBSOCKET_MAX_RECONNECTS

Maximum WebSocket reconnection attempts.

• Type: Integer
• Default: 100
• TOML Path: execution.resilience.websocket_max_reconnects
• Example: WEALTH__EXECUTION__RESILIENCE__WEBSOCKET_MAX_RECONNECTS=50

Position Reconciliation Configuration

Position reconciliation is a background task that monitors for unhedged positions and can automatically fix them. This is recommended for live trading to catch issues like partial fills that weren't properly hedged.

The reconciliation task monitors two types of positions:

1. Tracked positions - Positions opened by the bot and tracked by the AtomicOrderExecutor
2. Orphan positions - Positions found on exchanges but NOT tracked by the bot (requires explicit opt-in)

WEALTH__EXECUTION__RECONCILIATION__ENABLED

Enable background position reconciliation task.

• Type: Boolean
• Default: false
• TOML Path: execution.reconciliation.enabled
• Example: WEALTH__EXECUTION__RECONCILIATION__ENABLED=true

Note: Reconciliation only runs in live trading mode. Paper trading doesn't have real positions to reconcile.

WEALTH__EXECUTION__RECONCILIATION__CHECK_INTERVAL_SECS

Interval between reconciliation checks in seconds.

• Type: Integer
• Default: 30
• TOML Path: execution.reconciliation.check_interval_secs
• Example: WEALTH__EXECUTION__RECONCILIATION__CHECK_INTERVAL_SECS=60

Lower values detect issues faster but use more CPU. Typical range: 15-60 seconds.

WEALTH__EXECUTION__RECONCILIATION__AUTO_FIX_ENABLED

Enable automatic fixing of unhedged positions tracked by the bot.

• Type: Boolean
• Default: true
• TOML Path: execution.reconciliation.auto_fix_enabled
• Example: WEALTH__EXECUTION__RECONCILIATION__AUTO_FIX_ENABLED=false

When enabled, unhedged positions that are tracked by the AtomicOrderExecutor are automatically closed via emergency close. When disabled, only alerts are triggered and manual intervention is required.

WEALTH__EXECUTION__RECONCILIATION__AUTO_CLOSE_ORPHANS

Enable automatic closing of orphan positions not tracked by the bot.

• Type: Boolean
• Default: false
• TOML Path: execution.reconciliation.auto_close_orphans
• Example: WEALTH__EXECUTION__RECONCILIATION__AUTO_CLOSE_ORPHANS=true

⚠️ CAUTION: When enabled, the reconciliation task will automatically close ANY unhedged position found on exchanges that is NOT being tracked by the bot. This includes positions:

• Created manually outside the bot
• Left over from a previous bot session that crashed
• Opened by other trading systems on the same account

Only enable this if you exclusively use this bot for trading on the configured exchanges. When disabled (default), orphan positions trigger critical alerts but require manual intervention.

WEALTH__EXECUTION__RECONCILIATION__STUCK_EXECUTION_THRESHOLD_SECS

Threshold for stuck execution alerts in seconds.

• Type: Integer
• Default: 60
• TOML Path: execution.reconciliation.stuck_execution_threshold_secs
• Example: WEALTH__EXECUTION__RECONCILIATION__STUCK_EXECUTION_THRESHOLD_SECS=60

Alert when an execution has been running longer than this threshold. Reduced from 300s to 60s for faster detection of stuck executions that could lead to liquidation. Typical range: 30-120 seconds.

WEALTH__EXECUTION__RECONCILIATION__EMERGENCY_CLOSE_FAILURE_THRESHOLD

Maximum consecutive emergency close failures before auto-shutdown.

• Type: Integer
• Default: 3
• TOML Path: execution.reconciliation.emergency_close_failure_threshold
• Example: WEALTH__EXECUTION__RECONCILIATION__EMERGENCY_CLOSE_FAILURE_THRESHOLD=3

When this threshold is reached, the bot will automatically initiate a graceful shutdown to prevent further losses from unhedged positions. This is a critical safety feature to prevent liquidation during cascading failures. Set to 0 to disable auto-shutdown (not recommended).

WEALTH__EXECUTION__RECONCILIATION__HYPERLIQUID_CLOSE_SLIPPAGE

Slippage percentage for HyperLiquid force close operations.

• Type: Float (0.0 - 1.0)
• Default: 0.05 (5%)
• TOML Path: execution.reconciliation.hyperliquid_close_slippage
• Example: WEALTH__EXECUTION__RECONCILIATION__HYPERLIQUID_CLOSE_SLIPPAGE=0.05

This slippage setting is used in two scenarios:

1. Orphan Position Closing: When closing orphan positions on HyperLiquid during reconciliation
2. Atomic Executor Fallback: When reduce_only close orders return zero fill but positions still exist (v0.52+)

Higher values increase the chance of fill but may result in worse execution prices. The default 5% is recommended for reliable closes.

Note: This uses HyperLiquid's SDK market_close function which fetches the current position state directly from the exchange before closing, making it more reliable than standard reduce_only orders.

Pair Health Configuration

The pair health system monitors trading pair health to detect degraded or broken data feeds. Unhealthy pairs can be automatically disabled to prevent bad trades.

WEALTH__PAIR_HEALTH__ENABLED

Enable automatic health monitoring for trading pairs.

• Type: Boolean
• Default: true
• TOML Path: pair_health.enabled
• Example: WEALTH__PAIR_HEALTH__ENABLED=false

When enabled, the system tracks WebSocket disconnections, API errors, and data staleness for each trading pair.

WEALTH__PAIR_HEALTH__MAX_WS_DISCONNECTIONS

Maximum consecutive WebSocket disconnections before marking pair unhealthy.

• Type: Integer
• Default: 5
• TOML Path: pair_health.max_ws_disconnections
• Example: WEALTH__PAIR_HEALTH__MAX_WS_DISCONNECTIONS=10

WEALTH__PAIR_HEALTH__MAX_API_ERRORS

Maximum consecutive API errors before marking pair unhealthy.

• Type: Integer
• Default: 10
• TOML Path: pair_health.max_api_errors
• Example: WEALTH__PAIR_HEALTH__MAX_API_ERRORS=15

WEALTH__PAIR_HEALTH__MAX_FUNDING_RATE_STALENESS_SECS

Maximum age of funding rate data in seconds before considered stale.

• Type: Integer
• Default: 300 (5 minutes)
• TOML Path: pair_health.max_funding_rate_staleness_secs
• Example: WEALTH__PAIR_HEALTH__MAX_FUNDING_RATE_STALENESS_SECS=600

Funding rate data older than this threshold is excluded from opportunity detection. This prevents trading on outdated market data.

WEALTH__PAIR_HEALTH__MAX_PRICE_STALENESS_SECS

Maximum age of price data in seconds before considered stale.

• Type: Integer
• Default: 60 (1 minute)
• TOML Path: pair_health.max_price_staleness_secs
• Example: WEALTH__PAIR_HEALTH__MAX_PRICE_STALENESS_SECS=120

WEALTH__PAIR_HEALTH__AUTO_DISABLE_UNHEALTHY

Automatically disable pairs that become unhealthy.

• Type: Boolean
• Default: false
• TOML Path: pair_health.auto_disable_unhealthy
• Example: WEALTH__PAIR_HEALTH__AUTO_DISABLE_UNHEALTHY=true

When true, pairs are auto-disabled when health thresholds are exceeded. When false (default), pairs stay enabled but show unhealthy status in TUI.

WEALTH__PAIR_HEALTH__AUTO_REENABLE_HEALTHY

Automatically re-enable pairs after they become healthy again.

• Type: Boolean
• Default: true
• TOML Path: pair_health.auto_reenable_healthy
• Example: WEALTH__PAIR_HEALTH__AUTO_REENABLE_HEALTHY=false

WEALTH__PAIR_HEALTH__HEALTHY_CHECKS_FOR_REENABLE

Number of consecutive healthy checks before re-enabling auto-disabled pair.

• Type: Integer
• Default: 3
• TOML Path: pair_health.healthy_checks_for_reenable
• Example: WEALTH__PAIR_HEALTH__HEALTHY_CHECKS_FOR_REENABLE=5

WEALTH__PAIR_HEALTH__CHECK_INTERVAL_SECS

Health check interval in seconds.

• Type: Integer
• Default: 30
• TOML Path: pair_health.check_interval_secs
• Example: WEALTH__PAIR_HEALTH__CHECK_INTERVAL_SECS=60

Example Configuration:

[pair_health]
enabled = true
max_ws_disconnections = 5
max_api_errors = 10
max_funding_rate_staleness_secs = 300
max_price_staleness_secs = 60
auto_disable_unhealthy = false
auto_reenable_healthy = true
healthy_checks_for_reenable = 3
check_interval_secs = 30

Observability Configuration

WEALTH__OBSERVABILITY__METRICS_PORT

Port number for the metrics/API server.

• Type: u16
• Default: 9090
• TOML Path: observability.metrics_port
• Example: WEALTH__OBSERVABILITY__METRICS_PORT=9090

The metrics server exposes:

• /metrics - OpenTelemetry metrics info (JSON)
• /health, /ready, /live - Health check endpoints
• /api/positions, /api/funding_rates, /api/balances - HTTP API for querying bot state
• /api/arbitrage_positions - Cached arbitrage positions with funding collected (fast, no API quota)

WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS

IP address for the metrics/API server to bind to.

• Type: IP Address
• Default: 0.0.0.0 (all network interfaces)
• TOML Path: observability.metrics_bind_address
• Example: WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS=127.0.0.1

Set to 127.0.0.1 for localhost-only access (recommended for production with external proxy).

WEALTH__OBSERVABILITY__OTLP_ENDPOINT

OpenTelemetry Protocol (OTLP) endpoint URL for exporting traces, metrics, and logs.

• Type: String (URL)
• Default: None (OTLP export disabled, local logging only)
• TOML Path: observability.otlp_endpoint
• Example: WEALTH__OBSERVABILITY__OTLP_ENDPOINT=http://localhost:4317

When set, the bot will export all telemetry (traces, metrics, logs) to an OpenTelemetry Collector or compatible backend (Tempo, Jaeger, etc.) via gRPC. This replaces the previous Loki push logging with a unified observability pipeline.

URL Validation:

• Must start with http:// or https://
• Default port for OTLP gRPC is 4317
• Supports authentication via standard OTLP headers (configure in collector)

Resource Attributes: You can add custom resource attributes via the OTEL_RESOURCE_ATTRIBUTES environment variable:

export OTEL_RESOURCE_ATTRIBUTES="service.name=wealth-bot,deployment.environment=production,service.version=0.16.0"

WEALTH__OBSERVABILITY__SERVICE_NAME

Service name for telemetry resource attributes.

• Type: String
• Default: wealth
• TOML Path: observability.service_name
• Example: WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-prod

Used as the service.name resource attribute in OpenTelemetry spans, metrics, and logs. Useful when running multiple bot instances.

WEALTH__OBSERVABILITY__ENVIRONMENT

Environment name for telemetry resource attributes (e.g., production, development, staging).

• Type: String
• Default: development
• TOML Path: observability.environment
• Example: WEALTH__OBSERVABILITY__ENVIRONMENT=production

Used as a custom resource attribute for environment-based filtering in observability backends.

WEALTH__OBSERVABILITY__ENABLE_TRACES

Enable distributed tracing via OTLP.

• Type: Boolean
• Default: true
• TOML Path: observability.enable_traces
• Example: WEALTH__OBSERVABILITY__ENABLE_TRACES=false

When enabled alongside otlp_endpoint, exports trace spans to the OTLP endpoint for distributed tracing visualization in Tempo, Jaeger, or similar backends.

WEALTH__OBSERVABILITY__TRACE_SAMPLE_RATE

Trace sampling rate (0.0 = never sample, 1.0 = always sample).

• Type: Decimal (0.0 - 1.0)
• Default: 1.0 (100% of traces)
• TOML Path: observability.trace_sample_rate
• Example: WEALTH__OBSERVABILITY__TRACE_SAMPLE_RATE=0.1

Lower values reduce observability costs in high-throughput scenarios. Recommended: 1.0 for development, 0.1-0.01 for high-volume production.

WEALTH__OBSERVABILITY__LOG_FILE

Path to log file for file-based logging.

• Type: String (file path)
• Default: None (logs to stdout only)
• TOML Path: observability.log_file
• Example: WEALTH__OBSERVABILITY__LOG_FILE=/var/log/wealth.log

When set, logs are written to both stdout and the specified file. Useful for debugging without disrupting OTLP telemetry.

Configuration Methods:

1. Environment Variables:

   export WEALTH__OBSERVABILITY__OTLP_ENDPOINT=http://localhost:4317
   export WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-prod
   export WEALTH__OBSERVABILITY__ENVIRONMENT=production
   

2. TOML Config:

   [observability]
   otlp_endpoint = "http://localhost:4317"
   service_name = "wealth-prod"
   environment = "production"
   

3. JSON Config (Legacy):

   {
     "observability": {
       "otlp_endpoint": "http://localhost:4317",
       "service_name": "wealth-prod",
       "environment": "production"
     }
   }
   

Configuration Precedence: Environment variables > TOML config > JSON config (legacy) > Defaults

See Logging Guide for complete OpenTelemetry setup instructions.

Configuration Examples

Development (Paper Trading)

# Trading
WEALTH__TRADING__MIN_FUNDING_SPREAD=0.04
WEALTH__TRADING__MAX_POSITION_USD=10000
WEALTH__TRADING__POSITION_SIZE_PERCENT=0.3
WEALTH__TRADING__TARGET_PROFIT_PERCENT=0.05

# Execution
WEALTH__EXECUTION__MODE=paper

# Observability
RUST_LOG=info
# Optional: Enable OTLP export for development
WEALTH__OBSERVABILITY__OTLP_ENDPOINT=http://localhost:4317
WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-dev
WEALTH__OBSERVABILITY__ENVIRONMENT=development

Production (Live Trading)

# Trading
WEALTH__TRADING__MIN_FUNDING_SPREAD=0.04
WEALTH__TRADING__MAX_POSITION_USD=50000
WEALTH__TRADING__POSITION_SIZE_PERCENT=0.25
WEALTH__TRADING__TARGET_PROFIT_PERCENT=0.05

# Execution
WEALTH__EXECUTION__MODE=live

# Exchange Credentials (use encrypted credentials file instead)
CREDENTIALS_PASSPHRASE="your-secure-passphrase"

# Observability
RUST_LOG=info
WEALTH__OBSERVABILITY__OTLP_ENDPOINT=https://otlp.example.com:4317
WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-prod
WEALTH__OBSERVABILITY__ENVIRONMENT=production

Testing Configuration

# Execution
WEALTH__EXECUTION__MODE=paper

# Conservative settings
WEALTH__TRADING__MAX_POSITION_USD=100
WEALTH__TRADING__POSITION_SIZE_PERCENT=0.1

# Verbose logging
RUST_LOG=debug

Configuration Validation

All configuration is validated on startup with fail-fast behavior.

Validation Process:

• Type validation during JSON parsing (serde)
• Cross-field validation after loading
• Clear error messages indicating which rule failed

Validated Constraints:

• All numeric thresholds must be positive
• Percentages must be between 0 and 1
• Port numbers must be non-zero
• At least one instrument must be configured
• Retry counts and timeouts must be valid

Example Error:

ERROR Configuration validation failed: Metrics port must be non-zero
ERROR Configuration validation failed: At least one instrument must be configured

Debugging Configuration

Use the config show --show-sources command to see where each configuration value comes from:

$ wealth config show --show-sources

📋 Configuration Sources

Shows: default → file (config.toml) → env vars → ✓ final value

🎯 Trading Configuration:
  min_funding_spread:
    default:  0.0004
    file:     0.0005
    env:      0.0006
    ✓ final:  0.0006 ← using environment override

  max_position_usd:
    default:  10000
    ✓ final:  10000 ← using default

This helps identify configuration issues and understand which values are active.

Environment Variable Precedence

Configuration loading happens in this order:

1. Environment variables with WEALTH__ prefix (highest priority) - Override all other settings
2. TOML/JSON configuration file (config.toml or config.json) - Provides structured config
3. Default values (lowest priority) - Built-in sensible defaults

Example: If you set WEALTH__TRADING__MIN_FUNDING_SPREAD=0.001 in .env and min_funding_spread = 0.04 in config.toml, the environment variable takes precedence.

Best Practices:

• Use config.toml for static configuration (instruments, leverage, strategy parameters)
• Use environment variables with WEALTH__ prefix for deployment-specific settings
• Use encrypted credentials file for API keys (safer than environment variables)
• Use .env file for local development overrides

Using with Different Tools

Systemd

[Service]
Environment="WEALTH__EXECUTION__MODE=live"
Environment="CREDENTIALS_PASSPHRASE=your-passphrase"

Docker

docker run -e WEALTH__EXECUTION__MODE=live \
  -e CREDENTIALS_PASSPHRASE=xxx \
  -v $(pwd)/config.toml:/app/config.toml \
  wealth

Docker Compose

environment:
  - WEALTH__EXECUTION__MODE=live
  - CREDENTIALS_PASSPHRASE=${CREDENTIALS_PASSPHRASE}
volumes:
  - ./config.toml:/app/config.toml:ro
  - ./credentials.encrypted.json:/app/credentials.encrypted.json:ro

Kubernetes

env:
- name: WEALTH__EXECUTION__MODE
  value: "live"
- name: CREDENTIALS_PASSPHRASE
  valueFrom:
    secretKeyRef:
      name: wealth-secrets
      key: credentials-passphrase
volumeMounts:
- name: config
  mountPath: /app/config.toml
  subPath: config.toml

Configuration Debugging

Config Show Sources Command

Display where each configuration value comes from (default → file → env):

wealth config --show-sources

Example Output:

📋 Configuration Sources

Shows: default → file (config.toml) → env vars → ✓ final value

🎯 Trading Configuration:
  min_funding_spread:
    default:  0.0004
    env:      0.0008
    ✓ final:  0.0008 ← using environment override
    
  max_position_usd:
    default:  10000
    file:     15000
    ✓ final:  15000 ← from config file

Use cases:

• Debug which source is being used for each config value
• Verify environment variable overrides are working
• Identify misconfigured values before running the bot

Validation Error Messages

Configuration errors now include source tracking (v0.33.0+):

File-based error:

Error: Invalid value for leverage.default: Must be greater than 0 
(from config file: config.toml)

Environment variable error:

Error: Invalid value for trading.min_funding_spread: Cannot be negative
(from environment variable: WEALTH__TRADING__MIN_FUNDING_SPREAD)

Default value error:

Error: Invalid value for risk.max_slippage_bps: must be positive
(using default value)

Benefits:

• Quickly identify where the problematic value is configured
• Avoid checking multiple configuration sources manually
• Clear distinction between file errors and env var errors

Config Validation

Validate configuration without starting the bot:

wealth config --validate

Output:

🔍 Validating configuration...

  ✓ Loading config.toml
  ✓ TOML parsing successful
  ✓ Environment variable parsing successful
  ✓ Validating configuration... OK

✅ Configuration is valid!
   Instruments: 6
   Metrics Port: 9090
   Execution Mode: Paper

Common validation errors:

• Negative values (spreads, slippage, leverage)
• Out-of-range percentages (must be 0.0-1.0)
• Invalid exchange names (must be: binance, bybit, hyperliquid, aster)
• Missing required instruments

See Also

• CLI Reference - Command-line options
• Security Guide - Encrypted credentials
• Getting Started - Installation and setup

CLI Reference

Complete command-line interface reference for the Wealth Trading Bot

Overview

The wealth trading bot features a comprehensive command-line interface (CLI) built with clap. The CLI provides subcommands for all major operations, making it easy to manage the bot from the terminal.

Exchange Names

When specifying exchanges in CLI commands, use lowercase names:

Global Options

Available on all commands:

-v                         # Info-level logging
-vv                        # Debug-level logging
-vvv                       # Trace-level logging (very verbose)
-q, --quiet                # Error-level only (warnings suppressed)
-l, --log-file <FILE>      # Path to log file (default: stdout)
-c, --config <FILE>        # Path to custom configuration file
-h, --help                 # Show help information
-V, --version              # Show version information

Environment Variables:

WEALTH__OBSERVABILITY__LOG_FILE   # Default log file path
WEALTH_CONFIG                      # Default configuration file path

Commands

wealth run - Run the Trading Bot

Start the trading bot. All configuration is managed via config.toml or environment variables.

Usage:

wealth run [OPTIONS]

Options:

--enable-discovery     # Enable dynamic pair discovery (overrides config)

Note: The run command is required. Running wealth without a command displays help.

Configuration:

All runtime settings are configured via:

• Config file: config.toml (persistent settings)
• Environment variables: WEALTH__* prefix (see Configuration Guide)

Common Configuration Examples:

# Paper trading mode (via environment variable)
export WEALTH__EXECUTION__MODE=paper
wealth run

# Live trading mode (via environment variable)
export WEALTH__EXECUTION__MODE=live
wealth run

# Custom metrics port
export WEALTH__OBSERVABILITY__METRICS_PORT=8080
wealth run

# OpenTelemetry export
export WEALTH__OBSERVABILITY__OTLP_ENDPOINT=http://localhost:4317
export WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-prod
export WEALTH__OBSERVABILITY__ENVIRONMENT=production
wealth run

Examples:

# Run with default settings from config.toml
wealth run

# Show help
wealth

# Log to file
wealth run --log-file /tmp/wealth.log

# Verbose logging with file output
wealth run -v --log-file /var/log/wealth.log

# Very verbose (debug level)
export WEALTH__OBSERVABILITY__SERVICE_NAME=wealth-prod
export WEALTH__OBSERVABILITY__ENVIRONMENT=production
wealth run -vv

Environment Variables:

• WEALTH__EXECUTION__MODE - Execution mode: "paper", "live", or "dryrun" (default: paper)
• WEALTH__OBSERVABILITY__METRICS_PORT - Metrics port (default: 9090)
• WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS - Bind address (default: 0.0.0.0)
• WEALTH__OBSERVABILITY__OTLP_ENDPOINT - OpenTelemetry OTLP endpoint URL (e.g., http://localhost:4317)
• WEALTH__OBSERVABILITY__SERVICE_NAME - Service name for telemetry resource attributes (default: wealth)
• WEALTH__OBSERVABILITY__ENVIRONMENT - Environment name for telemetry resource attributes (default: development)

Note: All configuration can also be set in config.toml. See Configuration Guide for details.

wealth dashboard - Interactive TUI Dashboard

🖥️ Status: Fully implemented (requires tui feature)

Run the trading bot with an interactive terminal dashboard for real-time monitoring and control.

Usage:

wealth dashboard [OPTIONS]

Options:

--enable-discovery     # Enable dynamic pair discovery
--tick-rate <MS>       # UI refresh rate in milliseconds (default: 250)

Examples:

# Run with TUI dashboard (default settings)
wealth dashboard

# Enable dynamic pair discovery
wealth dashboard --enable-discovery

# Slower refresh rate (for remote connections)
wealth dashboard --tick-rate 500

📖 See TUI Dashboard Guide for full documentation including keybindings, tabs, and troubleshooting.

wealth verify - Verify Configuration

✅ Status: Fully implemented

Verify that configuration files and credentials are valid, with optional API validation.

Usage:

wealth verify [OPTIONS]

Options:

--check-credentials    # Make test API calls to verify credentials work
--encrypted            # Verify encrypted credential decryption

Examples:

# Basic verification
wealth verify

# Verify with real API calls (recommended)
wealth verify --check-credentials

# Verify encrypted credentials (will prompt for passphrase if not set)
wealth verify --encrypted --check-credentials
# 🔐 Enter credentials passphrase: ********

# Or set env var to skip prompt
export CREDENTIALS_PASSPHRASE="your_passphrase"
wealth verify --encrypted --check-credentials

Output Format:

🔍 Configuration Verification

✅ Configuration file loaded successfully
✅ Strategy parameters validated
✅ Instruments configured: 3

🔐 Credential Verification:
  ✅ BinanceFutures: Valid (API call successful)
  ✅ BybitPerpetualsUsd: Valid (API call successful)
  ✅ HyperLiquid: Valid (API call successful)

All checks passed!

wealth config - Display Configuration

Show current configuration settings.

Usage:

wealth config [OPTIONS]

Options:

--strategy       # Show only strategy configuration
--execution      # Show only execution configuration
--credentials    # Show credential status (redacted)
--validate       # Validate configuration file
--show-sources   # Show configuration sources (defaults, file, env vars)

Examples:

# Show all configuration
wealth config

# Validate configuration
wealth config --validate

# Debug configuration with source tracking
wealth config --show-sources

Sample Output (with --show-sources):

📋 Configuration Sources

Shows: default → file (config.toml) → env vars → ✓ final value

🎯 Trading Configuration:
  min_funding_spread:
    default:  0.0004
    file:     0.0005
    env:      0.0006
    ✓ final:  0.0006 ← using environment override

  max_position_usd:
    default:  10000
    ✓ final:  10000 ← using default

wealth license - Check License Status

✅ Status: Fully implemented

Check license status, validate connectivity, and show machine fingerprint for support.

Subcommands

check - Check License Status

wealth license check

Displays:

• License configuration (account, product)
• Machine fingerprint
• License validity status
• Expiration information (if available)

Example Output:

📋 License Information:
   Account:     fcaa9cfa-8236-4270-81b6-da3ddd238d70
   Product:     6f04c081-10d2-4222-8310-b314d82ac410
   Machine ID:  a1b2c3d4-e5f6-7890-abcd-ef1234567890

✅ License is valid!

show-fingerprint - Show Machine Fingerprint

wealth license show-fingerprint

Displays your machine's unique identifier. Use this when:

• Contacting support about licensing issues
• Requesting additional machine activations
• Troubleshooting activation problems

Example Output:

📌 Machine ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

This unique identifier is used to activate your license on this machine.
Share this ID with support when requesting license assistance.

License Status: ✅ Configured
Account: fcaa9cfa-8236-4270-81b6-da3ddd238d70

validate - Validate License Connectivity

wealth license validate

Performs comprehensive license validation:

• Tests connection to Keygen API
• Validates license configuration
• Checks machine activation status
• Provides detailed error messages with troubleshooting guidance

Example Output (Success):

🔍 Configuration:
   Account:  fcaa9cfa-8236-4270-81b6-da3ddd238d70
   Product:  6f04c081-10d2-4222-8310-b314d82ac410
   API URL:  https://api.keygen.sh

🖥️  Machine ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

📡 Connecting to Keygen API...
✅ License validation successful!

Your license is active and this machine is properly configured.

Example Output (Error with Guidance):

❌ License validation failed: Network error contacting license server

💡 Network Issue:
   - Check internet connectivity
   - Verify firewall allows HTTPS to api.keygen.sh
   - Check proxy configuration if applicable

Environment Variables:

• WEALTH__LICENSING__LICENSE_KEY - Your license key (required)
• WEALTH__LICENSING__API_URL - Custom Keygen API URL (optional, debug builds only)

deactivate - Deactivate License from Current Machine

wealth license deactivate --confirm

Deactivates your license from the current machine, allowing you to transfer it to another machine.

Use Cases:

• Migrating to a new server
• Replacing hardware
• Switching between development and production machines
• Freeing up a machine activation slot

Safety Features:

• Requires --confirm flag to prevent accidental deactivation
• Shows warning and confirmation prompt without flag
• Verifies license status before deactivation
• Provides clear next steps after deactivation

Example Usage:

# Show warning and instructions (safe dry-run)
wealth license deactivate

# Actually deactivate (requires confirmation)
wealth license deactivate --confirm

Example Output (Dry-Run):

⚠️  License Deactivation

This will deactivate your license from this machine.
You can reactivate it on another machine by running the bot there.

To confirm, run:
  wealth license deactivate --confirm

Example Output (Successful Deactivation):

📋 Deactivation Details:
  Account:     fcaa9cfa-8236-4270-81b6-da3ddd238d70
  Product:     6f04c081-10d2-4222-8310-b314d82ac410
  Machine ID:  a1b2c3d4-e5f6-7890-abcd-ef1234567890

🔍 Finding machine activation...
✅ License found: lic_1234567890

✅ License deactivated successfully!

📦 Your license is now available for activation on another machine.
  To activate on a new machine:
  1. Copy your license key to the new machine
  2. Set WEALTH__LICENSING__LICENSE_KEY environment variable
  3. Run: wealth run
  (The license will activate automatically)

Example Output (Already Deactivated):

ℹ️  License is not currently activated on this machine.

No action needed - you can activate on another machine anytime.

Error Handling:

• Invalid license key → Clear error message
• Network issues → Troubleshooting guidance
• Already deactivated → Informational message
• License not found → Verification steps

Environment Variables:

• WEALTH__LICENSING__LICENSE_KEY - Your license key (required)

Notes:

• Deactivation is immediate and cannot be undone
• After deactivation, simply run the bot on a new machine to reactivate
• No limit on number of deactivations/reactivations
• Your license key remains valid after deactivation

Related Documentation:

• Licensing Guide - Complete licensing documentation
• Troubleshooting - Common licensing issues

wealth credentials - Manage Encrypted Credentials

Manage encrypted credential storage.

Subcommands

create - Create New Encrypted Config

wealth credentials create

Creates .credentials.salt and credentials.encrypted.json files.

add - Add Exchange Credentials

wealth credentials add <EXCHANGE> [OPTIONS]

Arguments:

• <EXCHANGE> - Exchange name (binance, bybit, hyperliquid, aster)

Options:

• --api-key <KEY> - API key (or master wallet/vault address for HyperLiquid)
• --secret-key <KEY> - Secret key (or API wallet private key for HyperLiquid)
• --testnet - Use testnet mode
• --vault-mode - HyperLiquid only: Enable vault mode (API_KEY is vault address)

Security Recommendation:

For maximum security, omit the --api-key and --secret-key options to use interactive prompts. This prevents secrets from appearing in shell history.

# Recommended: Interactive mode (secrets not in shell history)
wealth credentials add binance
# Prompts for:
#   Enter API key: <your-api-key>
#   Enter secret key (hidden): <your-secret-key>

# Less secure: CLI arguments (visible in shell history)
wealth credentials add binance --api-key YOUR_API_KEY --secret-key YOUR_SECRET_KEY

HyperLiquid Examples:

# Direct wallet mode (simplest) - interactive
wealth credentials add hyperliquid
# API key: 0xYourWalletAddress
# Secret key: 0xYourPrivateKey

# API wallet (subkey) mode (recommended) - interactive
wealth credentials add hyperliquid
# API key: 0xYourMasterWalletAddress
# Secret key: 0xAPIWalletPrivateKey

# Vault mode - interactive
wealth credentials add hyperliquid --vault-mode
# API key: 0xVaultAddress
# Secret key: 0xAPIWalletPrivateKey

verify - Verify Encrypted Credentials

wealth credentials verify
# 🔐 Enter credentials passphrase: ********

You'll be prompted for the passphrase interactively, or set CREDENTIALS_PASSPHRASE environment variable to skip the prompt.

list - List Configured Exchanges

wealth credentials list

remove - Remove Credentials

wealth credentials remove <EXCHANGE> --confirm

Safety: Requires --confirm flag.

wealth health - System Health Checks

✅ Status: Fully implemented

Check system health including exchange connectivity, WebSocket connections, and data freshness.

Usage:

wealth health [OPTIONS]

Options:

--exchanges     # Check exchange API connectivity (validates credentials)
--websockets    # Check WebSocket connectivity
--all           # Run all health checks

Examples:

# Check all health indicators
wealth health --all

# Check only exchange connectivity
wealth health --exchanges

# Check only WebSocket connections
wealth health --websockets

Output Format:

🏥 Health Check

📡 Exchange API Connectivity:
  🟡 BinanceFutures ... ✅ OK (142ms)
  🟠 BybitPerpetualsUsd ... ✅ OK (98ms)
  🔵 HyperLiquid ... ✅ OK (76ms)

  Summary: 3/3 exchanges accessible

🔌 WebSocket Connectivity:
  ⚠️  WebSocket health checks require running bot instance
  💡 Tip: Use 'curl http://localhost:9090/ready' while bot is running

✅ Health check complete

wealth balance - Display Account Balances

✅ Status: Fully implemented

Usage:

wealth balance [OPTIONS]

Options:

--exchange <NAME>    # Filter by exchange (binance, bybit, hyperliquid, aster)
--total              # Show total USD equivalent balance
--detailed           # Show detailed asset breakdown with total and free balances

Examples:

# View all balances
wealth balance

# View specific exchange
wealth balance --exchange binance

# Show total USD equivalent
wealth balance --total

# Detailed breakdown
wealth balance --detailed

Output Format:

💰 Account Balances

📈 BinanceFutures
  USDT: 5000.00

📈 BybitPerpetualsUsd  
  USDT: 3000.00

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💵 Total Available (USDT equivalent): $8000.00

wealth positions - Display Current Positions

✅ Status: Fully implemented

Display current open positions across exchanges with funding rates and projected PnL. Automatically uses the bot's HTTP API when running for fast access to in-memory state.

Usage:

wealth positions [OPTIONS]

Options:

--exchange <NAME>    # Filter by exchange (binance, bybit, hyperliquid, aster)
--pnl                # Show P&L summary for all positions
--funding            # Show detailed funding rate breakdown

Smart Data Fetching:

• Bot running: Uses /api/positions and /api/funding_rates (fast, no API quota)
• Bot not running: Queries exchanges directly (slower, uses API quota)
• API port is configurable (default: 9090, set via WEALTH__OBSERVABILITY__METRICS_PORT)

Examples:

# View all positions (uses API if bot running)
wealth positions

# View positions on specific exchange
wealth positions --exchange binance

# Show detailed funding breakdown
wealth positions --funding

# Show with P&L summary
wealth positions --pnl

# Combine funding and P&L
wealth positions --funding --pnl

Output Format:

Positions table now includes funding rate information by default:

📊 Current Positions

  🔗 Using live data from running bot instance

# OR (if bot not running):

📊 Current Positions

  📡 Querying exchanges directly (bot not running or API unavailable)

╭──────────┬──────────┬───────┬────────┬─────────────┬────────────┬────────────────┬──────────────┬──────────╮
│ Exchange │ Symbol   │ Side  │ Size   │ Entry Price │ Mark Price │ Unrealized PnL │ Funding Rate │ Est. 8h  │
├──────────┼──────────┼───────┼────────┼─────────────┼────────────┼────────────────┼──────────────┼──────────┤
│ binance  │ BTCUSDT  │ LONG  │ 0.1000 │ $95000.00   │ $96000.00  │ $100.00        │ 0.0100%      │ -9.50    │
│ bybit    │ BTCUSDT  │ SHORT │ 0.1000 │ $95200.00   │ $96000.00  │ -$80.00        │ 0.0150%      │ +14.28   │
╰──────────┴──────────┴───────┴────────┴─────────────┴────────────┴────────────────┴──────────────┴──────────╯

Columns:

• Exchange: Exchange name
• Symbol: Trading pair
• Side: LONG or SHORT
• Size: Position size in base asset
• Entry Price: Average entry price
• Mark Price: Current mark price
• Unrealized PnL: Unrealized profit/loss
• Funding Rate: Current funding rate percentage
• Est. 8h: Estimated funding payment in next 8h (+ = receive, - = pay)

With --funding flag:

Additional detailed summary section:

📈 Summary:
  Total Long Notional:  $9600.00
  Total Short Notional: $9600.00
  Net Exposure:         $0.00

💰 Funding Rate PnL (Projected):
  binance BTCUSDT LONG: 0.0100% → -$9.50 USD (next 8h)
  bybit BTCUSDT SHORT: 0.0150% → +$14.28 USD (next 8h)

  Projected Next 8h:    +$4.78 USD
  Est. Daily Projected: +$14.34 USD (3 payments/day)

💹 Funding Collected (Actual):
  BTCUSDT (binance ↔ hyperliquid): +$15.50 (held 2d 5h)
  ETHUSDT (bybit ↔ binance): +$8.25 (held 1d 12h)

  Total Funding Collected: +$23.75

Funding PnL Details:

• Projected: Estimated funding payment for next 8h period based on current rates
• Actual (Collected): Real funding fees collected from active arbitrage positions (requires bot to be running)
• Long positions pay funding when rate is positive (negative PnL)
• Short positions receive funding when rate is positive (positive PnL)
• Funding collected is tracked by the bot's FundingTracker background task

Note:

• Position data fetched from bot's API or directly from exchange APIs
• Funding rates always displayed in table for immediate visibility
• Use --funding flag for detailed breakdown and projections

wealth funding - Display Funding Rates

✅ Status: Fully implemented

Display current funding rates, spreads, and calculate funding PnL for active positions.

Usage:

wealth funding [OPTIONS]

Options:

--symbol <SYMBOL>    # Filter by specific symbol (e.g., BTCUSDT)
--spreads            # Show funding rate spreads between exchanges
--pnl                # Show PnL from funding rates for current positions
--history            # Show historical funding rates (not yet implemented)

Note: The --history flag is reserved for future implementation of historical funding rate analysis.

Examples:

# View all funding rates
wealth funding

# View funding rate for specific symbol
wealth funding --symbol BTCUSDT

# Show spreads between exchanges
wealth funding --spreads

# Show funding rate PnL for current positions
wealth funding --pnl

# Combine spreads and PnL
wealth funding --spreads --pnl

Output Format:

📈 Funding Rates

┌─────────────┬───────────────┬────────────┬──────────────────────┐
│ Symbol      │ Exchange      │ Rate       │ Next Funding         │
├─────────────┼───────────────┼────────────┼──────────────────────┤
│ BTCUSDT     │ Binance       │    0.0100% │ in 5h 23m            │
│ BTCUSDT     │ Bybit         │    0.0500% │ in 5h 23m            │
│             │ Spread: 0.0400% (Bybit - Binance)                  │
└─────────────┴───────────────┴────────────┴──────────────────────┘

💰 Funding Rate PnL:
  Binance BTCUSDT LONG (0.5000 @ $95000.00): 0.0100% → -$4.75 USD (8h)
  Bybit BTCUSDT SHORT (0.5000 @ $95000.00): 0.0500% → +$23.75 USD (8h)

  Net 8h Funding:       +$19.00 USD
  Est. Daily Funding:   +$57.00 USD (3 payments/day)
  Est. Monthly Funding: +$1710.00 USD (30 days)

PnL Calculation:

• Long positions: Pay funding when rate is positive (cost), receive when negative (income)
• Short positions: Receive funding when rate is positive (income), pay when negative (cost)
• Formula: funding_payment = notional_value × funding_rate / 100
• Notional value: position_size × entry_price

Note: The --pnl flag fetches both funding rates and current positions from all configured exchanges to calculate expected funding payments.

wealth close - Close Positions

✅ Status: Fully implemented

Close open positions on exchanges with reduce-only market orders.

Usage:

wealth close [OPTIONS] --confirm

Options:

--exchange <NAME>    # Close positions on specific exchange (binance, bybit, hyperliquid, aster)
--symbol <SYMBOL>    # Close positions for specific symbol (e.g., BTCUSDT)
--all                # Close all positions (if --symbol not specified)
--confirm            # Required confirmation flag (safety)

Examples:

# Close all positions on Binance
wealth close --exchange binance --all --confirm

# Close specific symbol on all exchanges
wealth close --symbol BTCUSDT --all --confirm

# Close all positions on all exchanges
wealth close --all --confirm

# Close specific symbol on specific exchange
wealth close --exchange bybit --symbol ETHUSDT --confirm

Output Format:

🔴 Closing Positions

📊 Checking BinanceFutures positions...
  Found 2 position(s) to close:
    BTCUSDT Long 0.1 @ 35000.00 (PnL: $125.50)
      ✅ Closed (Order ID: 12345678)
    ETHUSDT Short 2.0 @ 2000.00 (PnL: $45.20)
      ✅ Closed (Order ID: 12345679)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Successfully closed: 2

Safety Features:

• Requires --confirm flag for all operations
• Uses reduce-only market orders (never increases position)
• Skips dust positions automatically
• Detailed error reporting per position

Note: This command fetches current positions from exchanges and closes them immediately. For graceful shutdown with automatic position closing, use Ctrl+C instead.

wealth stats - Trading Statistics

✅ Status: Fully implemented

Display trading performance statistics from the in-memory performance history repository.

Usage:

wealth stats [OPTIONS]

Options:

--period <PERIOD>    # Time period: 1h, 24h, 7d, 30d, 90d, all (default: 24h)
--detailed           # Show detailed breakdown with recent trades

Examples:

# View last 24 hours (default)
wealth stats

# View last 7 days
wealth stats --period 7d

# View all-time with details
wealth stats --period all --detailed

Output Format:

📊 Trading Statistics

  📅 Period: Last 7 Days (2025-11-07 10:00 - 2025-11-14 10:00)

  📈 Performance Summary:
     Total Trades: 42
     Winning Trades: 35 (83%)
     Losing Trades: 7
     Total P&L: $1,234.56
     Avg Win: $52.30
     Avg Loss: -$12.45
     Sharpe Ratio: 2.15

  � Recent Trades: (with --detailed)
     1. ✅ BTCUSDT → 2025-11-14 09:45 | $65.23 | WIN
     2. ✅ ETHUSDT → 2025-11-14 08:30 | $42.10 | WIN
     ...

Note: Data is collected while the bot is running from the InMemoryPerformanceHistoryRepository. Not persisted between restarts.

Important: Data Availability

The stats command displays data from an in-memory performance history repository. This has important implications:

• Data is not persisted: Trade statistics are stored in memory and reset when the bot restarts
• CLI creates new instance: Each CLI command creates a fresh, empty repository instance
• Bot must be running: To see meaningful data, the bot must be actively running and have executed trades
• Consider external monitoring: For persistent statistics, use the Prometheus metrics endpoint with Grafana or similar tools

If you see "No trading history found", this is expected behavior – it means:

1. The bot hasn't executed any trades in the specified period, OR
2. The bot was restarted (clearing in-memory history), OR
3. You're running the CLI while the bot is stopped

wealth profit - Total Profit Tracking

✅ Status: Fully implemented

Display cumulative profit/loss tracking with realized and unrealized PnL.

Usage:

wealth profit [OPTIONS]

Options:

--period <PERIOD>         # Time period: 1h, 24h, 7d, 30d, 90d, all (default: all)
--by-exchange             # Show breakdown by exchange
--by-symbol               # Show breakdown by symbol
--include-unrealized      # Include unrealized PnL from open positions

Examples:

# View all-time profit (default)
wealth profit

# View last 7 days with exchange breakdown
wealth profit --period 7d --by-exchange

# View total profit including unrealized PnL
wealth profit --include-unrealized

# Detailed view with all breakdowns
wealth profit --by-exchange --by-symbol --include-unrealized

Output Format:

💰 Profit Tracking

  📅 Period: All Time (1970-01-01 00:00 - 2025-11-28 12:00)

  📊 Realized Profit/Loss (Closed Positions):
     Total Trades: 156
     Total Realized PnL: $2847.92

  📈 Breakdown by Exchange: (with --by-exchange)
     binance (LONG): +$1523.45
     hyperliquid (SHORT): +$1324.47
     ...

  📈 Breakdown by Symbol: (with --by-symbol)
     BTCUSDT: +$1245.30
     ETHUSDT: +$892.15
     SOLUSDT: +$710.47

  💹 Funding Rate Profit/Loss (Active Positions):
     Active Arbitrage Pairs: 3
     Total Funding Collected: +$156.78

     Per-Position Breakdown: (with --by-symbol)
       BTCUSDT (binance ↔ hyperliquid): +$85.50
       ETHUSDT (bybit ↔ binance): +$45.28
       SOLUSDT (binance ↔ hyperliquid): +$26.00

  📊 Unrealized Profit/Loss (Open Positions): (with --include-unrealized)
     Open Positions: 4
     Total Unrealized PnL: $123.45
       binance BTCUSDT LONG: +$45.20
       hyperliquid BTCUSDT SHORT: +$78.25

  💵 Total Profit/Loss:
     Realized PnL:       $2847.92
     Funding Collected:  $156.78
     Unrealized PnL:     $123.45
     ─────────────────────────────
     Total PnL:          +$3128.15

Notes:

• Realized PnL comes from InMemoryPerformanceHistoryRepository (closed trades)
• Funding Collected shows actual funding fees received from active arbitrage positions (requires bot to be running)
• Important: The CLI creates a new repository instance, so it will show zero trades unless the bot is configured with persistent storage that the CLI can access
• Unrealized PnL requires bot to be running (fetched via API)
• Data is collected during bot runtime and not persisted between restarts
• Use --include-unrealized to see current position PnL
• Exchange breakdown splits PnL equally (50/50) between long and short legs of arbitrage pairs

Data Availability Summary:

For persistent profit tracking across restarts, consider:

• Using Grafana dashboards with Prometheus metrics (recommended)
• Implementing external trade logging

wealth completions - Generate Shell Completions

✅ Status: Fully implemented

Usage:

wealth completions <SHELL>

Supported Shells: bash, zsh, fish, powershell, elvish

Installation Examples:

Bash:

wealth completions bash > ~/.local/share/bash-completion/completions/wealth
# OR
echo 'source <(wealth completions bash)' >> ~/.bashrc

Zsh:

mkdir -p ~/.zfunc
wealth completions zsh > ~/.zfunc/_wealth
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

Fish:

wealth completions fish > ~/.config/fish/completions/wealth.fish

wealth init - Initialize Configuration

✅ Status: Fully implemented

Generate a new configuration file from the embedded example template. This is the recommended way to create your initial config.toml.

Usage:

wealth init [OPTIONS]

Options:

-o, --output <FILE>    # Output path (default: config.toml)
--force                # Overwrite existing file without prompting

Examples:

# Create config.toml in current directory
wealth init

# Create with custom filename
wealth init -o config.production.toml

# Create in subdirectory (creates parent dirs if needed)
wealth init -o configs/my-config.toml

# Overwrite existing config
wealth init --force

Output:

✓ Created configuration file: config.toml

Next steps:
  1. Edit config.toml to configure your trading parameters
  2. Set up credentials: wealth credentials create
  3. Verify setup: wealth verify --check-credentials
  4. Start trading: wealth run

Notes:

• The example configuration is embedded in the binary at compile time
• Creates parent directories automatically if they don't exist
• Fails safely if file exists (use --force to overwrite)
• Generated config includes all available options with documentation comments

Configuration

Custom Config Files

# Use custom configuration file
wealth run --config config.production.json

Environment Variables

All CLI options can be set via environment variables:

export WEALTH__EXECUTION__MODE=live
export WEALTH__OBSERVABILITY__METRICS_PORT=8080
wealth run

Logging Levels

# Default: INFO level
wealth run

# Debug level
wealth run --verbose

# Trace level
wealth run --trace

# Via environment
export RUST_LOG=debug
wealth run

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Configuration error
• 130 - Interrupted by Ctrl+C (graceful shutdown)

See Also

• HTTP API Reference - REST API for automation and scripting
• Configuration Guide - Environment variables and settings
• Security Guide - Encrypted credentials management
• Getting Started - Installation and first run

HTTP API Reference

REST API for querying bot state and automating workflows

Overview

The Wealth trading bot exposes an HTTP API alongside the metrics server for querying live bot state. This enables:

• Automation scripts to monitor positions and balances
• Custom dashboards to display real-time data
• Alert integrations with external monitoring systems
• Programmatic position management workflows

Base URL

http://localhost:9090

The port is configurable via WEALTH__OBSERVABILITY__METRICS_PORT (default: 9090).

Data Freshness

Endpoints

GET /api/positions

Fetches current open positions directly from exchanges. This endpoint queries each configured exchange in parallel.

⚠️ Note: This endpoint consumes exchange API quota. Use /api/arbitrage_positions for cached data without API impact.

Request:

curl http://localhost:9090/api/positions

Response:

{
  "positions": [
    {
      "exchange": "BinanceFutures",
      "position": {
        "symbol": "BTCUSDT",
        "side": "Long",
        "quantity": "0.1",
        "entry_price": "95000",
        "mark_price": "96000",
        "unrealized_pnl": "100",
        "leverage": "10",
        "liquidation_price": "86000"
      }
    },
    {
      "exchange": "Bybit",
      "position": {
        "symbol": "BTCUSDT",
        "side": "Short",
        "quantity": "0.1",
        "entry_price": "95100",
        "mark_price": "96000",
        "unrealized_pnl": "-90",
        "leverage": "10",
        "liquidation_price": "104500"
      }
    }
  ],
  "timestamp": "2024-12-27T10:30:00Z"
}

Response Fields:

Error Handling:

The endpoint returns partial results if some exchanges fail. Only returns an error if all exchanges fail:

{
  "error": "Failed to fetch positions from all exchanges"
}

Check logs for details on individual exchange failures.

GET /api/funding_rates

Returns cached funding rates from the in-memory repository. Fast and does not consume API quota.

Request:

curl http://localhost:9090/api/funding_rates

Response:

{
  "rates": [
    {
      "exchange": "BinanceFutures",
      "symbol": "BTCUSDT",
      "rate": "0.0001",
      "next_funding_time": "2024-12-27T16:00:00Z",
      "last_updated": "2024-12-27T10:25:00Z"
    },
    {
      "exchange": "Bybit",
      "symbol": "BTCUSDT",
      "rate": "-0.00015",
      "next_funding_time": "2024-12-27T16:00:00Z",
      "last_updated": "2024-12-27T10:25:30Z"
    },
    {
      "exchange": "HyperLiquid",
      "symbol": "BTCUSDT",
      "rate": "0.00008",
      "next_funding_time": "2024-12-27T11:00:00Z",
      "last_updated": "2024-12-27T10:29:00Z"
    }
  ],
  "timestamp": "2024-12-27T10:30:00Z"
}

Response Fields:

Note: Funding rate values are in decimal form. Multiply by 100 to get percentage (e.g., 0.0001 = 0.01%).

GET /api/balances

Returns cached balances from the balance repository. Fast response but may be slightly stale.

Request:

curl http://localhost:9090/api/balances

Response:

{
  "balances": [
    {
      "exchange": "BinanceFutures",
      "asset": "USDT",
      "free": "10000",
      "total": "12000",
      "wallet_balance": "11500",
      "reserved": "2000"
    },
    {
      "exchange": "Bybit",
      "asset": "USDT",
      "free": "8500",
      "total": "8500",
      "wallet_balance": "8200",
      "reserved": "0"
    },
    {
      "exchange": "HyperLiquid",
      "asset": "USDC",
      "free": "5000",
      "total": "7500",
      "wallet_balance": "7000",
      "reserved": "2500"
    }
  ],
  "timestamp": "2024-12-27T10:30:00Z"
}

Response Fields:

Balance Types: free is the correct balance for position sizing as it respects locked margin and automatically de-risks when positions are underwater. wallet_balance provides stable deposited capital for reporting/tracking that doesn't fluctuate with unrealized P&L.

GET /api/arbitrage_positions

Returns cached arbitrage positions with cumulative funding collected. This is the recommended endpoint for monitoring active arbitrage pairs.

Request:

curl http://localhost:9090/api/arbitrage_positions

Response:

{
  "positions": [
    {
      "symbol": "BTCUSDT",
      "long_exchange": "Bybit",
      "short_exchange": "BinanceFutures",
      "entry_spread": "0.00025",
      "position_size": "0.1",
      "entry_time": "2024-12-26T08:00:00Z",
      "funding_collected": "12.50"
    },
    {
      "symbol": "ETHUSDT",
      "long_exchange": "HyperLiquid",
      "short_exchange": "BinanceFutures",
      "entry_spread": "0.0003",
      "position_size": "1.5",
      "entry_time": "2024-12-25T16:00:00Z",
      "funding_collected": "28.75"
    }
  ],
  "total_funding_collected": "41.25",
  "timestamp": "2024-12-27T10:30:00Z"
}

Response Fields:

Health Endpoints

In addition to the data API, the metrics server exposes health check endpoints for monitoring and container orchestration:

GET /health

Returns comprehensive health status including exchange connectivity and system metrics.

Request:

curl http://localhost:9090/health | jq

Response:

{
  "status": "healthy",
  "exchanges": {
    "binance": "connected",
    "bybit": "connected",
    "hyperliquid": "connected"
  },
  "uptime_seconds": 3600
}

Response Fields:

Status Meanings:

• healthy - All exchanges connected, bot operating normally
• degraded - Some exchanges unavailable, bot still operating
• unhealthy - Critical failure, bot not functioning

GET /ready

Kubernetes-style readiness probe. Returns HTTP 200 when the bot is ready to accept traffic.

Request:

curl -s -o /dev/null -w "%{http_code}" http://localhost:9090/ready

Response:

• 200 OK - Bot is ready (connected to at least one exchange)
• 503 Service Unavailable - Bot is not ready (still initializing or all exchanges failed)

Body (when ready):

{
  "ready": true,
  "timestamp": "2024-12-27T10:30:00Z"
}

GET /live

Kubernetes-style liveness probe. Returns HTTP 200 if the bot process is alive and responsive.

Request:

curl -s -o /dev/null -w "%{http_code}" http://localhost:9090/live

Response:

• 200 OK - Bot is alive
• 503 Service Unavailable - Bot is unresponsive (should trigger container restart)

Body:

{
  "alive": true,
  "timestamp": "2024-12-27T10:30:00Z"
}

GET /metrics

Returns information about the OpenTelemetry metrics configuration (not Prometheus scrape format).

Request:

curl http://localhost:9090/metrics | jq

Response:

{
  "status": "operational",
  "backend": "OpenTelemetry OTLP",
  "endpoint": "http://localhost:4317",
  "protocol": "gRPC"
}

Note: For Prometheus-style metrics, configure OTLP export to your observability backend (Grafana Cloud, etc.) and query metrics there. See Monitoring Guide for details.

Kubernetes Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wealth-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: wealth
  template:
    metadata:
      labels:
        app: wealth
    spec:
      containers:
        - name: wealth
          image: ghcr.io/thiras/wealth:latest
          ports:
            - containerPort: 9090
          livenessProbe:
            httpGet:
              path: /live
              port: 9090
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 9090
            initialDelaySeconds: 5
            periodSeconds: 10

Usage Examples

Shell Scripts

Monitor total balance across exchanges:

#!/bin/bash
curl -s http://localhost:9090/api/balances | jq '
  .balances 
  | group_by(.asset) 
  | map({asset: .[0].asset, total: (map(.total | tonumber) | add)})
'

Get current funding spread for a symbol:

#!/bin/bash
SYMBOL="BTCUSDT"
curl -s http://localhost:9090/api/funding_rates | jq --arg sym "$SYMBOL" '
  .rates 
  | map(select(.symbol == $sym)) 
  | sort_by(.rate) 
  | {min: .[0], max: .[-1], spread: ((.[-1].rate | tonumber) - (.[0].rate | tonumber))}
'

Python Integration

import requests
from datetime import datetime

BASE_URL = "http://localhost:9090"

def get_positions():
    """Fetch current positions from all exchanges."""
    response = requests.get(f"{BASE_URL}/api/positions")
    response.raise_for_status()
    return response.json()

def get_arbitrage_summary():
    """Get arbitrage positions with funding collected."""
    response = requests.get(f"{BASE_URL}/api/arbitrage_positions")
    response.raise_for_status()
    data = response.json()
    
    print(f"Active positions: {len(data['positions'])}")
    print(f"Total funding collected: ${data['total_funding_collected']}")
    
    for pos in data['positions']:
        print(f"  {pos['symbol']}: {pos['long_exchange']} ↔ {pos['short_exchange']}, "
              f"funding: ${pos['funding_collected']}")

def check_funding_opportunity(symbol: str, min_spread: float = 0.0004):
    """Check if funding spread exceeds threshold."""
    response = requests.get(f"{BASE_URL}/api/funding_rates")
    response.raise_for_status()
    
    rates = [r for r in response.json()['rates'] if r['symbol'] == symbol]
    if len(rates) < 2:
        return None
    
    rates_sorted = sorted(rates, key=lambda x: float(x['rate']))
    spread = float(rates_sorted[-1]['rate']) - float(rates_sorted[0]['rate'])
    
    if spread >= min_spread:
        return {
            'symbol': symbol,
            'spread': spread,
            'long_exchange': rates_sorted[0]['exchange'],
            'short_exchange': rates_sorted[-1]['exchange']
        }
    return None

if __name__ == "__main__":
    get_arbitrage_summary()

Prometheus/Alertmanager Integration

While the bot exports native Prometheus metrics, you can also create custom scrapers:

# prometheus.yml
scrape_configs:
  - job_name: 'wealth-api'
    metrics_path: /metrics
    static_configs:
      - targets: ['localhost:9090']

For custom alerts based on API data, use a script with Alertmanager webhook receiver.

Rate Limiting

The HTTP API itself has no rate limiting. However:

• /api/positions triggers exchange API calls (subject to exchange rate limits)
• Other endpoints use cached data with no external API impact

Recommendation: Poll /api/positions no more than once per minute. Use /api/arbitrage_positions for frequent monitoring.

Error Responses

All endpoints return standard HTTP status codes:

Error responses include a message:

{
  "error": "Failed to fetch positions from all exchanges"
}

Configuration

Binding Address

By default, the API binds to all interfaces (0.0.0.0). For production, restrict to localhost:

[observability]
metrics_bind_address = "127.0.0.1"
metrics_port = 9090

Or via environment:

export WEALTH__OBSERVABILITY__METRICS_BIND_ADDRESS=127.0.0.1

Reverse Proxy

For external access, use a reverse proxy (nginx, Caddy) with authentication:

location /api/ {
    auth_basic "Wealth API";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:9090;
}

See Also

• CLI Reference - Command-line interface for the same data
• Monitoring & Metrics - Prometheus metrics and Grafana dashboards
• Configuration Guide - Server configuration options

TUI Dashboard

Interactive terminal interface for real-time monitoring and control

The Wealth Trading System includes a powerful terminal user interface (TUI) built with Ratatui. It provides real-time monitoring of your trading bot with an intuitive keyboard-driven interface.

Dashboard Navigation

flowchart LR
    subgraph Tabs["TUI Dashboard Tabs"]
        direction TB
        T1["📊 Dashboard<br/>Overview & Opportunities"]
        T2["📈 Positions<br/>Active Positions"]
        T3["🔗 Pairs<br/>Trading Pairs"]
        T4["💰 Funding<br/>Funding Rates"]
        T5["📊 Statistics<br/>Analytics"]
    end
    
    T1 --> T2
    T2 --> T3
    T3 --> T4
    T4 --> T5
    T5 -.-> T1
    
    style T1 fill:#e3f2fd
    style T2 fill:#e8f5e9
    style T3 fill:#fff3e0
    style T4 fill:#f3e5f5
    style T5 fill:#ffcdd2

Quick Start

# Run the TUI dashboard
wealth dashboard

# With dynamic pair discovery enabled
wealth dashboard --enable-discovery

# Custom refresh rate (for slow connections)
wealth dashboard --tick-rate 500

Building with TUI Support

The TUI feature must be enabled at compile time:

cargo build --release --features tui

Pre-built binaries from GitHub releases include TUI support by default.

Header Bar

The top header bar displays key metrics at a glance:

Note on Header vs Stats Tab: The header's "Net" shows funding minus fees only (cash flow from funding operations). The Stats tab's "Total P&L" includes price spread gains/losses as well, providing the complete P&L picture.

Dashboard Tabs

The dashboard has six main tabs, accessible with Tab and Shift+Tab:

📊 Dashboard Tab

The overview tab shows:

• Bot Status - Running state, uptime, mode (paper/live)
• Health Summary - Exchange connectivity, WebSocket status
• Key Metrics - Total P&L, open positions, funding collected
• Recent Opportunities - Latest arbitrage opportunities with individual funding rates and EV

The opportunities panel displays:

• Validity indicator: Shows whether an opportunity meets trading thresholds
  • ✓ (green) - Executed opportunity
  • ● (cyan) - Valid opportunity (meets spread and EV thresholds)
  • ○ (gray) - Invalid opportunity (below thresholds, shown for market context)
• Quality stars: Premium opportunities show ★★★ (gold) or ★★ (yellow)
• Symbol and exchange pair (long/short)
• Individual funding rates per leg (color-coded by magnitude)
• Leverage - Configured leverage for this symbol (e.g., "10x") or "max" if not configured
• Spread percentage
• Expected Value (EV) estimate

The title shows counts: Opportunities (1/50) [3● 1✓] means position 1 of 50, 3 valid opportunities, 1 executed.

📈 Positions Tab

Monitor your active positions with comprehensive metrics and risk indicators:

Column Reference (Full View)

Status Indicators (S Column)

APR Color Coding

The APR column shows annualized returns with color-coded quality:

Next Funding Countdown

Color-coded urgency for upcoming funding payments:

Liquidation Distance (Liq%)

Estimated distance to liquidation based on leverage:

Spread Trend Sparkline

The Trend column displays a mini-chart using Unicode block characters (▁▂▃▄▅▆▇█) showing how the spread has evolved over recent data points. Rising patterns indicate improving opportunity, falling patterns suggest declining returns.

ROI Status Indicators

Totals Row

A fixed summary row at the bottom shows portfolio totals:

• Total position count
• Combined size value
• Average APR (weighted by size)
• Total PnL
• Overall ROI percentage

Sorting Positions

Press s to cycle through sort columns:

Symbol → Size → PnL → ROI → Spread → APR → Age → Next Funding → (back to Symbol)

• The current sort column and direction (▲ ascending, ▼ descending) are shown in the title bar
• Direction toggles when cycling back to Symbol

Position Actions

Use j/k or arrow keys to select a position, then:

• h to toggle hold status (held positions bypass auto-close)
• x to manually close the position
• s to change sort order

Note: Scrolling is smart—arrow keys only scroll when there are more items than fit on screen.

🔗 Pairs Tab

Monitor and manage your trading pairs dynamically:

• Symbol - Trading pair symbol (e.g., BTCUSDT)
• Exchange - Exchange where the pair is tracked
• Status - Health status with color coding:
  • 🟢 Healthy - Pair is functioning normally
  • 🟡 Degraded - Some issues but still usable
  • 🔴 Unhealthy - Pair has significant issues
  • ⚪ Disabled - Pair has been manually disabled
• Enabled - Whether the pair is enabled for trading (✓ Yes / ✗ No)
• WS Disc - Consecutive WebSocket disconnection count
• API Err - Consecutive API error count
• Last FR Update - Time since last funding rate update
• Error - Last error message if any

Filtering Pairs

Press / to open the filter input. Type to filter pairs by symbol or exchange name:

• Filter matches both symbol (e.g., "BTC") and exchange (e.g., "binance")
• Case-insensitive matching
• Press Enter or Esc to close filter input
• Press c to clear the filter

The title bar shows the active filter: [filter: btc]

Sorting Pairs

Press s to cycle through sort columns:

Symbol → Exchange → Status → Enabled → WS Disc → API Err → (back to Symbol)

• The current sort column shows an indicator in the header (▲ ascending, ▼ descending)
• Direction toggles when cycling back to Symbol

Pair Management Controls

Dynamic Pair Management

Pairs can be added or removed at runtime without restarting the bot:

• Enable/Disable: Temporarily stop trading a pair while keeping it tracked
• Add Pair: Add a new trading pair to the active list
• Remove Pair: Remove a pair from trading entirely

Note: Runtime changes are not persisted to config.toml. To permanently add/remove pairs, update your configuration file.

💰 Funding Tab

Live funding rates across all exchanges:

• Real-time rates updated every tick
• Color-coded rates (green for positive, red for negative)
• Annualized rate display
• Next funding countdown timer
• Spread between exchanges highlighted

Positions/Opportunities Rate Colors: The individual funding rates in Positions and Opportunities panels use a gradient color scheme:

• Bright green: ≤ -0.05% (receiving significant funding)
• Green: Negative rates (receiving)
• Yellow: 0% to < 0.05% (low cost)
• Orange: 0.05% to < 0.1% (moderate cost)
• Red: ≥ 0.1% (high cost)

Note: Scrolling is dynamic—only activates when funding pairs exceed the visible area.

📊 Statistics Tab

Comprehensive trading analytics and metrics dashboard with six sections.

Responsive Layout: The Stats tab adapts to terminal size:

• ≥35 rows: All sections visible
• 25-34 rows: Session Activity hidden
• <25 rows: Session Activity + Risk Metrics hidden

Overview, Performance, and Breakdown sections are always visible.

Overview Section

• Active Positions - Currently open positions count
• Position Value - Sum of all active position sizes in USD (not total wallet balance)
• Total P&L - Net session P&L including price spread gains, funding collected, and fees paid (with trend indicator ▲/▼)
• Uptime - Duration since bot/session start

Performance Section

• PnL % - Percentage profit/loss relative to position value
• Win Rate - Percentage of profitable trades (green ≥50%, yellow 30-50%, red <30%)
• Daily P&L - Extrapolated daily profit/loss based on current performance
• Funding Collected - Total funding payments received this session
• Fees Paid - Total trading fees paid this session (shown as negative cost)

Risk Metrics Section

• Max Drawdown - Peak-to-trough decline in USD (stat box, not gauge)
• Current DD - Current drawdown from last peak in USD (stat box)
• Portfolio Util - Positions used vs max allowed (visual gauge, shows X/Y)
• Exposure Util - Current exposure vs total balance (visual gauge, shows $XK/$YK or "N/A" if balance data unavailable)

Visual gauges provide at-a-glance risk assessment with color-coded thresholds:

• Green (<50%): Safe operating range
• Yellow (50-80%): Moderate utilization
• Cyan (≥80%): High utilization

Session Activity Section

• Trades Executed - Total trades executed this session (opens + closes)
• Pos. Opened - Positions opened this session
• Pos. Closed - Positions closed this session
• Funding Events - Number of funding payments received this session

Exchange Breakdown Section

A detailed table showing per-exchange statistics:

Position Breakdown Section

Groups positions by exchange pair (e.g., "Binance ↔ Bybit") showing:

• Number of positions in that pair
• Combined size value
• Total funding collected from active positions (may differ from session total if positions were closed)

Scrollable with position indicator when content exceeds visible area.

P&L Trend Indicator: The Total P&L displays a colored arrow showing recent direction:

• ▲ (green): P&L increasing
• ▼ (red): P&L decreasing

�📜 Logs Tab

Real-time event viewer:

• Scrollable log history
• Color-coded log levels (INFO, WARN, ERROR)
• Trade executions, funding payments, system events
• Use j/k to scroll through history

Keybindings

Navigation

Scrolling

Smart Scrolling: Scroll keys only have effect when content exceeds the visible area. If all items fit on screen, scrolling is automatically disabled to prevent hiding content.

Actions

Hold Position Feature

The hold feature allows you to protect specific positions from being automatically closed by the bot's exit conditions (profit target, spread reversal, trailing stop, etc.).

How to Use

1. Navigate to the Positions tab
2. Select a position using j/k or arrow keys
3. Press h to toggle the hold status

Visual Indicators

• 🔒 - Lock icon appears in the "H" column for held positions
• The title bar shows the count of held positions (e.g., "│ 2 held")

Behavior

When a position is held:

• ✅ Continues collecting funding payments normally
• ✅ Displayed in TUI with all metrics
• ✅ Preserved during graceful shutdown (not closed on Ctrl+C)
• ❌ Bypassed by all auto-close mechanisms:
  • Spread reversal exits
  • Duration-based exits
  • Trailing stop triggers
  • Profit target exits
  • Spread narrowing exits

To close a held position, you must manually press x or Del.

Note: Held positions persist across bot restarts. When you restart the bot, held positions remain open on exchanges and will be tracked again.

Use Cases

• Strong conviction: Hold positions you believe will continue earning
• Temporary protection: Prevent premature closing during volatile periods
• Manual management: Take full control of specific high-value positions

Closing Positions

When you press x on a selected position, a confirmation dialog appears:

┌─ Close Position ─────────────────┐
│ Close position BTCUSDT?          │
│                                  │
│ Long: Binance                    │
│ Short: Bybit                     │
│ Size: $1000.00                   │
│                                  │
│ [Y] Yes  [N] No  [Esc] Cancel    │
└──────────────────────────────────┘

• Press Y to confirm and close the position
• Press N or Esc to cancel

The bot will atomically close both legs of the position with rollback protection.

Configuration Options

Command Line Options

wealth dashboard [OPTIONS]

Options:
  --enable-discovery     Enable dynamic pair discovery
  --tick-rate <MS>       UI refresh rate in milliseconds (default: 250)
  -v, -vv, -vvv          Verbosity level
  -c, --config <FILE>    Custom config file

Tick Rate Recommendations

Dashboard vs Headless Mode

Troubleshooting

TUI Not Available

If you see "TUI feature not enabled":

# Check if binary was built with TUI
wealth dashboard
# Error: TUI feature not enabled

# Rebuild with TUI feature
cargo build --release --features tui

Display Issues

Garbled output:

# Reset terminal
reset

# Try different terminal emulator
# Recommended: kitty, alacritty, wezterm, iTerm2

Colors not showing:

# Ensure TERM is set correctly
export TERM=xterm-256color
wealth dashboard

Too small:

# Minimum recommended size: 80x24
# Resize terminal or reduce font size

SSH/Remote Issues

# Use slower tick rate
wealth dashboard --tick-rate 1000

# Enable SSH compression
ssh -C user@host

# Use mosh for better responsiveness
mosh user@host -- wealth dashboard

Related

• CLI Reference - Full command documentation
• Getting Started - Initial setup
• Monitoring - Grafana dashboards for production

Monitoring Guide

Monitor your Wealth trading bot's performance with built-in dashboards and AI-powered queries.

Table of Contents

• Overview
• Quick Health Check
• AI-Powered Monitoring
• Grafana Dashboards
• Key Metrics
• Alerts
• Log Viewing
• Kubernetes Metrics Flow
• Docker Compose Monitoring Stack

Overview

flowchart TB
    subgraph Bot["Wealth Bot"]
        STRAT[Strategy Engine]
        METRICS[Metrics Exporter]
        LOGS[Structured Logs]
        HEALTH[Health Endpoint]
    end
    
    subgraph Collection["Data Collection"]
        OTEL[OpenTelemetry Collector]
        PROM_EXP[Prometheus Exporter<br/>:8889/metrics]
    end
    
    subgraph Storage["Storage Backends"]
        PROM[Prometheus]
        LOKI[Loki]
        TEMPO[Tempo]
    end
    
    subgraph Viz["Visualization"]
        GRAF[Grafana Dashboards]
        AI[AI Queries via MCP]
        ALERTS[Alert Manager]
    end
    
    STRAT --> METRICS
    STRAT --> LOGS
    STRAT --> HEALTH
    
    METRICS -->|OTLP| OTEL
    LOGS -->|OTLP| OTEL
    HEALTH --> GRAF
    
    OTEL --> PROM_EXP
    PROM -->|scrape| PROM_EXP
    OTEL --> LOKI
    OTEL --> TEMPO
    
    PROM --> GRAF
    LOKI --> GRAF
    TEMPO --> GRAF
    GRAF --> AI
    GRAF --> ALERTS
    
    style Bot fill:#e3f2fd
    style Collection fill:#fff3e0
    style Storage fill:#e8f5e9
    style Viz fill:#f3e5f5

The bot provides multiple monitoring options:

• 🤖 AI Queries - Ask questions in natural language via Grafana MCP
• 📊 Dashboards - Visual monitoring in Grafana
• 📈 Metrics - Real-time performance data via OpenTelemetry
• 🔔 Alerts - Automated notifications for important events
• ❤️ Health Endpoint - Quick status checks

Monitoring Options

flowchart LR
    subgraph Options["Monitoring Options"]
        CLI[CLI Commands]
        HEALTH[Health Endpoint]
        DASH[Grafana Dashboards]
        AI[AI Queries]
        ALERTS[Automated Alerts]
    end
    
    CLI --> |"wealth positions"| STATUS[Quick Status]
    HEALTH --> |":9090/health"| STATUS
    DASH --> |"Visual"| DEEP[Deep Analysis]
    AI --> |"Natural Language"| DEEP
    ALERTS --> |"Notifications"| AUTO[Automated Response]
    
    style CLI fill:#e3f2fd
    style HEALTH fill:#e3f2fd
    style DASH fill:#c8e6c9
    style AI fill:#f3e5f5
    style ALERTS fill:#fff3e0

Quick Health Check

CLI Commands

# Overall health status
curl http://localhost:9090/health | jq

# Check positions
wealth positions

# Check balances
wealth balance

# View configuration
wealth config

Health Endpoint Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "uptime_seconds": 3600,
  "components": {
    "websockets": {
      "binance": { "connected": true, "last_update": "2024-01-15T10:29:58Z", "error_count": 0 },
      "bybit": { "connected": true, "last_update": "2024-01-15T10:29:59Z", "error_count": 0 },
      "aster": { "connected": true, "last_update": "2024-01-15T10:29:57Z", "error_count": 0 }
    },
    "exchanges": {
      "binance_api": { "reachable": true, "consecutive_failures": 0 },
      "bybit_api": { "reachable": true, "consecutive_failures": 0 },
      "aster_api": { "reachable": true, "consecutive_failures": 0 }
    },
    "strategy": {
      "active_positions": 2,
      "fresh_funding_rates": 15
    }
  }
}

AI-Powered Monitoring

Ask your AI assistant (GitHub Copilot, Claude, etc.) natural language questions:

Examples:

• "What's my current P&L?"
• "Show funding rates for BTCUSDT"
• "Are there any firing alerts?"
• "Which exchange has the best execution performance?"
• "What's the average position holding time?"

No need to write queries or navigate dashboards - AI queries metrics automatically.

Setup (5 minutes)

1. Start services:

   docker compose up -d
   

2. Generate Grafana token at http://localhost:3000

3. Add to .env:

   GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_...
   

4. Restart MCP:

   docker compose restart grafana-mcp
   

Grafana Dashboards

Accessing Dashboards

1. Open Grafana: http://localhost:3000
2. Default credentials: admin / admin
3. Navigate to Dashboards → Wealth Trading Bot

Key Dashboard Panels

Setting Up Grafana Cloud

For cloud monitoring (recommended for production):

1. Create free Grafana Cloud account
2. Configure OTLP export
3. Import dashboard templates

See Grafana Cloud Setup for full instructions.

Key Metrics

Trading Performance

System Health

Error Types

Order errors are classified by type for easier diagnosis:

Rejection Reasons

Opportunities can be rejected for various reasons:

View in Terminal

# Metrics info endpoint
curl http://localhost:9090/metrics | jq

Alerts

Built-in Alert Types

Configuring Alerts in Grafana

1. Go to Alerting → Alert rules
2. Create new alert rule
3. Set condition (e.g., wealth_balance_total < 1000)
4. Add notification channel (email, Slack, Discord)

Example Alert Rule

# Low Balance Alert
condition: wealth_balance_total{exchange="binance"} < 1000
for: 5m
severity: critical

Log Viewing

Real-time Logs

# Follow bot logs
wealth run 2>&1 | tee -a bot.log

# Or with Docker
docker compose logs -f wealth

Log Levels

Searching Logs in Grafana (Loki)

# All errors
{service="wealth-bot"} |= "ERROR"

# Order execution logs
{service="wealth-bot"} |= "arbitrage"

# WebSocket issues
{service="wealth-bot"} |= "WebSocket"

Kubernetes Metrics Flow

When deploying to Kubernetes with the Helm chart, metrics flow through the OpenTelemetry Collector sidecar:

App → OTLP (gRPC :4317) → OTEL Collector → Prometheus Exporter (:8889) → Prometheus scrape

Configuration

The Helm chart enables the Prometheus exporter by default:

otelCollector:
  enabled: true
  prometheus:
    enabled: true   # Exposes :8889/metrics for Prometheus scraping
    port: 8889

How It Works

1. App exports OTLP - The wealth bot sends metrics via OTLP to the collector sidecar
2. Collector processes - Batching, resource enrichment, and format conversion
3. Prometheus scrapes - ServiceMonitor scrapes /metrics from the collector (port 8889)
4. Grafana queries - Dashboards query Prometheus for visualization

Note: The app's /metrics endpoint returns JSON info about OTLP config, not Prometheus format. For Prometheus-compatible metrics, enable otelCollector.prometheus.enabled=true.

Docker Compose Monitoring Stack

The included compose.yml provides:

• Grafana - Dashboards and visualization
• OpenTelemetry Collector - Metrics aggregation
• Prometheus - Metrics storage
• Loki - Log aggregation
• Tempo - Distributed tracing

Starting the Stack

# Start all services
docker compose up -d

# Check service status
docker compose ps

# View logs
docker compose logs -f

Accessing Services

Recommended Monitoring Setup

Development / Paper Trading

• Local Grafana (Docker Compose)
• Terminal logs
• Health endpoint checks

Production / Live Trading

• Grafana Cloud (free tier available)
• Alert notifications (email/Slack)
• AI-powered monitoring (MCP)
• 24/7 uptime monitoring

Quick Reference

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

# View positions
wealth positions

# View balances  
wealth balance

# Start monitoring stack
docker compose up -d

# View Grafana
open http://localhost:3000

# Follow logs
docker compose logs -f wealth

Related Documentation

Grafana Cloud Setup Guide

Quick 15-Minute Setup for Fully Managed Observability

Overview

This guide shows you how to migrate from self-hosted monitoring (Docker Compose) to Grafana Cloud - a fully managed observability platform with free tier (14-day trial, then free tier available).

Benefits:

• ✅ Zero infrastructure - No Prometheus, Grafana, Loki, or Tempo containers to manage
• ✅ Automatic scaling - Handles any volume of metrics/logs/traces
• ✅ High availability - 99.9% uptime SLA
• ✅ Global CDN - Fast dashboard loading worldwide
• ✅ Built-in alerting - Email, Slack, PagerDuty integrations
• ✅ Long-term retention - Metrics for 13 months (free tier)

Table of Contents

• Quick Start (15 Minutes)
• Prerequisites
• Step 1: Create Grafana Cloud Account
• Step 2: Get Your Cloud Credentials
• Step 3: Update OpenTelemetry Collector
• Step 4: Update Docker Compose
• Step 5: Configure Environment Variables
• Step 6: Test the Connection
• Step 7: Import Dashboards
• Step 8: Set Up Alerts
• Migration Checklist
• Architecture Comparison
• Cost Optimization
• Troubleshooting

Quick Start (15 Minutes)

TL;DR - Fast track to Grafana Cloud:

1. Create account → https://grafana.com/auth/sign-up/create-user
2. Get OTLP endpoint → Your stack → Send Data → OpenTelemetry → Copy endpoint URL
3. Configure collector (credentials already in otel-collector-grafana-cloud.yaml):

   # Verify endpoint in otel-collector-grafana-cloud.yaml matches your region
   # File already configured with prod-eu-central-0 credentials
   

4. Deploy:

   docker compose up -d
   
   # Update .env to point bot to local collector
   OTLP_ENDPOINT=http://localhost:4317
   
   # Run bot
   export CREDENTIALS_PASSPHRASE="your_passphrase"
   wealth run
   

5. View → https://YOUR-STACK.grafana.net → Explore → Query: wealth_funding_rate

Important: Do NOT send telemetry directly from the bot to Grafana Cloud's managed OTLP gateway. Always use a local OTLP Collector as a proxy (see Architecture and Troubleshooting for why).

For detailed instructions, continue reading below.

Prerequisites

• ✅ Wealth trading bot installed (see Getting Started)
• ✅ Docker and Docker Compose installed
• ✅ Credit card (for Grafana Cloud trial - free tier available after)

Step 1: Create Grafana Cloud Account

1.1 Sign Up

1. Go to https://grafana.com/auth/sign-up/create-user
2. Click "Start for free"
3. Fill in your details:
   • Email address
   • Company name (can use "Personal" or your name)
   • Password
4. Verify your email

1.2 Create a Stack

After email verification:

1. You'll be prompted to create a stack (your isolated Grafana Cloud instance)
2. Choose:
   • Stack name: wealth-trading-bot (or any name you prefer)
   • Region: Choose closest to you (e.g., us-east-1, eu-west-1)
   • Plan: Start with Free Trial (14 days, then free tier)
3. Click "Launch Stack"

1.3 Access Your Stack

Your stack will be created with a URL like:

https://YOUR-STACK-NAME.grafana.net

Save this URL - you'll need it later.

Step 2: Get Your Cloud Credentials

Note: The repository includes pre-configured credentials for prod-eu-central-0 region in otel-collector-grafana-cloud.yaml. If you're using a different region or want to use your own credentials, follow these steps.

2.1 Find Your OTLP Endpoint

1. In Grafana Cloud UI, go to your stack homepage
2. Click "Send Data" or "Connections"
3. Search for "OpenTelemetry" or "OTLP"
4. You'll see an endpoint like:
   • https://otlp-gateway-YOUR-REGION.grafana.net/otlp

Example regions:

• prod-eu-central-0 (Europe - Frankfurt)
• prod-us-east-0 (US East - Virginia)
• prod-us-central-0 (US Central)

2.2 Create an Access Token

1. Go to "Administration" → "Access Policies"
2. Click "Create access policy"
3. Set:
   • Name: wealth-bot-telemetry
   • Realms: Your stack
   • Scopes:
     • metrics:write
     • logs:write
     • traces:write
4. Click "Create"
5. Click "Add token" → Copy the token (starts with glc_)

2.3 Get Your Instance ID

Your instance ID (username) is visible in the OTLP configuration:

• Usually a 6-7 digit number (e.g., 1446931)
• Found in: "Send Data" → "OpenTelemetry" → Look for "Instance ID" or "Username"

2.4 Update Collector Configuration

Edit otel-collector-grafana-cloud.yaml:

exporters:
  otlphttp/grafana_cloud:
    endpoint: "https://otlp-gateway-YOUR-REGION.grafana.net/otlp"  # Update region
    auth:
      authenticator: basicauth/grafana_cloud

extensions:
  basicauth/grafana_cloud:
    client_auth:
      username: "YOUR_INSTANCE_ID"      # Update with your instance ID
      password: "YOUR_API_TOKEN"         # Update with your token (glc_...)

Security Note: These credentials are in the Docker Compose config file, not .env, as they're only used by the OTLP Collector container, not the bot itself.

Step 3: Configure Bot to Use Local Collector

The bot should send telemetry to the local OTLP Collector, not directly to Grafana Cloud.

3.1 Update Environment Variables

In your .env file:

# Point bot to LOCAL collector (NOT Grafana Cloud directly)
OTLP_ENDPOINT=http://localhost:4317

# Optional: Set service metadata
ENVIRONMENT=production
SERVICE_NAME=wealth-bot

Critical: Do NOT set OTLP_ENDPOINT to Grafana Cloud's managed gateway URL. Direct connections from the Rust SDK have compatibility issues. See Troubleshooting for details.

Step 4: Start the OTLP Collector

3.1 Collector Configuration Overview

The repository includes a pre-configured OTLP Collector at otel-collector-grafana-cloud.yaml. This collector:

• Receives OTLP data from the bot (gRPC on port 4317, HTTP on 4318)
• Processes telemetry (batching, resource detection, filtering)
• Exports to Grafana Cloud via OTLP/HTTP endpoint
• Generates additional metrics from traces (span metrics, service graphs)

Key Features:

• Uses grafanacloud connector for automatic span metrics generation
• Drops unnecessary resource attributes to reduce cardinality
• Adds deployment environment and service version to metrics
• Health check endpoint on port 13133

Configuration is already complete - you only need to update credentials if using a different region (see Step 2).

Step 4: Start the OTLP Collector

4.1 Start the Collector

The Docker Compose configuration is already in your repository at compose.yml (Grafana Cloud is now the default).

# Start the OTLP Collector
docker compose up -d

# Verify it's healthy
curl http://localhost:13133
# Expected: {"status":"Server available","upSince":"..."}

# Check logs
docker compose logs otel-collector
# Look for: "Everything is ready. Begin running and processing data."

What this deploys:

• Single container: OpenTelemetry Collector (otel/opentelemetry-collector-contrib:latest)
• Ports exposed:
  • 4317 - OTLP gRPC (bot connects here)
  • 4318 - OTLP HTTP (alternative)
  • 13133 - Health check endpoint
• Credentials: Read from otel-collector-grafana-cloud.yaml (hardcoded, not from .env)

Step 5: Configure and Run the Bot

5.1 Update Bot Configuration

In your .env file:

# Point to LOCAL collector (NOT Grafana Cloud)
OTLP_ENDPOINT=http://localhost:4317

# Optional: Service metadata
ENVIRONMENT=production
SERVICE_NAME=wealth-bot

Critical: The bot should connect to localhost:4317 (local collector), NOT to Grafana Cloud's managed gateway. The collector handles the connection to Grafana Cloud.

5.2 Verify .env is Gitignored

# Check if .env is gitignored
grep "\.env" .gitignore

# If not, add it
echo ".env" >> .gitignore

Step 6: Test the Connection

6.1 Verify Collector is Running

# Check collector health
curl http://localhost:13133
# Expected: {"status":"Server available","upSince":"..."}

# Check collector logs
docker compose logs otel-collector | tail -20
# Look for: "Everything is ready. Begin running and processing data."

# Check for export errors
docker compose logs otel-collector | grep -i error
# Should be empty or only show benign warnings

6.2 Run the Bot

# Set required credentials
export CREDENTIALS_PASSPHRASE="your_passphrase"

# Ensure OTLP_ENDPOINT points to local collector
echo $OTLP_ENDPOINT
# Should output: http://localhost:4317

# Run the bot
wealth run

6.3 Verify Bot is Exporting

# Check bot health endpoint
curl http://localhost:9090/health | jq
# Look for: "otlp_status": "connected" or similar

# Watch bot logs for OTLP connection
# Should see: "OpenTelemetry OTLP export enabled to: http://localhost:4317"
# Should NOT see: "BatchLogProcessor.ExportError" or "Timeout expired"

6.4 Verify Data in Grafana Cloud

1. Open your Grafana Cloud instance: https://YOUR-STACK.grafana.net
2. Go to "Explore"
3. Select data source: Prometheus (or "grafanacloud-YOUR-STACK-prom")
4. Run query:

   {__name__=~"wealth.*"}
   

5. You should see metrics appearing within 10-30 seconds

If no data appears, see Troubleshooting or OTLP Export Issues.

Step 7: Import Dashboards

7.1 Import Pre-built Dashboard

Your repository includes a pre-built dashboard at grafana/grafana-dashboard.json:

1. In Grafana Cloud UI, go to "Dashboards" → "Import"
2. Click "Upload JSON file"
3. Select grafana/grafana-dashboard.json from your repository
4. Configure:
   • Name: Keep default or rename (e.g., "Wealth Trading Bot")
   • Folder: Select or create a folder
   • Prometheus: Select your Grafana Cloud Prometheus data source
5. Click "Import"

7.2 Verify Dashboard Data

After import:

1. Dashboard should populate with data within 30 seconds
2. Check panels for:
   • Funding Rates by symbol and exchange
   • Account Balances by exchange
   • Trade Execution Metrics (success rate, errors)
   • WebSocket Connection Status

7.3 Dashboard Variables (if needed)

If variables need adjustment:

1. Open imported dashboard
2. Click ⚙️ (Settings) → "Variables"
3. Update $pair variable if needed:
   • Query: label_values(wealth_funding_rate, symbol)
   • Data source: grafanacloud-YOUR-STACK-prom
4. Save dashboard

Migration Checklist

Use this checklist to track your migration progress:

Pre-Migration

• Current self-hosted setup working (docker compose ps)
• Bot exporting metrics (curl http://localhost:9090/health)
• Optional: Export existing dashboards for backup

Grafana Cloud Setup

• Create Grafana Cloud account
• Create stack (save URL)
• Get Prometheus endpoint + credentials
• Get Loki endpoint (can reuse same credentials)
• Get Tempo endpoint (can reuse same credentials)

Configuration

• Copy .env.example to .env
• Uncomment and fill GRAFANA_CLOUD_* variables
• Set GRAFANA_CLOUD_USERNAME and GRAFANA_CLOUD_API_TOKEN
• Verify .env is in .gitignore

Deployment

• Stop old stack: docker compose down
• Start Cloud stack: docker compose up -d
• Verify collector health: curl http://localhost:13133
• Check collector logs for errors
• Run bot: wealth run
• Verify bot health: curl http://localhost:9090/health

Verification

• Open Grafana Cloud: https://YOUR-STACK.grafana.net
• Query wealth_funding_rate in Explore
• Check metrics appearing (10-30 seconds)
• Verify logs in Loki
• Check traces in Tempo (if enabled)

Dashboard & Alerts

• Import grafana/grafana-dashboard.json
• Update dashboard data source to Grafana Cloud Prometheus
• Create alert rules (low balance, WebSocket down, etc.)
• Set up notification channels (email, Slack)
• Test notifications

Post-Migration

• Monitor for 24 hours
• Check usage: Administration → Usage insights
• Optional: Clean up old Docker images
• Update team documentation

Time estimate: ~45 minutes total (~15 minutes active work)

Step 8: Set Up Alerts

8.1 Create Alert Rules

Grafana Cloud has built-in alerting:

1. In dashboard, click any panel → "Edit"
2. Click "Alert" tab → "Create alert rule from this panel"
3. Configure:
   • Name: Low Balance Alert
   • Query: sum(wealth_account_balance{type="total"}) < 1000
   • Threshold: Below 1000
   • Evaluation interval: 1m
4. Click "Save"

8.2 Notification Channels

Set up notifications:

1. Go to "Alerting" → "Contact points"
2. Click "Add contact point"
3. Choose:
   • Email (free)
   • Slack (requires webhook)
   • PagerDuty (requires integration key)
4. Test notification → Save

8.3 Recommended Alerts

Architecture Comparison

Before (Self-Hosted)

┌─────────────────────────────────────────────────────┐
│ Docker Compose (5 containers)                       │
├─────────────────────────────────────────────────────┤
│ Wealth Bot → OTLP Collector                         │
│              ↓                                       │
│              ├→ Prometheus (metrics)                │
│              ├→ Tempo (traces)                      │
│              └→ Loki (logs)                         │
│                 ↓                                    │
│              Grafana (dashboards)                   │
└─────────────────────────────────────────────────────┘

Resource Usage:

• CPU: ~500-800 MB RAM (all containers)
• Disk: ~1-5 GB (retention depends on volume)
• Maintenance: Manual updates, backups, scaling

After (Grafana Cloud)

┌─────────────────────────────────────────────────────────────┐
│ Wealth Bot (Rust)                                           │
│    ↓ OTLP gRPC (localhost:4317)                            │
│ OTLP Collector (Docker)                                     │
│    ↓ OTLP/HTTP + Basic Auth                                │
│ Grafana Cloud                                               │
│   ├→ Prometheus (metrics)                                  │
│   ├→ Loki (logs)                                           │
│   └→ Tempo (traces)                                        │
└─────────────────────────────────────────────────────────────┘

Architecture Benefits:

• ✅ Local Collector as Proxy: Handles batching, retries, and Grafana Cloud-specific requirements
• ✅ No Direct Bot → Cloud Connection: Avoids SDK compatibility issues (see Why Use a Collector)
• ✅ Single Point of Auth: Credentials managed in one place (collector config)
• ✅ Debugging Layer: Collector logs show exactly what's sent to Grafana Cloud

Resource Usage:

• CPU: ~100-200 MB RAM (OTLP Collector only)
• Disk: Minimal (no local storage)
• Maintenance: Zero (fully managed)
• Network: ~5-10 MB/hour (compressed telemetry)

Why This Architecture?

According to Grafana's best practices:

"We advise that you send directly to an OTLP endpoint in testing or small scale development scenarios only. Use a collector for production."

Direct SDK → Grafana Cloud connections are unreliable due to:

• Rate limiting on managed endpoints
• SDK-specific compatibility issues
• Missing batching/compression optimizations
• No retry buffer for network failures

See OTLP Troubleshooting for detailed explanation.

Cost Optimization

Free Tier Limits (Grafana Cloud)

Current Bot Usage (Estimated)

Based on your metrics:

• Metrics: ~500 series (well within free tier)
• Logs: ~1-2 GB/month (within free tier)
• Traces: ~500 MB/month (within free tier)

Expected Cost: $0/month (free tier) 🎉

Tips to Stay Within Free Tier

1. Reduce log volume:

   # In .env, set log level to INFO (not DEBUG)
   RUST_LOG=info
   

2. Sample traces (if you enable tracing heavily):

   # In otel-collector-grafana-cloud.yaml
   processors:
     probabilistic_sampler:
       sampling_percentage: 10  # Only send 10% of traces
   

3. Monitor usage:

   • Go to "Administration" → "Usage insights"
   • Check monthly consumption

Troubleshooting

Issue: "Connection refused" to Grafana Cloud

Symptom: OTLP Collector logs show connection errors

Solutions:

1. Check endpoints in .env:

   grep GRAFANA_CLOUD .env
   # Verify URLs match your region (e.g., us-east-1, eu-west-1)
   

2. Test connectivity:

   # Test Prometheus endpoint
   curl -u "$GRAFANA_CLOUD_USERNAME:$GRAFANA_CLOUD_API_TOKEN" \
     "$GRAFANA_CLOUD_PROMETHEUS_ENDPOINT"
   
   # Expected: 401 (auth works), 404 (endpoint works), or 200 (success)
   # Not expected: Connection refused, timeout
   

3. Check firewall:

   # Ensure outbound HTTPS (443) is allowed
   telnet prometheus-us-east-1.grafana.net 443
   

Issue: "Unauthorized" (401) from Grafana Cloud

Symptom: OTLP Collector logs show 401 errors

Solutions:

1. Verify credentials:

   echo $GRAFANA_CLOUD_API_TOKEN
   # Should start with "glc_"
   

2. Regenerate token:

   • Go to Grafana Cloud → "Administration" → "Access Policies"
   • Delete old token
   • Create new token with metrics:write, logs:write, traces:write scopes
   • Update .env

3. Restart collector:

   docker compose restart otel-collector
   

Issue: No metrics in Grafana Cloud

Symptom: Dashboard shows "No data"

Solutions:

1. Check bot is exporting:

   curl http://localhost:9090/metrics
   # Should show: "backend": "OpenTelemetry OTLP"
   

2. Check collector is receiving:

   docker compose logs otel-collector | grep "Metric"
   # Should show: "Metrics" ... "sent": true
   

3. Check data source in Grafana:

   • Go to "Connections" → "Data sources"
   • Click on Prometheus data source
   • Scroll down → "Save & test"
   • Should show: "Data source is working"

4. Query directly:

   # Query Grafana Cloud API
   curl -u "$GRAFANA_CLOUD_USERNAME:$GRAFANA_CLOUD_API_TOKEN" \
     "https://prometheus-us-east-1.grafana.net/api/v1/query?query=wealth_funding_rate"
   

Issue: High data usage

Symptom: Approaching free tier limits

Solutions:

1. Check current usage:

   • Grafana Cloud → "Administration" → "Usage insights"

2. Reduce metric cardinality:

   # In otel-collector-grafana-cloud.yaml
   processors:
     filter:
       metrics:
         exclude:
           match_type: strict
           metric_names:
             - wealth_websocket_message_latency_milliseconds
   

3. Aggregate metrics:

   processors:
     metricstransform:
       transforms:
         - include: wealth_.*
           match_type: regexp
           action: aggregate_labels
           aggregation_type: sum
           label_set: [exchange]
   

4. Reduce log verbosity:

   # In .env
   RUST_LOG=warn  # Only warnings and errors
   

Migration Checklist

Before switching to Grafana Cloud:

• Create Grafana Cloud account
• Get Prometheus, Loki, and Tempo credentials
• Create otel-collector-grafana-cloud.yaml
• Grafana Cloud is now default (compose.yml)
• Self-hosted stack available at compose.stack.yml
• Update .env with Grafana Cloud credentials
• Test connection: docker compose up -d
• Verify metrics in Grafana Cloud
• Import dashboards
• Set up alerts
• Configure notification channels
• Update documentation (if team project)
• Stop old local stack (if running): docker compose -f compose.stack.yml down

Next Steps

After successful migration:

1. Explore Grafana Cloud features:

   • Pre-built dashboards
   • SLO (Service Level Objectives) tracking
   • Incident management
   • OnCall rotation

2. Enable advanced features:

   • Grafana Machine Learning - Anomaly detection
   • Grafana Asserts - Automated root cause analysis
   • Grafana Faro - Frontend observability (if you add a web UI)

3. Integrate with CI/CD:

   • Use Grafana Cloud API for automated dashboard updates
   • Add monitoring checks to GitHub Actions

4. Join Grafana Community:

   • Slack: https://slack.grafana.com
   • Forum: https://community.grafana.com

Related Documentation

• Monitoring Guide - All available metrics
• Deployment Guide - Production deployment
• Configuration Guide - Bot configuration

Support

If you encounter issues:

1. Check collector logs: docker compose logs otel-collector
2. Verify credentials: grep GRAFANA_CLOUD .env
3. Test Grafana Cloud API: See troubleshooting section above
4. Consult Grafana Cloud docs: https://grafana.com/docs/grafana-cloud/

Grafana Cloud Support:

• Free tier: Community support (Slack, forum)
• Paid plans: Email and chat support

Still stuck? Open an issue in the project repo with:

• OTLP Collector logs
• Bot health check output: curl http://localhost:9090/health
• Grafana Cloud stack URL (redact credentials)

Log Collection Guide

This guide covers log configuration, formats, and querying. For the complete observability setup including OpenTelemetry, metrics, and Grafana dashboards, see Monitoring Guide.

Table of Contents

• Quick Start
• Log Levels
• Structured Logging
• Event-Based Queries
• Log File Rotation
• Troubleshooting

Quick Start

Enable OTLP Export (Recommended)

# Point to OpenTelemetry Collector (local or Grafana Cloud)
export OTLP_ENDPOINT=http://localhost:4317

wealth run

Logs, metrics, and traces are exported via OTLP gRPC. For complete OpenTelemetry setup, see Monitoring Guide - OpenTelemetry Metrics.

Local-Only Mode

If OTLP_ENDPOINT is not set, logs output to stdout/stderr:

# Optional: Enable file logging
export WEALTH__OBSERVABILITY__LOG_FILE=/tmp/wealth.log

wealth run

Log Query Examples

Basic Queries

# All logs from wealth bot
{job="wealth-bot"}

# Filter by log level
{job="wealth-bot"} |= "ERROR"
{job="wealth-bot"} |= "WARN"
{job="wealth-bot"} |= "INFO"

# Filter by level label (if parsed)
{job="wealth-bot", level="ERROR"}
{job="wealth-bot", level="INFO"}

# Filter by module
{job="wealth-bot"} |= "wealth::strategy"
{job="wealth-bot"} |= "wealth::execution"
{job="wealth-bot"} |= "wealth::market_data"

# Search for specific text
{job="wealth-bot"} |= "WebSocket"
{job="wealth-bot"} |= "arbitrage"
{job="wealth-bot"} |= "position"

Advanced Queries

# Errors in the last hour
{job="wealth-bot", level="ERROR"} [1h]

# Rate of errors per minute
rate({job="wealth-bot", level="ERROR"}[5m])

# Count logs by level
sum by (level) (count_over_time({job="wealth-bot"}[1h]))

# Logs containing correlation_id
{job="wealth-bot"} |~ "correlation_id=\\w+"

# WebSocket connection issues
{job="wealth-bot"} |~ "WebSocket.*error|WebSocket.*failed|WebSocket.*timeout"

# Order execution logs
{job="wealth-bot"} |= "Executing arbitrage" or |= "Order placed"

# Strategy-related logs
{job="wealth-bot", module=~"wealth::strategy.*"}

Event-Based Queries (Recommended)

All key log messages include a structured event field for precise filtering:

# Parse JSON and filter by event type
{service="wealth-bot"} | json | event="opportunity_detected"
{service="wealth-bot"} | json | event="arbitrage_executed"
{service="wealth-bot"} | json | event="position_close_succeeded"

# Trade skipped events (all use _skipped suffix)
{service="wealth-bot"} | json | event="quantity_validation_failed_skipped"
{service="wealth-bot"} | json | event="precision_mismatch_skipped"
{service="wealth-bot"} | json | event="unhedged_positions_skipped"
{service="wealth-bot"} | json | event="insufficient_balance_skipped"

# All skipped events
{service="wealth-bot"} | json | event=~".*_skipped"

# All position lifecycle events
{service="wealth-bot"} | json | event=~"position_.*"

# WebSocket and connection events
{service="wealth-bot"} | json | event=~"websocket_.*"

# Circuit breaker activity
{service="wealth-bot"} | json | event=~"circuit_breaker_.*"

# Error events requiring attention
{service="wealth-bot"} | json | event="unhedged_position_detected"
{service="wealth-bot"} | json | event="size_discrepancy_detected"

# Count opportunities vs executions
sum by (event) (count_over_time({service="wealth-bot"} | json | event=~"opportunity_detected|arbitrage_executed" [1h]))