Changelogs

version	time	content
V1.0.0	2022-04-26	init version

Introduction

Welcome to BIT API. You can retrieve market data, execute trades and manage your account through BIT API.

The document consists of three parts: table of contents for easy browsing (left), longer explanation of each API interface although they are quite self-explanatory already(middle), and example code (right)

How to contact us:
WEB: www.bit.com
support team: [email protected]

API hosts (production)

• REST API base url: https://mapi.matrixport.com

• Apply for API key: login portal

API rate limits

In order to ensure the system efficiency, matrixport implements the API rate limits and the private interface implements user-specified frequency limitation. When a breach happens, a prompt will be returned: “429 too many requests”.

• Rest API rate limits:
  Private API(wallet)): 1 requests per second per user.
  

Authentication

Authentication V2

Making requests

All private REST requests must contain the following headers:

• X-MatrixPort-Access-Key The API key
• X-Signature The signature of the request
• X-Timestamp The timestamp (epoch in millisecond) of your request
• X-Auth-Version The version of Authentication, the value is v2

Signature algorithm

1. Request parameters: JSON Body for POST and PUT, query string for the GET
2. Create a prehash string of timestamp + method + api_path + '&' + body (where + represents string concatenation)
3. signature = hex(hmac_sha256(prehash, secret_key))

Example

import time
import hmac
import hashlib
import json


def get_timestamp():
  return int(time.time() * 1000)


def sign(message, secret_key):
  mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod=hashlib.sha256)
  return mac.hexdigest()


def pre_hash(timestamp, method, request_path, body):
  return str(timestamp) + str.upper(method) + request_path + '&' + body


if __name__ == '__main__':
  secret_key = ""
  timestamp = get_timestamp()
  request_path = "/mapi/v1/wallet/withdraw"
  # POST
  params = {"currency": "ETH", "address": "0x2E555E9d8AB9E58595E7eB82fEE4b9E19bd97066", "amount": "1", "pwd": "lsrjXOipsCRBeL8o5JZsLOG4OFcjqWprg4hYzdbKCh4="}
  body = json.dumps(params)
  str_to_sign = pre_hash(timestamp, "POST", request_path, body)
  print(str_to_sign)
  signature = sign(str_to_sign, secret_key)
  print(signature)


  # GET
  body = ""
  request_path = "/mapi/v1/wallet/withdrawals"
  params = "currency=BTC&limit=50"
  str_to_sign = pre_hash(timestamp, "GET", request_path, params)
  print(str_to_sign)
  signature = sign(str_to_sign, secret_key)
  print(signature)

Get withdraw records as an example:

• timestamp = 1731931956000
• method = "GET"
• api_path = "/mapi/v1/wallet/withdrawals"
• query_string = "currency=BTC&limit=50"

Generate the prehash to be signed:

1731931956000GET/mapi/v1/wallet/withdrawals&currency=BTC&limit=50

Initiate withdraw, let's take ETH as an example:

• timestamp = 1731931956000
• method = "GET"
• api_path = "/mapi/v1/wallet/withdraw"
• body = {"currency":"ETH","address":"0x2E555E9d8AB9E58595E7eB82fEE4b9E19bd97066","amount":"1","pwd":"lsrjXOipsCRBeL8o5JZsLOG4OFcjqWprg4hYzdbKCh4="}

Generate the prehash to be signed:

1731931956000POST/mapi/v1/wallet/withdraw&{"currency":"ETH","address":"0x2E555E9d8AB9E58595E7eB82fEE4b9E19bd97066","amount":"1","pwd":"lsrjXOipsCRBeL8o5JZsLOG4OFcjqWprg4hYzdbKCh4="}

Authentication V1 (deprecated)

Private API mandatory fields

• User must put Access Key in http request header X-MatrixPort-Access-Key.
• User must add timestamp (epoch in millisecond) field in request parameter (query string for GET, json body for POST),API server will check this timestamp, if abs(server_timestamp - request_timestamp) > 5000, the request will be rejected.
• timestamp must be integer, not quoted string.
• User must add signature field in request parameter (query string for GET, json body for POST).
• For POST request, Header Content-Type should be set as application/json.

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

