Copied

Academy Beginners Tutorial Article

API trading on OKX — Capabilities and benefits of API v5 upgrade

2021.04.06 Matthew Lam

An overview of API trading and OKX’s latest API interface

Typically, trading requires the use of an exchange platform for screening stocks or digital assets like Bitcoin. A trader finds an asset to trade, observes the price quote, chart and the order book, and then places a market, limit or stop order via the interface.

This, in itself, is a major advancement over the stock trading systems of the past but is still not the most efficient process, particularly for high-frequency trading. The needs of advanced traders today are met by automated or algorithmic trading systems, which allow traders to program their strategies and set them to execute and adapt to market conditions without continuous human input.

API, or an application programming interface, is at the core of such automated trading systems and is essentially a set of programming code that allows software platforms to share data and communicate effectively in real-time.

Algo trading firms and professional traders are the main users of API trading, while retail traders can also make use of API connections for their portfolio-management apps or trading via third-party software.

In order to meet the needs of its users, OKX offers advanced API functionality and continues to upgrade it. In this article, we will provide a brief introduction to API trading on OKX as well as an overview of the new OKX API v5 upgrade.

API trading basics

There are three essential tools when it comes to API trading:

API keys
API documentation
Connection interfaces

API keys are unique identifiers that authenticate traders and developers who access the exchange’s API. In simple terms, API keys, consisting of a public key and a secret key, work much like a username and password combination.

The API documentation contains technical information on how to use and integrate an API — essentially acting as a reference manual for developers and traders alike.

There are two main types of APIs — REST and WebSocket. REST stands for Representational State Transfer and is the most common web service that supports a variety of formats under HTTP — such as JSON and XML. WebSocket is a new HTML5 protocol that enables efficient data transmission between client and server. This is particularly useful for developers intending to program and connect scripts, bots or other software with an exchange.

API trading on OKX

OKX offers three categories of API trading: account, trading and market trends. In the account and trading modules, users can place orders, enquire about order status and account information. In addition, OKX users can access historical price data of trading pairs via the publicly available market data API.

OKX supports both REST and WebSocket API for its users in API v3, and traders can use the API for five trading products, including spot, margin, futures, perpetual swaps and options.

While API v3 is accessible to both retail and institutional traders, in a bid to continue improving user experience, OKX has been working on an upgrade to its API system to improve capital efficiency, error-reporting mechanisms and much more.

OKX API v5

To offer a more seamless trading experience for users, OKX has launched its new API v5, which is currently available for all Unified Account users. Being a significant upgrade from v3 (v4 was skipped because “4” is considered an unlucky number in various East Asian regions), v5 makes key improvements in the following areas:

Enhanced efficiency in capital allocation
Simultaneous support multiple trading products
Order operation in both REST and WebSocket API
A unified JSON format for error reporting
More flexible WebSocket subscription and pushing in regular intervals

In this article, we compare the functionality of both API v3 and v5 and how API trading is improved in the new version.

Functional upgrades in v5

The functionality upgrades of API v5 apply to all API users. These pertain to account fund usage, support for multiple business lines and more.

Account funds usage

In API v3, there is a corresponding account for each business line. This means that users need to transfer their funds from one trading product to another. The frequent transfer of funds is time-consuming and reduces capital efficiency for users. Moreover, the fund transfer between different trading product accounts is limited to once per second.

Traders can leverage greater capital efficiency when using API v5. Similar to OKX’s Unified Account, traders using API v5 will be able to utilize their funds in one account. In addition, the profits and losses of various positions in v5 are also consolidated according to the user’s account mode — thereby improving capital efficiency.

Unified API across products

Unlike API v3, the endpoints in API v5, such as those for placing orders and retrieving positions, are unified across products. The same request and response data models are used across all instrument types in the same API, which means we no longer need to model each of the product APIs separately.

Order operations

Order operations include placing new orders, order amendments and order cancellations. While only the REST API in v3 supports order operations, the new API v5 allows both REST and WebSocket APIs to support order operations.

Scenario-based upgrades

Scenario-based upgrades refer to upgrades in a specific function or format. This includes order mode upgrades and format upgrades of time function and REST response function.

Order placement mode

API v3 supports only opening and closing positions — and if users hold both long and short positions in the same derivative contract, these positions are viewed separately and cannot be offset against each other.

In conjunction with Unified Accounts, API v5 includes a new net mode for users. This means that various long and short positions in the same trading pair or instrument can be offset against each other, and users can view the net positions.

WebSocket subscription function

The subscription function enables users to fetch data. Compared to API v3, API v5 enables users to subscribe to multiple trading pairs simultaneously.

Moreover, API v5 pushes in regular intervals for Account and Position channels, which is more user-friendly for risk management.

Format of REST response

Response refers to the data returned to users when they attempt to retrieve information. There are two REST response formats in API v3 — normal return format and error reporting format. These two formats are incompatible in the same interface, causing inconvenience to users. On the contrary, API v5 follows a unified JSON format for REST response.

Private liquidation order

In API v3, users cannot view the status of private liquidation orders directly. They need to do so by connecting endpoints from the REST API.

The order channel of API v5 supports private liquidation orders. Users can view the status directly, and the “Category” field indicates whether the order is a partial or a full liquidation one.

Number of opened contracts

When users in API v3 want to view the number of opened contracts, they need to send requests to the WebSocket account channel to view it.

Reading the number of opened contracts is more straightforward in API v5, as users can obtain such information through the “Get maximum number of contracts” interface in the REST API.

Sub-account module

API v5 offers this module to support:

Management of API Keys for sub-accounts, including creation, deletion and resetting functionalities.
Querying account balances of sub-accounts.
Fund transfers between two sub-accounts directly.

Format of time

API v3 adopts the ISO8601 time format, referring to the UTC time zones. However, this time format may not be compatible across all programming languages. This requires additional functionality for time zone conversion.

API v5 adopts a more universal time format: the Unix Epoch, which does not take time zones into account. API v5 also has relevant resources in the library, allowing easy time format conversion for developers.

Market order of spot trading

When spot trading with API v5, users can choose the unit of size when placing market orders according to their needs. In contrast, API v3 users can only use the quote currency as the buying market order unit and the base currency as the selling market order unit.

The launch of API v5

As of March 31, API v5 is available to all Unified Account users. Since API v3 will be discontinued shortly after v5 has been fully rolled out, we encourage users to upgrade their API to v5 for better functionalities and a more seamless trading experience.

For more technical details regarding the new API v5, please refer to our guide here.

Follow OKX

Telegram API community: https://t.me/OKXAPI
Telegram: https://t.me/OKXOfficial_English
Twitter: https://twitter.com/OKX
Facebook: https://www.facebook.com/okexofficial/
LinkedIn: https://www.linkedin.com/company/okex/
Reddit: https://www.reddit.com/r/OKX/
Instagram: https://www.instagram.com/okex_exchange

Disclaimer: This material should not be taken as the basis for making investment decisions, nor be construed as a recommendation to engage in investment transactions. Trading digital assets involve significant risk and can result in the loss of your invested capital. You should ensure that you fully understand the risk involved and take into consideration your level of experience, investment objectives and seek independent financial advice if necessary.