NAV Navbar
json

Changelogs

version time content
V1.0.2
2021 DEC 9
* GET /um/v1/transactions add instrument_id filter, and response add cash_flow
V1.0.1
2021 NOV 11
* Release production
V1.0.0
2021 SEP 1
* Um doc init version

Introduction

Unified margin trade account abbreviation is UM account.
Unified margin account mode abbreviation is UM mode.

Guidelines for unified margin mode

Wallet functions under UM mode

REST trading functions under UM mode

Subscription channel under UM mode

UM mode API hosts (production)

Same as derivatives api hosts

UM mode API hosts (testnet)

UM account API rate limit

In order to ensure system efficiency, bit.com implements the API rate limits. The public interface implements IP-specified frequency limitation, and the private interface implements user-specified frequency limitation. When a breach happens, a prompt will be returned: “429 too many requests”. The individual API limits can be found on the webpage of the trading centre. Users who need to increase the speed limit please contact the support team via [email protected]

Public API(UM-mode Public): 10 requests per second per IP.
Private API(UM-mode Others): 10 requests second per user.

About the type of API rate limits, please refer to API summary.

Authentication

Private API mandatory fields

If authentication fails, a prompt will be returned: “AkId is invalid” and http status code is 412

Signature algorithm

Same as derivative API

    #########
    # Python code to calc BIT.COM API signature
    #########
    import hashlib
    import hmac

    def encode_list(self, item_list):
        list_val = []
        for item in item_list:
            obj_val = self.encode_object(item)
            list_val.append(obj_val)
        output = '&'.join(list_val)
        output = '[' + output + ']'
        return output

    def encode_object(self, param_map):
        sorted_keys = sorted(param_map.keys())
        ret_list = []
        for key in sorted_keys:
            val = param_map[key]
            if isinstance(val, list):
                list_val = self.encode_list(val)
                ret_list.append(f'{key}={list_val}')
            elif isinstance(val, dict):
                # call encode_object recursively
                dict_val = self.encode_object(val)
                ret_list.append(f'{key}={dict_val}')
            elif isinstance(val, bool):
                bool_val = str(val).lower()
                ret_list.append(f'{key}={bool_val}')
            else:
                general_val = str(val)
                ret_list.append(f'{key}={general_val}')

        sorted_list = sorted(ret_list)
        output = '&'.join(sorted_list)
        return output

    def get_signature(self, http_method, api_path, param_map):
        str_to_sign = api_path + '&' + self.encode_object(param_map)
        print('str_to_sign = ' + str_to_sign)
        sig = hmac.new(self.secret_key.encode('utf-8'), str_to_sign.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
        return sig

    #########
    # END
    #########

  1. Request parameters: JSON Body for POST, query string for the rest
  2. Encode string to sign, for simple json object, sort your parameter keys alphabetically, and join them with '&' like 'param1=value1&param2=value2', then get str_to_sign = api_path + '&' + 'param1=value1&param2=value2'
  3. For nested array objects, encode each object and sort them alphabetically, join them with '&' and embraced with '[', ']', e.g. str_to_sign = api_path + '&' + 'param1=value1&array_key1=[array_item1&array_item2]', see example below.
  4. Signature = hex(hmac_sha256(str_to_sign, secret_key))
  5. Add signature field to request parameter:
    for query string, add '&signature=YOUR_SIGNATURE' for JSON body, add {'signature':YOUR_SIGNATURE}


































Example for GET request

Secret Key: eabc3108-dd2b-43df-a98d-3e2054049b73
HTTP method: GET
API Path: /v1/margins
Query string: price=8000&qty=30&instrument_id=BTC-PERPETUAL&timestamp=1588242614000

Then str_to_sign = /v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30&timestamp=1588242614000

> echo -n "/v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30&timestamp=1588242614000" | openssl dgst -sha256 -hmac "eabc3108-dd2b-43df-a98d-3e2054049b73"

> e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

sig = hex(hmac_sha256(str_to_sign, secret_key)) = e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

Final query string: price=8000&qty=30&instrument_id=BTC-PERPETUAL&timestamp=1588242614000&signature=e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

Example for POST request

Secret Key: eabc3108-dd2b-43df-a98d-3e2054049b73
HTTP Method: POST
API Path: /v1/orders
JSON body:
{ "instrument_id": "BTC-27MAR20-9000-C", "order_type": "limit", "price": "0.021", "qty": "3.14", "side": "buy", "time_in_force": "gtc", "stop_price": "", "stop_price_trigger": "", "auto_price": "", "auto_price_type": "", "timestamp": 1588242614000 }

Then str_to_sign = /v1/orders&auto_price=&auto_price_type=&instrument_id=BTC-27MAR20-9000-C&order_type=limit&price=0.021&qty=3.14&side=buy&stop_price=&stop_price_trigger=&time_in_force=gtc&timestamp=1588242614000

> echo -n "/v1/orders&auto_price=&auto_price_type=&instrument_id=BTC-27MAR20-9000-C&order_type=limit&price=0.021&qty=3.14&side=buy&stop_price=&stop_price_trigger=&time_in_force=gtc&timestamp=1588242614000" | openssl dgst -sha256 -hmac "eabc3108-dd2b-43df-a98d-3e2054049b73"

> 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817

sig = hex(hmac_sha256(str_to_sign, secret_key)) = 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817

Final JSON body:
{ "instrument_id": "BTC-27MAR20-9000-C", "order_type": "limit", "price": "0.021", "qty": "3.14", "side": "buy", "time_in_force": "gtc", "stop_price": "", "stop_price_trigger": "", "auto_price": "", "auto_price_type": "", "timestamp": 1588242614000, "signature": "34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817" }

POST request json body with boolean field

For example, When calling POST /v1/orders with boolean fields:

Take post_only as example,

Example

request

string to sign

POST request json body with array field

for item in object_array:
    str_list.add(encode(item))
str_to_sign = '&'.join(str_list)

For example, When calling POST /v1/blocktrades with array fields:

Take trades as example,

And secret key is eabc3108-dd2b-43df-a98d-3e2054049b73

Example

request

string to sign

API summary

Path Method Description Scope Rate Limit Type Permission
/um/v1/index_price GET Query index price public public /
/um/v1/loan_rates GET Query loan rate public public /
/um/v1/account_mode GET Query Account mode private others read
/um/v1/accounts GET Query um account information private others read
/um/v1/transactions GET Query um transaction logs private others read
/um/v1/interest_records GET Query um interest records private. others read
/v1/wallet/um-withdraw POST withdrawl from um-account private wallet wallet
/v1/wallet/um-withdrawals GET query um-account withdrawl records private others read
/v1/wallet/um-deposits GET query um-account deposit records private wallet read
/v1/wallet/transfer POST transfer private wallet wallet
/v1/wallet/transfer GET query transfer records private wallet read
/v1/wallet/sub-user-transfer POST transfer between parent and sub accounts private wallet wallet
/v1/wallet/sub-user-transfer GET query sub account transfer records private wallet read

Market

Get USD/USDT index price

GET /um/v1/index_price

curl "https://betaapi.bitexch.dev/um/v1/index_price?currency=BTC&quote_currency=USDT"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "index_name": "BTC-USDT",
            "index_price": "50000"
        }
    ]
}