Signature algorithm

    #########
    # Python code to calc BIT 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}

API summary

• User defined string fields(label etc): valid characters are [A-Z], [a-z], [0-9], "-", "_"

Path	Method	Description	Scope	Rate Limit Type	Permission
/mapi/v1/wallet/withdraw	POST	withdraw	private	wallet	wallet
/mapi/v1/wallet/withdrawals	GET	query withdrawal records	private	read	read
/mapi/v1/wallet/deposits	GET	query deposit records	private	read	read
/mapi/v1/wallet/balance	GET	query balance	private	read	read
/mapi/v1/wallet/currencies	GET	query all currency info	private	read	read
/mapi/v1/wallet/bills	GET	query account bills	private	read	read

Wallet

Withdraw

POST /mapi/v1/wallet/withdraw

curl -X POST "https://api.matrixport.com/mapi/v1/wallet/withdraw" -H "Content-Type: application/json" -H "X-MatrixPort-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"
    }
}

Withdraw address need to be whitelisted first.
Password need to be encoded to base64(sha256(pwd)). For example, if password is 123456, the encoded password will be:jZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI=

Query Parameter

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
tag	string	false	""

Response

Name	Type	Description
withdraw_id	string	Withdraw ID

---

Withdrawal history

GET /mapi/v1/wallet/withdrawals

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/withdrawals?currency=BTC&limit=10&offset=0&timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
        "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.

Query parameters

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

Response

Name	Type	Description
code	int	Withdraw ID error code, 0 means normal, rest means failed
state	string	pending/confirmed/rejected/failed
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 /mapi/v1/wallet/deposits

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/deposits?currency=BTC&limit=10&offset=0&timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
        "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.

Query parameters

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

Response

Name	Type	Description
code	int	Deposit error code, 0 means normal, rest means failed
state	string	mempool/rollback/pending/confirmed/rejected
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

Currency list

GET /mapi/v1/wallet/currencies

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/currencies?timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
        "currencies": [{
            "currency": "BTC",
            "chains": ["BTC","BSC"], 
            "networks": [
                {
                    "chain":"BSC",
                    "can_withdraw":true,
                    "can_deposit":true,
                    "min_deposit_amount":"0.00001",
                    "min_withdraw_amount":"0.000055"
                },
                {
                    "chain":"BTC",
                    "can_withdraw":true,
                    "can_deposit":true,
                    "min_deposit_amount":"0.00001",
                    "min_withdraw_amount":"0.000055"
                }
            ]
        }]
    }
}

Get all the currencies.

Query parameters

None

Response

Name	Type	Description
currency	string	currency
chains	[]string	chains
networks	[]object	networks
- chain	string	chain
- can_withdraw	bool	can withdraw
- can_deposit	bool	can deposit
- min_deposit_amount	string	min deposit amount
- min_withdraw_amount	string	min withdraw amount

Wallet balance

GET /mapi/v1/wallet/balance

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/balance?timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
        "items": [{
            "currency": "BTC",
            "balance": "1.2",
            "available_balance": "1.2",
            "frozen_balance": "0",
            "unconfirmed_balance": "0.5"
        }]
    }
}

Retrieves the balances.

Query parameters

None

Response

Name	Type	Description
currency	string	currency
balance	string	balance
available_balance	string	available balance
frozen_balance	string	frozen balance
unconfirmed_balance	string	unconfirmed balance

Get deposit address

GET /mapi/v1/wallet/deposit-address

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/deposit-address?currency=USDT&chain=ERC20&timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
        "address": "0xF2Bd6Bb7B22875Ac582Ec1A718F63b532045401D",
        "memo": ""
    }
}

Get the deposit address.

Query parameters

Parameter	Type	Required	Default	Description
currency	String	true	""	Currency
chain	string	true	""	chain

Response

Name	Type	Description
address	string	deposit address
memo	string	memo, if needed

Query bills

