okxr: R Interface to the OKX API

okxr is an R package for working with the OKX REST API from R. It provides typed wrappers for market data, account endpoints, asset history, trading, and copy trading, and affiliate invitee data, with shared request signing and schema-based response parsing.

Status

okxr is available on CRAN. Install the stable release from CRAN or use the GitHub repository for development versions between CRAN releases.

Current GitHub release: v0.5.1. CRAN currently publishes 0.4.8. Current development version: 0.5.1.9000.

Installation

Stable CRAN release:

install.packages("okxr")

Development release from GitHub:

# install.packages("devtools")
# devtools::install_github("OliverLDS/okxr")
install.packages("okxr", repos = c('https://oliverlds.r-universe.dev', 'https://cloud.r-project.org'))

Features

Signed OKX REST requests with HMAC authentication
Typed parsing into tabular R objects with variable labels
Shared internal GET/POST generators backed by endpoint specs
User-facing wrappers for account, asset, market, trade, copy-trading, and affiliate APIs
Configurable raw vs parsed return mode via set_okxr_options()
Structured okxr_api_error conditions with endpoint and request metadata
Opt-in retries for transient HTTP failures and reusable cursor pagination

Setup

config <- list(
  api_key = "your_api_key",
  secret_key = "your_secret_key",
  passphrase = "your_passphrase"
)

Public market and public reference endpoints can be called without credentials. Private account, asset, trade, and copy-trading endpoints require signed OKX API credentials.

Do not store real credentials in committed R scripts, examples, or tests. For interactive use, load them from environment variables or another local secret store. If you use OKX simulated trading, set demo = TRUE in config.

config <- list(
  api_key = Sys.getenv("OKX_API_KEY"),
  secret_key = Sys.getenv("OKX_SECRET_KEY"),
  passphrase = Sys.getenv("OKX_PASSPHRASE"),
  demo = TRUE,
  timeout = 10,
  max_retries = 2,
  retry_base_delay = 1
)

USD spot pair migration

OKX is migrating affected Crypto-USD spot instruments to Crypto-USDC. Use the new instrument ID after the announced delisting on September 30, 2026. If you want to keep trading with USD, explicitly pass trade_quote_ccy = "USD" when placing orders. Otherwise OKX defaults to the quote currency in the new instrument ID (USDC). Check tradeQuoteCcyList from get_account_instruments() for the account and instrument before ordering. Accounts that have not traded USDC instruments must first call post_account_activate_usdc_trading(config = config); each master or sub-account activates separately. This call changes account state.

instruments <- get_account_instruments(
  inst_type = "SPOT", inst_id = "BTC-USDC", config = config
)
jsonlite::fromJSON(instruments$tradeQuoteCcyList[[1]])
# After checking the supported quote currencies and activating if needed:
post_trade_order(
  inst_id = "BTC-USDC", td_mode = "cash", side = "buy",
  ord_type = "limit", sz = "0.001", px = "50000",
  trade_quote_ccy = "USD", config = config
)

The order example submits a real order; adapt it to your account and use demo trading when testing. See the OKX migration notice.

Return values

By default, wrappers return parsed data.table objects with typed columns and variable labels where schemas are defined. Use set_okxr_options(raw_data = TRUE) to return the raw OKX data payload instead.

Empty API data payloads return NULL. Network failures, HTTP failures, and OKX error responses raise an okxr_api_error condition. It retains status_code, okx_code, okx_msg, endpoint, and request_id, so callers can use tryCatch() for recovery or logging. Named API responses include an extra JSON column when OKX returns fields that are newer than the local schema.

Request timeout defaults to 10 seconds. Retries are disabled by default; enable them globally with set_okxr_options(max_retries = 2) or per request with config$max_retries. Retries apply to HTTP 429/5xx and transport failures, with exponential backoff and Retry-After support.

Migrating to 0.5.0

Before 0.5.0, failed requests emitted a warning and returned NULL. They now raise an okxr_api_error so applications cannot silently confuse a failed request with an empty OKX response. Use tryCatch() when continuing after a request failure is appropriate:

balance <- tryCatch(
  get_account_balance(config = config),
  okxr_api_error = function(error) {
    message("OKX request failed for ", error$endpoint, ": ", error$okx_msg)
    NULL
  }
)

Examples

Public market examples require network access but no OKX credentials. Private account, trading, asset, and copy-trading examples require valid OKX credentials; trading examples may have account side effects.