Get index price with quote currency USD/USDT.

Supported pairs:

USD: BTC-USD, ETH-USD, BCH-USD

USDT: BTC-USDT, ETH-USDT, BCH-USDT, USDC-USDT

If currency is empty, return all pair index prices associated with quote_currency.

Query parameters

Parameter Type Required Default Description
currency string false "" Currency
quote_currency string true "" Quote currency(USD/USDT)

Response

Name Type Description
index_name string Index name
index_price string Index price

Get loan interest rates

GET /um/v1/loan_rates

curl "https://betaapi.bitexch.dev/um/v1/loan_rates?currency=ETH"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "currency": "ETH",
        "last_hour_rate": "0.03000000"
    }
}

Get average loan rate of last hour.

Query parameters

Parameter Type Required Default Description
currency string false "" Currency

Response

Name Type Description
currency string Currency
last_hour_rate string Average loan rate of last hour

Account

Get account mode

GET /um/v1/account_mode


curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/account_mode?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"

Response


// account_mode = Um
{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 1,
        "account_mode": "um",
        "auto_borrow": true,
        "um_risk_mode": "regular",
        "classic_accounts": []
    }
}

// account_mode = classic
{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 1,
        "account_mode": "classic",
        "auto_borrow": false,
        "um_risk_mode": "",
        "classic_accounts": [
            {
                "currency": "BCH",
                "classic_risk_mode": "portfolio_margin"
            },
            {
                "currency": "BTC",
                "classic_risk_mode": "portfolio_margin"
            },
            {
                "currency": "ETH",
                "classic_risk_mode": "portfolio_margin"
            }
        ]
    }
}