GET /mapi/v1/wallet/bills

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/bills?timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
       "next_id": "123",
        "bills": [{
            "currency": "BTC",
            "balance": "1.2",
            "sn": "200392005083904086016",
            "timestamp": "1652712901013",
            "amount": "0.5",
            "direction": 1,
            "tx_type": "2046"
        }]
    }
}

Retrieves the bills.

Query parameters

Parameter	Type	Required	Default	Description
currency	String	false	""	Currency
limit	int	false	10	Number of requested items, Max - 50
start_time_ms	int	false	0	the start time in millisecond
end_time_ms	int	false	0	the end time in millisecond
start_id	string	false	0	the start id

Response

Name	Type	Description
currency	string	currency
sn	string	the bill's serial number
timestamp	string	timestamp
amount	string	amount of the order
balance	string	balance after this order
direction	int	1: transfer-in 2: transfer-out
tx_type	string	type of the bill

Get withdraw fee

GET /mapi/v1/wallet/withdraw-fees

curl -H "X-MatrixPort-Access-Key: Your Access Key" "https://api.matrixport.com/mapi/v1/wallet/withdraw-fees?timestamp=1589522687689&signature=signature"

Response

{
    "code": 0,
    "data": {
       "fee": "0.01"
    }
}

Get withdraw fee.

Query parameters

Parameter	Type	Required	Default	Description
currency	String	true		Currency
chain	string	true		chain
amount	string	true		withdraw amount

Response

Name	Type	Description
fee	string	fee

tx_type description

