Troubleshooting Guide

Common issues and solutions when running the Wealth trading bot.

Table of Contents

Authentication Errors

Error: Binance API error (status=401, code=-2015): Invalid API-key

Causes:

  • Incorrect API key or secret
  • API key not enabled for futures trading
  • IP address not whitelisted
  • API key expired or revoked

Solutions:

  1. Verify API key is correct:

    wealth config show

  2. Check IP whitelist on your exchange (Binance → API Management → Edit API)

  3. Ensure API permissions include "Futures Trading"

  4. Regenerate keys if unsure and update configuration

Prevention:

  • Use encrypted credentials instead of environment variables
  • Enable IP whitelisting after creating API keys
  • Test on testnet before live trading

Timestamp Errors

Error: Binance API error (status=400, code=-1021): Timestamp out of sync

Causes:

  • System clock drift
  • NTP service not running
  • Network latency issues

Solutions:

# Sync system clock with NTP
sudo ntpdate -s time.nist.gov

# Or use systemd-timesyncd
sudo systemctl restart systemd-timesyncd
sudo timedatectl status

# Install chrony (recommended for production)
sudo apt install chrony
sudo systemctl enable chrony
sudo systemctl start chrony

Verification:

timedatectl
# Should show: System clock synchronized: yes

Insufficient Balance

Error: Binance API error (status=400, code=-2019): Margin insufficient

Causes:

  • Insufficient USDT in futures wallet
  • Existing positions using available margin
  • Position size exceeds available balance

Solutions:

  1. Check current balance:

    wealth balance

  2. Transfer funds to your futures wallet on the exchange

  3. Reduce position size in config.toml:

    [trading]
max_position_usd = 5000  # Lower this value

  4. Close existing positions if needed:

    wealth close --all

Rate Limiting

Error: Rate limit exceeded or 429 Too Many Requests

Causes:

  • Too many API requests in short time
  • Aggressive polling settings
  • Multiple bot instances sharing API keys

Solutions:

  1. Wait and retry - Rate limits typically reset in 1-5 minutes

  2. Check for multiple instances:

    ps aux | grep wealth

  3. Upgrade exchange tier for higher limits (Binance VIP, Bybit API tier)

  4. Spread API keys across different bots if running multiple

WebSocket Issues

Error: WebSocket connection failed or WebSocket disconnected

Causes:

  • Unstable internet connection
  • Firewall blocking WebSocket connections
  • Exchange maintenance

Solutions:

  1. Check internet connection:

    ping fapi.binance.com
ping api.bybit.com

  2. Allow WebSocket connections through firewall (port 443)

  3. Check exchange status:

    • Binance: https://www.binance.com/en/support/announcement
    • Bybit: https://announcements.bybit.com/

  4. Restart the bot - It auto-reconnects, but a restart ensures clean state:

    # Stop with Ctrl+C, then restart
wealth run

Connection Issues

Error: Failed to connect to exchange or Network error

Causes:

  • DNS resolution failure
  • Network timeout
  • Exchange API down

Solutions:

  1. Test connectivity:

    curl -I https://fapi.binance.com
curl -I https://api.bybit.com
curl -I https://api.hyperliquid.xyz

  2. Check DNS:

    nslookup fapi.binance.com

  3. Use alternative DNS (Google: 8.8.8.8, Cloudflare: 1.1.1.1)

Configuration Issues

Error: Configuration validation failed

Solutions:

  1. Validate configuration:

    wealth verify

  2. Check config file syntax:

    cat config.toml

  3. Use example config as reference:

    cp config.example.toml config.toml
# Then edit with your values

Credential Issues

Error: Failed to decrypt credentials

Causes:

  • Wrong passphrase
  • Missing credentials file
  • Corrupted credentials file

Solutions:

  1. Verify passphrase is set correctly:

    echo $CREDENTIALS_PASSPHRASE

  2. Check credentials file exists:

    ls -la credentials.encrypted.json

  3. Re-create credentials if corrupted:

    export CREDENTIALS_PASSPHRASE="your_passphrase"
wealth credentials create
wealth credentials add binance YOUR_KEY YOUR_SECRET
wealth credentials verify

Health Check

Quick diagnostic commands:

# Check bot health
curl http://localhost:9090/health | jq

# Check positions
wealth positions

# Check balances
wealth balance

# Verify configuration
wealth verify

# View current config
wealth config

Common Log Messages

Normal Operation

  • Initializing bot | mode=paper_trading - Starting in paper mode
  • WebSocket connected - Exchange connection established
  • Bot running | metrics_port=9090 - Bot is operational

Warnings (Usually OK)

  • Opportunity detected but spread too low - Normal filtering
  • Skipping execution: insufficient balance - Not enough funds for trade
  • Rate limit approaching - Consider reducing activity

Errors (Need Attention)

  • Authentication failed - Check API credentials
  • Order placement failed - Check balance and configuration
  • WebSocket disconnected - Network issue, will auto-reconnect

Getting Help

If you can't resolve an issue:

  1. Check logs for detailed error messages:

    wealth run --verbose 2>&1 | tee bot.log

  2. Collect diagnostic info:

    wealth --version
wealth verify
curl http://localhost:9090/health

  3. Test in paper mode first:

    export WEALTH__EXECUTION__MODE=paper
wealth run

See Also