Get account mode.

Query parameters

None

Response

Name Type Desc
user_id int User ID
account_mode string Account mode
auto_borrow bool Auto borrow or not
um_risk_mode string Um risk mode, regular/pm (only valid when account_mode = um)
classic_accounts array classic account info (only valid when account_mode = classic)
Name Type Desc
currency string Currency
classic_risk_mode string regular/pm

Get UM user accounts

GET /um/v1/accounts


curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/accounts?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"

Response


{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 1,
        "created_at": 1632642549581,
        "usdt_total_collateral": "200.00000000",
        "usdt_total_margin_balance": "190.00000000",
        "usdt_total_available": "80.00000000",
        "usdt_total_initial_margin": "90.00000000",
        "usdt_total_maintenance_margin": "120.00000000",
        "usdt_total_initial_margin_ratio": "0.60000000",
        "usdt_total_maintenance_margin_ratio": "0.60000000",
        "usdt_total_liability": "8060000.00000000",
        "usdt_total_unsettled_amount": "322143.95604395",
        "spot_orders_hc_loss": "30.00000000",
        "details": [
            {
                "currency": "BTC",
                "equity": "100.00000000",
                "liability": "0.00000000",
                "usdt_index_price": "40000.00000000",
                "cash_balance": "100.00000000",
                "margin_balance": "100.00000000",
                "available_balance": "50.00000000",
                "initial_margin": "20.00000000",
                "spot_margin": "30.00000000",
                "maintenance_margin": "80.00000000",
                "potential_liability": "0.00000000",
                "interest": "1.00000000",
                "interest_rate": "0.01000000",
                "pnl": "0.11538462",
                "total_delta": "0.38461538",
                "session_rpl": "10.00000000",
                "session_upl": "0.11538462",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.11538462",
                "future_session_rpl": "10.00000000",
                "future_session_upl": "0.11538462",
                "future_session_funding": "10.00000000",
                "future_delta": "0.38461538",
                "future_available_balance": "0.00200000",
                "option_available_balance": "0.00200000",
                "unsettled_amount": "9.11538462"
            },
            {
                "currency": "USDT",
                "equity": "-8000000.00000000",
                "liability": "8000000.00000000",
                "usdt_index_price": "1.00000000",
                "cash_balance": "-8000000.00000000",
                "margin_balance": "-8000000.00000000",
                "available_balance": "0.00000000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "8000000.00000000",
                "interest": "300.00000000",
                "interest_rate": "0.00500000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "0.00000000",
                "option_available_balance": "0.00000000",
                "unsettled_amount": "-300.00000000"
            }
        ]
    }
}


Get Um user account information

PM usdt_total_initial_margin_ratio calculation formula
true (usdt_total_im + spot_haircut_loss) / collateral
false (usdt_total_im + spot_haircut_loss) / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

PM usdt_total_maintenance_margin_ratio calculation formula
true total_maintenance_margin / collateral
false total_maintenance_margin / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

Query parameters

None

Response

Name Type Desc
user_id int User Id
created_at int Timestamp (query time)
usdt_total_collateral string USDT Total Collateral
usdt_total_margin_balance string USDT Total Margin Balance
usdt_total_available string USDT Total Available
usdt_total_initial_margin string USDT Total Initial Margin
usdt_total_maintenance_margin string USDT Total Maintenance Margin
usdt_total_initial_margin_ratio string USDT Total Initial Margin Ratio, may returns "infinity"
usdt_total_maintenance_margin_ratio string USDT Total Maintenance Margin Ratio, may returns "infinity"
usdt_total_liability string USDT total liability
usdt_total_unsettled_amount string USDT total unsettled amount
spot_orders_hc_loss string Total spot order haircut loss
details array Details, array of currency level detail
Name Type Desc
currency string Currency
equity string Equity
liability string Liability
usdt_index_price string USDT index price
cash_balance string Cash Balance
margin_balance string Margin Balance
available_balance string Account Available Balance
initial_margin string Initial Margin
spot_margin string Spot Margin
maintenance_margin string Maintenance Margin
potential_liability string Potential Liability
interest string Interest
interest_rate string Interest Rate
pnl string Account P&L
total_delta string Total delta of account
session_rpl string Session realized pnl
session_upl string Session unrealized pnl
option_value string Option market value
option_pnl string Option P&L
option_session_rpl string Option session realized P&L
option_session_upl string Option session unrealized P&L
option_delta string Option delta
option_gamma string Option gamma
option_vega string Option vega
option_theta string Option theta
future_pnl string Future P&L
future_session_rpl string Future session realized P&L
future_session_upl string Future session unrealized P&L
future_session_funding string Future session funding
future_delta string Future delta
future_available_balance string Available balance for new futures order
option_available_balance string Available balance for new option order
unsettled_amount string Unsettled amount

