💫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

Get the server time of ZKEX

Http Method : GET
Http Path : /mm/api/server
Response :

{
  "timeNow": 1650958799 
}

Get all trading pairs supported by ZKEX

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

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

Name

Type

Required

Example

Description

timestamp

long

YES

1653983486

unix timestamp

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZGRyZXNzIjoiMHgzNDk4ZjQ1NjY0NTI3MGVlMDAzNDQxZGY4MmM3MThiNTZjMGU2NjY2IiwiZXhwaXJlZEF0IjoxNjU0MDU1MDMzLCJpZCI6NDksInB1YmtleSI6IjBkZDRmNjAzNTMxYmQ3OGJiZWNkMDA1ZDllN2NjNjJhNzk0ZGNmYWRjZWZmZTAzZTI2OWZiYjZiNzJlOWM3MjQifQ.2S1wt6KxfJU8kxvESbrdUW1jxYyqxXlcIhL9DwtW3Yc

Get Market Maker's user info

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

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

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

Name

Type

Required

Example

Description

timestamp

long

YES

1653983486

unix timestamp

count

int

YES

[
  {
    "slot":  10,             
    "nonce": 100
  }
]

New Order

Send in a new order.

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

Name

Type

Required

Example

Description

clientOid

string

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

decimals=4

makerFeeRatio

int

YES

decimals=4

slot

int

YES

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

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

Name

Type

Required

Example

Description

timestamp

long

YES

1654060757

unix timestamp

symbol

string

YES

UNI-USDC

The trading pair name

orderId

int

YES

755

Cancel all Open Orders on a Symbol

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

Name

Type

Required

Example

Description

timestamp

long

YES

1654060757

unix timestamp

symbol

string

YES

UNI-USDC

The trading pair name

Get all orders

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

Name

Type

Required

Example

Description

timestamp

long

YES

1654060757

unix timestamp

symbol

string

YES

UNI-USDC

The trading pair name

status

string

filled filled,partial

The order status (support combined status)

startTime

long

YES

endTime

long

YES

1654063467

limit

int

YES

{
  "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

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

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

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

Name

Type

Required

Example

Description

timestamp

long

YES

1654060757

unix timestamp

symbol

string

YES

UNI-USDC

The trading pair name

limit

int

YES

{
  "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

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

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

PreviousTestnet Contract Address NextWebsocket Subscribe & Unsubscribe

Last updated 7 months ago

Prerequisites

Maintain trading pairs information

REST Interface (Recommend)

Get the server time of ZKEX

Get all trading pairs supported by ZKEX

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

Get Market Maker's user info

Apply Order Slots Batchly

New Order

Cancel Order

Cancel all Open Orders on a Symbol

Get all orders

Query Order

Get all open orders

Account Info