Changelogs
version | time | content |
---|---|---|
V1.0.0 | 2022-04-26 |
init version |
Introduction
Welcome to Matrixport API. You can retrieve market data, execute trades and manage your account through Matrixport 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.matrixport.com
support team: [email protected]
API hosts (production)
- REST API base url: https://mapi.matrixport.com
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
Private API mandatory fields
- User must put
Access Key
in http request headerX-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, ifabs(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 asapplication/json
.
If authentication fails, a prompt will be returned: “AkId is invalid” and http status code is 412
Signature algorithm
#########
# Python code to calc Matrixport 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
#########
- Request parameters: JSON Body for POST, query string for the rest
- Encode string to sign, for simple json object, sort your parameter keys alphabetically, and join them with '&' like 'param1=value1¶m2=value2', then get str_to_sign = api_path + '&' + 'param1=value1¶m2=value2'
- 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.
- Signature = hex(hmac_sha256(str_to_sign, secret_key))
- 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×tamp=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×tamp=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"],
}]
}
}
Get all the currencies.
Query parameters
None
Response
Name | Type | Description |
---|---|---|
currency | string | currency |
chains | []string | chains |
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×tamp=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 |