Market data

get_market_candles(
  inst_id = "BTC-USDT",
  bar = "1m",
  limit = 100
)

Account data

get_account_balance(config = config)
get_account_positions(config = config)

Place an order

post_trade_order(
  inst_id = "BTC-USDT",
  td_mode = "cross",
  side = "buy",
  ord_type = "market",
  sz = "0.01",
  config = config
)

Copy trading

get_copy_trade_my_leaders(config = config)
get_copy_trade_current_subpos(config = config)

Cursor pagination

bills <- okx_paginate(
  get_account_bills,
  cursor_column = "billId",
  inst_type = "SWAP",
  limit = 100,
  config = config
)

Wrapper categories

Category	Method	Example function
market	GET	`get_market_candles()`
market	GET	`get_market_tickers()`
market	GET	`get_market_books_rpi()`
market	GET	`get_market_trades()`
market	GET	`get_market_mark_price_candles()`
market	GET	`get_market_index_tickers()`
market	GET	`get_market_index_candles()`
market	GET	`get_market_index_components()`
public	GET	`get_public_time()`
public	GET	`get_public_event_contract_series()`
public	GET	`get_public_event_contract_events()`
public	GET	`get_public_event_contract_markets()`
public	GET	`get_public_mm_instrument_types()`
public	GET	`get_public_delta_hedge_currencies()`
public	GET	`get_public_historical_market_data()` (historical ZIP file listings)
public	GET	`get_public_underlying()`
public	GET	`get_public_estimated_price()`
public	GET	`get_public_estimated_settlement_info()`
public	GET	`get_public_opt_summary()`
public	GET	`get_public_position_tiers()`
public	GET	`get_public_discount_rate_interest_free_quota()`
public	GET	`get_public_interest_rate_loan_quota()`
public	GET	`get_public_insurance_fund()`
public	GET	`get_public_block_trades()`
public	GET	`get_public_convert_contract_coin()`
public	GET	`get_public_instrument_tick_bands()`
public	GET	`get_public_premium_history()`
public	GET	`get_public_option_trades()`
account	GET	`get_account_balance()`
account	GET	`get_account_instruments()`
user	GET	`get_user_glp_today_performance()`
user	GET	`get_user_glp_historical_performance()`
account	GET	`get_account_bill_types()`
account	GET	`get_account_subtypes()`
account	GET	`get_account_adjust_leverage_info()`
account	GET	`get_account_position_risk()`
account	GET	`get_account_max_loan()`
account	GET	`get_account_max_size()`
account	GET	`get_account_max_avail_size()`
account	GET	`get_account_trade_fee()`
account	GET	`get_account_interest_rate()`
account	GET	`get_account_interest_accrued()`
account	GET	`get_account_max_withdrawal()`
account	GET	`get_account_risk_state()`
account	GET	`get_account_interest_limits()`
account	GET	`get_account_greeks()`
account	GET	`get_account_position_tiers()`
account	GET	`get_account_collateral_assets()`
account	GET	`get_account_mmp_config()`
account	GET	`get_account_move_positions_history()`
account	GET	`get_account_precheck_set_delta_neutral()`
account	GET	`get_account_bills_history_archive()`
account	GET	`get_account_subaccount_balances()`
account	GET	`get_account_subaccount_max_withdrawal()`
account	GET	`get_account_set_account_switch_precheck()`
account	GET	`get_account_spot_borrow_repay_history()`
account	GET	`get_account_bills()`
account	POST	`post_account_set_leverage()`
account	POST	`post_account_activate_usdc_trading()`
account	POST	`post_account_set_position_mode()`
account	POST	`post_account_set_fee_type()`
account	POST	`post_account_set_greeks()`
account	POST	`post_account_set_auto_repay()`
account	POST	`post_account_set_auto_loan()`
account	POST	`post_account_set_account_level()`
account	POST	`post_account_set_collateral_assets()`
account	POST	`post_account_position_margin_balance()`
account	POST	`post_account_spot_manual_borrow_repay()`
account	POST	`post_account_account_level_switch_preset()`
account	POST	`post_account_mmp_reset()`
account	POST	`post_account_mmp_config()`
account	POST	`post_account_move_positions()`
asset	GET	`get_asset_balances()`
asset	GET	`get_asset_deposit_history()`
asset	GET	`get_asset_withdrawal_history()`
asset	GET	`get_asset_currencies()`
asset	GET	`get_asset_non_tradable_assets()`
asset	GET	`get_asset_asset_valuation()`
asset	GET	`get_asset_bills()`
asset	GET	`get_asset_transfer_state()`
asset	GET	`get_asset_convert_history()`
asset	POST	`post_asset_transfer()`
asset	POST	`post_asset_withdrawal()`
asset	POST	`post_asset_cancel_withdrawal()`
asset	POST	`post_asset_convert_estimate_quote()`
asset	POST	`post_asset_convert_trade()`
trade	GET	`get_trade_order()`
trade	GET	`get_trade_orders_history()`
trade	GET	`get_trade_orders_algo_pending()`
trade	GET	`get_trade_easy_convert_history()`
trade	GET	`get_trade_one_click_repay_history_v2()`
trade	GET	`get_trade_account_rate_limit()`
trade	GET	`get_trade_fills()`
trade	POST	`post_trade_order()`
trade	POST	`post_trade_cancel_order()`
trade	POST	`post_trade_batch_orders()`
trade	POST	`post_trade_cancel_batch_orders()`
trade	POST	`post_trade_amend_order()`
trade	POST	`post_trade_amend_batch_orders()`
trade	POST	`post_trade_order_precheck()`
trade	POST	`post_trade_order_algo()`
trade	POST	`post_trade_cancel_all_after()`
trade	POST	`post_trade_cancel_algos()`
trade	POST	`post_trade_amend_algos()`
trade	POST	`post_trade_mass_cancel()`
copy trading	GET	`get_copy_trade_my_leaders()`
copy trading	GET	`get_copy_trade_settings()`
copy trading	GET	`get_copy_trade_current_subpos()`
copy trading	GET	`get_copy_trade_historical_subpos()`
copy trading	GET	`get_copy_trade_instruments()`
copy trading	GET	`get_copy_trade_public_config()`
copy trading	GET	`get_copy_trade_public_lead_traders()`
copy trading	GET	`get_copy_trade_public_copy_traders()`
copy trading	GET	`get_copy_trade_public_preference_currency()`
copy trading	GET	`get_copy_trade_public_current_subpositions()`
copy trading	GET	`get_copy_trade_public_subpositions_history()`
copy trading	GET	`get_copy_trade_public_pnl()`
copy trading	GET	`get_copy_trade_public_stats()`
copy trading	GET	`get_copy_trade_public_weekly_pnl()`
copy trading	GET	`get_copy_trade_profit_sharing_details()`
copy trading	GET	`get_copy_trade_total_profit_sharing()`
affiliate	GET	`get_affiliate_invitee_list()`
affiliate	GET	`get_affiliate_invitee_detail()`

