ZKEX Docs
Search
⌃K
💫

Getting Started

Prerequisites

  • address
  • active address
  • apply to ZKEX Team to get api key and api secret
  • depoly market maker signer service and send signer url to ZKEX Team

Maintain trading pairs information

  • Get all trading pairs infomation through the REST interface BnGetProducts​
  • Get any trading pair infomation through ws, subscribe channel ws-level2​
  • When you subscribe to ws-level2 for the first time, you will receive the snapshot data by push-snapshot​
  • When the data of the ws-level2 changes, you will receive the data in the type of l2update​

REST Interface (Recommend)

Get the server time of ZKEX

Request
Response
  • Http Method : GET
  • Http Path : /mm/api/server
  • Response :
{
"timeNow": 1650958799
}

Get all trading pairs supported by ZKEX

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
},
......
]

Get Market Maker's JWT-Token (use to subscribe Websocket)

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

Get Market Maker's user info

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)
}

Apply Order Slots Batchly

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
}
]

New Order

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
}

Cancel Order

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

Cancel all Open Orders on a Symbol

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

Get all orders

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
}]
}

Query Order

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
}

Get all open orders

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
}]
}

Account Info

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"
}
]
NETWORK INFORMATION - Previous
Testnet Contract Address
Next - ZKEX2.0 MARKET MAKER APIS
Websocket Subscribe & Unsubscribe
Last modified 14d ago