# What is ZKEX? Offering bridgeless multi-chain trading secured with zero-knowledge, ZKEX is a trust-minimised and self-custodial order book DEX with CeFi performance. Users are able to trade assets across multiple chains with a similar experience as on Binance or Coinbase, but instead, ZKEX is decentralized and non-custodial, with transactions secured with zero-knowledge proofs. The exchange runs on a customised L3 app-rollup that aggregates liquidity from a number of EVM-compatible chains and L2 rollups. ZKEX is built upon pioneering blockchain infrastructure from zkLink, LayerZero, Polyhedra, and Pyth Network. {% hint style="info" %} Note: the ZKEX exchange is now live. These Docs give a conceptual overview of the platform, and will be updated on a regular basis. {% endhint %} Official channels: * Website: [https://zkex.com](https://zkex.com/) * Twitter/X: * Telegram: * Discord: * Blog: [https://zkex.medium.com](https://zkex.medium.com/) * Newsletter: ## Why use ZKEX instead of another DEX? A decentralized exchange (DEX) is a trading marketplace that allows secure peer to peer trading without any overseeing authority or custody of assets. An algorithm (in the form of code in a self-executing smart contract), rather than a middle party, checks to make sure both the buyer and seller complete their side of the trade on the platform. Crypto traders on other DEXs often encounter volatile liquidity, high slippage costs, unpredictable gas fees, and limited functionality while stuck on a single chain. > #### High costs and fees > > * Gas fees: Some DEX protocols run inefficient smart contracts to oversee transactions, resulting in high gas fees, especially for multi step processes. > * Lack of micro-transactions: Due to gas fees, orders need to be above a certain value for transactions to be efficient. > #### Losses on Automated Market Maker (AMM) exchanges: > > * Impermanent Loss: When assets inside a liquidity pool change in value, it often creates a discrepancy in asset prices. AMM liquidity pools rebalance the value of the assets, but this often causes a net loss in value for people contributing assets to the liquidity pool. > * Slippage: If the price of a token you are trading changes while you are in the process of purchasing it, you would get a different rate than you intended. This may happen because of limited liquidity in an AMM that dynamically changes the value of the tokens as a supply of one is depleted. Alternatively, this could be caused by the token changing in value in the time it takes the transaction to be confirmed. > * Maximal Extractable Value (MEV): The majority of MEV is conducted as hidden arbitrage in the form of Front/Back running and Sandwich attacks. Bad actors can extract profits by changing the order of transactions in a block, or inserting their own trades to push up or down prices. > #### Limited functionality: > > * Isolated blockchains: If someone has USDC on the ETH-20 network, but would like to trade on another chain, they can’t make the trade directly. Instead they would need to bridge their funds over using a separate service, which can be tedious, subject to extra fees, and potentially unsafe. > * Fewer trading strategies: Limit orders are often missing from most DEXs, which prevents automated trading. ## Core Concepts Learning a few basic technical terms will help you understand crypto and web3 a little better. Here are some common concepts that you might come across when trading on ZKEX: > #### L1 Networks > > A Layer1 (L1) network is the underlying blockchain infrastructure. They are self-contained ecosystems that handle transactions, security, consensus, and data availability - for this reason trading on L1 is known as being ‘on-chain’. > > For example, Ethereum or Solana are both L1 protocols, with their own different advantages. > #### L2 Networks > > A Layer2 (L2) network is a network built on top of one of more L1 blockchains. They rely on the underlying L1 network for security and data availability, but process transactions at higher scale on separate infrastructure - for this reason trading on L2 is known as being ‘off-chain’. > > There are many types of L2 networks, with zero-knowledge rollups considered to be one of the most promising for enhanced scalability, privacy, and security. > #### L3 Networks > > A Layer3 (L3) network is a third blockchain layer built on top of one of more L2 networks. The primary goal of an L3 network is to provide additional specialization and efficiency for specific use cases or to enable new functionalities that are not feasible directly on L2 due to constraints like standardization, privacy requirements, or interoperability issues. > #### Zero-Knowledge Rollups > > A zero-knowledge rollup (ZK-rollup) is a way of using mathematics to verify the outcome of a transaction, and compress transaction data down to a minimum. A proof is generated, which is double-checked for judgement, after which the trade is confirmed as being successful, and written to the underlying L1 blockchain. > > The advantages of this method are that it enables higher scalability (and lower gas fees), fast finality, and a high level guarantee that the transaction has not been faked or tampered with. > > You can read more about ZK-Rollups in the [**Security**](https://github.com/ZKEX/docs/blob/master/docs/Concepts/Security) section. > #### Order Book Matching Engine > > A central limit order book (CLOB) is essentially a meeting place for buyers and sellers to be matched together to fulfil their trades. ZKEX’s order book works in a similar way to a centralised order book exchange, however the the execution of the matched orders is decentralized and trustless. > > You can read more about order books in the [**Trading**](https://github.com/ZKEX/docs/blob/master/docs/Concepts/Trading) section. # How ZKEX works {% hint style="info" %} ZKEX will feel very much like Binance, but will be decentralized, trust minimized, and non-custodial. Users can use their Metamask wallet to deposit/withdraw funds to ZKEX. Both spot trading and derivatives trading will be available. {% endhint %} ## ## Basic trading Users will be able to deposit assets from any connected L1 chain or L2 into their ZKEX account and start trading. They can withdraw the assets back anytime, with the re-assurance that every transaction was verified with zero-knowledge proofs. #### Example: * Bob has 10 ETH, which he deposits to his L2 Wallet in his ZKEX account. He pays gas fees since he is moving assets from L1 > L2. * Bob makes a few spot trades, and in the end makes a small profit of 1 ETH by buying and selling SOL and AVAX. He pays transaction fees for the trades. * He decides to leave 5 ETH in his L2 wallet to trade with later, and withdraw 6 ETH back to his Metamask wallet. He pays gas fees + withdrawal fee since he is moving some assets from L2 > L1. Note: Users only pay gas fees whenever they deposit or withdraw funds between L1 and L2. There are no fees for keeping your assets in your own L2 wallet, which are always in your custody. ## Benefits of using ZKEX * **One-step multi-chain trades—** a faster and simplified user experience using the order book model for spot trading and derivatives — similar to DYDX, but multi-chain; * **Deep liquidity—** get buy and sell orders filled at competitive spread prices; * **No gas fees while trading on L2\*—** by moving transactions off-chain to Layer2 all you pay are low transaction fees; * **Guaranteed security—** with ‘zero-knowledge’ technology, the danger of malicious behaviour by anyone (not even the ZKEX team) is virtually eliminated; * **Better capital efficiency—** aggregate your stablecoins from multiple chains into a universal 'USD' coin for more trading opportunities; * **Non-custodial—** you retain control over your assets at all times. * **No uncertainty—** with the order book model, prices and trades can be controlled. Risks of slippage and MEV are eliminated. * **Auto trading:** Automate your trading with order types such as limit, stop-loss, and partial fills. * **Adaptable:** Support for new chains, currencies and trading options can be added as needed within the original framework. \*Note there are still gas fees when depositing or withdrawing funds between L1 and L2. To summarize, ZKEX is an order book exchange designed for both new and professional DeFi traders, with a seamless user experience, that is ultra-secure, capital efficient, multi-chain, decentralized, with competitive fees and access to massive liquidity from all supported blockchains. ## Advanced trading Later, users will be able to collaterize their stablecoins and stablecoin-LP tokens, to borrow a new stablecoin for more trading opportunities on ZKEX. This isx the same mechanism of getting a loan, but using as crypto assets as collateral. # Supported chains and coins ## Networks We've successfully integrated the following blockchain networks, with more coming soon. > #### Networks: > > * Ethereum > * Avalanche > * BSC > * BNB Chain > * Polygon > * Linea > * StarkNet > * zkSync Era > * Arbitrum > * Optimism > * Base ## ## Stablecoins Stablecoins are a cryptocurrency pegged to a target value such as the US Dollar at a 1:1 ratio. Users can deposit any of the following fiat-backed stablecoins, which are merged to a unified 'USD' equivalent in a user's ZKEX wallet: * USDC * USDT Since all deposited stablecoins are equivalent to USD, the number of trading pairs is minimized, making it simpler to trade. # ZKEX Account {% hint style="info" %} In order to trade on ZKEX, users need to deposit their funds from the original L1 chain or L2 rollup (e.g. Ethererum, Polygon, zkSync etc.) to their account on ZKEX. The original assets are locked by ZKEX’s smart contract on the original chain, and equivalent funds released for trading on the ZKEX dApp. Since all deposits, transactions, and withdrawals are secured with zero-knowledge proofs, this allows assets to be used safely on the ZKEX dApp, while still ensuring security at the same level as the original chain. {% endhint %} ## Deposits Depositing into your Account is simple. The user selects the supported chain where their assets are, then selects a token amount to lock those funds into the ZKEX smart contract. There is no charge for a deposit, other than any gas fees incurred from the originating chain. ## Withdrawals There are currently two ways to withdraw assets from a user's ZKEX’s Account, with different speeds and costs. Withdrawals incur both a fee and gas fees to the destination chain. > #### Fast Withdrawal > > ZKEX offers a fast withdraw option, which allows users to withdraw assets from your Account via a broker. The broker will take a fee based on the required amount, and send the funds quickly. Fast withdrawals are still completed on-chain, but using a broker bypasses the normal transaction time taken with a standard withdraw. > #### Standard Withdrawal > > Standard withdrawal times depend on the level of trading activity on the dApp. They can be as fast as an hour, but could take upto 24 hours. # Trading ## Trading Types * Limit Order (available) * Market Order (available) * Stop Market * Stop Limit * Trailing Stop * Take Profit * Take Profit Limit ## Trading Pairs We plan to go live with a small number of pairs, with the potential of hundreds being eventually available. ## Self Trade At ZKEX, a "Self Trade" is identified when the creator (maker) and the receiver (taker) of the order are the same address. In such instances, ZKEX refrains from pushing the transaction to Layer 2, thereby not incurring any transaction fees. The implementation of this feature is aimed at ensuring the fairness and transparency of transactions. Since a self-trade does not lead to any actual change in user assets, we opt not to process it to prevent potential market manipulation and unnecessary network congestion. Furthermore, we would like to emphasize that ZKEX only levies fees on genuinely effective transactions, a measure designed to maintain and enhance the overall health and stability of the trading environment. # Fees {% hint style="info" %} Please note, all fees below are estimated, and subject to change. {% endhint %} ## No activation fee There is no charge or fee to activate your L2 account on ZKEX. ## No deposit fees There are no fees for depositing money - but you may need to pay a 'gas fee' to the blockchain you're sending assets from. ## Gas fees The 'gas fee' is a charge from the L1 chain when you move funds to/from L1 (on-chain) <> L2 (off-chain), which can vary depending on network congestion. There are no gas fees once you are trading on L2. ## Trading fees > #### Our fee structure is as follows: > > * The basic fee rate is set at 0.2% for taker orders and 0.1% for maker orders. > * If the anticipated fee for an individual order falls below 0.2U, the fee will be standardized to 0.2U. In such instances, the effective fee rate will be calculated as 0.2 divided by the Order Amount. > #### Why do we impose a minimum fee of 0.2U? > > To guarantee the security of all assets and to maintain trading fairness on our DEX, it’s necessary to record all assets and transaction data on the blockchain after zero-knowledge proofs are implemented. This process generates specific costs. Thus, we aim to fairly distribute these costs across each order. Once a user’s transaction value reaches 100U (or 200U for makers), the actual fee rate reverts to the base fee rate, which is 0.2% for takers and 0.1% for makers. These rates align with the fees charged by major centralized exchanges, while providing our users with the level of asset security that centralized exchanges are unable to offer. ## Withdraw fees Fees associated with the withdrawal vary by the destination network and token used: * Regular withdrawal - TBC * Fast withdrawal - TBC # Security {% hint style="info" %} 'Security by design' is one of the guiding principles at ZKEX. Security is implemented at every level: the wallet, deposits, withdrawals, computations and consensus of transactions. By removing token bridges, mathematically verifying transactions, and implementing multiple fail safes, the danger of malicious behaviour done by anyone (including the ZKEX team) is virtually eliminated. Transactions are mathematically verified to ensure every trade completes as expected, or is rejected. {% endhint %} ## Wallet When you connect your browser wallet to ZKEX and 'deposit' funds into ZKEX for trading, your assets are temporarily 'locked' in your browser wallet, and only moved when a transaction is successfully completed. This ensures you retain custody in your own wallet, and there are no assets on ZKEX to attack. ## ## Deposits Moving your assets to trade on ZKEX is safe and secure, as no bridges are involved. Instead, an L2 network is built natively on top of each connected blockchain, which makes it quick and easy to 'move' assets into ZKEX to trade from your browser wallet. ## ## Transactions ZKEX applies a two-step security guarantee of verification + judgment. > #### Applying ZK-Proofs > > Zero Knowledge is a branch of cryptography that uses mathematics to calculate something called a 'zero-knowledge proof' (ZK-Proof) - which is like 'a seal of approval' to check if a given statement is true. > > When applying ZK-proofs to cryptocurrency trading, a proof is generated from the transaction data using an algorithm. This ZK-Proof is a one-way calculation of the transaction, that cannot be reverse engineered to reveal the details of that transaction or any details of the people involved. > > This proof can be sent to a 'verifier', who checks that the proof is correct using another special algorithm. > #### Step 1: Verification > > In the case of a multi-chain transaction (say from Ethereum to Avalanche), there are assets moving between two different blockchains, so we actually have two ZK-Proofs. By further calculating these two ZK-Proofs together, we create something called a ‘ZK-recursive-proof’. > > In the end, we have one single calculation to verify the entire multi-chain transaction. This single ‘ZK-recursive-proof’ can be verified if transactions happened and completed successfully — and if so, can be published on both blockchains. > #### Step 2: Judgement > > To double-check the verification was correct, an independent network of juries (that is on LayerZero) judges the consistency of the two generated 'ZK-proofs' sent to each connected blockchain. > > This additional check by an independent third-party gives peace of mind and guarantees consistency, while keeping the details of the trade completely private. ## ## Disaster recovery ZKEX allows an emergency withdrawal function - giving users the ability to unlock their assets in case of an extreme situation. Details of how to do this will be released soon on the [**L2Wallet**](https://github.com/ZKEX/docs/blob/master/docs/Concepts/L2Wallet) page. ## ## Technical details For more technical information about our security stack, please see: * * * ## ## Security audits A security audit is currently under way and will be published on our website. In future, a security review will be conducted before every update. ## ## Bug Bounty Program After launch, we will offer a bug bounty program, with generous rewards to participants. ## ## Decentralization During the development phase, ZKEX is operating as non-custodial, centrally operated entity. As the project progresses, we will further decentralise all parts of our infrastructure and organization. # Tokenomics No information about a ZKEX token is available yet. Any information regarding a governance token will be released only via our official channels. Please be wary of scams and fake announcements. # Resources ## Testnet The testnet is a public demo of the ZKEX app. You can place test trades with 'fake' tokens to try the experience of decentralized crypto trading across multiple chains. Access the testnet: If you see anything broken or incorrect, you can report the bug to us: Complete quests and collect points to earn future rewards: ## ## Branding A download with our logo and branding guidelines will be available soon. # Roadmap ## Q1 2024 * [x] ZKEX V3 testnet launch * [x] Develop perpetual trading engine * [x] Redesigned UI for a better user experience ## Q2 2024 * [x] ZKEX V3 Mainnet Launch * [x] Support Perpetual Trading * [x] 1,000 TPS with enhanced scalability * [x] Integrated ETH mainnet * [x] Launch “Trade to Earn” Pre-season Farming campaign ## Q3 2024 * Mobile support for the product * Integrate Scroll, Manta, Mantle, Metis and other L2 networks ## Q4 2024 * Launch token staking * Partnership and ecosystem building
# Supported Tokens ### USDC
Chain IDBlockchainAddressDecimalsfastWithdraw
1Polygon0x2791bca1f2de4661ed88a30c99a7a9449aa841746✓YES
2Avalanche C-Chain0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E6✓YES
4Ethereum0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb486✓YES
5ZkSync Era0x3355df6D4c9C3035724Fd0e3914dE96A5a83aaf46✓YES
7Linea0x176211869cA2b568f2A7D4EE941E073a821EE1ff6✓YES
9Arbitrum One0xaf88d065e77c8cc2239327c5edb3a432268e58316✓YES
10Optimism0x7f5c764cbc14f9669b88837ca1490cca17c316076✓YES
### USDT
Chain IDBlockchainAddressDecimalsfastWithdraw
1Polygon0xc2132D05D31c914a87C6611C10748AEb04B58e8F6✓YES
2Avalanche C-Chain0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c76✓YES
3BinanceSmartChain0x55d398326f99059ff775485246999027b319795518
4Ethereum0xdac17f958d2ee523a2206206994597c13d831ec76✓YES
7Linea0xA219439258ca9da29E9Cc4cE5596924745e12B936✓YES
9Arbitrum One0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb96✓YES
10Optimism0x94b008aa00579c1307b0ef2c499ad98a8ce58e586✓YES
### DAI
Chain IDBlockchainAddressDecimalsfastWithdraw
1Polygon0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A06318✓YES
4Ethereum0x6B175474E89094C44Da98b954EedeAC495271d0F18✓YES
### ARB
Chain IDBlockchainAddressDecimalsfastWithdraw
9Arbitrum One0x912ce59144191c1204e64559fe8253a0e49e654818✓YES
### OP
Chain IDBlockchainAddressDecimalsfastWithdraw
10Optimism0x420000000000000000000000000000000000004218✓YES
# Mainnet Contract Address `Deploy Time`: Jul-17-2023 07:42:35 AM +UTC `Tag`: Mainnet Alpha `zkLink Version`: [f809e1a05e18457bd98c9a2027c967839f980dc1](https://github.com/zkLinkProtocol/zklink-periphery/commit/f809e1a05e18457bd98c9a2027c967839f980dc1) (private)
NetworkContract Address
Ethereum Mainnet0x629d74d459f072914f0b2aab9f7232fa36c1baed
Polygon0xb5b7644a0e8f1fd12040298eacf8012ae96158a2
Avalanche0xb86934fa6e53e15320911485c775d4ba4020fa5a
Binance Smart Chain0xb86934fa6e53e15320911485c775d4ba4020fa5a
zkSync Era0x927e26fe316af1da346a056353d1e5237bc3d503
Linea0x629d74d459f072914f0b2aab9f7232fa36c1baed
Arbitrum One0xb86934fa6e53e15320911485c775d4ba4020fa5a
Optimism0xb86934fa6e53e15320911485c775d4ba4020fa5a
Base0xb86934fa6e53e15320911485c775d4ba4020fa5a
opBNB0xb5b7644a0e8f1fd12040298eacf8012ae96158a2
# Testnet Contract Address `Deploy Time`: Jul-07-2023 06:58:12 AM +UTC `Tag`: `Latest (0.9.0)` `zkLink Version`: [b39c90da2b49ec61402d1359a07adf3090f51735](https://github.com/zkLinkProtocol/zklink-periphery/commit/b39c90da2b49ec61402d1359a07adf3090f51735) (private)
NetworkContract Address
Goerli Testnet0x4e1ed4eccaf6a56e8da95cbb3d2c5aa298d43913
zkSync Era Testnet0x2b068879129a7a5e397a06a067a46cf3f158287d
Linea Goerli Testnet0xdda221cc960f8af74f90c04bfd05dd224ce1fcb8
Bsc Testnet0x8a7e5ad62af369be612a142d7211d336e4c877ac
Polygon Testnet0x162cf62e14eca1abcf89a88f9a21e1d2632b6446
Avax Testnet0xe691cd1445599b02f1e69591942479910834c673
Arbitrum Testnet0xa216d959bcaa5937ca876a70eec41080ff6172ce
`Deploy Time:` Apr-28-2023 05:37:24 AM +8 UTC `Tag: Dunkirk` `dApps: ZKEX` `zkLink Version:` [4f909ef1da5a8f62b6c4a38c80319be6d2da40ef](https://github.com/zkLinkProtocol/zklink-periphery/commit/4f909ef1da5a8f62b6c4a38c80319be6d2da40ef) (private)
NetworkContract Address
Goerli Testnet0xC668dE72C9eb10870D52E618A44f4182d428825e
zkSync Era Testnet0xa2e2Bc5ce03443BeC5094cEd04BF8E0EC887aDC9
Scroll Alpha Testnet0x378de89c13df5e428d9f1edff4ae305764d592e2
Linea Goerli Testnet0x4931cb9e5fc58be00c5fd133d0961347f3406b86
Bsc Testnet0x0473ecc194462dd4010c6be0d1dac73e7ca9fc7f
Polygon Testnet0x4d6f405639f4bcf3e58505ee0965ae2cb4201be3
Avax Testnet0x2096eAD9d82ca596Ca807e82b2D61c15aDCb5fFF
`Deploy Time:` Apr-28-2023 05:37:24 AM +8 UTC `Tag: Dunkirk` `dApps: ZKEX` `zkLink Version:` [4f909ef1da5a8f62b6c4a38c80319be6d2da40ef](https://github.com/zkLinkProtocol/zklink-periphery/commit/4f909ef1da5a8f62b6c4a38c80319be6d2da40ef) (private)
NetworkContract Address
Goerli Testnet0x4d116306C418010F85d6905457239349914bF1Cd
Scroll Alpha Testnet0xcC85Ae89DC053e34a58f04e88571644F41A0e5c0
Linea Goerli Testnet0xc04A47344C362b6a4DD1E7b7Fd080ac6ABA36C95
Bsc Testnet0x15ee6c6360f62db16250B84A2efDA48f001740E8
Polygon Testnet0xd5a67aE094D26451C5CE592798C9CaDE55f968aa
Avax Testnet0x7a185Fa2CC782639bCEeb28ecD0cD85b8709EC98
# 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](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#bngetproducts) * Get any trading pair infomation through `ws`, subscribe channel [ws-level2](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#ws-level2) * When you subscribe to [ws-level2](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#ws-level2) for the first time, you will receive the snapshot data by [push-snapshot](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#push-snapshot) * When the data of the [ws-level2](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#ws-level2) changes, you will receive the data in the type of [l2update](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#l2update) *** ## REST Interface (Recommend) ### Get the server time of ZKEX {% tabs %} {% tab title="Request" %} * Http Method : `GET` * Http Path : `/mm/api/server` * Response : {% endtab %} {% tab title="Response" %} ``` { "timeNow": 1650958799 } ``` {% endtab %} {% endtabs %} *** ### Get all trading pairs supported by ZKEX {% tabs %} {% tab title="Request" %} * Http Method : `GET` * Http Path : `/mm/api/products` {% endtab %} {% tab title="Response" %} ``` [ { "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 }, ...... ] ``` {% endtab %} {% endtabs %} *** ### Get Market Maker's JWT-Token (use to subscribe Websocket) {% tabs %} {% tab title="Request" %} * HTTP Method: `GET` * HTTP Path: `/mm/api/users` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1653983486unix timestamp
{% endtab %} {% tab title="Response" %} 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZGRyZXNzIjoiMHgzNDk4ZjQ1NjY0NTI3MGVlMDAzNDQxZGY4MmM3MThiNTZjMGU2NjY2IiwiZXhwaXJlZEF0IjoxNjU0MDU1MDMzLCJpZCI6NDksInB1YmtleSI6IjBkZDRmNjAzNTMxYmQ3OGJiZWNkMDA1ZDllN2NjNjJhNzk0ZGNmYWRjZWZmZTAzZTI2OWZiYjZiNzJlOWM3MjQifQ.2S1wt6KxfJU8kxvESbrdUW1jxYyqxXlcIhL9DwtW3Yc
{% endtab %} {% endtabs %} *** ### Get Market Maker's user info {% tabs %} {% tab title="Request" %} * HTTP Method: `GET` * HTTP Path: `/mm/api/self` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1653983486unix timestamp
{% endtab %} {% tab title="Response" %} ``` { "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) } ``` {% endtab %} {% endtabs %} *** ### Apply Order Slots Batchly {% tabs %} {% tab title="Request" %} * HTTP Method: `GET` * HTTP Path: `/mm/api/slot` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1653983486unix timestamp
countintYES1
{% endtab %} {% tab title="Response" %} ``` [ { "slot": 10, "nonce": 100 } ] ``` {% endtab %} {% endtabs %} *** ### New Order Send in a new order. {% tabs %} {% tab title="Request" %} * 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:**
NameTypeRequiredExampleDescription
clientOidstringNO1234The order id from client
symbolstringYESUNI-USDCThe trading pair name
sidestringYESSELLSELL/BUY
typestringYESLIMITonly support LIMIT now
timestamplongYES1654060757unix timestamp
timeInForcestringYESGTCGTC/IOC/GTX/FOK
quantitystringYES20000000000000000000decimals=18
pricestringYES5000000000000000000decimals=18
takerFeeRatiointYES10decimals=4
makerFeeRatiointYES5decimals=4
slotintYES10
nonceintYES310
userPubkeystringYES0dd4f603531bd78bbecd005d9e7cc62a794dcfadceffe03e269fbb6b72e9c724zk-layer2 pubkey
orderSignaturestringYES17039d98f87640c452ec4ab6bb91d2044a97ff516a920cd09bddacd774175a28d3836dc0d84c31cc862a1c1099f430adb3f7826bf97a086eba59b6ced3e4ef04zk-layer2 signature for order
{% endtab %} {% tab title="Response" %} ``` { "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 } ``` {% endtab %} {% endtabs %} *** ### Cancel Order {% tabs %} {% tab title="Request" %} Cancel an active order * HTTP Method: `DELETE` * HTTP Path: `/mm/api/order` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
symbolstringYESUNI-USDCThe trading pair name
orderIdintYES755
{% endtab %} {% tab title="Response" %} none {% endtab %} {% endtabs %} *** ### Cancel all Open Orders on a Symbol {% tabs %} {% tab title="Request" %} * HTTP Meth: `DELETE` * HTTP PATH: `/mm/api/orders` (HMAC SHA256) * HTTP HEADER: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
symbolstringYESUNI-USDCThe trading pair name
{% endtab %} {% tab title="Response" %} none {% endtab %} {% endtabs %} *** ### Get all orders {% tabs %} {% tab title="Request" %} 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:**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
symbolstringYESUNI-USDCThe trading pair name
statusstringNOfilled filled,partialThe order status (support combined status)
startTimelongYES1
endTimelongYES1654063467
limitintYES20
{% endtab %} {% tab title="Response" %} ``` { "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 }] } ``` {% endtab %} {% endtabs %} *** ### Query Order {% tabs %} {% tab title="Request" %} Check an order's status. * HTTP Method: `GET` * HTTP PATH: `/mm/api/order` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
symbolstringYESUNI-USDCThe trading pair name
orderIdintYES755
{% endtab %} {% tab title="Response" %} 
{
    "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 
}
{% endtab %} {% endtabs %} *** ### Get all open orders {% tabs %} {% tab title="Request" %} * HTTP Method: `GET` * HTTP Path: `/mm/api/openOrders` (HMAC SHA256) * HTTP Header: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
symbolstringYESUNI-USDCThe trading pair name
limitintYES20
{% endtab %} {% tab title="Response" %} ``` { "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 }] } ``` {% endtab %} {% endtabs %} *** ### Account Info {% tabs %} {% tab title="Request" %} * HTTP Method: `GET` * HTTP Path: `/mm/api/accounts` * HTTP HEADER: `X-MBX-APIKEY` : `api key` **Parameters:**
NameTypeRequiredExampleDescription
timestamplongYES1654060757unix timestamp
{% endtab %} {% tab title="Response" %} ``` [ { "id": "1", "currency": "USDC", "available": "952011220000", "hold": "1030410000000" }, { "id": "2", "currency": "USDT", "available": "4444030410000000", "hold": "766652011220000" } ] ``` {% endtab %} {% endtabs %} # Websocket Subscribe & Unsubscribe ### Order data of any trading pair (`level2`) {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "level2" ], "token": "" #option } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "level2" ], "token": "" #option } ``` {% endtab %} {% endtabs %} **Notice:** When you subscribe to [level2](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#ws-level2) for the first time, you will receive the snapshot data by [push-snapshot](https://github.com/ZKEX/dev-docs/tree/main/market-maker-apis#push-snapshot) *** ### K-line data of a trading pair (1/3/5/15/30/60min/2/4/6/12/24hour) {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "candles_1m" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "candles_1m" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% tab title="Channel name comparison table" %}
channel nametime
candles_1m1min
candles_3m3min
candles_5m5min
candles_15m15min
candles_30m30min
candles_60m60min
candles_120m2hour
candles_240m4hour
candles_360m6hour
candles_720m12hour
candles_1440m24hour
{% endtab %} {% endtabs %} *** ### Ticker info of a trading pair {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "ticker" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "ticker" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% endtabs %} *** ### Matching information of a trading pair {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "match" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "match" ], "token": "" # optional (JWT-token) } ``` {% endtab %} {% endtabs %} *** ### Success order information of a trading pair {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "trade" ], "token": "" # required (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "trade" ], "token": "" # required (JWT-token) } ``` {% endtab %} {% endtabs %} *** ### Order change infomation of a trading pair {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "order" ], "token":"" # required (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "product_ids": [ "UNI-USDC" ], "channels": [ "order" ], "token": "" # required (JWT-token) } ``` {% endtab %} {% endtabs %} *** ### The asset change information of an account {% tabs %} {% tab title="Subscribe" %} ``` { "type": "subscribe", "currency_ids": [ "UNI", "USDC" ], "channels": [ "funds" ], "token": "" # required (JWT-token) } ``` {% endtab %} {% tab title="Unsubscribe" %} ``` { "type": "unsubscribe", "currency_ids": [ "UNI", "USDC" ], "channels": [ "funds" ], "token":"" # required (JWT-token) } ``` {% endtab %} {% endtabs %} # Websocket Data Push ## Overview *** ### Snapshot data * Subscribe channel : `level2` * Push only once, when the `level2` channel is established *** ### Data changes * Subscribe channel : `level2` ``` { "type": "l2update", "productId": "UNI-USDC", "time": 1686645711, "changes": [ [ "sell", "90000000000000000000", // price "100000000000" // amount ] ] } ``` *** ### K-line data * Subscribe channel: `candles_1m`,`candles_3m`,`candles_5m`.... * Maximum 1 push within 1s ``` { "type": "candles_1m", "productId": "UNI-USDC", "time": 1653273480, "open": "1100000000000000000", "close": "1100000000000000000", "low": "1100000000000000000", "high": "1100000000000000000", "volume": "10000000000000000000" } ``` *** ### Ticker info * Subscribe channel: `match` * Maximum 1 push within 3s ``` { "type": "ticker", "tradeSeq": 20, "sequence": 85, "time": 1650958799, "productId": "UNI-USDC", "price": "90000000000", "side": "sell", "lastSize": "10000000", "bestBid": "", "bestAsk": "", "volume24h": "110000000000000000", "volume30d": "310000000000000000", "low24h": "1000000000000000", "high24h": "1000000000000000", "open24h": "1000000000000000", "close24h": "1000000000000000" } ``` *** ### Matching info * Subscribe channel: `match` * Since the settlement of ZKEX is in Layer 2, `match` only means that the matching is successful, not that the transaction is successful ``` { "type": "match", "tradeSeq": 20, "sequence": 100, "time": 1650958799, "productId": "UNI-USDC", "price": "900000000000", "size": "1000000000", "makerOrderId": "1666371045063401472", # maker's order id "takerOrderId": "1666371045063401471", # taker's order id "side": "sell" } ``` *** ### Trading info * Subscribe channel: `trade` * After the `match` channel is pushed, if layer2 is actually done, the `trade` channel will be pushed. ``` { "type": "trade", "tradeSeq": 20, "time": 1650958799, "productId": "UNI-USDC", "price": "900000000000", "size": "1000000000", "makerOrderId": "1666371045063401472", # maker's order id "takerOrderId": "1666371045063401471", # taker's order id "side": "sell", "status": 2, "failReason": "" } ``` *** ### Order change infomation of a trading pair * Subscribe channel: `order` ``` { "userId": 1, "clientOid": "1234", "type": "order", "sequence": 0, "id": "50", "price": "1000000000", "size": "1000000000000", "funds": "0", "productId": "UNI-USDC", "side": "sell", "orderType": "limit", "createdAt": 1650958799, "fillFees": "0", # fee (calculated in quote tokens) "filledSize": "0", # number of successfully matched (calculated in base tokens) "executedValue": "0", # value of successfully matched (calculated in quote tokens) "status": "new", # order status: `new`, `open`, `filled`, `cancelled`, `cancelling`, `partial` "settled": false, # whether the matching was successful "timeInForce": "GTC" } ``` *** ### The asset change information of an account * Subscribe channel: `funds` ``` { "type": "funds", "sequence": 0, "userId": "1", "currencyCode": "UNI", "available": "820900000000000000", "hold": "11741000000000000000" } ```