An asynchronous object-oriented program for arbitrage between perpetual futures and spot on OKEx using V5 API. Initially written in April 2021 for my personal use. Modified and optimized OKEx V3 API SDK according to V5 API documentation.

Chinese and English support, completed with annotations and docstrings.

This project was started when I was a newbie in Python and software development. I am glad it gathers a decent number of stars and hopefully some usage. However it feels outdated and lacking maintenance even though it still functions and makes money.

Therefore I'm soliciting feedbacks or suggestions to make an improvement plan. Given enough feedbacks and community contribution, an improvement plan will take effect. Please see the list of issues or create new issues.

• Command line interface;
• Sort and output historical funding rates over a given period;
• Analyze historical funding rates and volatility (taken as NATR) to find most profitable underlying for arbitrage;
• Open a position by longing spot and shorting perpetual futures equally and simultaneously
  • Use historical tickers and statistics to open position when futures have max premium, assuming that the premium over a period of time satisfies Gaussian distribution;
  • Accelerate when a desired premium does not appear by given time;

• Close a position by selling spot and closing short on perpetual futures
  • Use historical tickers and statistics to close position when futures have max discount;
  • Accelerate when a desired discount does not appear by given time;
  • Proactively close a position when the predicted funding rate is low enough such that it is better off to reopen later;
• Monitor existing positions
  • Sell spot and close short to add margin when price rises to avoid liquidation;
  • Reduce margin to buy spot and open short when price drops to maintain exposure;
• Precise order size control and leverage management;
• Store tickers, funding rates, portfolio and transactions in MongoDB;
• Calculate current and historical PnL, APR and APY;
• Plot the distribution of premium/discount for an underlying over a given period.

• Typical arbitrage of perpetual futures and spot is passively receiving funding fees while keeping the position open. However it is profitable to proactively close a portion of the position when the futures premium surges and reopen it later when the premium subdues.

Implemented asyncio and websocket. Web IOs are parallelized where possible. AsyncClient is initialzed as a class member instead of Context Manager to avoid constantly creating and killing sessions which has non-negligible overheads. Special care was taken for proper client closure. A custom semaphore was created to control concurrent REST API access. Websocket is used to fetch real time price feed. Websocket streaming functions are used as AsyncGenerators for elegant integration.

Classes are given __await__ attribute where necessary and can be initialized asynchronously. Decorator @call_coroutine was created to call coroutines directly in normal context instead of loop.run_until_complete(coro). So simply call coro in normal context and await coro in async context.

Install Python 3.8+ and required packages.

python setup.py install or pip install -r requirements.txt

git submodule update --init --recursive

Install MongoDB.

Store API keys in .env (use account 3 for demo trading).

Set language='cn' for Chinese and language='en' for English in config.py.

Simply python main.py.

Contributions are welcome. Please open an issue if you have any questions or suggestions.

Futures spot arbitrage in crypto is profitable because there is a huge demand for long leverage in the crypto market. Arbitrageurs act as the counterparty to buyers in the perpetual swap market. They effectively multiply and transfer the buying pressure in the perpetual swap market to the spot market. Leverage comes at a cost. Therefore arbitrageurs or market makers are entitled to charge interest on futures buyers, just like stockbrokers charge interest for margin. As a result the APY depends on the market sentiment, ranging from 10% to 100%+.

The author does not assume responsibilities for the use of this program, nor is warranty granted.

This program is licensed under the AGPL-3.0 License. See LICENSE for full disclosure.

Permissions of this license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. When a modified version is used to provide a service over a network, the complete source code of the modified version must be made available.

[1] OKEx V5 API

[2] Cryptocurrency Spot-Futures Arbitrage Strategy Report

[3] Alternative Opportunities In Crypto Space: Spot-Futures Arbitrage