Get UM user transactions

GET /um/v1/transactions

curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/transactions?currency=BTC&type=trade-recv&limit=2&timestamp=1620369292928&signature=35d76033f6e251ce85524ec4310417fd555953fff00cd33f3a94e3d27d062965" 


Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "tx_time": 1631240595162,
            "tx_type": "deposit",
            "ccy": "BTC",
            "instrument_id": "",
            "direction": "",
            "qty": "3.20000000",
            "price": "",
            "position": "",
            "fee_paid": "0.00000000",
            "fee_rate": "",
            "funding": "",
            "change": "3.20000000",
            "balance": "107.00000000",
            "order_id": "",
            "trade_id": "",
            "remark": ""
        },
        {
            "tx_time": 1630722195162,
            "tx_type": "spot-trade-recv",
            "ccy": "BTC",
            "instrument_id": "BTC-USDT",
            "direction": "buy",
            "qty": "2.00000000",
            "price": "60000.00000000",
            "position": "",
            "fee_paid": "0.00030000",
            "fee_rate": "0.00000000",
            "funding": "",
            "change": "2.00000000",
            "balance": "102.00000000",
            "order_id": "9001",
            "trade_id": "3001",
            "remark": ""
        }
    ],
    "page_info": {
        "has_more": false
    }
}

Get UM user transaction logs.

Query Parameters

Parameter Type Required Default Description
currency string false "" Currency
instrument_id string false "" Instrument ID
start_time integer false One month ago Start timestamp millisecond
end_time integer false Now End timestamp millisecond
type string false "" Transaction type
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

Name Type Desc
tx_time integer Transaction time
tx_type string Transaction type
ccy string Currency
instrument_id string Instrument Id
direction string buy/sell
qty string Qty
price string Trade price (for trade transactions)
position string Futures/Options position
fee_paid string Fee paid
fee_rate string Fee rate
funding string Perpetual funding
change string Change
cash_flow string Cashflow(spot cash_flow=change, derivatives cash_flow please refer to derivatives doc for transactions)
balance string Balance after change
order_id string Order ID
trade_id string Trade ID
remark string Remark

Get interest records

GET /um/v1/interest_records


curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/interest_records?currency=BTC&timestamp=1631669478618&signature=3d4685f07751cd51f42ee631938f189cbe6e9712cc6d559881e5b3b6d1ba1224" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "currency": "BTC",
            "time": 1631559600000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.05000000"
        },
        {
            "currency": "BTC",
            "time": 1631556000000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.06000000"
        },
        {
            "currency": "BTC",
            "time": 1631552400000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.07000000"
        }
    ],
    "page_info": {
        "has_more": true
    }
}

Get UM interest records.

Query Parameters

Parameter Type Required Default Description
currency string true "" Currency
start_time integer false One month ago Start timestamp millisecond
end_time integer false Now End timestamp millisecond
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

Name Type Desc
currency string Currency
time integer Interest accrual time
loan_rate string Annual interest rate
liability string liability
interest string Accrued interest

Wallet

Bit.com has 3 types of accounts: spot accounts, contract accounts, and unified margin accounts.

Withdraw

POST /v1/wallet/um-withdraw

curl -X POST "https://betaapi.bitexch.dev/v1/wallet/um-withdraw" -H "Content-Type: application/json" -H "X-Bit-Access-Key: Your Access Key" -d '{"currency": "BTC", "address": "Your address", "amount": "1.2", "pwd": "Your password", "timestamp": 1589523989378, "signature": "signature"}'

Response


{
    "code": 0,
    "message": "",
    "data": {
        "withdraw_id": "b61c2b93-8a25-44d4-9715-023cce61dc50"
    }
}

This endpoint means withdraw cash from unified margin account. Withdraw address need to be whitelisted first here: https://www.bit.com/propertyCenter/withdraw
Password need to be encoded to base64(sha256(pwd)). For example, if password is 123456, the encoded password will be:jZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI=

