NAV
中文
HTTP Python

Broker Program

If your business platform offers cryptocurrency services, you can apply to join the OKX Broker Program, become our partner broker, enjoy exclusive broker services, and earn high rebates through trading fees generated by OKX users.
The Broker Program includes, and is not limited to, integrated trading platforms, trading bots, copy trading platforms, trading bot providers, quantitative strategy institutions, asset management platforms etc.

Relevant information for specific Broker Program documentation and product services will be provided following successful applications.

Broker guide

Get rebate guide

When an OKX broker is using any of our V5 APIs, there is a tag field. Do make sure to use your unique broker code in order to ensure we know the volume is coming from your end.
This code can be seen in your Broker Dashboard
With the broker code attached, brokers will be able to receive commissions and able to track the trading data on the dashboard

Common V5 API for brokers

When the OKX Broker broker calls the OKX V5 API interface, when the request parameter has tag, please be sure to enter your exclusive Broker code information to realize the association between the order and the broker.
When the order is entered into the Brokercode information, the broker can enjoy the corresponding commission reward, data statistics and other specific logic tracking.

Core trading

More details

Algo trading

More details

Grid trading

More details

Recurring Buy

More details

Block trading

More details

Spread Trading

More details

Convert

More details

Financial Product

More details

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

Applies to ND broker master accounts API Key only.

Get broker account information

Retrieve broker account information

Rate Limit: 1 request per second

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/broker/nd/info

Request Example

GET /api/v5/broker/nd/info
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Retrieve broker account information
result = ndBrokerAPI.get_broker_info()
print(result)

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 Unix timestamp format in milliseconds, e.g. 1597026383085

Create sub-account

Create a sub-account from the broker master account.

Rate Limit: 40 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

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

Request Example

POST /api/v5/broker/nd/create-subaccount
body
{
    "subAcct":"brokerTest5",
    "label":"5566"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Create a sub-account
result = ndBrokerAPI.create_subaccount(
    subAcct="brokerTest5",
    label="5566"
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
6-20 letters (case sensitive) or numbers, which can be pure letters and not pure numbers.
label String No Sub-account notes
No more than 50 letters (case sensitive) or numbers, which can be pure letters or pure numbers.
clientIP String No Sub-account register IP
Please use ND server IP for non personal accounts
mainAcct String Conditional Main account name of the second-level sub-account
When you are creating the first-level sub-account, it should be ""
When you are creating the second-level sub-account, it is required and should be the first-level sub-account.

Response Example

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

Response Parameters

Parameter Type Description
subAcct String Sub-account name
label String Sub-account notes
acctLv String Account level
1: Simple
If you want to set account level, refer to Set the account level of the sub-account
uid String Account ID
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: 10 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

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

Request Example

POST /api/v5/broker/nd/delete-subaccount
body
{
    "subAcct":"yonxws"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Delete a sub-account
result = ndBrokerAPI.delete_subaccount(
    subAcct="brokerTest5"
)
print(result)

Request Parameters

Parameter Type Required Description
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

Rate Limit: 1 request per second

Rate limit rule: UserID

Permissions: Read

HTTP Request

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

Request Example

GET /api/v5/broker/nd/subaccount-info
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account list
result = ndBrokerAPI.get_subaccount_info()
print(result)

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
uid String No Sub-account UID
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",
                    "canTransOut": false,
                    "mainAcct": "",
                    "enable": true,
                    "frozenFunc": [],
                    "label": "1",
                    "subAcct": "h*******5",
                    "ts": "1648521249000",
                    "uid": "289*********1696"
                }
            ],
            "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
> uid String Sub-account UID
> label String Sub-account notes
> acctLv String Account level
1: Simple
2: Single-currency margin
3: Multi-currency margin
4:Portfolio margin
> enable Boolean Sub-account status
true: normal
false: frozen (global)
> frozenFunc Array of string Frozen functions
trading
convert
transfer
withdrawal
deposit
flexible_loan
> canTransOut String Whether the sub-account has the right to transfer out.(Directly transfer to another sub account through the sub account APIKey)
true: can transfer out
false: cannot transfer out
> mainAcct String Main account name of the second-level sub-account
It is the first-level sub-account when mainAcct is ""
It is the second-level sub-account when mainAcct has value.
> ts String Creation time of sub-account, Unix timestamp format in milliseconds, e.g. 1597026383085

Create an API Key for a sub-account

Rate limit:40 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

POST /api/v5/broker/nd/subaccount/apikey

Request sample

POST /api/v5/broker/nd/subaccount/apikey
body
{
    "subAcct":"panpanBroker2",
    "label":"broker3",
    "passphrase":"Qwr4321!",
    "perm":"read_only,trade",
    "ip":"10.0.108.9"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Create an API Key for a sub-account
result = ndBrokerAPI.create_subaccount_apikey(
    subAcct="panpanBroker2",
    label="broker3",
    passphrase="Qwr4321!",
    perm="trade",
    ip="10.0.108.9"
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name, supports 6 to 20 characters that include numbers and letters (case sensitive, space character is not supported).
label String Yes API Key note
No more than 50 letters (case sensitive) or numbers, which can be pure letters or pure numbers.
passphrase String Yes API Key password, supports 8 to 32 alphanumeric characters containing at least 1 number, 1 uppercase letter, 1 lowercase letter and 1 special character.
ip String No Link IP addresses, separate with commas if more than one. Support up to 20 addresses.
For security reasons, it is recommended to bind IP addresses.
API keys with trading or withdrawal permissions that are not bound to IPs will expire after 14 days of inactivity. (API keys in demo trading will not be deleted.)
perm String No API Key permissions
read_only: Read only, it is the default value and can't be removed
trade: Trade
withdraw: Withdraw

Returned result

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "panpanBroker2",
        "label": "broker3",
        "apiKey": "****",
        "secretKey": "****",
        "passphrase": "Qwr4321!",
        "perm": "read_only,trade",
        "ip": "10.0.108.9",
        "ts": "1597026383085"
    }]
}

