OKX Trade Connector

Features

crypto-okxConnector Key

Instruments

FXFUTUREOPTION

Request Types

SUBMITCANCELREPLACE

Order Types

MARKETLIMIT

Time In Force

GTCIOCFOK

Order ID Mapper

SEQUENCE

✗

Order Status Request

✗

Cancel On Disconnect

✓

Commission

✓

Post Only

✓

Fast Cancel

✗

Fast Replace

Notes

Rounding

Important: Prices and quantities are silently rounded if they do not match the tick size or quantity increment.
This can lead to overfills and incorrect replacement behavior.

Market Orders

Market BUY orders are not supported.

Contract Expiration

When the contract expires, the exchange sends an unsolicited cancellation event.
If this event is missed, the connector cannot restore the order state.

Rate limits

Submit/Cancel/Replace: 60 requests per 2 seconds (for each). Rate limit rule (except Options): UserID + Instrument ID.

https://www.okx.com/docs-v5/en/#overview-rate-limits-trading-related-apis

Post Only and ELP orders

The connector sends an ELP order when the order is marked as Post Only and useELP is set to true.
ELP orders can be placed by all users and match only with taker orders not placed via OpenAPI.

In the OKX API, both Post Only and ELP orders are represented as OKX Order Types.
When the Post Only flag is set, it takes precedence over the specified Order Type — the Order Type is ignored and the order is placed as Post Only.

ELP Taker Access

isElpTakerAccess can be set via 6025 order attribute.

true - the request can trade with ELP orders but a speed bump will be applied.
false - the request cannot trade with ELP orders and no speed bump.

The default value is false while true is only applicable to IOC orders.

Trade Quote Currency

The quote currency used for trading. Only applicable to FX (SPOT) instruments.
By default the quote currency is set to USDC for XXX-USD FX (Spot) contracts.
The default value can be redefined either via okxTradeQuoteCcy column in securities or via 6015 custom attribute in order request.

Trade Mode

Check trade mode description in API docs.

Default Trade Mode value can be configured via tradeMode settings. Trade Mode can also be specified per order via the 6001 attribute.

Trade Mode must be set according to the account type and instrument type.

Spot mode:

SPOT and OPTION buyer: cash

Futures mode:

Isolated MARGIN: isolated
Cross MARGIN: cross
SPOT: cash
Cross FUTURES/SWAP/OPTION: cross
Isolated FUTURES/SWAP/OPTION: isolated

Multi-currency margin:

Isolated MARGIN: isolated
Cross SPOT: cross
Cross FUTURES/SWAP/OPTION: cross
Isolated FUTURES/SWAP/OPTION: isolated

Portfolio margin:

Isolated MARGIN: isolated
Cross SPOT: cross
Cross FUTURES/SWAP/OPTION: cross
Isolated FUTURES/SWAP/OPTION: isolated

Position side and offset

Position side can be determined via two attributes: 6003 (Position side) or 6470 (Position offset).\

Order type	Side	Position side	Offset
Open Long	BUY	long	open
Close Long	SELL	long	close
Open Short	SELL	short	open
Close Short	BUY	short	close

Fills Channel

OKX supports consuming fills via a separate Fills WebSocket channel.

Important:

This channel is only available to users with trading fee tier VIP5 or above.
Fee information is not included in this channel.
When a fill event is received by this channel, the account balance, margin, and position information might not have changed yet.

To enable the Fills channel, set useFillsChannel = true.

Symbology

Instruments information can be requested via Get instruments endpoint:

https://www.okx.com/api/v5/public/instruments?instType=SWAP (perpetual instruments)

The connector requires both instrument ID (instId) and instrument numeric code (instIdCode)
to be defined in separate columns in securities stream.

Column	OKX Property	Example	Description
`okxSymbol`	`instId`	`BTC-USD-SWAP`	Instrument ID
`okxInstrumentCode`	`instIdCode`	`10458`	Instrument Code
`okxTradeQuoteCcy`	`tradeQuoteCcy`	`USDG`	Quote currency.

Important: Instrument codes (instIdCode) differ between production and demo-trading environments.

Use the script below to download instruments info for demo-trading env:

curl -o okx_symbols_perpetual_demo.json \
     --request GET --url https://www.okx.com/api/v5/public/instruments?instType=SWAP \
	 -H "x-simulated-trading: 1"

Configuration

Connector settings

Parameter	Default Value	Description
apiPassphrases		List of passphrases. The passphrases you specified when creating the APIKey
tradeMode	CASH	Default trade Mode, when placing an order, you need to specify the trade mode. Values: `ISOLATED`, `CROSS`, `CASH`, `SPOT_ISOLATED`.
marginCurrency		Default margin currency.
positionSide		Default position side: `SHORT`, `LONG`
selfTradePrevention		Self trade prevention mode. Valid values: `CANCEL_MAKER`, `CANCEL_TAKER`, `CANCEL_BOTH`.
reduceOnly		Default reduce only. When placing an order with this parameter set to true, it means that the order is considered reduce-only, which is intended to only reduce a current position,Only applicable to `MARGIN` orders.
orderTag		Order tag. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.
cancelOnFail	false	For replace. Default cancel on fail, whether the order needs to be automatically canceled when the order amendment fails
useFillsChannel	false	Switch connector to consume trades from Fills channel.
useELP	false	Flag to use `elp` (Enhanced Liquidity Program) order type for Post Only orders.
simulation	false	Include simulation header to REST requests. Must be enabled if you are working with test environment.
enablePingLogging	false	Turn on ping pong messages logging
pingInterval	10 seconds	Ping interval.

Supported order attributes

Key	Description
18	Post only. `6` value used for post only orders submission
6001	Trade mode. Allowed values: `cross`, `isolated`, `cash`, `spot_isolated`
6002	Margin currency
6003	Position side (short, long). See Position side and offset section
6004	Whether to reduce positions only. When placing an order with this parameter set to true, it means that the order is considered reduce-only, which is intended to only reduce a current position,Only applicable to `MARGIN` orders.
6005	For replace. Cancel on fail, whether the order needs to be automatically canceled when amendment fails
6015	The quote currency used for trading. Only applicable to FX (Spot) instruments.
6025	ELP Taker Access. If `true` - the request can trade with ELP orders but a speed bump will be applied (IOC orders only).
6040	OKX order type. Allowed values: `market`, `limit`, `post_only`, `fok`, `ioc`, `optimal_limit_ioc`, `mmp`, `mmp_and_post_only`, `elp`.
6470	Position offset (open, close). See Position side and offset section
6304	Self trade prevention mode. Valid values: `cancel_maker`, `cancel_taker`, `cancel_both`.
6405	Order tag. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.

Config sample

connectors {
  OKX: ${template.connector.crypto.okx} {
    settings {
      apiKeys: [
        {
          apiKey = "<API_KEY>"
          apiSecret = "<API_SECRET>"
        }
      ]

      apiPassphrases = [
        {
          apiPassphrase = "<API_PASSPHRASE>"
        }
      ]

      tradeMode = CASH
    }
  }
}

Features​

Notes​

Rounding​

Market Orders​

Contract Expiration​

Rate limits​

Post Only and ELP orders​

ELP Taker Access​

Trade Quote Currency​

Trade Mode​

Position side and offset​

Fills Channel​

Symbology​

Configuration​

Connector settings​

Supported order attributes​

Config sample​