Release notes

See NEWS.md for release history.

Development status

GET support for major endpoints
POST support for order, cancel, leverage, close position
Copy trading wrappers
Package metadata and generated documentation aligned for GitHub release
Automated test suite foundation
GitHub Actions package check workflow
CRAN-safe package examples and package-level help
Unsigned public endpoints and request timeout handling
CRAN policy hygiene files and release metadata cleanup
Mocked request/parser robustness tests
CRAN release-candidate documentation alignment
Manual CRAN preflight workflow for release checks
CRAN submission checklist for final manual steps
Final CRAN submission metadata update
CRAN reviewer-requested DESCRIPTION and Rd fixes
First CRAN release published
First post-CRAN endpoint expansion batch
Expanded public reference and index market coverage
Broader account inspection and sub-account GET coverage for v0.3.2
Broader trade history, algo-order, asset billing, and convert GET coverage for v0.3.3
Broader copy-trading coverage plus expanded asset history filter support for v0.3.4
Remaining copy-trading GET endpoints and copy-trading parameter completeness fixes for v0.3.5
First trade action expansion batch for v0.4.0
Advanced trade algo and mass-cancel action coverage for v0.4.1
Account configuration action coverage for v0.4.2
Account operational action coverage for v0.4.3
Asset transfer, withdrawal, and convert action coverage for v0.4.4
POST wrapper validation and cancellation parameter completeness for v0.4.5
OKX compatibility patch for base URL, RPI migration, chase algo orders, asset bill filters, and parser fields for v0.4.6
2026 compatibility-completion patch for event contracts, MM instrument types, instrument metadata, ELP, slippage, bill types, and parser fields for v0.4.7
Websocket support

License

MIT

Author

Oliver Zhou Lily Li