Response parameters

Parameter Type Description
subAcct String Sub-account name
label String API Key note
apiKey String API public key
secretKey String API private key
passphrase String API Key password
perm String API Key access
read_only: Read only trade: Trade
ip String IP address that linked with API Key
ts String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Query the API Key of a sub-account

Rate limit:1 request per second

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/broker/nd/subaccount/apikey

Request sample

Get /api/v5/broker/nd/subaccount/apikey?subAcct=panpanBroker2
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Query the API Key of a sub-account
result = ndBrokerAPI.get_subaccount_apikey(
    subAcct="panpanBroker2",
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
apiKey String No API public key

Returned results

    "code":"0",
    "msg":"",
    "data":[
        {
            "label":"v5",
            "apiKey":"arg13sdfgs",
            "perm":"read_only,trade",
            "ip":"1.1.1.1,2.2.2.2",
            "ts":"1597026383085"
        },
        {
            "label":"v5.1",
            "apiKey":"arg13sdfgs",
            "perm":"read_only",
            "ip":"1.1.1.1,2.2.2.2",
            "ts":"1597026383085"
        }
    ]
}

Response parameters

Parameter Type Description
label String API Key note
apiKey String API public key
perm String API Key access
read_only: Read
trade: Trade
withdraw: Withdraw
ip String IP address that linked with API Key
ts String API Key creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Reset the API Key of a sub-account

Rate limit:10 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

POST /api/v5/broker/nd/subaccount/modify-apikey

Request sample

POST /api/v5/broker/nd/subaccount/modify-apikey
body
{
    "subAcct":"yongxu",
    "perm":"read_only",
    "label":"test7",
    "apiKey":"49e1b84b-6dee-4894-80ee-ce9eb7ad614f"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Reset the API Key of a sub-account
result = ndBrokerAPI.reset_subaccount_apikey(
    subAcct="panpanBroker2",
    perm="read_only",
    label="test7",
    apiKey="49e1b84b-6dee-4894-80ee-ce9eb7ad614f"
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
apiKey String Yes API public key
label String No API Key note
No more than 50 letters (case sensitive) or numbers, which can be pure letters or pure numbers.
The field will be reset if set.
perm String No API Key permissions
read_only: Read only, it is the default value and can't be removed
trade: Trade
withdraw: Withdraw
Separate with commas if more than one.
The field will be reset if set.
ip String No Link IP addresses, separate with commas if more than one. Support up to 20 IP addresses.
The field will be reset if set.

Returned results

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "yongxu",
        "label": "test7",
        "apiKey": "arg13sdfgs",
        "perm": "read,trade",
        "ip": "",
        "ts": "1597026383085"
    }]
}

Response parameters

Parameter Type Description
subAcct String Sub-account name
label String API Key note
apiKey String API public key
perm String API Key access
read_only: Read only
trade: Trade
ip String IP address that linked with API Key
ts String Updated time, Unix timestamp format in milliseconds, e.g. 1597026383085

Delete the API Key of sub-accounts

Rate limit:10 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

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

Request sample

