OKX API Trading, Pt. 2: How to trade derivatives on a Jupyter Notebook

okx learn
OKX Learn
2022.12.08

In our previous tutorial, OKX API Trading: How to trade spot on a Jupyter Notebook, we introduced simple Spot trading by calling the functions in the python-okx library on a Jupyter Notebook.

This tutorial walks you through how to do simple derivatives trading with the same tools. Let's use the comprehensive features available in python-okx at a higher level.

Derivatives Types

There are three types of derivatives available for trading on OKX:

  1. Futures
  2. Perpetual swaps
  3. Options

You can head over to Bitcoin derivatives, explained: Futures, perpetual swaps and options to learn about the characteristics of different types of derivatives on OKX. In this tutorial, we will use perpetual swaps as an example.

1. Get market data from Get market data

You can also replace instType with "FUTURES" or "OPTION" for your information. import okx.MarketData as MarketData

flag = "1"  # live trading: 0, demo trading: 1
marketDataAPI = MarketData.MarketAPI(flag = flag)
result = marketDataAPI.get_tickers(instType = "SWAP")
print(result)

2. Get available trading pairs from Get instruments

In the same manner, choose the instType for which you'd like to get information. import okx.PublicData as PublicData

if __name__ == '__main__':
flag = "1"  # live trading: 0, demo trading: 1
publicDataAPI = PublicData.PublicAPI(flag = flag)
result = publicDataAPI.get_instruments(instType = "SWAP")
print(result)

2.1 Calculate the notional value of a derivative contract with the instrument parameter ctVal and ctMult

To calculate the notional value of a derivative contract (i.e. future, perpetual swap, or option), you need ctVal (contract value) and ctMult (contract multiplier) from the instrument parameters. The notional value of a derivative contract can be calculated as ctValctMult (unit: ctValCcy); For example, from the instrument parameters shown below we can calculate the notional value of an LTC-USD perpetual contract as: ctValctMult (unit:ctValccy) = 10 * 1 USD = 10 USD

"instType":"SWAP",
"instId":"LTC-USD-SWAP",
"instFamily":"LTC-USD",
"uly":"LTC-USD",
"settleCcy":"LTC",
"ctVal":"10",
"ctMult":"1",
"ctValCcy":"USD"

3. Check your balance from Get balance

import okx.Account as Account
flag = "1"  # live trading:0, demo trading: 1
accountAPI = Account.AccountAPI(api_key, secret_key, passphrase, False, flag)
result = accountAPI.get_account_balance()
print(result)

4. Account mode and margin/trade mode that eligible to trade derivatives

As mentioned in our last tutorial, in unified account, there are four account modes:

  • Simple account
  • Single-currency margin account
  • Multi-currency margin account
  • Portfolio margin account Note that only the last three margin modes, single-currency margin, multi-currency margin and portfolio margin, are eligible for derivatives trading. Please refer to how to set up the account mode to understand the differences between the four modes and how to switch between them through our Web UI.

4.1 Get the current account configuration from the acctLv parameter in Get account configuration

Make sure that you are in the correct account mode to trade derivatives.

import okx.Account as Account
flag = "1"  # live trading: 0, demo trading: 1
accountAPI = Account.AccountAPI(api_key, secret_key, passphrase, False, flag)
result = accountAPI.get_account_config()
print(result)
if result['code'] == "0":
acctLv = result["data"][0]["acctLv"]
if acctLv == "1":
print("Simple mode")
elif acctLv == "2":
print("Single-currency margin mode")
elif acctLv == "3":
print("Multi-currency margin mode")
elif acctLv == "4":
print("Portfolio margin mode")

5. Set leverage via Set account leverage

One important parameter we need to set when trading derivatives is leverage. Leverage allows a trader to borrow money and thereby enter a position that is worth much more than their out of pocket investment while committing only a small amount of money. This great magnifies their gains or losses. A trade can have as much as 125x leverage when trading derivatives on OKX. You can read references of setting leverage for different levels of leverage allowed under different tiers of positions.

OKX leverage tiers

Here are definitions for the glossaries shown above:

  • Max. Leverage: Maximum multiple of borrowed capital to increase the potential return of an investment
  • Initial margin ratio (IMR): Margin required for holding current positions
  • Maintenance margin ratio (MMR): Minimum margin required to maintain current positions – liquidation will occur if the account equity drops below the maintenance margin For example, if you want to trade 3,000 ETHUSDT perpetual contracts, you can leverage a maximum of 75x the capital you own. IMR = 1 / 75 = 1.3%, and you must maintain 0.8% MMR or above to avoid liquidation. You can refer to OKX Margin Trading Rules section 6.2 Leverage and 6.3 Margin ratio and forced liquidation to understand more about leverage, margin requirements and liquidation rules.

There are 9 different scenarios for leverage setting via OKX open APIs. Please refer to Set leverage scenarios for different cases. For perpetual swaps, there are 3 different scenarios for leverage setting:

  • Set leverage for SWAP instruments under cross-margin trade at contract level
  • Set leverage for SWAP instruments under isolated-margin trade mode and buy/sell position mode at contract level
  • Set leverage for SWAP instruments under isolated-margin trade mode and long/short position mode at contract and position side level The following example shows how to set leverage for a single SWAP contract and position side, as compared to across all the SWAP contracts for a certain underlying asset.

