Connecting a bot to your exchange

This is what a user does on their own machine, and what you do on yours if you run a bot outside the Bot Instances panel. The page at /hb/setup walks the same first four steps with live status derived from the account's real keys, and adds an optional fifth for the local agent — so send people there rather than to a copy of the commands.

What has to be true first

A bot needs four things from the exchange and one of them cannot be put in a file:

The kit deliberately contains nothing account-specific — no key, no secret, no base URL. Those belong in connect, not in a zip thousands of people download, which is also what makes it safe for any authenticated user to fetch.

Step 1 — install the connector

Hummingbot has no idea your exchange exists until a package named bicrypto is inside its own checkout. Until then connect bicrypto answers "not a valid connector" and nothing is logged, because Hummingbot's discovery imports each connector inside a bare except ModuleNotFoundError: continue — an absent or unimportable connector is silently skipped rather than reported.

Download the kit from Connect your bot, unzip it next to the checkout, and run the installer inside the Hummingbot conda environment:

conda activate hummingbot
python install_connectors.py /path/to/your/hummingbot

python install_connectors.py /path/to/your/hummingbot --doctor

python install_connectors.py /path/to/your/hummingbot --clean

The installer places both packages (spot and perpetual) and the controller module, patches setup.py, and then imports everything to prove it worked. If it reports that setup.py changed, rebuild before starting Hummingbot:

./install && ./compile

Run the installer with the same interpreter the bot runs. A verification that passes under a different Python can pass while Hummingbot still fails to import.

Step 2 — mint a key and connect it

Create the key at /hb/keys. Pick the narrowest preset that does the job:

Optional but worth doing: restrict the key by IP, so a leaked secret is unusable from anywhere else, and set an expiry to force rotation. An IP-restricted key with an empty allowlist denies everything — that is deliberate, because an empty list previously meant allow-all and silently defeated the restriction the user had just switched on.

Then, inside Hummingbot:

connect bicrypto

Three prompts:

For perpetuals the connector is bicrypto_perpetual and connects the same way.

Verify with balance. You should see the assets in the Funding (ECO) wallet for the spot connector, and the Futures wallet for the perpetual one.

Step 3 — add a strategy

Download a preset from /hb/strategies. What you get is a V2 controller config, and Hummingbot never starts one of those directly: a script config names the controller, and you start the script.

id: my-strategy
controller_name: bicrypto_pmm
controller_type: market_making
connector_name: bicrypto
trading_pair: BTC-USDT

script_file_name: v2_with_controllers.py
controllers_config:
  - my-strategy.yml

Every downloaded preset prints this two-file layout in its own header comment, naming the exact filenames to save it under.

Step 4 — start it

conda activate hummingbot
python bin/hummingbot_quickstart.py --headless --v2 my-strategy.yml

Or start --v2 my-strategy.yml from inside an interactive session. The flag takes the script config's name, resolved against conf/scripts/. Passing the controller's filename is the usual mistake and fails with "V2 config file not found". If your build rejects the flag, run start --help — the option name has moved between Hummingbot releases, and the config files are valid either way.

An MQTT bridge warning every five seconds is expected and unavoidable in headless mode: Hummingbot forces mqtt_autostart on whenever --headless is passed and raises if it is off, so there is no configuration that both keeps headless working and silences the bridge. Nothing in the connector depends on it.

Step 5 — confirm it is actually talking to the exchange

Open /hb/console. The setup page and the console both compute one honest verdict from the account's real records, because a customer cannot "connect" a bot from a web page — detecting the link is the only truthful thing either surface can do:

A tie between a success and a rejection in the same second resolves to the rejection. Both are recorded to the nearest second and a bot polls several times a second, so the exact situation this status exists to describe — last success moments before a block, everything since refused — otherwise landed in one second and reported "your bot is connected" during an emergency stop.

Clock drift is the failure nobody expects

Signed requests carry a timestamp and are refused more than 10 seconds away from the exchange's clock. The rejection is recorded against the key and names the direction and size of the drift:

Request outside recvWindow: this machine's clock is 12400ms ahead of the
exchange, limit 10000ms. Sync the clock on the machine running the bot.

Being ahead is the case people do not expect a receive window to reject, which is why the direction is stated rather than an absolute difference. Enable NTP on the bot's host. Anything drifting more than five minutes is refused before the key is even looked up, so probe traffic never reaches your account records.

Where to go next

• Strategies and presets — every PMM and XEMM parameter, and how to tune them.
• Monitoring and stopping bots — the console, the emergency stop and the optional local agent.
• Troubleshooting — connect not listing the connector, empty balances, empty books.