POST /api/v5/broker/nd/subaccount/delete-apikey
body
{
    "subAcct":"test00001",
    "apiKey":"b521e11c-b4ed-4c80-9624-346d69749a85"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Delete the API Key of sub-accounts
result = ndBrokerAPI.delete_subaccount_apikey(
    subAcct="panpanBroker2",
    apiKey="49e1b84b-6dee-4894-80ee-ce9eb7ad614f"
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
apiKey String Yes API public key

Returned results

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

Response parameters

Parameter Type Description
subAcct String Sub-account name

Set the account level of the sub-account

Adjusts the account level of the sub-account from the broker master account.
If the master account wants to adjust its account level, refer to Set account mode.

Rate Limit: 5 requests 2 seconds

Rate limit rule: UserID

Permissions: Trade

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"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Set the account level of the sub-account
result = ndBrokerAPI.set_subaccount_level(
    subAcct="panpanBroker2",
    acctLv="3",
)
print(result)

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 T+1 hour (HKT).

Rate Limit: 5 requests per 2 seconds

Rate limit rule: UserID

Permissions: Trade

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"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Set trading fee rate for the sub-account
result = ndBrokerAPI.set_subaccount_fee_rate(
    subAcct="panpanBroker2",
    chgType="absolute",
    chgTaker= "90",
    chgMaker= "90",
    effDate= "20211219"
)
print(result)

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
quoteCcyType String No Quote currency type
2: USDT
3: USDⓈ/Crypto
Applicated to SPOT
When specifying this parameter, instType is required.
mgnType String No Margin type
1: USDT-margined
2: crypto-margined
3: USDC-margined
Applicated to FUTURES/SWAP
When specifying this parameter, instType is required.
chgType String Yes Type of fee rate
absolute: Absolute change of the fee rate
percentage: Percentage change of the fee rate based on basic trading fee
chgTaker String Conditional Taker fee rate for changing
For absolute: The unit is bp (1bp = 0.01%). Range belongs to [0 bp, 1,000bp], same as [0.00%, 10%]. Precision is 0.1 bp.
For percentage: The unit is percent(%). Range belongs to [0%, 10000%]. Precision is 1%
chgMaker String Conditional Maker fee rate for changing
For absolute: The unit is bp (1bp = 0.01%). Range belongs to [0 bp, 1,000bp], same as [0.00%, 10%]. Precision is 0.1 bp.
For percentage: The unit is percent(%). Range belongs to [0%, 10000%]. Precision is 1%
Either chgTaker or chgMaker is required.
effDate String No Effective date
Format: YYYYMMDD, e.g. 20210623
It will be effective on the next day (T+1) when do not use effDate;
It will be effective at 00:00(HKT) on the day you set when using effDate.

Response Example

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

Response Parameters

Parameter Type Description
subAcct String Sub-account name
effTs String Effective data
Format: YYYYMMDD, e.g. 20210623

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. Lightning deposits has the independent API.

Rate Limit: 10 requests per second

Rate limit rule: UserID

Permissions: Trade

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"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Create deposit address for sub-account
result = ndBrokerAPI.create_subaccount_deposit_address(
    ccy="BTC",
    subAcct="panpanBroker2"
)
print(result)

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
If the parameter is not filled in, the default will be the main chain.
addrType String No Deposit address type
1: Regular addres
2: SegWit address (Only applicable to BTC/LTC)
Default is 1
to String No The beneficiary account
6: Funding
18: Trading account
Default is 6

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, e.g. XMR.
If this field is not applicable for the currency, the parameter will not be returned
tag String This field is required for some currency withdrawals, e.g. XRP
If this field is not applicable for the currency, the parameter will not be returned
memo String This field is required for some currency withdrawals, e.g. EOS
If this field is not applicable for the currency, the parameter will not be returned
comment String This field is required for some currency withdrawals, e.g. TON
If this field is not applicable for the currency, the parameter will not be returned
ts String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Modify sub-account deposit address

Currently only the adjustment of beneficiary account is supported.

Rate Limit: 6 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

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

Request Example

POST /api/v5/asset/broker/nd/modify-subaccount-deposit-address
body
{
    "subAcct":"test",
    "ccy":"USDT",
    "chain":"USDT-ERC20"
    "addr":"1123456",
    "to":"18"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Modify sub-account deposit address
result = ndBrokerAPI.reset_subaccount_deposit_address(
    ccy="USDT",
    subAcct="panpanBroker2",
    chain="USDT-ERC20",
    addr="1123456",
    to="18"
)
print(result)

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
If the parameter is not filled in, the default will be the main chain.
addr String Yes Deposit address
Some digital currency addresses are formatted as 'address+tag', e.g. 'ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456'
to String Yes The beneficiary account
6:Funding 18:Trading account
The beneficiary account is a global setting, which will affect the beneficiary account of all the deposit addresses for the single sub-account

Response Example

{
    "code": "0",
    "data": [
        {
            "chain": "USDT-ERC20",
            "ccy": "USDT",
            "to": "18",
            "addr": "1123456",
            "ts": "1654778132000"
        }
    ],
    "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 ""
comment String This field is required for some currency withdrawals. If this field is not applicable for the currency, e.g. TON, then return ""
to String Current beneficiary account
6: Funding 18: Trading account
ts String Updated time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get sub-account deposit address

Retrieve the deposit addresses of the sub-account.

Rate Limit: 6 requests 1 second

Rate limit rule: UserID

Permissions: Read

HTTP Request

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

Request Example

GET /api/v5/asset/broker/nd/subaccount-deposit-address?ccy=BTC&subAcct=brokerTest1
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account deposit address
result = ndBrokerAPI.get_subaccount_deposit_address(
    ccy="USDT",
    subAcct="panpanBroker2"
)
print(result)

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)
comment String Deposit comment (it will not be returned if the currency does not require a comment for deposit)
ccy String Currency, e.g. BTC
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20
to String The beneficiary account
6: Funding account
18: Trading 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.
Websocket API is also available, refer to Deposit info channel.

Rate Limit: 5 requests 2 seconds

Rate limit rule: UserID

Permissions: Read

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
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get sub-account deposit history
result = ndBrokerAPI.get_subaccount_deposit_history()
print(result)

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
ccy String No Currency, e.g. BTC
txId String No Hash record of the deposit
type String No Deposit Type
3: internal transfer
4: deposit from chain
state String No Status of deposit

0: waiting for confirmation
1: deposit credited
2: deposit successful
8: Pending due to temporary deposit suspension on this crypto currency
11: match the address blacklist
12: account or deposit is frozen
13: sub-account deposit interception
14: KYC limit
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",
      "actualDepBlkConfirm":"20",
      "txId": "1915737_3_0_0_asset",
      "ccy": "BTC",
      "chain":"BTC-Bitcoin",
      "from": "13801825426",
      "areaCodeFrom": "86",
      "to": "",
      "ts": "1597026383085",
      "state": "2",
      "subAcct": "brokerTest1",
      "depId": "4703879"
    }
  ]
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name
ccy String Currency
chain String Chain name
amt String Deposit amount
from String Deposit account
Only the internal OKX account is returned, not the address on the blockchain.
areaCodeFrom String If from is a phone number, this parameter returns the area code of the phone number
to String Deposit address
txId String Hash record of the deposit
ts String The timestamp that the deposit record is created, 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
11: match the address blacklist
12: account or deposit is frozen
13: sub-account deposit interception
14: KYC limit
depId String Deposit ID
actualDepBlkConfirm String The actual amount of blockchain confirmed in a single deposit

Sub-account withdrawal

ND sub-account supports withdrawal, and you can use an ND sub-account API Key to call Withdrawal.

Get sub-account withdrawal history

Retrieve the withdrawal history of the sub-account.
Websocket API is also available, refer to Withdrawal info channel.

Rate Limit: 5 requests 2 seconds

Rate limit rule: UserID

Permissions: Read

HTTP Request

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

Request Example

GET /api/v5/asset/broker/nd/subaccount-withdrawal-history?subAcct=brokerTest1

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
ccy String No Currency, e.g. BTC
wdId String No Withdrawal ID
clientId String No Client-supplied ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
txId String No Hash record of the deposit
type String No Withdrawal type
3: internal transfer
4: withdrawal to chain
state String No Status of withdrawal
-3:canceling
-2:canceled
-1:failed
0:waiting withdrawal
1:withdrawing
2:withdraw success
7: approved
10: waiting transfer
4, 5, 6, 8, 9, 12: waiting mannual review
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1654041600000
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1656633600000
limit String No Number of results per request. The maximum is 100; The default is 100

Response Example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "subAcct":"brokerTest1",
      "chain": "ETH-Ethereum",
      "fee": "0.007",
      "feeCcy": "ETH",
      "ccy": "ETH",
      "clientId": "",
      "amt": "0.029809",
      "txId": "0x35c******b360a174d",
      "to": "0xa30d1fab********7CF18C7B6C579",
      "areaCodeTo": "",
      "state": "2",
      "ts": "1655251200000",
      "wdId": "15447421"
    }
  ]
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name
ccy String Currency
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20
nonTradableAsset Boolean Whether it is a non-tradable asset or not
true: non-tradable asset, false: tradable asset
amt String Withdrawal amount
ts String Time the withdrawal request was submitted, Unix timestamp format in milliseconds, e.g. 1655251200000.
to String Receiving address
areaCodeTo String Area code for phone number
If to is a phone number, this parameter return the area code for phone number
tag String Some currencies require a tag for withdrawals. This is not returned if not required.
pmtId String Some currencies require a payment ID for withdrawals. This is not returned if not required.
memo String Some currencies require this parameter for withdrawals. This is not returned if not required.
addrEx Object Withdrawal address attachment (This will not be returned if the currency does not require this) e.g. TONCOIN attached tag name is comment, the return will be {'comment':'123456'}
txId String Hash record of the withdrawal.
This parameter will return "" for internal transfers.
fee String Withdrawal fee amount
feeCcy String Withdrawal fee currency, e.g. USDT
state String Status of withdrawal
-3:canceling
-2:canceled
-1:failed
0:waiting withdrawal
1:withdrawing
2:withdraw success
7: approved
10: waiting transfer
4, 5, 6, 8, 9, 12: waiting mannual review
wdId String Withdrawal ID
clientId String Client-supplied ID

