💫
Getting Started
- address
- active address
- apply to ZKEX Team to get
api key
andapi secret
- depoly
market maker signer service
and sendsigner url
to ZKEX Team
- When you subscribe to ws-level2 for the first time, you will receive the snapshot data by push-snapshot
Request
Response
- Http Method :
GET
- Http Path :
/mm/api/server
- Response :
{
"timeNow": 1650958799
}
Request
Response
- Http Method :
GET
- Http Path :
/mm/api/products
[
{
"id": "XNY-USDT",
"baseCurrency": "XNY",
"quoteCurrency": "USDT",
"baseMinSize": "10000000000000", //base asset minimal amount
"baseMaxSize": "10000000000000000000000000", //unused
"quoteIncrement": "10000000000000000", //quote asset minimal amount
"baseScale": -12, //decimals
"quoteScale": -16, //decimals
"l2symbolId": 2, // trading pair id on layer2
"l2baseCurrencyId": 3, // currency id on layer2
"l2quoteCurrencyId": 4 // currency id on layer2
},
......
]
Request
Response
- HTTP Method:
GET
- HTTP Path:
/mm/api/users
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1653983486 | unix timestamp |
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZGRyZXNzIjoiMHgzNDk4ZjQ1NjY0NTI3MGVlMDAzNDQxZGY4MmM3MThiNTZjMGU2NjY2IiwiZXhwaXJlZEF0IjoxNjU0MDU1MDMzLCJpZCI6NDksInB1YmtleSI6IjBkZDRmNjAzNTMxYmQ3OGJiZWNkMDA1ZDllN2NjNjJhNzk0ZGNmYWRjZWZmZTAzZTI2OWZiYjZiNzJlOWM3MjQifQ.2S1wt6KxfJU8kxvESbrdUW1jxYyqxXlcIhL9DwtW3Yc
Request
Response
- HTTP Method:
GET
- HTTP Path:
/mm/api/self
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1653983486 | unix timestamp |
{
"id": 39,
"address": "0x9f44be256f9b0797dc26bfeed70e57a4ac4258c6",
"initHeight": 0,
"l2active": 1, // 0: actived in layer2 1:not actived in layer2
"l2userId": 67, // layer2 account id
"userLevel": "v1", // fee level
"verifyType": 0, // 0: common mode 1: unipass mode
"chainId": 0 // layer2 chain id (only used in unipass mode)
}
Request
Response
- HTTP Method:
GET
- HTTP Path:
/mm/api/slot
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1653983486 | unix timestamp |
count | int | YES | 1 | |
[
{
"slot": 10,
"nonce": 100
}
]
Send in a new order.
Request
Response
- HTTP Method:
POST
- HTTP Path:
/mm/api/orders
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
- API Limit: A single account is only allowed to send maximum of 30 new order per second
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
clientOid | string | NO | 1234 | The order id from client |
symbol | string | YES | UNI-USDC | The trading pair name |
side | string | YES | SELL | SELL/BUY |
type | string | YES | LIMIT | only support LIMIT now |
timestamp | long | YES | 1654060757 | unix timestamp |
timeInForce | string | YES | GTC | GTC/IOC/GTX/FOK |
quantity | string | YES | 20000000000000000000 | decimals=18 |
price | string | YES | 5000000000000000000 | decimals=18 |
takerFeeRatio | int | YES | 10 | decimals=4 |
makerFeeRatio | int | YES | 5 | decimals=4 |
slot | int | YES | 10 | |
nonce | int | YES | 310 | |
userPubkey | string | YES | 0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724 | zk-layer2 pubkey |
orderSignature | string | YES | 17039d98f87640c452ec4ab6bb91d2044a97ff516a920cd09bddacd774175a28d3836dc0d84c31cc862a1c1099f430adb3f7826bf97a086eba59b6ced3e4ef04 | zk-layer2 signature for order |
{
"id": "1666371045063401472",
"createdAt": 1650958799,
"updatedAt": 1650958799,
"productId": "UNI-USDT",
"userId": 1,
"clientOid": "1234",
"size": "1000000000000000000",
"funds": "70000000",
"filledSize": "0",
"executedValue": "0",
"price": "70000000",
"fillFees": "0",
"type": "limit",
"side": "buy",
"timeInForce": "GTC",
"status": "new",
"l2Status": "none",
"preSettled": false,
"settled": false
}
Request
Response
Cancel an active order
- HTTP Method:
DELETE
- HTTP Path:
/mm/api/order
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
symbol | string | YES | UNI-USDC | The trading pair name |
orderId | int | YES | 755 | |
none
Request
Response
- HTTP Meth:
DELETE
- HTTP PATH:
/mm/api/orders
(HMAC SHA256) - HTTP HEADER:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
symbol | string | YES | UNI-USDC | The trading pair name |
none
Request
Response
Get all orders, includes
new
, open
, filled
, cancelled
, cancelling
, partial
- HTTP Method:
GET
- HTTP PATH:
/mm/api/orders
(HMAC SHA256) - HTTP HEADER:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
symbol | string | YES | UNI-USDC | The trading pair name |
status | string | NO | filled filled,partial | The order status (support combined status) |
startTime | long | YES | 1 | |
endTime | long | YES | 1654063467 | |
limit | int | YES | 20 | |
{
"total": 1000,
"orders": [{
"id": "1666371045063401472", # order id
"userId": "28", # user id
"price": "9000000000000000",
"size": "2500000000",
"funds": "19997", # price*size/pow(10,18)
"productId": "UNI-USDT",
"side": "sell", # buy or sell
"type": "limit",
"createdAt": 1650958799,
"fillFees": "0",
"filledSize": "200000000", # The actual transaction quantity of the order
"executedValue": "1800000", # The actual transaction value of the order
"status": "open", #order status `new`, `open`, `filled`, `cancelled`, `cancelling`, `partial`
"l2Status": "none", #order layer2 status `none`: init status `confirming`:The order is fully filled, but not confirmed by layer2 `filled`:The order is fully filled, and confirmed by layer2 `cancelled`:The order has been cancelled, and cancelled in layer2 `partial`:The order is partial filled, and confirmed by layer2
"preSettled": false,
"settled": false,
"chanFrom": 0, # 0 : user order 1 : market maker order
"trades": [{
"id": 1,
"time": 1650958799,
"tradeSeq": 231628,
"price": "9000000000000000",
"takerOrderId": "1666371045063401472",
"makerOrderId": "1666371045063401471",
"size": "100000",
"side": "buy",
"status": 3, # 0:not sent to layer2 1:sent to layer2 2:layer2 success 3:layer2 fail 9:matching fail(not sent to layer2)
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}, {
"id": 2,
"time": 1650958799,
"tradeSeq": 231627,
"price": "9000000000000000",
"takerOrderId": "1666371045063401473",
"makerOrderId": "1666371045063401474",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}],
"cancelFill": {
"id": 1,
"time": 1650958799,
"size": "199800000",
"doneReason": "cancelled"
}
"isFullFill": true, # If isFullFill is true, it means that the order has actually been filled completely. But `trade.status` may not be `filled` , but it will eventually become filled.
}, {
"id": "1666371045063401471",
"userId": "28", # user id
"price": "8000000000000000",
"size": "2500000000",
"funds": "0",
"productId": "BTC-USDT",
"side": "buy",
"type": "limit",
"createdAt": 1650958799,
"fillFees": "0",
"filledSize": "0",
"executedValue": "0",
"status": "cancelled",
"l2Status": "none",
"preSettled": false,
"settled": false,
"trades": [{
"id": 1,
"time": 1650958799,
"tradeSeq": 231628,
"price": "8000000000000000",
"takerOrderId": "1666371045063401471",
"makerOrderId": "1666371045063401472",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}, {
"id": 2,
"time": 1650958799,
"tradeSeq": 231627,
"price": "8000000000000000",
"takerOrderId": "1666371045063401473",
"makerOrderId": "1666371045063401474",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}]
"cancelFill": {
"id": 1,
"time": 1650958799,
"size": "199800000",
"doneReason": "cancelled"
},
"isFullFill": true
}]
}
Request
Response
Check an order's status.
- HTTP Method:
GET
- HTTP PATH:
/mm/api/order
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
symbol | string | YES | UNI-USDC | The trading pair name |
orderId | int | YES | 755 | |
{
"id": "1666371045063401472",
"userId": "28",
"price": "9000000000000000",
"size": "2500000000",
"funds": "19997",
"productId": "UNI-USDT",
"side": "sell",
"type": "limit",
"createdAt": 1650958799,
"fillFees": "0",
"filledSize": "200000000",
"executedValue": "1800000",
"status": "open",
"l2Status": "none",
"preSettled": false,
"settled": false,
"chanFrom": 0,
"trades": [{
"id": 1,
"time": 1650958799,
"tradeSeq": 231628,
"price": "9000000000000000",
"takerOrderId": "1666371045063401473",
"makerOrderId": "1666371045063401474",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}, {
"id": 2,
"time": 1650958799,
"tradeSeq": 231627,
"price": "9000000000000000",
"takerOrderId": "1666371045063401472",
"makerOrderId": "1666371045063401471",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}],
"cancelFill": {
"id": 1,
"time": 1650958799,
"size": "199800000",
"doneReason": "cancelled"
},
"isFullFill": true
}
Request
Response
- HTTP Method:
GET
- HTTP Path:
/mm/api/openOrders
(HMAC SHA256) - HTTP Header:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
symbol | string | YES | UNI-USDC | The trading pair name |
limit | int | YES | 20 | |
{
"total": 1000,
"orders": [{
"id": "1666371045063401472", # order id
"userId": "28", # user id
"price": "9000000000000000",
"size": "2500000000",
"funds": "19997", # price*size/pow(10,18)
"productId": "UNI-USDT",
"side": "sell", # buy or sell
"type": "limit",
"createdAt": 1650958799,
"fillFees": "0",
"filledSize": "200000000", # The actual transaction quantity of the order
"executedValue": "1800000", # The actual transaction value of the order
"status": "open", #order status `new`, `open`, `filled`, `cancelled`, `cancelling`, `partial`
"l2Status": "none", #order layer2 status `none`: init status `confirming`:The order is fully filled, but not confirmed by layer2 `filled`:The order is fully filled, and confirmed by layer2 `cancelled`:The order has been cancelled, and cancelled in layer2 `partial`:The order is partial filled, and confirmed by layer2
"preSettled": false,
"settled": false,
"chanFrom": 0, # 0 : user order 1 : market maker order
"trades": [{
"id": 1,
"time": 1650958799,
"tradeSeq": 231628,
"price": "9000000000000000",
"takerOrderId": "1666371045063401472",
"makerOrderId": "1666371045063401471",
"size": "100000",
"side": "buy",
"status": 3, # 0:not sent to layer2 1:sent to layer2 2:layer2 success 3:layer2 fail 9:matching fail(not sent to layer2)
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}, {
"id": 2,
"time": 1650958799,
"tradeSeq": 231627,
"price": "9000000000000000",
"takerOrderId": "1666371045063401473",
"makerOrderId": "1666371045063401474",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}],
"cancelFill": {
"id": 1,
"time": 1650958799,
"size": "199800000",
"doneReason": "cancelled"
}
"isFullFill": true, # If isFullFill is true, it means that the order has actually been filled completely. But `trade.status` may not be `filled` , but it will eventually become filled.
}, {
"id": "1666371045063401471",
"userId": "28", # user id
"price": "8000000000000000",
"size": "2500000000",
"funds": "0",
"productId": "BTC-USDT",
"side": "buy",
"type": "limit",
"createdAt": 1650958799,
"fillFees": "0",
"filledSize": "0",
"executedValue": "0",
"status": "cancelled",
"l2Status": "none",
"preSettled": false,
"settled": false,
"trades": [{
"id": 1,
"time": 1650958799,
"tradeSeq": 231628,
"price": "8000000000000000",
"takerOrderId": "1666371045063401471",
"makerOrderId": "1666371045063401472",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}, {
"id": 2,
"time": 1650958799,
"tradeSeq": 231627,
"price": "8000000000000000",
"takerOrderId": "1666371045063401473",
"makerOrderId": "1666371045063401474",
"size": "100000",
"side": "buy",
"status": 3,
"productId": "UNI-USDT",
"funds": "900",
"txHash": "0x40acae664609d1115f5ab32d9f3c0fedd7609daa6a4a5515333f583fba10f545",
"failReason": ""
}]
"cancelFill": {
"id": 1,
"time": 1650958799,
"size": "199800000",
"doneReason": "cancelled"
},
"isFullFill": true
}]
}
Request
Response
- HTTP Method:
GET
- HTTP Path:
/mm/api/accounts
- HTTP HEADER:
X-MBX-APIKEY
:api key
Parameters:
Name | Type | Required | Example | Description |
---|---|---|---|---|
timestamp | long | YES | 1654060757 | unix timestamp |
[
{
"id": "1",
"currency": "USDC",
"available": "952011220000",
"hold": "1030410000000"
}, {
"id": "2",
"currency": "USDT",
"available": "4444030410000000",
"hold": "766652011220000"
}
]