Query parameters

Parameter Type Required Default Description
currency string true "" Currency, BTC
address string true "" Withdrawal address
amount string true "" Withdrawal amount
pwd string true "" Fund password
chain string false "" ETH for USDTERC, TRX for USDTTRC

Response

Name Type Description
withdraw_id string Withdraw ID, can be used in later inquires

Withdrawal history

GET /v1/wallet/um-withdrawals

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/um-withdrawals?currency=BTC&limit=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 2,
        "items": [{
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.001",
            "code": 0,
            "confirmations": 0,
            "currency": "BTC",
            "fee": "0.00001",
            "state": "confirmed",
            "transaction_id": "52e1537002f51acbf5f52b9dfeab6a9e7cc185a669cda2573e768420b0839523",
            "created_at": 1608606000000,
            "updated_at": 1608606000000,
            "is_onchain": true
        }, {
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.11",
            "code": 13100100,
            "confirmations": 0,
            "currency": "BTC",
            "fee": "0.00001",
            "state": "rejected",
            "transaction_id": "",
            "created_at": 1608606000000,
            "updated_at": 1608606000000,
            "is_onchain": false
        }]
    }
}

Retrieves the withdrawal records of a specific currency

Query parameters

Parameter Type Required Default Description
currency String true "" Currency
limit int false 10 Number of requested items, Max - 50
offset int false 0 the offset for pagination
withdraw_id string false "" withdraw order id

Response

Name Type Description
code int Withdraw ID error code, 0 means normal, rest means failed
state string withdrawal state
address string Withdraw address
amount string Withdraw amount
confirmations int Confirmation counts, 0 for internal transfers since they are offchain
currency string Currency
fee string Withdraw fee
transaction_id string Transaction hash
created_at int Timestamp of the order created
updated_at int Timestamp of the order updated
is_onchain bool Whether the order is onchain

Deposits history

GET /v1/wallet/um-deposits

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/um-deposits?currency=BTC&limit=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 1,
        "items": [{
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.001",
            "code": 0,
            "confirmations": 0,
            "currency": "BTC",
            "state": "confirmed",
            "transaction_id": "52e1537002f51acbf5f52b9dfeab6a9e7cc185a669cda2573e768420b0839523",
            "created_at": 1608606000000,
            "updated_at": 1608606000000,
            "is_onchain": true
        }]
    }
}

Retrieves the deposit records of a specific currency

Query parameters

Parameter Type Required Default Description
currency String true "" Currency
limit int false 10 Number of requested items, Max - 50
offset int false 0 the offset for pagination

Response

Name Type Description
code int Deposit error code, 0 means normal, rest means failed
state string deposit state
address string Deposit address
amount string Deposit amount
confirmations int Confirmation counts, 0 for internal transfers since they are offchain
currency string Currency
transaction_id string Transaction hash
created_at int Timestamp of the order created
updated_at int Timestamp of the order updated
is_onchain bool Whether the order is onchain

Transfer

POST /v1/wallet/transfer

curl -X POST "https://betaapi.bitexch.dev/v1/wallet/transfer" -H "Content-Type: application/json" -H "X-Bit-Access-Key: Your Access Key" -d '{"currency": "BTC", "amount": "1.2", "type": 1, "timestamp": 1589523989378, "signature": "signature"}'

Response


{
    "code": 0,
    "message": ""
}

Bit.com has three types of accounts: spot account, contract account and unified margin account. Bit.com supports transfer between Bit.com accounts and Matrixport cash account.

When the mode does not match the transfer type, an error will be returned.

Query Parameters

Parameter Type Required Default Description
currency string true Currency, e.g. BTC
amount string true Transfer amount
type int true Transfer type, 1: spot-to-Contract, 2: Contract-to-spot, 3: spot-to-Matrixport, 4: Matrixport-to-spot, 5: contract-to-Matrixport, 6: Matrixport-to-contract, 7: um-to-Matrixport, 8: Matrixport-to-um

Transfer history

GET /v1/wallet/transfer

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/transfer?currency=BTC&count=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 2,
        "items": [{
            "status": "done",
            "currency": "BTC",
            "amount": "1.2",
            "type": 1,
            "created_at": 1608606000000,
            "id": "123"
        }, {
            "status": "done",
            "currency": "ETH",
            "amount": "1.2",
            "type": 2,
            "created_at": 1608606000000,
            "id": "124"
        }]
    }
}

