DEV Community

Cover image for Hummingbot Arbitrage Usage Guide
Einar César
Einar César

Posted on

Hummingbot Arbitrage Usage Guide

#python #tutorial

Table of Contents

  1. Introduction
  2. Installation
  3. Hummingbot Commands
  4. Initial Configuration
  5. Connecting Exchanges
  6. Cross Exchange Market Making
  7. Spot-Perpetual Arbitrage
  8. Monitoring
  9. Troubleshooting
  10. Official Resources

Introduction

What is Hummingbot?

Hummingbot is an open-source algorithmic trading platform that allows you to create and execute automated trading strategies across multiple cryptocurrency exchanges.

Main Architecture:

  • CLI (Command Line Interface)
  • Cython-based system for high performance
  • Connectors for 30+ exchanges
  • v1 strategies (traditional) and v2 (modular)

What is Cython?

Cython = Python + C Performance

Cython is an extension which gives Python a C-like performance. Hummingbot uses Cython for performance-critical components:

  • Clock System (clock.pyx) - Ultra-precise timing for trading operations
  • Order Books - Lightning-fast order book processing
  • Event System - Instant event propagation for market data
  • Strategy Base - High-speed execution of trading logic

This gives Hummingbot near C-language speed for critical operations while maintaining Python's flexibility. Essential for arbitrage where milliseconds matter in capturing market opportunities.

Available Arbitrage Strategies

  1. Cross Exchange Market Making - Makes market on one exchange using prices from another
  2. Spot Perpetual Arbitrage - Exploits differences between spot and perpetual markets
  3. AMM Arbitrage - Arbitrage with Automated Market Makers

Installation

Docker (Recommended) 

# Clone repository
git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot

# Start with Docker Compose
docker compose up -d

# Connect to container
docker attach hummingbot
Enter fullscreen mode Exit fullscreen mode

Source 

git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot
pip install -e .
python bin/hummingbot.py
Enter fullscreen mode Exit fullscreen mode

Using Conda/Miniconda:

git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot
conda activate hummingbot
./install
./compile
./start
Enter fullscreen mode Exit fullscreen mode

Hummingbot Commands

The available commands in Hummingbot are:

Essential Commands

  • help - Shows general help or specific command help
  • connect [exchange] - Connects to an exchange
  • create - Creates new strategy
  • import [config] - Imports existing configuration
  • start [strategy] - Starts strategy
  • stop - Stops active strategy
  • status - Shows current status
  • balance - Shows exchange balances
  • history - Shows trade history
  • config [parameter] - Configures parameters
  • export - Exports data to CSV
  • exit - Exit Hummingbot

Information Commands

  • ticker [exchange] [pair] - Shows current prices
  • order_book [exchange] [pair] - Shows order book
  • rate - Shows rate oracle conversion rates

Advanced Commands

  • gateway [subcommand] - Gateway commands (DEX)
  • mqtt [subcommand] - MQTT commands for automation

Initial Configuration

1. First Access

When starting Hummingbot for the first time:

# Set password for encryption
Enter your new password: ********
Please reconfirm your password: ********
Enter fullscreen mode Exit fullscreen mode

2. Global Configuration 

# View current configurations
config

# Configure important parameters
config kill_switch_mode
>>> kill_switch_enabled

config kill_switch_rate
>>> -5.0  # Stop if losing 5%

config rate_oracle_source
>>> binance
Enter fullscreen mode Exit fullscreen mode

3. View Initial Status 

status
# Shows current configurations and connections
Enter fullscreen mode Exit fullscreen mode

Connecting Exchanges

Binance 

connect binance

# Follow prompts for:
# - API Key
# - Secret Key  
# - For testnet, provide testnet keys
Enter fullscreen mode Exit fullscreen mode

OKX 

connect okx

# Follow prompts for:
# - API Key
# - Secret Key
# - Passphrase
# - Environment (live/sandbox)
Enter fullscreen mode Exit fullscreen mode

Hyperliquid 

connect hyperliquid

# Follow prompts for:
# - Private Key
# - Vault Address (optional)
Enter fullscreen mode Exit fullscreen mode

Verify Connections 

balance
# Shows balances from all connected exchanges

status
# Shows connection status
Enter fullscreen mode Exit fullscreen mode