Set leverage to be 5x for all cross-margin BTC-USDT SWAP positions, by providing the SWAP instId:

result = accountAPI.set_leverage(
instId = "BTC-USDT-SWAP",
lever = "5",
mgnMode = "cross"
)
print(result)

In buy/sell position mode, set leverage to be 5x for all isolated-margin BTC-USDT SWAP positions by providing the SWAP instId:

result = accountAPI.set_leverage(
instId = "BTC-USDT-SWAP",
lever = "5",
mgnMode = "isolated"
)
print(result)

In long/short position mode, set leverage to be 5x for an isolated-margin BTC-USDT-SWAP long position. This does NOT affect the leverage of the BTC-USDT-SWAP short positions:

result = accountAPI.set_leverage(
instId = "BTC-USDT-SWAP",
lever = "5",
posSide = "long",
mgnMode = "isolated"
)
print(result)

Note that the request parameter posSideis only required when margin mode is isolated in long/short position (order placement) mode for FUTURES/SWAP instruments (see scenario 6 and 9 in Set leverage scenarios).

6. Place orders under different position (order placement) modes: long/short and buy/sell

There are two position (order placement) modes when trading FUTURES and perpetual SWAP: long/short and buy/sell (net). You can change the position (order placement) mode between long/short and buy/sell (net), via the API Set position mode:

result = accountAPI.set_position_mode(
posMode = "long_short_mode"
)
print(result)

You also can change the position via the web user interface "settings":

OKX user interface settings

In buy/sell (net) mode, the position of a certain contract is the net quantity of your buy and sell trades. When you place orders via Place order, the request parameter posSide is not mandatory. If you pass it through, the only valid value is net. In long/short mode, long and short positions of a certain contract will be independent from each other and will need to be closed separately. When you place orders via Place order, the request parameter posSide is mandatory. Valid values are long or short. Showing below is how to set the parameter side (side of the trade) and posSide (side of the position) when you place an order under different scenarios:

  • Place a buy order and open/increase a long position: side = buy, posSide = long
  • Place a sell order and open/increase a short position: side = sell, posSide = short
  • Place a sell order and close/reduce a long position: side = sell, posSide = long
  • Place a buy order and close/reduce a short position: side = buy, posSide = short Then you are ready to place derivatives orders.

6.1 Place a limit order via Place order

The following example details how to buy 100 BTC-USDT Swap contract at the price of 19,000 USDT.

result = tradeAPI.place_order(
instId = "BTC-USDT-SWAP",
tdMode = "isolated",
side = "buy",
posSide = "net",
ordType = "limit",
px = "19000",
sz = "100"
)
print(result)
if result["code"] == "0":
print("Successful order request,order_id = ",result["data"][0]["ordId"])
else:
print("Unsuccessful order request,error_code = ",result["data"][0]["sCode"], ", Error_message = ", result["data"][0]["sMsg"])

6.2 Place a market order via Place order

This example details how to buy a 100 BTC-USDT swap contract at market price.

result = tradeAPI.place_order(
instId = "BTC-USDT-SWAP",
tdMode = "isolated",
side = "buy",
posSide = "net",
ordType = "market",
sz = "100"
)
print(result)

if result["code"] == "0":
print("Successful order request,order_id = ",result["data"][0]["ordId"])
else:
print("Unsuccessful order request,error_code = ",result["data"][0]["sCode"], ", Error_message = ", result["data"][0]["sMsg"])

7. To get details/state of a certain order, please refer to Get order details

Other than ordId, you can also specify clOrdId to get order details.

result = tradeAPI.get_order(instId="BTC-USDT-SWAP", ordId="505073046126960640")
print(result)

8. Cancel an order via Cancel order

You also use clOrdId in place of ordId:

    result = tradeAPI.cancel_order(instId="BTC-USDT-SWAP", ordId="505073046126960640")
print(result)

9. Amend an order via Amend order

You also use clOrdId in place of ordId. This example shows the revision of a new size.

result = tradeAPI.amend_order(
instId = "BTC-USDT-SWAP", 
ordId = "505073046126960640",
newSz = "80"
)
print(result)

10. Get the list of open orders via Get order List

result = tradeAPI.get_order_list()
print(result)

11. Get order history via Get order history (last 7 days) and Get order history (last 3 months)

For the last 7 days:

result = tradeAPI.get_orders_history(
instType = "SWAP"
)
print(result)

For the last 3 months:

result = tradeAPI.get_orders_history_archive(
instType = "SWAP"
)
print(result)

12. Get transaction details via Get transaction details (last 3 days) and Get transaction details (last 3 months)

For the last 3 days:

result = tradeAPI.get_fills()
print(result)

For the last 3 months:

result = tradeAPI.get_fills_history(
instType = "SWAP"
)
print(result)

13. Get positions via Get positions

When your account is in net mode, the net position of each contract will be displayed; when your account is in long/short mode, the long or short position of each contract will be displayed separately.

result = accountAPI.get_positions()
print(result)

For example, you can track your unrealized profit and loss through the response parameter upl.

More examples

For more examples, please download the full Jupyter Notebook. If have any questions about OKX APIs, please feel free to ask in our API support Telegram channel.