Add cleaning up logic into trailing stop logic

 - Finishes #7 for real this time.

Author: Fernando Fernandes

Sources/SwiftTrader/Model/Error/SwiftTraderError.swift

@@ -17,34 +17,45 @@ public enum SwiftTraderError: Error {
 
     // MARK: - Kucoin Related
 
+    /// The response status code is something other than `200`.
+    ///
+    /// The underlying Kucoin system error may be verified by reading the returned extra arguments, if present.
+    case statusCodeNotOK(
+        statusCode: Int,
+        localizedErrorMessage: String,
+        kucoinErrorCode: String? = nil,
+        kucoinErrorMessage: String? = nil
+    )
+    
+    // MARK: Account Overview
+    
     /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesAccountOverview(currencySymbol:)`.
     case kucoinFuturesAccountOverview(error: Error)
 
+    // MARK: Cancel Stop Orders
+    
     /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesCancelStopOrders(symbol:)`.
     case kucoinFuturesCancelStopOrders(error: Error)
 
+    // MARK: Order
+    
     /// Something went wrong while trying to set the target price.
-    case kucoinCouldNotCalculateTheTargetPrice(input: SwiftTraderOrderInput)
+    case kucoinCouldNotCalculateTheTargetPrice(input: SwiftTraderStopLimitOrderInput)
+    
+    /// The offsett has to be lower than the percentage of the profit; the order will not be placed.
+    case kucoinInvalidOffset(offset: Double, profitPercentage: Double)
 
     /// The target price is lower than the entry price; the order will not be placed.
     case kucoinInvalidTargetPrice(entryPrice: String, targetPrice: String)
 
-    /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesPlaceOrder()`.
-    case kucoinPlaceOrder(error: Error)
-    
     /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesOrderList(orderStatus:)`.
     case kucoinOrderList(error: Error)
 
+    /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesPlaceStopLimitOrder()`.
+    case kucoinPlaceStopLimitOrder(error: Error)
+    
+    // MARK: Positions
+    
     /// And error ocurred while executing the function `SwiftTrader.kucoinFuturesPositionList()`.
     case kucoinPositionList(error: Error)
-    
-    /// The response status code is something other than `200`.
-    ///
-    /// The underlying Kucoin system error may be verified by reading the returned extra arguments, if present.
-    case statusCodeNotOK(
-        statusCode: Int,
-        localizedErrorMessage: String,
-        kucoinErrorCode: String? = nil,
-        kucoinErrorMessage: String? = nil
-    )
 }

Sources/SwiftTrader/Model/SwiftTraderOperation.swift

@@ -12,6 +12,6 @@ public enum SwiftTraderOperation {
     case kucoinFuturesAccountOverview
     case kucoinFuturesCancelStopOrders
     case kucoinFuturesOrderList
-    case kucoinFuturesPlaceOrder
+    case kucoinFuturesPlaceStopLimitOrder
     case kucoinFuturesPositionList
 }

Sources/SwiftTrader/Model/SwiftTraderOrderInput.swift

@@ -7,8 +7,8 @@
 
 import Foundation
 
-/// Encapsulates all the arguments required for submiting orders to supported exchanges.
-public struct SwiftTraderOrderInput {
+/// Encapsulates all the arguments required for submiting stop limit orders to supported exchanges.
+public struct SwiftTraderStopLimitOrderInput {
 
     // MARK: - Properties
 
@@ -20,17 +20,36 @@ public struct SwiftTraderOrderInput {
     public let currentPrice: Double
     public let profitPercentage: Double
     public let offset: Double
+    public let clean: Bool
 
     // MARK: - Lifecycle
 
+    /// Creates a `SwiftTraderOrderInput` instance.
+    ///
+    /// - Parameters:
+    ///   - exchange: E.g.: Kucoin, Binance
+    ///   - ticker: E.g.: BTCUSDT
+    ///   - tickerSize: E.g.: "1", "0.05", "0.00001"
+    ///   - contractSymbol: E.g.: XBTCUSDTM
+    ///   - entryPrice: E.g.: "42.856", "43567.98", "127.01".
+    ///   - currentPrice: The current price of the asset.
+    ///   - profitPercentage: The percentage of the profit at this point, e.g.: "1.5", "0.67".
+    ///   - offset: How far the **"target price"** of the stop order will be from the `currentPrice`. For example,
+    ///   suppose the `profitPercentage` is `1.0%` and the `offset` is `0.75%`. The stop order to be placed will be `0.25%`
+    ///   of the current price (`1.0%` - `0.75%`). Using the same `offset`, if the `profitPercentage` is now `2.0%`, the stop order
+    ///   will be placed at `1.25%` of the current price (`2.0%` - `0.75%`).
+    ///   - clean: When `true`, all the untriggered stop orders for the `contractSymbol` will be cancelled before placing a new one.
+    ///   Cleaning is done via `SwiftTrader.kucoinFuturesCancelStopOrders(symbol:)`. In case that fails, the execution continues
+    ///   and a new order will be placed regardless.
     public init(exchange: SwiftTraderExchange,
                 ticker: String,
                 tickerSize: String,
                 contractSymbol: String,
                 entryPrice: Double,
                 currentPrice: Double,
                 profitPercentage: Double,
-                offset: Double) {
+                offset: Double,
+                clean: Bool) {
         self.exchange = exchange
         self.ticker = ticker
         self.tickerSize = tickerSize
@@ -39,5 +58,6 @@ public struct SwiftTraderOrderInput {
         self.currentPrice = currentPrice
         self.profitPercentage = profitPercentage
         self.offset = offset
+        self.clean = clean
     }
 }

Sources/SwiftTrader/SwiftTrader+Offset.swift renamed to Sources/SwiftTrader/SwiftTrader+TrailingStop.swift

@@ -1,20 +1,20 @@
 //
-//  SwiftTrader+Offset.swift
+//  SwiftTrader+TrailingStop.swift
 //  
 //
 //  Created by Fernando Fernandes on 10.02.22.
 //
 
 import Foundation
 
-/// Creates a set of predefined parameters for interacting with target exchanges, based on a given offset.
+/// Creates a set of parameters for placing stop limit orders on the target exchange.
 ///
 /// For example: before executing a `KucoinFuturesPlaceOrdersRequest`, this extension will create
 /// a `KucoinOrderParameters` instance that can be used as an argument. The business logic for creating
-/// such instance is based on a given `SwiftTraderOrderInput`/`offset`.
+/// such instance is based on a given `SwiftTraderStopLimitOrderInput`/`offset`.
 public extension SwiftTrader {
 
-    func createOrderParameters(for input: SwiftTraderOrderInput) throws -> KucoinOrderParameters {
+    func createStopLimitOrderParameters(for input: SwiftTraderStopLimitOrderInput) throws -> KucoinOrderParameters {
         logger.log("Creating order parameters...")
 
         // E.g: 7.47 -> 0.0747
@@ -25,7 +25,11 @@ public extension SwiftTrader {
         let offset: Double = (input.offset / 100)
         logger.log("Offset: \(offset.toDecimalString())")
 
-        // E.g.: (0.0747 - 0.0073) = 0.0674 (6,74%)
+        guard offset < profitPercentage else {
+            throw SwiftTraderError.kucoinInvalidOffset(offset: offset, profitPercentage: profitPercentage)
+        }
+        
+        // E.g.: (0.0747 - 0.0075) = 0.0672 (6,72%)
         // Use "abs" to filter out negative numbers.
         let targetPercentage: Double = profitPercentage - offset
         logger.log("Target percentage: \(targetPercentage.toDecimalString())")

Sources/SwiftTrader/SwiftTrader.swift

@@ -88,23 +88,23 @@ public extension SwiftTrader {
 
     // MARK: Place Orders
 
-    /// Places a Futures order.
+    /// Places a Futures stop limit order.
     ///
     /// https://docs.kucoin.com/futures/#place-an-order
     ///
     /// - Parameter orderInput: `SwiftTraderOrderInput` instance that encapsulates
-    /// all the arguments required for submiting the orders.
+    /// all the arguments required for submiting the stop limit order.
     /// - Returns: An instance of `KucoinFuturesPlaceOrder` or `SwiftTraderError`.
-    func kucoinFuturesPlaceOrder(_ orderInput: SwiftTraderOrderInput) async throws -> Result<KucoinFuturesPlaceOrder, SwiftTraderError> {
+    func kucoinFuturesPlaceStopLimitOrder(_ stopLimitOrderInput: SwiftTraderStopLimitOrderInput) async throws -> Result<KucoinFuturesPlaceOrder, SwiftTraderError> {
 
-        #warning("TODO: parameterize cleaning up untriggered stop orders")
-        let orderParameters = try createOrderParameters(for: orderInput)
-    
-        do {
-            #warning("TODO: test")
-            try await kucoinFuturesCancelStopOrders(symbol: orderInput.contractSymbol)
-        } catch {
-            #warning("TODO: log")
+        let orderParameters = try createStopLimitOrderParameters(for: stopLimitOrderInput)
+    
+        if stopLimitOrderInput.clean {
+            do {
+                try await kucoinFuturesCancelStopOrders(symbol: stopLimitOrderInput.contractSymbol)
+            } catch {
+                logger.log("Could not cancel untriggered stop orders: \(error)")
+            }
         }
 
         let request = KucoinFuturesPlaceOrdersRequest(
@@ -119,7 +119,7 @@ public extension SwiftTrader {
             }
             return .success(placeOrder)
         case .failure(let error):
-            let swiftTraderError = handle(networkRequestError: error, operation: .kucoinFuturesPlaceOrder)
+            let swiftTraderError = handle(networkRequestError: error, operation: .kucoinFuturesPlaceStopLimitOrder)
             return .failure(swiftTraderError)
         }
     }
@@ -193,8 +193,8 @@ private extension SwiftTrader {
                 return .kucoinFuturesCancelStopOrders(error: networkRequestError)
             case .kucoinFuturesOrderList:
                 return .kucoinOrderList(error: networkRequestError)
-            case .kucoinFuturesPlaceOrder:
-                return .kucoinPlaceOrder(error: networkRequestError)
+            case .kucoinFuturesPlaceStopLimitOrder:
+                return .kucoinPlaceStopLimitOrder(error: networkRequestError)
             case .kucoinFuturesPositionList:
                 return .kucoinPositionList(error: networkRequestError)
             }