Get daily rebate records

Retrieve the rebate records of the sub-account from the broker master account. Rebate records is hourly calculated (T+1 Hour).
Return results in reverse chronological order.

Rate Limit: 1 request 10 seconds

Rate limit rule: UserID

Permissions: Read

HTTP Request

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

Request Example

GET /api/v5/broker/nd/rebate-daily
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get daily rebate records
result = ndBrokerAPI.get_rebate_daily()
print(result)

Request Parameters

Parameter Type Required Description
subAcct String No Sub-account name
begin String No Begin date, in the format of YYYYMMDD, e.g. 20210623, search data after 2021/06/23 00:00:00 (include)
end String No End date, in the format of YYYYMMDD, e.g. 20210623, search data before 2021/06/24 00:00:00 (exclude)
beginTime String No Begin time, Unix timestamp format in milliseconds, e.g. 1597026383085 , search data after 1597026383085 (include)
endTime String No End time, Unix timestamp format in milliseconds, e.g. 1597026383085 , search data before 1597026383085 (exclude)
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": "0.01857038047018",
                "incomeCat": {
                  "convert": "0",
                  "derivative": "0",
                  "spot": "0.01857038047018"
                },
                "markupFee": "-0.0147228174975",
                "markupFeeCat": {
                  "convert": "0",
                  "derivative": "0",
                  "spot": "-0.0147228174975"
                },
                "netFee": "0.0096189074317",
                "netFeeCat": {
                  "derivative": "0",
                  "spot": "0.0096189074317"
                },
                "rebateDate": "20230718",
                "rebateTime": "1689609601000",
                "subAcct": "testing"
              }
            ],
            "page": "1",
            "totIncome": "0.51129485727208",
            "totIncomeCat": {
                "convert": "0",
                "derivative": "0",
                "spot": "0.50704793427208"
            },
            "totPage": "1",
            "ts": "1689846562790"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp of data query, Unix timestamp format in milliseconds, e.g. 1597026383085
totIncome String The total rebate amount
totIncomeCat Object Category statistics for the total rebate amount
> spot String Total Rebate amount for spot, the unit is USDT
> derivative String Total Rebate amount for derivative, the unit is USDT
> convert String Total Rebate amount for convert, the unit is USDT
totPage String Total number of pages
page String Current page number
details Array of object Sub-account rebate amount record list
> subAcct String Sub-account name
> income String Rebate amount of the sub-account, the unit is USDT
> incomeCat Object Category statistics for the rebate amount of the sub-account
>> spot String The rebate amount of the sub-account for spot, the unit is USDT
>> derivative String The rebate amount of the sub-account for derivative, the unit is USDT
>> convert String The rebate amount of the sub-account for convert, the unit is USDT
> netFee String The net fee of the sub-account, the unit is USDT
> netFeeCat Object Category statistics for the net fee of the sub-account
>> spot String The net fee of the sub-account for spot, the unit is USDT
>> derivative String The net fee of the sub-account for derivative, the unit is USDT
> markupFee String The markup fee of the sub-account, the unit is USDT
> markupFeeCat Object Category statistics for the markup fee of the sub-account
>> spot String The markup fee of the sub-account for spot, the unit is USDT
>> derivative String The markup fee of the sub-account for derivative, the unit is USDT
>> convert String The markup fee of the sub-account for convert, the unit is USDT
> rebateDate String Rebate date, in the format of YYYYMMDD, e.g. 20210623
> rebateTime String Rebate time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get the download link of the commission rebate details that have been successfully applied for. After the download link is generated, it will only be valid for 9 hours.

GET /api/v5/broker/nd/rebate-per-orders

Request Example

GET /api/v5/broker/nd/rebate-per-orders?type=false&begin=20221207&end=20230207
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get the download link of the commission rebate details
result = ndBrokerAPI.get_rebate_details_download_link()
print(result)
Parameter Type Required Description
type String Yes Type
true: Get all the generated history for the current user
false: Query the specified history
begin String Optional Begin date for download link generated, in the format of YYYYMMDD, e.g. 20210623, search data after 2021/06/23 00:00:00 (include)
If type is false, this field is required
end String Optional End date for download link generated, in the format of YYYYMMDD, e.g. 20210623, search data before 2021/06/24 00:00:00 (exclude)
If type is false, this field is required