Name	Description
2002	Withdraw
2003	Transfer In
2004	Transfer Out
2005	Receive
2006	Pay
2007	Buy
2008	Sell
2009	OTC Buy
2010	OTC Sell
2011	Borrow
2012	Lend
2013	Reward
2014	Expense
2015	Liquidation Short
2016	Liquidation Long
2031	Insurance Fund Compensation Deduction
2002	Withdraw
2003	Transfer In
2004	Transfer Out
2005	Receive
2006	Pay
2007	Buy
2008	Sell
2009	OTC Buy
2010	OTC Sell
2011	Borrow
2012	Lend
2013	Reward
2014	Expense
2015	Liquidation Short
2016	Liquidation Long
2017	Loan Repayment
2018	Repay Loan Interest
2019	Leverage Funding
2020	Leverage Repay
2021	Repay Leverage Princpal
2022	Repay Leverage Interest
2023	Refund
2024	Repayment Credited
2025	Collateral Outflow
2026	Collateral credited
2027	Service Fee
2028	Platform Service Fee
2029	Insurance Fund Deduction
2030	Insurance Fund Credited
2031	Insurance Fund Compensation Deduction
2032	Insurance Fund Compensation Credit
2033	Liquidation Surplus Refund
2034	Liquidation Surplus Credit
2035	Collateral Deduction
2036	Collateral Credited
2037	Collateral Credit
2038	Collateral Release
2039	Collateral Liquidation
2041	Refund
2046	Product Purchase
2047	Product Settlement
2048	Product Refund
2050	Locking-Rate Credited
2051	Locking-Rate Deduction
2052	Locking-Rate Settlement Transfer out
2053	Locking-Rate Settlement Transfer in
2054	Advance Funds Repayment Transfer in
2055	Advance Funds Repayment Transfer out
2056	Payment Return to ABS Transfer Out
4004	Transaction Refund
2036	Collateral Credited
2037	Collateral Credit
2038	Collateral Release
2039	Collateral Liquidation
2039	Collateral Liquidation
2041	Refund
2046	Product Purchase
2047	Product Settlement
2048	Product Refund
2050	Locking-Rate Credited
2051	Locking-Rate Deduction
2052	Locking-Rate Settlement Transfer out
2053	Locking-Rate Settlement Transfer in
2054	Advance Funds Repayment Transfer in
2055	Advance Funds Repayment Transfer out
2056	Payment Return to ABS Transfer Out
2057	Payment Return to ABS Transfer In
2058	Payment Return Transfer Out
2059	Asset Redemption
2060	Assignment Settlement Transfer Out
2061	Assignment Receivable
2062	Assignment Refund Transfer Out
2063	Assignment Refund
2064	Renew Interest Transfer In
4004	Transaction Refund
4006	Collateral Repay
2066	Collateral Deduction
2069	Collateral Refund
3000	Other
2001	Deposit
4005	Transaction Refund
3001	Transfer In
3002	Transfer Out
3003	Transfer In
3004	Transfer Out
3005	Transfer In
3006	Transfer Out
3007	Transfer In
3008	Transfer Out
3009	Transfer In
3010	Transfer Out
2065	Renew Interest Transfer Out
2067	Collateral Deduction in
2068	Collateral Refund out
2070	Income Deduction out
2071	Income Deduction in
2080	Pay-Center Settlement Transfer out
2081	Pay-Center Settlement Transfer in
2110	Zero Interest Borrow
2112	Zero Interest Repay
2114	Zero Interest Settle
2119	Zero Interest Liquidation Refund In
2202	Fixed Income Investment
2084	Margin Transfer Out
2087	Leverage Settle In
2099	liquidation In
2101	Margin Refund In
2126	Add Margin Out
2401	DeFi investment transfer out
2404	DeFi token issuance transfer in
2406	DeFi withdrawal transfer in
2407	DeFi token withdrawal transfer out
2501	Wealth investment transfer out
2504	Wealth settlement transfer in
2409	Currency investment transfer out
2412	Currency redeem transfer in
2413	Currency redeem fee transfer out
2416	Currency refund transfer in
2508	Wealth refund transfer in
2142	Fund Investment
2145	Cancelled Fund Investment
2147	Fund Redemption
2154	Distribution
2156	Fundraising Period Revenue
2134	Leverage Ballance Repay
2137	Leverage Ballance Repay Refund
2139	Leverage Withdraw
2506	Wealth redeem transfer in
2525	Flexi Saving Deposit Out
2526	Flexi Saving Deposit In
2527	Flexi Saving Withdraw Out
2528	Flexi Saving Withdraw In
2529	Flexi Saving Borrow Transfer Out
2530	Flexi Saving Borrow Transfer In
2531	Flexi Saving Repay Transfer Out
2532	Flexi Saving Repay Transfer In
2533	Fixed Income Investment
2534	Fixed Income Investment In
2536	Fixed Income Redeem
2535	Fixed Income Redeem Out
2538	Fixed Income Settle
2537	Fixed Income Settle Out
2540	Fixed Income Refund
2539	Fixed Income Refund Out
2509	Trend refund transfer out
2510	Trend refund transfer in
2511	Trend Fundraising Period Revenue out
2512	Trend Fundraising Period Revenue
2513	Trend investment transfer out
2514	Trend investment transfer in
2515	Trend settlement transfer out
2516	Trend settlement transfer in
2517	Trend redeem transfer out
2518	Trend redeem transfer in
2545	ETH 2.0 investment transfer out
2546	ETH 2.0 investment transfer in
2547	ETH 2.0 settlement transfer out
2548	ETH 2.0 settlement transfer in
2549	ETH 2.0 redeem transfer out
2550	ETH 2.0 redeem transfer in
2551	Range Sniper investment
2552	Range Sniper investment transfer in
2553	Range Sniper settlement
2554	Range Sniper settlement transfer in
2555	Buy via Auto-Invest
2556	Pay for Auto-Invest
2633	Red envelope expenditure
2634	Red envelope credited
2542	Commission
2544	Commission
2559	Buy-below-market investment
2560	Buy-below-market investment transfer in
2561	Buy-below-market settlement
2562	Buy-below-market settlement transfer in
2563	Buy-below-market refund
2564	Buy-below-market refund transfer in
2565	Sell-above-market investment
2566	Sell-above-market investment transfer in
2567	Sell-above-market settlement
2568	Sell-above-market settlement transfer in
2569	Sell-above-market refund
2570	Sell-above-market refund transfer in
2572	create grid trading
2571	close grid trading