Comprehensive API Documentation for Hyperforge - Trading Bot Development Kit

Welcome to the Hyperforge Trading Bot API Documentation!

This guide walks you through the primary functions provided by the Hyperforge - Trading Bot Development Kit, helping you automate trading strategies on Gate.io. We will cover key functionalities such as fetching balance, placing stop-limit orders, managing trades, applying slippage protection, and taking profits. The API is designed for integration with the CCXT library, enabling smooth interaction with the Gate.io exchange.

Table of Contents

1. Overview of Hyperforge API

2. Library Functions: Balance Fetching

3. Library Functions: Stop-Limit Orders

4. Library Functions: Order Management

5. Slippage Protection Mechanism (Work in Progress)

6. Order Book Analysis

7. Take Profit Functionality (Work in Progress)

8. Average Price & Amount Calculations

9. Telegram Notification System

   
   

1. Overview of Hyperforge API

The Hyperforge API provides an interface for automated trading on the Gate.io exchange, focusing on:

• Fetching balance information and tracking available/locked balances.

• Placing stop-limit buy/sell orders with a fallback mechanism.

• Managing open buy/sell orders and canceling obsolete ones.

• Tracking unresolved trades and applying slippage protection.

• Automatically taking profit when a specified target balance is reached.

• Calculating average trade prices and fetching available asset amounts.

  
  

2. Library Functions: Balance Fetching

Function: getBalance()

Purpose:

Fetches the current balance from the Gate.io exchange and returns it as a formatted string.

Returns:

• balance_text (str): Formatted balance information as a string.

Pseudo Code:

1. Fetch the current balance using exchange.fetch_balance().

2. Format the balance data into a string.

3. Return the formatted string.

Example:

in python
def getBalance():
	balance = exchange.fetch_balance()
	balance_text = "BALANCE:"
	for info in balance['info']:
		balance_text += str(info) print(balance_text)
		return balance_text

3. Library Functions: Stop-Limit Orders

Function: create_stop_limit_buy_order(symbol, amount, stop_buy_price, limit_buy_price, enableInsteadMode)

Purpose:

Places a stop-limit buy order for a trading pair, with an optional fallback to a normal limit buy order.

Returns:

• Success: Confirmation of the stop-limit order placement or fallback order.

• Failure: Error message if the order fails.

Parameters:

• symbol (str): Trading pair (e.g., BTC/USDT).

• amount (float): Amount to buy.

• stop_buy_price (float): The stop price to trigger the buy order.

• limit_buy_price (float): The limit price for the buy order.

• enableInsteadMode (bool): If True, places a regular limit buy order if the stop-limit order fails.

Function: create_stop_limit_sell_order(symbol, amount, stop_sell_price, limit_sell_price, enableInsteadMode)

Purpose:

Places a stop-limit sell order for a trading pair, with an optional fallback to a normal limit sell order.

Returns:

• Success: Confirmation of the stop-limit order placement or fallback order.

• Failure: Error message if the order fails.

Parameters:

• symbol (str): Trading pair (e.g., BTC/USDT).

• amount (float): Amount to sell.

• stop_sell_price (float): The stop price to trigger the sell order.

• limit_sell_price (float): The limit price for the sell order.

• enableInsteadMode (bool): If True, places a regular limit sell order if the stop-limit order fails.

  
  

4. Library Functions: Order Management

Function: manage_open_buy_orders(open_orders)

Purpose:

Manages open buy orders and cancels the lowest-priced orders if the number of buy orders exceeds a certain threshold.

Returns:

• Success: Confirmation of the order cancellation(s).

• Failure: Error message if the cancellation fails.

Parameters:

• open_orders (list): A list of open buy orders.

Function: manage_open_sell_orders(open_orders)

Purpose:

Manages open sell orders and cancels the highest-priced orders if the number of sell orders exceeds a certain threshold.

Returns:

• Success: Confirmation of the order cancellation(s).

• Failure: Error message if the cancellation fails.

Parameters:

• open_orders (list): A list of open sell orders.

Function: cancel_order(order_id, symbol)

Purpose:

Cancels a specific order by its order ID on the exchange.

Returns:

• Success: Confirmation that the order has been canceled.

• Failure: Error message if the cancellation fails.

Parameters:

• order_id (str): The ID of the order to cancel.