Query parameters

Parameter Type Required Default Description
currency string false
limit int false 10 Number of requested items, Max - 50
offset int false 1 the offset for pagination

Response

Name Type Description
status string Transfer status, failed/done/dealing
type int 1: spot-to-contract, 2: contract-to-spot, 3: spot-to-Matrixport, 4: Matrixport-to-spot, 5: contract-to-Matrixport, 6: Matrixport-to-contract, 7: um-to-Matrixport, 8: Matrixport-to-um
currency string
amount string
created_at int Timestamp of the order created
order_id string transfer id

Sub-user Transfer (only for parent user)

POST /v1/wallet/sub-user-transfer

curl -X POST "https://betaapi.bitexch.dev/v1/wallet/sub-user-transfer" -H "Content-Type: application/json" -H "X-Bit-Access-Key: Your Access Key" -d '{"currency": "BTC", "amount": "1.2", "type": 1, "from_user": "123", "to_user": "124", "timestamp": 1589523989378, "signature": "signature"}'

Response


{
    "code": 0,
    "message": ""
}

Note

Query parameters

Parameter Type Required Default Description
from int true Transfer out user id, parent user id or sub user id
to int true Transfer in user id, parent user id or sub user id
type int true Transfer account type, 1:spot-to-spot 2:contract-to-contract, 3: spot-to-contract, 4: contract-to-spot, 5: um-to-um, 6: um-to-contract, 7: contract-to-um, 8: um-to-spot, 9: spot-to-um
currency string true
amount string true

Sub user transfer history (only for parent user)

GET /v1/wallet/sub-user-transfer

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/sub-user-transfer?currency=BTC&count=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 2,
        "items": [{
            "status": "done",
            "currency": "BTC",
            "amount": "1.2",
            "type": 1,
            "created_at": 1608606000000,
            "id": "123"
        }, {
            "status": "done",
            "currency": "ETH",
            "amount": "1.2",
            "type": 2,
            "created_at": 1608606000000,
            "id": "124"
        }]
    }
}

Query parameters

Parameter Type Required Default Description
currency string false
limit int false 10 Number of requested items, Max - 50
page int false 1 the offset for pagination
sub_user_id int true

Response

Name Type Description
type int 1:spot-to-spot 2:contract-to-contract, 3: spot-to-contract, 4: contract-to-spot, 5: um-to-um, 6: um-to-contract, 7: contract-to-um, 8: um-to-spot, 9: spot-to-um
currency string
amount string
created_at int Timestamp of the order created
order_id string transfer id
from int
to int

Websocket subscription

There is no new websocket service in UM mode. Users can subscribe to UM channels through spot or contracted websocket services.

Subscription method reference: Contract & Spot

Um channels can be subscribed together with contract and spot other channels.

Channel Summary

Channel Scope Arguments Description
um_index_price.{pair} public Index price of the specific pair
um_account private UM user's account information

Index Price Channel

Request