Cross Exchange Market Making

1. Create Strategy 

create

# Follow prompts:
What is your market making strategy?
>>> cross_exchange_market_making

Import previous configs or create a new config file?
>>> create

Enter a configuration name for your strategy:
>>> my_xemm_strategy
Enter fullscreen mode Exit fullscreen mode

2. Strategy Configuration

During creation, configure:

  • Maker Market: Exchange where you'll place limit orders
  • Taker Market: Exchange for market orders
  • Trading Pairs: Pairs to trade (e.g., BTC-USDT)
  • Min Profitability: Minimum profitability (e.g., 0.003 = 0.3%)
  • Order Amount: Order size
  • Conversion Rate: rate_oracle recommended

3. Execute 

start my_xemm_strategy

# Monitor with:
status
history
Enter fullscreen mode Exit fullscreen mode

4. Stop 

stop
Enter fullscreen mode Exit fullscreen mode

Spot-Perpetual Arbitrage

1. Create Strategy 

create

What is your market making strategy?
>>> spot_perpetual_arbitrage

Import previous configs or create a new config file?
>>> create

Enter a configuration name for your strategy:
>>> spot_perp_arb
Enter fullscreen mode Exit fullscreen mode

2. Configuration

During creation:

  • Spot Connector: Spot exchange (e.g., binance)
  • Derivative Connector: Perpetual exchange (e.g., hyperliquid_perpetual)
  • Trading Pairs: Corresponding pairs
  • Min Divergence: Minimum difference for trading
  • Order Amount: Order size
  • Max Inventory: Maximum exposure allowed

3. Execute and Monitor 

start spot_perp_arb

# Monitor:
status
balance
history
Enter fullscreen mode Exit fullscreen mode

Monitoring

Monitoring Commands 

# General status
status

# Balances
balance

# Trade history
history

# Current prices
ticker binance BTC-USDT

# Order book
order_book binance BTC-USDT
Enter fullscreen mode Exit fullscreen mode

Export Data 

# Export history to CSV
export

# Follow prompts to choose period and format
Enter fullscreen mode Exit fullscreen mode

Runtime Configuration 

# Adjust parameters without stopping strategy
config min_profitability
>>> 0.004

config order_amount
>>> 0.005
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Connection Issues 

# Check connection status
status

# Reconnect exchange
connect binance

# Check balances
balance
Enter fullscreen mode Exit fullscreen mode

Strategy Issues 

# View current configuration
config

# Stop strategy
stop

# Reconfigure if necessary
config [parameter]
>>> new_value

# Restart
start [strategy_name]
Enter fullscreen mode Exit fullscreen mode

Debug 

# Increase log verbosity
config log_level
>>> DEBUG

# View detailed configurations
help config
Enter fullscreen mode Exit fullscreen mode

Important Configurations

Kill Switch 

config kill_switch_mode
>>> kill_switch_enabled

config kill_switch_rate
>>> -5.0  # Stop with 5% loss
Enter fullscreen mode Exit fullscreen mode

Rate Oracle 

config rate_oracle_source
>>> binance  # or coingecko, kucoin, etc.
Enter fullscreen mode Exit fullscreen mode

Logging 

config log_level
>>> INFO  # or DEBUG for more details
Enter fullscreen mode Exit fullscreen mode

Configuration Files

Configurations are stored in conf/:

  • conf_client.yml - Global configurations
  • conf_[strategy_name]_strategy.yml - Strategy configurations
  • conf_fee_overrides.yml - Fee overrides

MQTT (Advanced Automation) 

# Start MQTT bridge
mqtt start

# Stop MQTT bridge  
mqtt stop

# MQTT status
mqtt status
Enter fullscreen mode Exit fullscreen mode

Gateway (for DEX) 

# Check Gateway status
gateway status

# Connect to Gateway
gateway connect

# List available connectors
gateway list
Enter fullscreen mode Exit fullscreen mode

Official Resources

Documentation

Community

Scripts and Tools

Limitations and Warnings

Risks

  • Automated trading involves significant risks
  • Always test on testnet first
  • Monitor positions regularly
  • Use kill switch for protection

Support

  • For bugs: GitHub Issues
  • For questions: Discord
  • For documentation: Official website

Guide based on actual Hummingbot v2.7.0+ source code

Top comments (0)