How to Install and Use the OKX Trading Plugin for Kungfu Trader

Introduction

This plugin is designed for digital asset trading on the OKX exchange and can be integrated with the "Kungfu Trader" software to enable automated quantitative trading strategies.

It supports both live trading and simulated trading environments.

If you wish to modify the source code for custom development, you will need to recompile the project. Please refer to the "Build" section for instructions on compilation and subsequent installation into the Kungfu Trader plugin directory.

Prerequisites and Installation

To begin, you will need to download both the Kungfu Trader client and the OKX plugin.

1. Download the Required Software:

   • Kungfu Trader Client: Download the latest stable version from the official releases page. It is recommended to use the .zip package for easier directory navigation.
   • OKX Plugin: Navigate to the "Releases" section on the right side of this project's page to download the latest version of the plugin package.

2. Locate the Installation Directory:

   • If you installed the .exe version: Run the Kungfu client, click on "File" in the top-left menu bar, and select "Open Kungfu Installation Directory".
   • If you are using the .zip version: Simply navigate to the unpacked kungfu folder and enter the resources subdirectory.

3. Install the Plugin:

   • Copy the downloaded okx plugin folder.
   • Navigate to your Kungfu installation directory, then proceed to app -> kungfu-extensions.
   • Paste the okx folder into this kungfu-extensions directory.
4. Restart the Client: After pasting the folder, a full restart of the Kungfu Trader client is required for the changes to take effect.

Generating Your OKX API Keys

To enable the software to trade on your behalf, you must grant it access via an API (Application Programming Interface). This is created within your OKX account.

1. Initiate Creation: Log in to your OKX account and navigate to the API management section. Click on "Create API".

2. Configure API Settings:

   • Select the account you want to trade with.
   • For "Usage", select "API Trading".
   • For permissions, ensure "Trade" is added.
3. Set a Passphrase: You will be prompted to create a custom password. This passphrase is crucial for future API management and login verification; please remember it.
4. Finalize Creation: Review your settings and click "Submit" to complete the API creation process.
5. Retrieve Credentials: After creation, click "View" to access your new API Key and Secret Key. You will need these for the software login.

An example trading strategy is provided for reference. Please check the end of the readme for details.

Logging into the Trading Platform

Before you can trade, you must log in to both the market data source and the trading account within the Kungfu software.

1. Open the Client: Launch the Kungfu Trader application.

2. Login to Market Data (Quote Source):

   • Locate the "Quote Source" panel, typically on the right side.
   • Click "Add", then select "okx-digital currency".

3. Login to Trading Account:

   • Locate the "Trading Account" panel, usually on the left side.
   • Click "Add", then select "okx-digital currency".

You will need to fill in the following details in the login dialog:

• Account: A nickname or remark for your own reference. This can be any text.
• Password: The passphrase you set during the API creation process.
• api_key: The "API Key" you retrieved after creating the API.
• Secret Key: The "Secret Key" you retrieved.
• Sync External Orders: Enable this option if you want orders placed on other platforms (like the OKX website or app) to be visible and synchronized within Kungfu Trader.
• Simulated Trading: Enable this switch if you wish to test strategies in a risk-free模拟环境 using testnet funds.

Once the credentials are entered, click the "Open" button for both the quote source and trading account processes. When their status changes to "Ready", you are connected and can begin trading.

👉 Explore more strategies for connecting to various exchanges

Supported Features and Trading Instruments

This plugin provides robust support for several trading instruments, with some specific limitations.

• Supported Instruments: Spot trading, perpetual swaps, and futures contracts are fully supported.
• Unsupported Instruments: Trading, position queries, and margin functionality for leveraged tokens and options are not currently available.

Trading Modes:

• Futures & Perpetual Swaps: Only cross-margin mode is supported. Isolated margin and leverage adjustment through the plugin are not available.
• Spot Trading: Only cash (standard) mode is supported. Margin trading on spot pairs is not available.

Important Notes for Trading:

• You must specify the exact currency pair for spot trading (e.g., BTC-USDT).
• For manual trading, you must first search for and subscribe to the desired symbol (e.g., "BCH-BTC") in the market subscription panel before you can trade it.
• For strategy trading, the code must also explicitly subscribe to the required symbols (e.g., context.subscribe(source, ["BCH-BTC"])).

Viewing Assets:

• Your spot assets can be viewed in the "Positions" panel within Kungfu Trader. This reflects the data available under the "Assets" tab on the OKX website.

Strategy Configuration:

• When writing a strategy, you must specify the correct exchange constant for the instrument:

  • Spot: Exchange.OKX_SPOT
  • USDT-Margined Futures: Exchange.OKX_USD_FUTURE
  • Coin-Margined Futures: Exchange.OKX_COIN_FUTURE

Data Synchronization:

• Account equity, unrealized profit and loss (PnL), and position data are sourced directly from OKX's servers.

• Synchronization occurs through two primary mechanisms:

  • Timed Synchronization: Data is updated every 60 seconds.
  • Event-Driven Synchronization: Any change in order status triggers an immediate synchronization of funds and position data.

Spot Trading Mechanics:

• Spot trades are displayed and executed as currency pairs. When an order is filled, the holdings for both currencies in the pair are adjusted accordingly.

  • Example: Buying 1 lot of ETH-BTC will result in your ETH balance increasing by 1 and your BTC balance decreasing by the cost of the trade.

Building the Plugin from Source

For developers who want to customize the plugin, follow these steps to compile it from the source code.

Windows Build Environment Setup

1. Required Software: You must install Visual Studio Community 2022. This installation will include necessary tools like CMake.

2. Download Visual Studio: Use the provided download link to get the correct version. It is critical to use the 2022 version as newer releases may not be compatible.

   • After downloading, run the installer and ensure you complete all updates by clicking "Download and Update".
3. Use the Correct Developer Shell: Compilation must be done from the "x64 Native Tools Command Prompt for VS 2022". You can find this by clicking the Windows Start menu and searching for it under "Visual Studio 2022".

Compilation Process

1. Download Kungfu Trader: If you haven't already, download and install the Kungfu Trader package to a known location (e.g., D:\Kungfu-trader).
2. Download the Plugin Source Code: Clone or download the kfx-broker-okx source code from GitHub to your local machine (e.g., D:\kfx-broker-okx).

3. Execute the Build Command:

   • Open the "x64 Native Tools Command Prompt for VS 2022".
   • Navigate to the directory containing the kfx-broker-okx source code.
   • Run the compilation command: D:\Kungfu-trader\resources\kfc\kfs.exe extension build
4. Locate the Output: Upon successful compilation, the built plugin will be generated in a new dist directory within your source folder.

Deployment and Testing

1. Copy the Plugin: Take the okx folder from the dist directory and paste it into your Kungfu Trader's plugin folder: D:\Kungfu-trader\resources\app\kungfu-extensions.

2. Add and Run the Plugin in Client:

   • Restart the Kungfu Trader client if it was open.
   • Add the OKX trading柜台 (broker) and quote source柜台 from the respective panels.
   • Run the counters. Their status should change to "Ready".

3. Test with the Demo Strategy:

   • Add the provided demo strategy to your strategy list.
   • Run the strategy.
   • Monitor the account position information and the strategy运行日志 (operation logs) to verify everything is working correctly.

👉 Get advanced methods for automated trading system configuration

Frequently Asked Questions

Q: Is this plugin officially supported by OKX?
A: This plugin is a community-developed tool designed to connect the Kungfu Trader software to the OKX exchange via its public API. It is not an official product of OKX, and support is provided by the developer community.

Q: Can I use this plugin for leveraged trading?
A: The plugin currently supports trading in cross-margin mode for futures and perpetual swaps, which involves leverage. However, you cannot adjust the leverage multiplier through the plugin itself; it uses the default leverage set on your OKX account for the chosen cross-margin mode. Spot trading is cash-based only.

Q: My strategy isn't submitting orders. What should I check?
A: First, verify that both the quote source and trading account processes show a "Ready" status. Double-check your API key, secret key, and passphrase for accuracy. Ensure your API key has the necessary "Trade" permissions and that it is not restricted by IP whitelisting if you have it enabled.

Q: How often does my portfolio data update?
A: Your balance and position data are updated every 60 seconds automatically. They are also updated instantly whenever there is a change related to your orders, providing a near real-time view upon trade execution.

Q: Why can't I see my options positions?
A: This plugin is specifically built for spot, perpetual swap, and futures trading. It does not support retrieving data or executing trades for options contracts or leveraged tokens. These instruments will not be visible within the Kungfu Trader interface when using this plugin.

Q: I'm getting a compilation error. What's wrong?
A: The most common cause is using an incorrect version of Visual Studio. Please ensure you are using the 2022 community edition and are compiling from the "x64 Native Tools Command Prompt" that comes with it. Also, verify that the path to the kfs.exe tool in your build command is correct for your Kungfu installation directory.