Response Example

{
    "code": "0",
    "data": [
        {
            "beginTime": "1671638400000",
            "cTime": "1671675432000",
            "endTime": "1671638400000",
            "fileHref": "http://okg-pri-hk.oss-cn-hongkong.aliyuncs.com/okex/broker/pap/brokerRebateInfo/dc9df1365dac6695737e7f17cae14198/21754f4be28dBCDE/2022-12-22/RebateDetails/RebateDetails1222-1222.csv?Expires=1697617451&OSSAccessKeyId=LTAI5tKNPwWs7AttSPZn4iaa&Signature=EdnQthE3PgXHFVtGlQ7gGILi%2Fbw%3D",
            "state": "finished",
            "ts": "1671676696000"
        }
    ],
    "msg": ""
}
Parameter Type Description
fileHref String Download file link
beginTime String Rebate record begin time, Unix timestamp format in milliseconds, e.g. 1597026383085
endTime String Rebate record end time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Generate download link request time, Unix timestamp format in milliseconds, e.g. 1597026383085
ts String Download link generation time, Unix timestamp format in milliseconds, e.g. 1597026383085
state String Download link status
"finished" "ongoing"
Parameter Description
subAcct Sub-account name
instId Instrument ID
ordId Order ID
rebate Rebate amount, in unit of USDT
rebateCat Rebate category
spot
derivative
convert
netFee Net fee (The handling fee base for commission settlement after removing data such as commission cards and counterparties), in unit of USDT
markupFee Markup fee, in unit of USDT
ts The last trade time of the order , Unix timestamp format in milliseconds, e.g. 1597026383085

Generate historical commission details for all ND accounts under NDBroker

POST /api/v5/broker/nd/rebate-per-orders

Request Example

POST /api/v5/broker/nd/rebate-per-orders
body
{
    "begin":"20210623",
    "end":"20210626"
}
import okx.NDBroker as NDBroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "1"  # Production trading: 0, Demo trading: 1

ndBrokerAPI = NDBroker.NDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Generate historical commission details
result = ndBrokerAPI.generate_rebate_details_download_link(
      begin="20220623",
      end="20210922"
)
print(result)
Parameter Type Required Description
begin String Yes Begin date, in the format of YYYYMMDD, e.g. 20210623, search data after 2021/06/23 00:00:00 (include)
end String Yes End date, in the format of YYYYMMDD, e.g. 20210623, search data before 2021/06/24 00:00:00 (exclude)

Response Example

{
    "code": "0",
    "data":[
      {
        "result": "false",
        "ts": "1646892328000"
      }
    ],
    "msg": ""
}
Parameter Type Description
result String Whether there is already a download link for this section
true: Existed, can check from "Get download link".
false: Does not exist and is generating, can check the download link after 6 hours
ts String Time when the server received the request to generate historical commission details. Unix timestamp format in milliseconds, e.g. 1597026383085

Get DCD products

DCD is also known as Dual Investment.

Please contact your account manager to enable the DCD feature. Return list of product details with indicative quote.

Rate limit:30 requests per 2 seconds

Rate limit rule: IP

Permissions: Read

HTTP Request

GET /api/v5/finance/sfp/dcd/products

Request Example

GET /api/v5/finance/sfp/dcd/products?ccy=BTC&alternativeCcy=USDT&optType=C&tag=123456789ABCDEFG

Request Parameters

Parameter Type Required Description
ccy String Yes Risky asset currency, e.g. BTC
alternativeCcy String Yes Stable-coin currency, e.g. USDT
optType String Yes Option type
C: Call, P: Put
For C, subscription currency is ccy
For P, subscription currency is alternativeCcy
tag String Yes Broker Code tag
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters.

Response Example

{
    "code": 0,
    "data": [
        {
            "absYield": "0.01302066",
            "altCcy": "USDT",
            "annualYield": "0.683",
            "ccy": "BTC",
            "expTime": "1683878400000",
            "interestAccrualTime": "1683277200000",
            "listTime": "1682969037000",
            "maxSize": "200.0000000000000000",
            "minSize": "0.0001000000000000",
            "notionalCcy": "BTC",
            "optType": "C",
            "productId": "BTC-USDT-230512-29500-C",
            "quota": "198.9990000000000000",
            "quoteTime": "1683275022001",
            "settTime": "1683885600000",
            "stepSize": "0.0001",
            "stk": "29500",
            "tag": "123456789ABCDEFG",
            "uly": "BTC-USD"
        }
    ],
    "msg": ""
}

Response parameters

Parameter Type Description
absYield String Indicative yield of the product
alternativeCcy String Stablecoin currency
annualYield String Indicative annualised yield of the product
ccy String Risky asset currency
expTime String Expiry time of the product
interestAccrualTime String Interest Accrual Time
listTime String Listing time of the product
maxSize String Maximum order size in notional currency
minSize String Minimum order size in notional currency
notionalCcy String Subscription currency
For Call, subscription currency is ccy
For Put, subscription currency is alternativeCcy
optType String Option type,
C: Call
P: Put
productId String Product ID
quota String Subscription quota in notional currency
quoteTime String Timestamp in ms of the quote
settTime String Timestamp in ms of settlement
stopTradingTime String Timestamp in ms of last trading time
stepSize String Order step size in notional currency
stk String Strike price
tag String Broker Code tag
uly String Underlying of the product

Request DCD quote

DCD is also known as Dual Investment.

Return the final quote of the product. Must be accessed from sub-account API key.

Rate limit:2 requests per 2 seconds

Rate limit rule: UserID

Permissions: Trade

HTTP Request

POST /api/v5/finance/sfp/dcd/quote

Request Example