• symbol (str): The trading pair of the order (e.g., BTC/USDT).

  
  

5. Slippage Protection Mechanism (Work in Progress)

Function: check_for_slippage()

Purpose:

Checks unresolved trades and applies slippage protection by automatically selling trades that have suffered significant price drops or have been unresolved for too long.

Returns:

• Success: Confirmation of the sell action taken for trades.

• Failure: Error message if the sell action fails.

Function: adaptive_protection(trade)

Purpose:

Applies slippage protection logic by checking whether the trade should be sold based on time elapsed and price movement.

Returns:

• Success: Confirmation of the adaptive protection action taken.

• Failure: Error message if the action fails.

Parameters:

• trade (dict): The trade to protect, containing information such as price, timestamp, and amount.

Function: place_market_sell_order(symbol, amount)

Purpose:

Places a market sell order to quickly exit a trade if the price has dropped significantly or the trade has been unresolved for too long.

Returns:

• Success: Confirmation of the market sell order placement.

• Failure: Error message if the order fails.

Parameters:

• symbol (str): The trading pair to sell (e.g., BTC/USDT).

• amount (float): The amount to sell.

  
  

6. Order Book Analysis

Function: analyze_order_book(symbol)

Purpose:

Analyzes the order book for a specific symbol and identifies the optimal bid and ask prices based on cumulative volume.

Returns:

• optimal_bid_price (float): The best bid price based on cumulative volume.

• optimal_ask_price (float): The best ask price based on cumulative volume.

Parameters:

• symbol (str): The trading pair to analyze (e.g., BTC/USDT).

  
  

7. Take Profit Functionality (Work in Progress)

Function: take_profit_if_target_reached(total_balance, initial_balance, asset_balances, locked_balances, takeProfitTargetPercentage)

Purpose:

Takes profits by selling all assets when the total balance reaches a target balance.

Returns:

• Success: Confirmation that profits have been taken.

• Failure: Error message if the profit-taking process fails.

Parameters:

• total_balance (float): The current total balance of the account.

• initial_balance (float): The initial balance before trading started.

• asset_balances (dict): A dictionary of asset balances.

• locked_balances (dict): A dictionary of locked asset balances.

• takeProfitTargetPercentage (float): The target profit percentage to trigger the take-profit action.

8. Average Price & Amount Calculations

Function: generate_trade_summary(symbol, queryTradesInMinutes, currentBalanceText)

Purpose:

Generates a summary of average price, available amount, and total cost for a trading pair over a specified time period.

Returns:

• averagePrice (float): The weighted average price of trades.

• availAmount (float): The available amount of the symbol.

• total_cost (float): The total cost of the available assets.

Parameters:

• symbol (str): The trading pair to analyze (e.g., BTC/USDT).

• queryTradesInMinutes (int): The time window (in minutes) to fetch trade data.

• currentBalanceText (str): The current balance information in text format.

Function: get_available_amount(symbol, currentBalanceText)

Purpose:

Fetches the available amount of a specific symbol from the balance text.

Returns:

• available_amount (float): The available amount of the specified symbol.

Parameters:

• symbol (str): The trading pair to query (e.g., BTC/USDT).

• currentBalanceText (str): The current balance information in text format.

Function: get_average_price_of_trades(symbol, minutes)

Purpose:

Calculates the average price of trades for a specific symbol over the past specified number of minutes.

Returns:

• average_price (float): The weighted average price of trades, or None if no trades were found.

Parameters:

• symbol (str): The trading pair to analyze (e.g., BTC/USDT).

• minutes (int): The time window in minutes to fetch trade data.

  
  

9. Telegram Notification System

Function: telegram_bot_sendtext(bot_message)

Purpose:

Sends a message to a Telegram bot for real-time notifications regarding trades, errors, and other events.

Returns:

• response (dict): The response from the Telegram API, confirming whether the message was successfully sent.

Parameters:

• bot_message (str): The message to send to the Telegram bot.

  
  

Conclusion

This Hyperforge API Documentation offers a powerful and modular toolkit for automating your trading strategies on Gate.io. With its comprehensive features for fetching balance, placing orders, managing trades, and tracking slippage, Hyperforge is designed to optimize the trading experience.

By leveraging the provided API, developers can efficiently build and expand upon their trading strategies while maintaining full control over order execution, risk management, and profit-taking.