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

  • Stage 1 : Pending withdrawal
    • 10: Waiting transfer
    0: Waiting withdrawal
    4/5/6/8/9/12: Waiting manual review
    7: Approved

  • Stage 2 : Withdrawal in progress (Applicable to on-chain withdrawals, internal transfers do not have this stage)
    • 1: Broadcasting your transaction to chain
    15: Pending transaction validation
    16: Due to local laws and regulations, your withdrawal may take up to 24 hours to arrive
    -3: Canceling

  • Final stage
    • -2: Canceled
    -1: Failed
    2: Success
    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
    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

    Get the user's broker rebate information

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

    Rate Limit: 5 requests per 2 second

    Rate limit rule: UserID

    Permissions: Read

    HTTP Request

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

    Request Example

    GET /api/v5/broker/nd/if-rebate?subAcct=ndsubaccount1

    Request Parameters

    Parameter Type Required Description
    apiKey String Conditional The sub-account's API key
    The priority from high to low: apiKey, uid, subAcct, e.g. if you fill uid and subAcct, we will take uid.
    uid String Conditional Sub-account UID
    subAcct String Conditional Sub-account name

    Response Example

    {
    "code": "0",
    "data": [
        {
            "lastRebate": "",
            "type": "0"
        }
    ],
    "msg": ""
}

    Response Parameters

    Parameter Type Description
    type String The reason that Broker cannot get broker basic rebate
    0：Broker can get broker rebate
    2：The trading fee level >=VIP4 and and the monthly commission amount has reached the upper limit
    3：You are using VIP fee rate mode.
    lastRebate String Account monthly rebate amount when VIP>=4.
    It is "" when VIP<4.

    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
    HTTP Python