Introduction - Connectors¶
What are connectors?¶
Exchange connectors are modules that allow Hummingbot to connect to an exchange. Connecting to an exchange requires constant retrieval of live exchange/order book data as well as handling interactions with the exchange.
Examples / templates¶
There are existing connectors (each folder contained here is a different exchange connector) that can serve as a template for creating a new exchange connector.
Building a new exchange connector requires conforming to the template code to the new exchange's APIs, identifying and handling any differences in functions/behaviors, and testing the new exchange connector on that exchange.
- Centralized exchange: Binance, Coinbase Pro, Huobi, Bittrex
- Ethereum DEX (0x open order book): Radar Relay
- Ethereum DEX (0x open order book w/coordinator support): Bamboo Relay
Exchange connector requirements¶
- A complete set of exchange connector files as listed above.
Unit tests (see existing unit tests):
- Code commenting (particularly for any code that is materially different from the templates/examples)
- Any specific instructions for the use of that exchange connector (example)
Requirements for community-developed connectors¶
If you would like to create a connector for a currently unsupported exchange, please contact the Hummingbot team to discuss beforehand and for approval. Due to the large amount of work in reviewing, testing, and maintaining exchange connectors, we will only merge in connectors that will have a meaningful benefit and impact to the Hummingbot community.
Introducing an exchange connector into the Hummingbot code base requires a mutual commitment from the Hummingbot team and community developers to maintaining a high standard of code quality and software reliability.
We encourage and welcome contributions from the community, subject to the guidelines and expectations outlined below.
Guidelines for community developers¶
- Provide a point of contact to the Hummingbot team.
- Commitment to connector maintenance and keeping it up to date with Hummingbot releases.
Any connectors that are not kept up to date or have unaddressed bugs will be removed from subsequent releases of Hummingbot unless such issues are resolved.
- Adhere to contributing guide, code conventions used in the Hummingbot repo, and these guidelines outlined here.
- Complete all of the work listed in Exchange connector requirements.
- Address any comments or issues raised by the Hummingbot development team during the code review process.
- Notify the Hummingbot team and community of any known issues are bugs that are discovered.
- The best way to create a connector that adheres to Hummingbot’s standard is by cloning the logic of existing connectors. We’ve done a lot of work to build our core connectors, so no need to reinvent the wheel.
- Existing connector files to use as code samples are in Exchange connector requirements.
- While we don't require developers to have every file (You don’t need to implement a user stream if the exchange doesn’t support user stream, for instance), some general guidelines are:
- Websocket > Rest. Hummingbot is a high-frequency trading bot, which means it’d perform better when it has all the information in real-time.
- Adhere to conventions. Using the same naming pattern / code structure will help our developers review your code and get your connector approved faster.
- Always add in-code comments for your custom logic.
- Required functionalities;
- Tracking real-time order book snapshots / diffs / trades
- Getting prices from top of the order book
- Order parameter quantization (Adjust any order price / quantity inputs into values accepted by the exchange, taking into account min / max order size requirement, number of digits, etc)
- Submitting limit buy and sell orders
- Submitting market buy and sell orders
- Cancelling a single order
- Cancelling all orders that the bot submitted
- Tracking all in-flight orders
- Updating statuses of in-flight orders
- Updating user balance (all balance & balance available for trading)
- Any other functionalities / error handling required in order to trade on the exchange
- Extensive unit tests that cover all functionalities above
- Once the PR is submitted, our developers will review your code and likely request changes. Please expect the review process to take 2-3 weeks before the PR is merged.
- After the requirements above are fulfilled, we will merge the PR to
developmentbranch, which will be merged into
masterin the next release.
- In the future, we may separate community-contributed connectors and strategies from the core Hummingbot codebase, so that users can choose to install exchange connectors that they are using. However, we will not do that right now.
General Note on Trading Pair Conversion: HummingBot's standard pair format is:
Quote_Asset. Therefore, a new connector that doesn't follow that convention of naming pairs would require both
convert_from_exchange_trading_pairmethods to be implemented in the connector's market.pyx file. In addition, such connectors have to convert trading pairs in the
execute_sellmethods using the
convert_to_exchange_trading_pairbefore placing order and also ensure that the dictionary keys for
self._trading_rulesare in HummingBot's pair format using
Expectations for the Hummingbot team¶
- Make available a dedicated channel on discord (https://discord.hummingbot.io) during the initial development process.
- Provide a main point of contact for the developer.
- Notify developer of code changes that may affect the connector.
- Notify the developer of any bug reports or issues reported by Hummingbot users.
- Code review.
- Testing and QA.
The Hummingbot team reserves the right to withhold community code contributions and excluding them from the Hummingbot code base should any such contributions fail to meet the above requirements.
- Prior Cython experience is a plus