NAV
中文
Java Python Go C++

Non-Disclosed Broker

Introduction

Already have R&D and operational resources? Use our non-disclosure API broker services to build your unique trading platform. You can handle user operations and front-end development, while we take care of back-end and market liquidity.

The advantages of Non-disclosed broker are as follows:

API

Get broker account information

Retrieve broker account information

Rate Limit: 1 request per second

HTTP Request

GET /api/v5/broker/nd/info

Request Example

GET /api/v5/broker/nd/info

Response Example

{
    "code": "0",
    "data": [
        {
            "level": "lv1",
            "maxSubAcctQty": "1000",
            "subAcctQty": "6",
            "ts": "1637301641775"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
subAcctQty String Number of created sub-accounts
maxSubAcctQty String Maximum number of sub-accounts that can be created
level String The user level of the current real trading volume on the platform, e.g lv1
ts String Time,Unix timestamp format in milliseconds, e.g. 1597026383085

Create sub-account

Create a sub-account from the broker master account.

Rate Limit: 1 request per second

HTTP Request

POST /api/v5/broker/nd/create-subaccount

Request Example

POST /api/v5/broker/nd/create-subaccount
body
{
    "pwd":"1234567890",
    "subAcct":"brokerTest5",
    "acctLv":"3",
    "label":"5566"
}

Request Parameters

Parameter Type Required Description
pwd String Yes Funds password of the primary account
subAcct String Yes Sub-account name
label String Yes Sub-account notes
acctLv String No Account level
1: Simple 2: Single-currency margin 3: Multi-currency margin 4:Portfolio margin

Response Example

{
    "code": "0",
    "data": [
        {
            "acctLv": "3",
            "label": "5566",
            "subAcct": "brokerTest5",
            "ts": "1637141950450"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name
label String Sub-account notes
acctLv String Account level
ts String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Delete sub-account

Before the sub-account can be deleted, all funds must be transferred from this sub-account

Rate Limit: 1 request per second

HTTP Request

POST /api/v5/broker/nd/delete-subaccount

Request Example

POST /api/v5/broker/nd/delete-subaccount
body
{
    "pwd":"1234567890",
    "subAcct":"yonxws"
}

Request Parameters

Parameter Type Required Description
pwd String Yes Funds password of the primary account
subAcct String Yes Sub-account name

Response Example

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "test-1"
    }]
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name

Get sub-account list

Get details of the sub-account list

Rate Limit: 1 request per second

HTTP Request

GET /api/v5/broker/nd/subaccount-info

Request Example

GET /api/v5/broker/nd/subaccount-info

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
page String No Page for pagination
limit String No Number of results per request. The maximum is 100; the default is 100

Response Example

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "acctLv": "1",
                    "label": "11122",
                    "subAcct": "yonxws",
                    "ts": "1637052976000"
                },
                {
                    "acctLv": "1",
                    "label": "11122",
                    "subAcct": "brokerTest1",
                    "ts": "1637056638000"
                }
            ],
            "page": "1",
            "totalPage": "1"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
totalPage String Total number of pages
page String Current page number
details Array List of sub-accounts
> subAcct String Sub-account name
> label String Sub-account notes
> acctLv String Account level
1: Simple 2: Single-currency margin 3: Multi-currency margin 4:Portfolio margin
> ts String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Set the account level of the sub-account

Adjusts the account level of the sub-account from the broker master account

Rate Limit: 5 requests 2 seconds

HTTP Request

POST /api/v5/broker/nd/set-subaccount-level

Request Example

POST /api/v5/broker/nd/set-subaccount-level
body
{
    "acctLv":"3",
    "subAcct":"brokerTest3"
}

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
acctLv String Yes Account level
1: Simple 2: Single-currency margin 3: Multi-currency margin 4:Portfolio margin

Response Example

{
    "code": "0",
    "data": [
        {
            "acctLv": "3"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
acctLv String Account level
1: Simple 2: Single-currency margin 3: Multi-currency margin 4:Portfolio margin

Set trading fee rate for the sub-account

The sub-accounts trading fee rate is the base fee rate of the current tier plus the change that either absolute or percentage.
After setting the sub-accounts’ trading fee rate, the effective time is 00:00 of T+1. For example, if the trading fee rate of the sub-account is adjusted today, it will take effect at 0:00 tomorrow. There may be about 15 minutes delay in the effective time.

Rate Limit: 5 requests 2 seconds

HTTP Request

POST /api/v5/broker/nd/set-subaccount-fee-rate

Request Example

POST /api/v5/broker/nd/set-subaccount-fee-rate
body
{
    "subAcct":"broker4",
    "chgType":"absolute",
    "chgTaker":"90",
    "chgMaker":"90",
    "effDate":"20211219"
}

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
chgType String Yes absolute: Absolute change of the fee rate
percentage: Percentage change of the fee rate
chgTaker String Optional Taker fee rate
chgMaker String Optional Maker fee rate
Either chgTaker or chgMaker is required
effDate String No Effective date
Format: YYYYMMDD, e.g. 20210623

Response Example

{
    "code": "0",
    "data": [
        {
            "subAcct": "brokerTest4",
            "effTs": "20211119"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name
effDate String Effective date

Create deposit address for sub-account

Create the deposit address for the sub-account from the broker master account Up to 20 deposit addresses for each currency.

Rate Limit: 5 requests 2 seconds

HTTP Request

POST /api/v5/asset/broker/nd/subaccount-deposit-address

Request Example

POST /api/v5/asset/broker/nd/subaccount-deposit-address
body
{
    "ccy":"BTC",
    "subAcct":"brokerTest5"
}

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
ccy String Yes Currency, e.g. USDT
chain String No Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
addrType String No Deposit address type
1: SegWit addres
2: Regular address
Only applicable to BTC and LTC
to String No The beneficiary account
6:Funding 18:Unified account

Response Example

{
    "code": "0",
    "data": [
        {
            "chain": "EOS-EOS",
            "ccy": "EOS",
            "memo": "10810086",
            "addr": "okbtothemoon",
            "ts": "1637141950450"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ccy String Currency, e.g. USDT
addr String Deposit address
chain String Network name
pmtId String This field is required for certain currency withdrawals. If this field is not applicable for the currency, e.g. XMR, then return ""
tag String This field is required for some currency withdrawals. If this field is not applicable for the currency, e.g. XRP, then return ""
memo String This field is required for some currency withdrawals. If this field is not applicable for the currency, e.g. EOS, then return ""
ts String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get sub-account deposit address

Retrieve the deposit addresses of the sub-account.

Rate Limit: 5 requests 2 seconds

HTTP Request

GET /api/v5/asset/broker/nd/subaccount-deposit-address

Request Example

GET /api/v5/asset/broker/nd/subaccount-deposit-address?ccy=BTC

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
ccy String Yes Currency, e.g. BTC

Response Example

{
    "code": "0",
    "data": [
        {
            "chain": "XMR-Monero",
            "ctAddr": "",
            "ccy": "XMR",
            "to": "6",
            "addr": "884ifkSCavs9X759FZhfmrNmEbimqnXdofsd5kqXwuxfJMKZPKCfSAubrnwanuUf2JJi6hwskfcYzAUGodkJj3RsHAVFoDm",
            "selected": false
        },
        {
            "chain": "XMR-Monero",
            "ctAddr": "",
            "ccy": "XMR",
            "to": "6",
            "addr": "88aCNpJgfX1DGZ2HPd5i9DaAmyuRiQbnFGVbc8AFXgAhi4i7eX6sRm75m1UuJNZxwfMh4xBwV5fv6h4A5v1qQET5LHnXqgn",
            "selected": false
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
addr String Deposit address
tag String Deposit tag (it will not be returned if the currency does not require a tag for deposit)
memo String Deposit memo (it will not be returned if the currency does not require a memo for deposit)
pmtId String Deposit payment ID (it will not be returned if the currency does not require a pmtId for deposit)
ccy String Currency, e.g. BTC
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
to String The beneficiary account
6:Funding account 18:Unified account
selected Boolean Return true if the current deposit address is selected on the website page
ctAddr String Last 6 digits of the contract address

Get sub-account deposit history

Retrieve the deposit history of the sub-account.

Rate Limit: 5 requests 2 seconds

HTTP Request

GET /api/v5/asset/broker/nd/subaccount-deposit-history

Request Example

GET /api/v5/asset/broker/nd/subaccount-deposit-history?subAcct=brokerTest1&state=1

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
ccy String No Currency, e.g. BTC
txId String No Hash record of the deposit
state String No Status of deposit
0: waiting for confirmation 1: deposit credited 2: deposit successful
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
limit string No Number of results per request. The maximum is 100; The default is 100

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "amt": "0.01044408",
      "txId": "1915737_3_0_0_asset",
      "ccy": "BTC",
      "chain":"BTC-Bitcoin",
      "from": "13801825426",
      "to": "",
      "ts": "1597026383085",
      "state": "2",
      "depId": "4703879"
    }
  ]
}

Response Parameters

Parameter Type Description
ccy String Currency
chain String Chain name
amt String Deposit amount
from String Only the internal OKEx account is returned, not the address on the blockchain.
to String Deposit address
txId String Hash record of the deposit
ts String Time that the deposit is credited, Unix timestamp format in milliseconds, e.g. 1597026383085
state String Status of deposit
0: waiting for confirmation 1: deposit credited 2: deposit successful 8: Pending due to temporary deposit suspension on this crypto currency
depId String Deposit ID

Get daily rebate records

Retrieve the rebate records of the sub-account from the broker master account

Rate Limit: 1 request 10 seconds

HTTP Request

GET /api/v5/broker/nd/rebate-daily

Request Example

GET /api/v5/broker/nd/rebate-daily

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
begin String No Start date, in the format of YYYYMMDD, e.g. 20210623
end String No End date, in the format of YYYYMMDD, e.g. 20210627
page String No Page number for pagination
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
    "code": "0",
    "data": [
        {
            "details": [
                {
                    "income": "1.9050116363636365",
                    "rebateDate": "20211119",
                    "subAcct": "brokerTest2"
                },
                {
                    "income": "3.5728228419999565",
                    "rebateDate": "20211119",
                    "subAcct": "brokerTest1"
                },
                {
                    "income": "10.6047378063846898",
                    "rebateDate": "20211119",
                    "subAcct": "brokerTest2"
                }
            ],
            "page": "",
            "totIncome": "16.0630733992516302",
            "totPage": "1",
            "ts": "1637303853605"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp of data query, Unix timestamp format in milliseconds, e.g. 1597026383085
totIncome String The total cash back amount under the broker
totPage String Total number of pages
page String Current page number
details Array Sub-account rebate amount record list
> subAcct String Sub-account name
> income String Rebate amount for each sub-account, the unit is USDT
> rebateDate String Rebate date, in the format of YYYYMMDD, e.g. 20210623

Position risk warning push

WebSocket : pre-warning notification of liquidation
Channel : liquidation-warning
This push channel is only used as a risk warning, and is not recommended as a risk judgment for strategic trading
In the case that the market is not moving violently, there may be the possibility that the position has been liquidated at the same time that this message is pushed.

OAuth Broker

Introduction

With OKEx OAuth 2.0, users can trade with OKEx after one-click authorization from third-party applications. No password or account AP key is required.
OKEx OAuth 2.0 is available in both Web and Mobile applications and is developed based on some new features in the OAuth 2.0 protocol (RFC 6749) and the OAuth 2.1 draft protocol.

Preparation before Integration

  1. Register your account and apply for broker via the official website
    You need to apply for an OAuth broker first and gain access to client_id and client_secret information after approval.
    Integration Procedures:
    1) Brokers apply for OKEX accounts.
    2) Brokers apply to be an OAuth broker via OKEx official website and fill out the application form and fields with red asterisk are mandatory.
    3) OKEX will review the application form within 2 days after receiving it.
    4) The broker will receive an email notification including client_id and client_secret once the application form is approved by OKEx's platform.

  2. OAuth Rebate settings
    OAuth-Broker needs to add BrokerCode in the Tag during order placement, and OKEx will use that Tag to calculate rebate.

Introduction of authorization mode

OKEx OAuth 2.0 provides: authorization code mode and PKCE mode.

Authorization mode Descriptions Scenario
Authorization code mode With user authorization, the third-party app provides client_secret to get authorization code. access token and refresh token can be retrieved based on authorization codes. The application has a server, which can store app keys and interact with the OKEx OAuth server .
PKCE mode With User authorization, the third-party app provides code_verifier as a temporary key to obtain authorization code. access token and refresh token can be retrieved based on authorization codes. The application has no server (or does not want the back-end server to intervene in the authorization process), therefore it can not store the app key or interact with the OKEx OAuth server through random characters.

Authorization code mode

This mode is available in both App and Web application. User authorizes third-party application from an authorisation page, which receives user authorization code. After that, application exchanges it for access token, which can be used to call OKEx OpenAPI.

PKCE mode

If the third-party application does not have a server or does not want the server to participate in the authorization process or not able to store the third-party app key (client_secret), then this mode is recommended to obtain token through client device access to effectively enhance the security of developer applications.

Usage of Token

Differences between tokens

After the third-party application calls the token exchange endpoint through authorization code, there will be two types of tokens.

How to use

Example

curl -H "Content-Type:application/json" \
-H "Authorization:Bearer eyJhbGciOiJIUzUxMiIsImNpZCI6ImFhIn0.eyJqdGkiOiJleDExMDE2Mzg4NDM3ODg1MzIxMzMzNUVGMkVGRTNGOUM2Y1BJWiIsInVpZCI6IlEybEZxMnY2N0VybnVMZ0o1cFYzdUE9PSIsIm1pZCI6InFGbG5lVEc4dnlJeDNMSnNSa29qZ0E9PSIsImlhdCI6MTYzODg0Mzc4OCwiZXhwIjoxNjM4ODQ3Mzg4LCJzdWIiOiIxMC4yNTQuMjcuMTIwIiwiYW95IjoiOSIsInZlciI6IjEiLCJkZXYiOiIzMmNmOWM2My02NzM3LTRhYjUtYjFhYi04ODU4YWU2NTkxODUiLCJndHkiOiJhdXRob3JpemUifQ.bWXsgN7hTszxmdFB9xhr0Qh67HQWIp2zoxoqMCUzw2y1MBFPm38nNJJY9coljkivgAQPso81YUnHoLsFOLjxGg"  \
-H "TERMID:32cf9c63-6737-4ab5-b1ab-8858ae659185" \
https://www.okex.com/api/v5/asset/currencies

After the third-party app completes the authorization and obtains the token, it will be able to call the OKEx OpenAPI endpoint through the access token. When requesting, you need to carry the following information in the request header:

Header Parameters Required Descriptions
Authorization Yes Fill in the access token as bearer to this field, e.g. Access token is "1234567890", then the content of the field should be "Bearer 1234567890"
TERMID Optional This field is used to verify the validity of the request
If the request is initiated by the third-party client device app (such as selecting PKCE mode), the client device should include the device ID when requesting again
If the request is initiated by the third-party app server (if the authorization code mode is selected), there is no need to fill in this field

Token validity

If the access token expires, the endpoint will no longer be accessible. If the refresh token is still within the valid period, the third-party app needs to call the refresh token endpoint to obtain a new pair of access token and refresh token. The new access token can continue to be used.
When a new access token is retrieved via refresh token, the old access token can not be used regardless of whether it has expired or not.
When you revoke the token, the original one will no longer be valid.

Permissions

Permissions Scope Descriptions
read_only For read-only function permissions (not include sub-account modules)
trade For trading function permissions (not include sub-account modules)

Error Code

Error Message HTTP Status Code Error Code
53000 400 Invalid token
53001 400 Authorization canceled
53002 400 Token expired
53003 400 Token revoked
53004 400 Account has been frozen
53005 400 Wrong refresh token
53006 401 Invalid device
53009 400 Authorization failed
53010 400 Parameter {0} error
53011 400 Parameter {0} cannot be empty
53012 400 Authorization code expired
53013 400 You need higher permissions
53014 401 Invalid IP
53015 400 Parameter {name} length cannot exceed {max length}
53016 400 Invalid redirect_uri