Adding Exchange 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.
Each exchange connector is comprised of the following components:
|(1) Trade execution||Sending buy/sell/cancel instructions to the exchange.|
|(2) Conforming order book data||Formatting an exchange's order book data into the standard format used by Hummingbot.|
|(3) Order book tracking||State management: tracking exchange's real-time order book data.|
|(4) Active order tracking||State management: tracking orders placed by the bot on the exchange.|
|(5) User stream tracker||Tracking data specific to the user of the bot.|
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
- Ethereum DEX (0x open order book): Radar Relay
- Ethereum DEX (0x open order book w/coordinator support): Bamboo Relay
- Ethereum DEX (matcher model): DDEX
- Ethereum DEX (deposit/redeem model): IDEX
Exchange connector files¶
Each exchange connector consists of the following files:
1 2 3 4 5 6 7 8
<market_name> # folder for specific exchange ("market") ├── *_market # handles trade execution (buy/sell/cancel) ├── *_auth # handles authentication for API requests (for CEX) ├── *_data_source # initializes and maintains a websocket connection ├── *_order_book # takes order book data and formats it with a standard API ├── *_order_book_tracker # maintains a copy of the market's real-time order book ├── *_active_order_tracker # for DEXes that require keeping track of └── *_user_stream_tracker # tracker that process data specific to the user running the bot
||Connector modules are centered around a
||This class handles the work of creating access requests from information provided by Hummingbot. Arguments tend to include:
Depending on the specific exchange, different information may be needed for authorization. Typically, the
Placing and tracking orders¶
Market classes place orders via
execute_sell commands, which require the following arguments:
- The order ID
- The market symbol
- The amount of the order
- The type (limit or market)
- The price, if limit order
execute_sell methods verify that the trades would be legal given the trading rules pulled from the exchange and calculate applicable trading fees. They then must do the following:
- Quantize the order amount to ensure that the precision is as required by the exchange
- Create a
paramsdictionary with the necessary parameters for the desired order
- Pass the
Authobject to generate the signature and place the order
- Pass the resulting order ID and status along with the details of the order to an
InFlightOrders are stored within a list in the
Market class, and are Hummingbot’s internal records of orders it has placed that remain open on the market. When such orders are either filled or canceled, they are removed from the list and the relevant event completion flag is passed to the strategy module.
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¶
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.
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