POST /api/v5/finance/sfp/dcd/quote
body
{
    "clReqId": "Q001",  
    "markUp": "0.05",
    "notional": "1", 
    "notionalCcy": "BTC", 
    "productId": "BTC-USDT-220414-30800-C", 
    "tag": "123456789ABCDEFG"
}

Request Parameters

Parameter Type Required Description
clReqId String No Client Quote Request ID
Must be unique if populated
markUp String No Override default mark up of the quote. If omitted, the system will apply the default mark up.
Must be 0<=x<1
notional String Yes Notional amount of the quote, in the unit of the notional currency
notionalCcy String Yes Notional currency of the quote. It must match the notional currency of the product.
productId String Yes Product ID
tag String Yes Broker Code tag.

Response Example

{
    "code": 0,
    "msg": "",
    "data": [
        {
            "absYield": "0.001",
            "annualYield": "0.0822",
            "clQReqId": "Q001",
            "notional": "5", 
            "notionalCcy": "BTC",
            "productId": "BTC-USDT-221221-16900-C",
            "quoteId": "quoterbcDCD-QUOTE16715309383851388", 
            "ttlMs": "30000",
            "tag": "123456789ABCDEFG",
            "markUp": "0.05"
        }
    ]
}

Response parameters

Parameter Type Description
absYield String Yield of the product
annualYield String Annualised yield of the product
clReqId String Client Quote Request ID
notional String Notional amount of the quote, in the unit of the notional currency
notionalCcy String Notional currency of the quote. It must match the notional currency of the product.
productId String Product ID
quoteId String Quote ID
ttlMs String TTL in ms
tag String Broker Code tag.
markUp String Overridden mark up of the quote.
Return "" if it is not included in the request

Execute DCD order

Confirm order using the quote ID. The order must be confirmed within the TTL of the quote. Must be accessed from sub-account API key.

Rate limit:2 requests per 2 seconds

Rate limit rule: UserID

Permissions: Trade

HTTP Request

POST /api/v5/finance/sfp/dcd/order

Request Example

POST /api/v5/finance/sfp/dcd/order
body
{
    "clOrdId": "T001",
    "quoteId": "quoterbcDCD-QUOTE16715309383851388"
}

Request Parameters

Parameter Type Required Description
clOrdId String No Client Order ID as assigned by the client
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
Must be unique if populated
quoteId String Yes Quote ID from quote endpoint

Response Example

{
    "code": 0,
    "data": {
        "clOrdId": "T001",
        "orderId": "fa478b7a60d24cac966ea97c7e837380",
        "quoteId": "quoterbcDCD-QUOTE16715309383851388"
    },
    "msg": ""
}

Response parameters

Parameter Type Description
clOrdId String Client Order ID as assigned by the client
ordId String Order ID
quoteId String Quote ID

Get DCD order

DCD is also known as Dual Investment.

Must be accessed from sub-account API key.

Rate limit:10 requests per 2 seconds

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/finance/sfp/dcd/order

Request Example

GET /api/v5/finance/sfp/dcd/order

Request Parameters

Parameter Type Required Description
ordId String Conditional Order ID
Either ordId or clOrdId must be passed. If both ordId or clOrdId are passed, ordId will be used
clOrdId String Conditional Client Order ID as assigned by the client

Response Example

{
    "code": 0,
    "data": [
        {
            "absYield": "0.00282333",
            "alternativeCcy": "USDT",
            "annualYield": "1.12420000",
            "cTime": "1683193229000",
            "ccy": "BTC",
            "clOrdId": "fa478b7a60d24cac966ea97c7e837380",
            "notional": "0.0100000000000000",
            "notionalCcy": "BTC",
            "ordId": "1",
            "productId": "BTC-USDT-230505-29250-C",
            "quoteId": "abcd1234",
            "settAmt": "0.01002823",
            "settCcy": "BTC",
            "settPrice": "23000.0000000000000000",
            "settledTime": "1683280819000",
            "state": "settled",
            "stk": "29250",
            "tag": "123456789ABCDEFG",
            "uTime": "1683280819000",
            "uly": "BTC-USD",
            "yieldAmt": "0.00002823",
            "yieldCcy": "BTC"
        }
    ],
    "msg": ""
}

Response parameters

Parameter Type Description
absYield String Indicative yield of the product
alternativeCcy String Stablecoin currency
annualYield String Indicative annualised yield of the product
ccy String Risky asset currency
clOrdId String Client Order ID as assigned by the client
cTime String Creation time, Unix timestamp format in milliseconds
optType String Option type,
C: Call
P: Put
ordId String Order ID
notional String Notional amount of the quote, in the unit of the notional currency
notionalCcy String Notional currency
For Call, subscription currency is ccy
For Put, subscription currency is alternativeCcy
productId String Product ID
quoteId String Quote ID
settTime String Timestamp in ms of settlement
settAmt String Settlement amount in settlement currency
settCcy String Settlement currency
settPrice String Settlement price. Only available when the state is pending_settled or settled
state String Order state
initial, live, pending_settled, settled, rejected
stk String Strike price
uTime String Update time, Unix timestamp format in milliseconds
tag String Broker Code tag
uly String Underlying of the product

Get DCD orders

DCD is also known as Dual Investment.

Must be accessed from sub-account API key.

Rate limit:10 requests per 2 seconds

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/finance/sfp/dcd/orders

Request Example

GET /api/v5/finance/sfp/dcd/orders

Request Parameters

Parameter Type Required Description
productId String No Product ID
uly String No Underlying
state String No Order state
initial, live, pending_settled, settled, rejected
beginId String No Pagination of data to return records earlier than the requested ordId
endId String No Pagination of data to return records newer than the requested ordId
begin String No Filter with a begin timestamp, return records newer than the timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
(by cTime)
end String No Filter with an end timestamp, return records older than the timestamp. Unix timestamp format in milliseconds, e.g. 1597026383085
(by cTime)
limit String No Number of results per request. The maximum is 100; The default is 100
(by cTime)

