MCDEX
Search…
Trade
This guide shows how to trade by using the LiquidityPoolFactory function and estimated amount out for a trade, then execute a trade.

QueryTrade

This section shows how to get estimated amount out for a trade.
CallStatic method provided by ethers.js. callStatic is a useful method that submits a state-changing transaction to an Ethereum node, but asks the node to simulate the state change, rather than to execute it. Our script can then return the result of the simulated state change.

Function

queryTrade(perpetualIndex, traderAddress, amount, referrer, flags)
parameters
type
description
perpetualIndex
number
index of perpetual in the liquidity pool
traderAddress
string
address of trader
amount
number
amount of position to trader, positive for buying and negative for selling. The amount always use decimals 18
referrer
string
address of referrer who will get rebate from the deal
flags
number
flags of the trade is a 32 bit uint value which indicates: (from the highest bit)
  • close only: only close position during trading
  • market order: do not check limit price during trading
  • stop loss: only available in brokerTrade mode
  • take profit: only available in brokerTrade mode
1
Flags is a 32 bit uint value which indicates: (from highest bit)
2
31 27 26 7 6 0
3
+---+---+---+---+---+------------------------+----------------+
4
| C | M | S | T | R | Target leverage 20bits | Reserved 7bits |
5
+---+---+---+---+---+------------------------+----------------+
6
| | | | | ` Target leverage Fixed-point decimal with 2 decimal digits.
7
| | | | | 0 means don't automatically deposit / withdraw.
8
| | | | `--- Reserved
9
| | | `------- Take profit Only available in brokerTrade mode.
10
| | `----------- Stop loss Only available in brokerTrade mode.
11
| `--------------- Market order Do not check limit price during trading.
12
`------------------- Close only Only close position during trading.
13
For stop loss and take profit, see `validateTriggerPrice` in OrderModule.sol for details.
Copied!
Return information from queryTrade function
returns
type
description
tradePrice
number
average fill price
totalFee
number
total fee collected from the trader after the trade
cost
number
deposit or withdraw to let effective leverage == assign flag
  • > 0 if deposit
  • < 0 if withdraw
Notice
  • Query the prices, fees and cost when trade against amm.
  • The trading price is determined by the AMM based on the index price of the perpetual.
  • This method should return the same result as a 'read-only' trade.

Example

1
import { LiquidityPoolFactory } from '@mcdex/mai3.js'
2
const liquidityPool = LiquidityPoolFactory.connect(liquidityPoolAddress, provider)
3
let { tradePrice, totalFee, cost } = await liquidityPool.callStatic.queryTrade(0, signer.address, toWei("1"), NONE, 12800) // please check permission of sender
Copied!

Execute Trade

Function

trade(perpetualIndex, traderAddress, amount, limitPrice, deadline, referrer, flags)
parameters
type
description
perpetualIndex
number
index of perpetual in the liquidity pool
traderAddress
string
address of trader
amount
number
amount of position to trader, positive for buying and negative for selling. The amount always use decimals 18
limitPrice
number
worst price the trader accepts
deadline
number
deadline of the trade (unix timestamp)
referrer
string
address of referrer who will get rebate from the deal
flags
number
flags of the trade is a 32 bit uint value which indicates: (from the highest bit)
  • close only: only close position during trading
  • market order: do not check limit price during trading
  • stop loss: only available in brokerTrade mode
  • take profit: only available in brokerTrade mode
1
Flags is a 32 bit uint value which indicates: (from highest bit)
2
31 27 26 7 6 0
3
+---+---+---+---+---+------------------------+----------------+
4
| C | M | S | T | R | Target leverage 20bits | Reserved 7bits |
5
+---+---+---+---+---+------------------------+----------------+
6
| | | | | ` Target leverage Fixed-point decimal with 2 decimal digits.
7
| | | | | 0 means don't automatically deposit / withdraw.
8
| | | | `--- Reserved
9
| | | `------- Take profit Only available in brokerTrade mode.
10
| | `----------- Stop loss Only available in brokerTrade mode.
11
| `--------------- Market order Do not check limit price during trading.
12
`------------------- Close only Only close position during trading.
13
For stop loss and take profit, see `validateTriggerPrice` in OrderModule.sol for details.
Copied!
Return information from trade function
returns
type
description
tradeAmount
number
amount of positions actually traded in the transaction. The amount always use decimals 18.
Notice
  • Trade with AMM in the perpetual, require sender is granted the trade privilege by the trader.
  • The trading price is determined by the AMM based on the index price of the perpetual.
  • A successful trade should:
    • The trade transaction not exceeds deadline;
    • Current liquidity of amm is enough to make the deal;
    • to open position:
      • Trader's margin balance must be greater then or equal to initial margin after trading;
      • Full trading fee will be charged if trader is opening position.
    • to close position:
      • Trader's margin balance must be greater then or equal to 0 after trading;
      • Trader need to pay the trading fee as much as possible before all the margin balance drained.

Example

Here we take position = 1/-1, limitPrice = 4500, no referrer, user target leverage for example.
1
// execute trade(): open position with 1 leverage
2
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("1"), toWei("4500"), Math.floor(Date.now()/1000)+999999, NONE, 12800))
3
4
// execute trade(): close position with 1 leverage
5
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("-1"), toWei("3000"), Math.floor(Date.now()/1000)+999999, NONE, 12800))
6
7
// execute trade(): open position with 2 leverage
8
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("1"), toWei("4500"), Math.floor(Date.now()/1000)+999999, NONE, 25600))
9
10
// execute trade(): close position with 2 leverage
11
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("-1"), toWei("3000"), Math.floor(Date.now()/1000)+999999, NONE, 25600))
12
13
// execute trade(): open position without automatically deposit. make sure your marginAccount is safe.
14
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("1"), toWei("4500"), Math.floor(Date.now()/1000)+999999, NONE, 0))
15
16
// execute trade(): close position without automatically withdraw. make sure your marginAccount is safe.
17
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("-1"), toWei("3000"), Math.floor(Date.now()/1000)+999999, NONE, 0))
18
19
// execute trade(): market price with 1 leverage
20
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("1"), toWei("3000"), Math.floor(Date.now()/1000)+999999, NONE, 0x40000000+12800))
21
22
// execute trade(): close only. make sure you have position to close
23
await ensureFinished(liquidityPool.connect(signer).trade(0, signer.address, toWei("-1"), toWei("3000"), Math.floor(Date.now()/1000)+999999, NONE, 0x80000000+12800))
Copied!

Sample Code

Trade
Last modified 4d ago