Untrade SDK#

Installation#

Execute the git clone command:

git clone https://github.com/ztuntrade/untrade-sdk.git && cd untrade-sdk

Install the package using pip3:

pip3 install .

Initialisation#

To start using the Untrade API, first initialize the client:

from untrade.client import Client
client = Client()

Module Functions#

Create New Order#

To create a new order, use the following function:

client.create_order(
    symbol="BTCUSDT",
    side="BUY",
    type="MARKET",
    market="COIN-M",
    quantity=100,
    leverage=10,
    target=45000,
    stop_loss=35000
)

Parameters:

symbol (string): The trading pair symbol (e.g., BTCUSDT, ETHUSDT).
side (string): ‘BUY’ or ‘SELL’.
type (string): ‘LIMIT’ or ‘MARKET’.
market (string): ‘SPOT’, ‘COIN-M’, or ‘USD-M’.
quantity (float, optional): Trade quantity.
leverage (int, optional): Leverage for the trade (for non-SPOT markets).
target (float, optional): Target price.
stop_loss (float, optional): Stop loss price.
price (float, optional): Entry price (for LIMIT orders).
position (float, optional): Position size.

Close Order#

Closes an existing trading order.

client.close_order(
     symbol="BTCUSDT",
     market="COIN-M",
     parent_order_id="68b195ec-150e-47e1-8e01-694b719acdd8"
)

Parameters:

symbol (string): The trading pair symbol (e.g., BTCUSDT, ETHUSDT).
market (string): ‘SPOT’, ‘COIN-M’, or ‘USD-M’.
parent_order_id (string): The ID of the parent order being closed.

Target Order#

…

client.create_target_order(
     symbol="BTCUSDT",
     type="TAKE_PROFIT_MARKET",
     market="COIN-M",
     stop_price=45000,
     parent_order_id="68b195ec-150e-47e1-8e01-694b719acdd8"
)

Parameters:

symbol (string): The trading pair symbol (e.g., BTCUSDT, ETHUSDT).
type (string): ‘TAKE_PROFIT_MARKET’.
market (string): ‘SPOT’, ‘COIN-M’, or ‘USD-M’.
stop_price (float): Stop price for target.
parent_order_id (string): The ID of the parent order being closed.

Stop-Loss Order#

…

client.create_stoploss_order(
     symbol="BTCUSDT",
     type="STOP_MARKET",
     market="COIN-M",
     stop_price=35000,
     parent_order_id="68b195ec-150e-47e1-8e01-694b719acdd8"
)

Parameters:

symbol (string): The trading pair symbol (e.g., BTCUSDT, ETHUSDT).
type (string): ‘STOP_MARKET’.
market (string): ‘SPOT’, ‘COIN-M’, or ‘USD-M’.
stop_price (float): Stop Price of stop-loss.
parent_order_id (string): The ID of the parent order being closed.

Backtest#

Use the following method to initiate a backtest:

client.backtest(file_path="/your/path")

Parameters:

leverage (int): The leverage for the trade (for non-SPOT markets). Default value is 1.
chain (bool): Specifies whether to use chain trading(Reverse orders). Default value is False.
commission (float): The commission rate for the trade. Default value is 0.15.
result_type (str):
“Q” - Quarterly Analysis(last dates of quarters) “QS” - Quarterly Analysis(start dates of quarters) “M” - Monthly Analysis(last date of months) “MS”- Monthly Analysis(start dates of months) “Y” - Yearly Analysis(last dates of years) “YS” - Yearly Analysis(start dates of years) “6M” - Semi Annual Analysis(last dates of 6 months) “6MS” - Semi Annual Analysis(start dates of 6 months)

File Requirements#

Format: CSV (Comma-Separated Values) Content Structure: The CSV file must include the following headers in the exact order:

datetime (datetime) : Format YYYY-MM-DD HH:MM:SS
open (float)
high (float)
low (float)
close (float)
volume (float)
TP (float) : The take profit price. –OPTIONAL
SL (float) : The stop loss price. –OPTIONAL
signals (int)

Each row in the file should represent a different time point in the dataset.

TP and SL#

Any strategy which involves limit orders for take profit (TP) and stop loss (SL) set at X and Y respectively, our backtesting process requires timestamped signals of 1/-1 to indicate long/short positions. Alongside these signals, TP and SL rows are provided, specifying the numerical values for TP and SL .
When the order is executed at the close of a timestamp, our engine initiates monitoring of price movements from the next candle onwards. It continuously checks if the market tick reaches either the TP or SL levels. Upon reaching either level, the engine calculates the profit or loss based on the difference between the entry and exit prices. This calculation is expressed as a percentage return on investment (ROI).
This approach ensures accurate evaluation of the strategy’s performance by simulating real market conditions and computing profits or losses based on actual price movements relative to the predefined TP and SL levels.

Important Note#

Logs must be submitted in the format: (1, 0, -1, 2, -2), under the following conditions:

If you are willing to open a long trade and cut it :- then your entry is 1 and exit is -1 (just square off)
If you are willing to open a short trade and cut it :- then your entry is -1 and exit is 1 (just square off)
If you are willing to open a long trade and then square it off and open a new short trade at the same timestamp’s closing :-then your entry is 1 and exit is -2. (square off and new initiate)
If you are willing to open a short trade and then square it off and open a new long trade at the same timestamp’s closing :- then your entry is -1 and exit is 2. (square off and new initiate)
When there is no signal - mark the timestamps with 0.
In between entry(1 or -1) and exit (1 or -1) of a trade , mark the timestamps with 0 .

Refer Strategy Submission for more details

Error Codes#

4001: Position not needed if quantity provided
4002: Leverage mandatory for Futures (USD-M, COIN-M)
4003: Leverage not for SPOT orders
4004: Specify Quantity or Position
4005: Price needed for LIMIT orders
4006: Target price > Entry price
4007: Stop-Loss price > Entry price
4008: Only .csv files accepted
4009: Parent order not found
4010: Parent order already closed
4011: Backtest error
4012: jupyter_id not found