Response Example

{
    "code": 0,
    "data": [
        {
            "absYield": "0.01163784",
            "alternativeCcy": "USDT",
            "annualYield": "0.51750000",
            "cTime": "1683166630000",
            "ccy": "BTC",
            "clOrdId": "fa478b7a60d24cac966ea97c7e837376",
            "notional": "0.0100000000000000",
            "notionalCcy": "BTC",
            "ordId": "1",
            "productId": "BTC-USDT-230512-30000-C",
            "quoteId": "abcd1234",
            "settAmt": "",
            "settCcy": "",
            "settPrice": "",
            "settledTime": "",
            "state": "live",
            "stk": "30000",
            "tag": "123456789ABCDEFG",
            "uTime": "1683166632000",
            "uly": "BTC-USD",
            "yieldAmt": "",
            "yieldCcy": ""
        }
    ],
    "msg": ""
}

Response parameters

Parameter Type Description
absYield String Indicative yield of the product
alternativeCcy String Stablecoin currency
annualYield String Indicative annualised yield of the product
ccy String Risky asset currency
clOrdId String Client Order ID as assigned by the client
cTime String Creation time, Unix timestamp format in milliseconds
optType String Option type,
C: Call
P: Put
ordId String Order ID
notional String Notional amount of the quote, in the unit of the notional currency
notionalCcy String Notional currency
For Call, subscription currency is ccy
For Put, subscription currency is alternativeCcy
productId String Product ID
quoteId String Quote ID
settTime String Timestamp in ms of settlement
settAmt String Settlement amount in settlement currency
settCcy String Settlement currency
settPrice String Settlement price. Only available when the state is pending_settled or settled
state String Order state
initial, live, pending_settled, settled, rejected
stk String Strike price
uTime String Update time, Unix timestamp format in milliseconds
tag String Broker Code tag
uly String Underlying of the product

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 volatile, there may be the possibility that the position has been liquidated at the same time that this message is pushed.

Set ND sub-account asset in demo trading

Rate limit:40 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

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

Request sample

POST /api/v5/broker/nd/set-subaccount-assets
body
{
    "subAcct":"brokerTest5",
    "ccy":"BTC"
}

Request Parameters

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

Returned result

{
    "code": "0",
    "data": [
        {
            "amt": "3",
            "ccy": "BTC",
            "subAcct": "brokerTest5"
        }
    ],
    "msg": ""
}

Response parameters

Parameter Type Description
subAcct String ND sub-account name
ccy String Currency, e.g. BTC
amt String Current amount of currency in trading account

Report sub-account IP

Rate Limit: 40 requests per second

Rate limit rule: UserID

Permissions: Trade

HTTP Request

POST /api/v5/broker/nd/report-subaccount-ip

Request Example

POST /api/v5/broker/nd/report-subaccount-ip
body
{
    "subAcct":"brokerTest5",
    "clientIP":"1.1.1.1"
}

Request Parameters

Parameter Type Required Description
subAcct String Yes Sub-account name
clientIP String Yes Sub-account login IP

Response Example