{
    "type":"subscribe",
    "channels":[
        "um_index_price.BTC-USDT"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"um_index_price",
    "timestamp":1632439007081,
    "data":{
        "index_name":"BTC-USDT",
        "index_price":"44715.50000000"
    }
}

um_index_price pushes index price with quote currency USD/USDT.

Supported pairs:

USD: BTC-USD, ETH-USD, BCH-USD

USDT: BTC-USDT, ETH-USDT, BCH-USDT, USDC-USDT

Channel Information

Channel Scope Arguments Interval
um_index_price public [raw, 100ms]

Response

Name Type Description
index_name string Index name
index_price string Index price

UM Account Channel

Request

{
    "type":"subscribe",
    "channels":[
        "um_account"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

Response


{
    "channel":"um_account",
    "timestamp":1632439007081,
    "data": {
        "user_id": 1,
        "created_at": 1632642549581,
        "usdt_total_collateral": "200.00000000",
        "usdt_total_margin_balance": "190.00000000",
        "usdt_total_available": "80.00000000",
        "usdt_total_initial_margin": "90.00000000",
        "usdt_total_maintenance_margin": "120.00000000",
        "usdt_total_initial_margin_ratio": "0.60000000",
        "usdt_total_maintenance_margin_ratio": "0.60000000",
        "usdt_total_liability": "8060000.00000000",
        "usdt_total_unsettled_amount": "322143.95604395",
        "spot_orders_hc_loss": "30.00000000",
        "details": [
            {
                "currency": "BTC",
                "equity": "100.00000000",
                "liability": "0.00000000",
                "usdt_index_price": "40000.00000000",
                "cash_balance": "100.00000000",
                "margin_balance": "100.00000000",
                "available_balance": "50.00000000",
                "initial_margin": "20.00000000",
                "spot_margin": "30.00000000",
                "maintenance_margin": "80.00000000",
                "potential_liability": "0.00000000",
                "interest": "1.00000000",
                "interest_rate": "0.01000000",
                "pnl": "0.11538462",
                "total_delta": "0.38461538",
                "session_rpl": "10.00000000",
                "session_upl": "0.11538462",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.11538462",
                "future_session_rpl": "10.00000000",
                "future_session_upl": "0.11538462",
                "future_session_funding": "10.00000000",
                "future_delta": "0.38461538",
                "future_available_balance": "0.00200000",
                "option_available_balance": "0.00200000",
                "unsettled_amount": "9.11538462"
            },
            {
                "currency": "USDT",
                "equity": "-8000000.00000000",
                "liability": "8000000.00000000",
                "usdt_index_price": "1.00000000",
                "cash_balance": "-8000000.00000000",
                "margin_balance": "-8000000.00000000",
                "available_balance": "0.00000000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "8000000.00000000",
                "interest": "300.00000000",
                "interest_rate": "0.00500000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "0.00000000",
                "option_available_balance": "0.00000000",
                "unsettled_amount": "-300.00000000"
            }
        ]
    }
}


um_account pushes UM user's account information.

Channel Information

Channel Scope Arguments Interval
um_account private [raw, 100ms]

Response

Name Type Description
user_id int User Id
created_at int Timestamp (query time)
usdt_total_collateral string USDT Total Collateral
usdt_total_margin_balance string USDT Total Margin Balance
usdt_total_available string USDT Total Available
usdt_total_initial_margin string USDT Total Initial Margin
usdt_total_maintenance_margin string USDT Total Maintenance Margin
usdt_total_initial_margin_ratio string USDT Total Initial Margin Ratio, may returns "infinity"
usdt_total_maintenance_margin_ratio string USDT Total Maintenance Margin Ratio, may returns "infinity"
usdt_total_liability string USDT total liability
usdt_total_unsettled_amount string USDT total unsettled amount
spot_orders_hc_loss string Total spot order haircut loss
details array of Detail Details, array of currency level detail
Name Type Description
currency string Currency
equity string Equity
liability string Liability
usdt_index_price string USDT index price
cash_balance string Cash Balance
margin_balance string Margin Balance
available_balance string Account Available Balance
initial_margin string Initial Margin
spot_margin string Spot Margin
maintenance_margin string Maintenance Margin
potential_liability string Potential Liability
interest string Interest
interest_rate string Interest Rate
pnl string Account P&L
total_delta string Total delta of account
session_rpl string Session realized pnl
session_upl string Session unrealized pnl
option_value string Option market value
option_pnl string Option P&L
option_session_rpl string Option session realized P&L
option_session_upl string Option session unrealized P&L
option_delta string Option delta
option_gamma string Option gamma
option_vega string Option vega
option_theta string Option theta
future_pnl string Future P&L
future_session_rpl string Future session realized P&L
future_session_upl string Future session unrealized P&L
future_session_funding string Future session funding
future_delta string Future delta
future_available_balance string Available balance for new futures order
option_available_balance string Available balance for new option order
unsettled_amount string Unsettled amount

Constant definitions

Account Mode

Account mode Description
classic Classic mode
um Unified margin mode
migrating-to-um Migrating from classic to um (transient state)
migrating-to-classic Migrating from um to classic (transient state)

Transaction log type

Um Tx log type Description
spot-trade-pay Paying out cash for spot trade
spot-trade-recv Receiving cash of spot trade
deri-trade Derivative trade
deri-delivery Derivative delivery
deri-settlement Derivative settlement
deri-socialized-fund Derivative socialized fund
pay-accrued-interest Paying interest
um-pex-trade-pay Auto sell
um-pex-trade-recv Auto buy
deposit Deposit
bad-deposit Deposit rollback
withdraw Withdraw
withdraw-revert Withdraw refund
transfer-in Fund transfer in
transfer-out Fund transfer out

Errors

Please refer to spot error code definitions.