{
    "code": "0",
    "data": [
        {
            "subAcct": "brokerTest5",
            "ts": "1637141950450"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
subAcct String Sub-account name
ts String IP report time, Unix timestamp format in milliseconds, e.g. 1597026383085

Fully Disclosed Broker (API and Oauth)

Introduction

There are 2 types of FD brokers. API brokers and OAuth brokers. If you are trading aggregator platform, trading bot platform, technical provider, asset management platform or a social trading platform, FD broker will be the most suitable option for you

API Broker

OAuth Broker

FD broker advanges:

OAuth Broker

Introduction

OAuth login provides your users a safer and more convenient way to use your product.
With OKX OAuth 2.0, users can trade with OKX after one-click authorization from third-party applications. No password or account API key is required.
OKX 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.
To receive documents for OAuth, please contact your BD.

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 OKX accounts.
    2. Brokers apply to be an OAuth broker via OKX official website and fill out the application form and fields with red asterisk are mandatory.
    3. OKX 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 OKX's platform.
  2. OAuth Rebate settings
    OAuth-Broker needs to add BrokerCode in the Tag during order placement, and OKX will use that Tag to calculate rebate.

Introduction of authorization mode

OKX 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 OKX 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 cannot store the app key or interact with the OKX 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 OKX 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.okx.com/api/v5/asset/currencies

After the third-party app completes the authorization and obtains the token, it will be able to call the OKX 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 Conditional 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 cannot 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)

Fast API


Introduction

Fast API is a feature that helps OKX users quickly authorize third-party apps, create API Keys and bind third-party apps.


Fast API workflow

After the Broker user logs in on the Broker interface, he can jump to the login OKX page through Oauth authorization. After the login authorization on the OKX page, OKX will authorize the API broker to create an API Key for his user with read-only and trade permissions.


Application process

  1. Apply for API and OAuth Brokers on OKX

    • It is recommended to apply for a third-party APP IP Whitelist
  2. In the Oauth Broker application, provide

    • Third-Party Servers IP Whitelist
    • Redirect URL
    • Logo
    • Fast API permissions
    • Cross Domain Name
  3. After your application is successful, you will receive an email with client_id and client_secret. Please keep this information safe and do not show it to others.

Broker Commision API

Get the download link of the commission rebate details that have been successfully applied for. Every request gets refreshed links that are valid for 2 hours.

GET /api/v5/broker/fd/rebate-per-orders

Request Example

GET /api/v5/broker/fd/rebate-per-orders?type=false&begin=20211109&end=20211208
import okx.FDBroker as FDbroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "0"  # Production trading: 0, Demo trading: 1

fdBrokerAPI = FDbroker.FDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Get the download link of the commission rebate details
result = fdBrokerAPI.get_rebate_details_download_link(
    type="true"
)
print(result)
Parameter Type Required Description
type String Yes Type
true: Get all the generated history for the current user
false: Query the specified history
begin String Optional Begin date for download link generated, in the format of YYYYMMDD, e.g. 20210623, search data after 2021/06/23 00:00:00 (include)
If type is false, this field is required
end String Optional End date for download link generated, in the format of YYYYMMDD, e.g. 20210623, search data before 2021/06/24 00:00:00 (exclude)
If type is false, this field is required
brokerType String Optional Broker type
api: API Broker
oauth: Oauth Broker
When the broker has only one broker type, this parameter can be left blank
This parameter is required when the broker has multiple broker types

Response Example

{
    "code": "0",
    "data": [
        {
            "fileHref": "http://okg-pri-hk.oss-cn-hongkong.aliyuncs.com/okex/broker/pap/brokerRebateInfo/2c0ca94923dca9f53659507ee20a1f/2022-05-16/RebateDetails/RebateDetails0510-0513.xls?Expires=1652880844&OSSAccessKeyId=LTAIKNPwWs7ASPZn4iaa&Signature=ro%2BD2OMAgVzDrfguxjIM%2FY%3D",
            "state": "finished",
            "ts": "1646892328000"
        }
    ],
    "msg": ""
}
Parameter Type Description
fileHref String Download file link
beginTime String Rebate record begin time, Unix timestamp format in milliseconds, e.g. 1597026383085
endTime String Rebate record end time, Unix timestamp format in milliseconds, e.g. 1597026383085
cTime String Generate download link request time, Unix timestamp format in milliseconds, e.g. 1597026383085
ts String Download link generation time, Unix timestamp format in milliseconds, e.g. 1597026383085
state String Download link status
finished
ongoing
Parameter Description
brokerCode Brokercode the user tag with
level The user level,e.g Lv1, Lv2, VIP1, VIP2
instId Instrument ID
ordId Order ID
spotTradeAmt Spot trade volume, in unit of USDT
derivativeTradeAmt Derivative trade, in unit of USDT
fee Fee, in unit of USDT
netFee Net fee (The fee base for commission settlement after removing data such as commission cards and counterparties), in unit of USDT
settlementFee Settlement fee (The fee base before settlement removing node commission rebates, commission cards, etc. ), in unit of USDT
brokerRebate Rebate amount to broker, in unit of USDT
suBrokerRebate Rebate amount to sub-broker, in unit of USDT
userRebate Rebate amount to user, in unit of USDT
affiliated Whether there is affiliated rebate. true or false
ts The last trade time of the order. Unix timestamp format in milliseconds, e.g. 1597026383085

Generate historical commission details for FD Broker.

POST /api/v5/broker/fd/rebate-per-orders

Request Example

POST /api/v5/broker/fd/rebate-per-orders
body
{
    "begin":"20210623",
    "end":"20210626"
}
import okx.FDBroker as FDbroker

# API initialization
apikey = "YOUR_API_KEY"
secretkey = "YOUR_SECRET_KEY"
passphrase = "YOUR_PASSPHRASE"
flag = "0"  # Production trading: 0, Demo trading: 1

fdBrokerAPI = FDbroker.FDBrokerAPI(apikey, secretkey, passphrase, False, flag)

# Generate historical commission details
result = fdBrokerAPI.generate_rebate_details_download_link(
    begin="20210623",
    end="20210626"
)
print(result)
Parameter Type Required Description
begin String Yes Begin date, in the format of YYYYMMDD, e.g. 20210623, search data after 2021/06/23 00:00:00 (include)
end String Yes End date, in the format of YYYYMMDD, e.g. 20210623, search data before 2021/06/24 00:00:00 (exclude)
brokerType String Optional Broker type
api: API Broker
oauth: Oauth Broker
When the broker has only one broker type, this parameter can be left blank
This parameter is required when the broker has multiple broker types

Response Example

{
    "code": "0",
    "data":[
      {
        "result": "true",
        "ts": "1646892328000"
      }
    ],
    "msg": ""
}
Parameter Type Description
result String Whether request successfully
true: request successfully
false: request unsuccessfully
If result is true, check the download link after 1 hour
ts String Timestamp when the server received the request to generate historical commission details. Unix timestamp format in milliseconds, e.g. 1597026383085

Get the user's broker rebate information

If the user meets rebate conditions, places orders with brokerCode and pays the transaction fee, FD brokers will get broker rebate.

Rate Limit: 2 requests per second

Rate limit rule: UserID

Permissions: Read

HTTP Request

GET /api/v5/broker/fd/if-rebate

Request Example

GET /api/v5/broker/fd/if-rebate?apiKey=63d54aa0-0020-4ad9-a9f0-ac92654bc831

Request Parameters

Parameter Type Required Description
apiKey String Yes The user's API key
brokerType String Optional Broker Type
api: API Broker
oauth: Oauth Broker
When the broker has only one broker type, this parameter can be left blank
This parameter is required when the broker has multiple broker types

Response Example

{
    "code": "0",
    "data":[
      {
        "affiliated": false,
        "brokerCode": "6099c63a8d75SCDE",
        "type": "0",
        "clientRebateRatio":"0", 
        "lastRebate":""
      }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
type String The reason that Broker cannot get broker rebate
0: Broker can get broker rebate
1: Broker identification is expired
2: The trading fee level is VIP4/5 and the monthly commission amount has reached the upper limit
3: The trading fee level is greater than or equal to VIP6
brokerCode String Broker code for FD broker
affiliated String Whether there is an affiliated rebate
true: there is an affiliated rebate
false: no affiliated rebate
clientRebateRatio String Commission rebate ratio for client
lastRebate String Account monthly rebate amount. Only applicable to VIP4 and VIP5

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 don’t have permission to access this API
53014 401 Invalid IP
53015 400 Parameter {name} length cannot exceed {max length}
53016 400 Invalid redirect_uri
53017 400 Fast API permissions not enabled