Markets
Transactions

Market Transactions

The Market Transactions module provides methods for interacting with perpetual markets, including opening and closing positions, managing limit orders, and handling take profit/stop loss orders.

All methods return an InputEntryFunctionData object that can be used with an Aptos wallet for transaction submission.

All inputs except keeper methods designed to be called on behalf of users must be signed by the owner of the relevant Position/LimitOrder/TpSl object.

Position Management

createPosition

Creates a new position with an order in a single transaction. Supports market orders with TPSL, and limit/stop orders.

type CreatePositionOptionals = {
  takeProfit?: number // optional, only for market orders
  stopLoss?: number // optional, only for market orders
  expiration?: bigint // optional, only for limit/stop orders
}
 
async getCreatePositionWithOrderPayload(
  perpSymbol: string,
  marginSymbol: string,
  orderType: OrderType,
  marginAmount: number,
  positionSize: number,
  side: PositionSide,
  desiredPrice: number,
  maxPriceSlippage: number,
  createPositionOptionals?: CreatePositionOptionals
): Promise<InputEntryFunctionData>

Example with Market Order and TPSL:

const txPayload = await mirageClient.market.transactions.getCreatePositionWithOrderPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  OrderType.MARKET,
  1000,           // 1000 mUSD margin
  0.1,            // 0.1 BTC position
  PositionSide.LONG,
  100000,         // $100,000 entry price
  100,            // $100 max slippage
  {
    takeProfit: 110000,  // Optional take profit at $110,000
    stopLoss: 95000      // Optional stop loss at $95,000
  }
)
await wallet.signAndSubmitTransaction(txPayload)

Example with Limit Order:

const txPayload = await mirageClient.market.transactions.getCreatePositionWithOrderPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  OrderType.LIMIT,
  1000,           // 1000 mUSD margin
  0.1,            // 0.1 BTC position
  PositionSide.LONG,
  98000,          // Trigger at $98,000
  100,            // $100 max slippage
  {
    expiration: BigInt(1698793200) // Optional expiration timestamp
  }
)
await wallet.signAndSubmitTransaction(txPayload)

placeOrder

Places an order for an existing position.

async getPlaceOrderPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  orderType: OrderType,
  marginAmount: number,
  positionSize: number,
  side: PositionSide,
  desiredPrice: number,
  maxPriceSlippage: number,
  expiration?: bigint
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getPlaceOrderPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  OrderType.MARKET,
  1000,           // 1000 mUSD margin
  0.1,            // 0.1 BTC position
  PositionSide.LONG,
  100000,         // $100,000 entry price
  100             // $100 max slippage
)
await wallet.signAndSubmitTransaction(txPayload)

closePosition

Closes an existing position. All margin +- PnL/fees will be returned to the position owner.

async getClosePositionPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getClosePositionPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123..."      // Position object address
)
await wallet.signAndSubmitTransaction(txPayload)

Position Size Management

increasePositionSize

Increases the size of an existing position while maintaining the same margin.

async getIncreasePositionSizePayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  positionSizeIncrease: number
): Promise<InputEntryFunctionData>

Example:

// Add 0.1 BTC to position size
const txPayload = await mirageClient.market.transactions.getIncreasePositionSizePayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.1             // Add 0.1 BTC to position
)
await wallet.signAndSubmitTransaction(txPayload)

decreasePositionSize

Decreases the size of an existing position while maintaining the same margin.

async getDecreasePositionSizePayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  decreasePositionSize: number
): Promise<InputEntryFunctionData>

Example:

// Remove 0.05 BTC from position size
const txPayload = await mirageClient.market.transactions.getDecreasePositionSizePayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.05            // Remove 0.05 BTC from position
)
await wallet.signAndSubmitTransaction(txPayload)

Margin Management

increaseMargin

Adds additional margin to an existing position.

async getIncreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  increaseMarginAmount: number
): Promise<InputEntryFunctionData>

Example:

// Add 1000 mUSD margin to position
const txPayload = await mirageClient.market.transactions.getIncreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  1000            // Add 1000 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

decreaseMargin

Removes margin from an existing position.

async getDecreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  decreaseMarginAmount: number
): Promise<InputEntryFunctionData>

Example:

// Remove 500 mUSD margin from position
const txPayload = await mirageClient.market.transactions.getDecreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  500             // Remove 500 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

updateMargin

Updates the margin amount of an existing position.

async getUpdateMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  oldMarginAmount: number,
  newMarginAmount: number
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getUpdateMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  1000,           // Current margin of 1000 mUSD
  1500            // New margin of 1500 mUSD
)
await wallet.signAndSubmitTransaction(txPayload)

Combined Size and Margin Management

increaseSizeAndIncreaseMargin

Increases both the position size and margin amount simultaneously.

async getIncreaseSizeAndIncreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  positionSizeIncrease: number,
  marginAmountIncrease: number
): Promise<InputEntryFunctionData>

Example:

// For a BTCPERP-mUSD position, increase size by 0.1 BTC and add 1000 mUSD margin
const txPayload = await mirageClient.market.transactions.getIncreaseSizeAndIncreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.1,            // Add 0.1 BTC to position
  1000            // Add 1000 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

increaseSizeAndDecreaseMargin

Increases position size while simultaneously decreasing margin, effectively increasing leverage.

async getIncreaseSizeAndDecreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  positionSizeIncrease: number,
  marginAmountDecrease: number
): Promise<InputEntryFunctionData>

Example:

// Increase position by 0.1 BTC while removing 500 mUSD margin
const txPayload = await mirageClient.market.transactions.getIncreaseSizeAndDecreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.1,            // Add 0.1 BTC to position
  500             // Remove 500 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

decreaseSizeAndDecreaseMargin

Decreases both position size and margin amount proportionally.

async getDecreaseSizeAndDecreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  positionSizeDecrease: number,
  marginAmountDecrease: number
): Promise<InputEntryFunctionData>

Example:

// Decrease position by 0.05 BTC and remove 500 mUSD margin
const txPayload = await mirageClient.market.transactions.getDecreaseSizeAndDecreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.05,           // Remove 0.05 BTC from position
  500             // Remove 500 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

decreaseSizeAndIncreaseMargin

Decreases position size while adding margin, effectively decreasing leverage.

async getDecreaseSizeAndIncreaseMarginPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  positionSizeDecrease: number,
  marginAmountIncrease: number
): Promise<InputEntryFunctionData>

Example:

// Decrease position by 0.05 BTC but add 1000 mUSD margin
const txPayload = await mirageClient.market.transactions.getDecreaseSizeAndIncreaseMarginPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position object address
  0.05,           // Remove 0.05 BTC from position
  1000            // Add 1000 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

Limit Orders

updateLimitOrder

Updates parameters of an existing limit order.

async getUpdateLimitOrderPayload(
  perpSymbol: string,
  marginSymbol: string,
  limitOrderObjectAddress: MoveObjectType,
  newPositionSize: number,
  newSide: PositionSide,
  newTriggerPrice: number,
  newMaxPriceSlippage: number,
  newIsDecreaseOnly: boolean,
  newTriggersAbove: boolean,
  newExpiration: bigint
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getUpdateLimitOrderPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Limit order address
  0.15,           // New position size of 0.15 BTC
  PositionSide.LONG,
  98000,          // New trigger price of $98,000
  100,            // $100 max slippage
  false,          // Not decrease-only
  true,           // Trigger above price
  BigInt(1698793200) // New expiration timestamp
)
await wallet.signAndSubmitTransaction(txPayload)

cancelLimitOrder

Cancels an existing limit order.

getCancelLimitOrderPayload(
  limitOrderObjectAddress: MoveObjectType
): InputEntryFunctionData

Example:

const txPayload = mirageClient.market.transactions.getCancelLimitOrderPayload(
  "0x123..."      // Limit order address
)
await wallet.signAndSubmitTransaction(txPayload)

cleanupLimitOrder

Cleans up a limit order object after the associated position has been closed or liquidated, recovering gas costs.

getCleanupLimitOrderPayload(
  limitOrderObjectAddress: MoveObjectType
): InputEntryFunctionData

Example:

const txPayload = mirageClient.market.transactions.getCleanupLimitOrderPayload(
  "0x123..."      // Limit order object address
)
await wallet.signAndSubmitTransaction(txPayload)

Limit Order Margin Management

increaseLimitOrderMargin

Adds margin to a pending limit order.

async getIncreaseLimitOrderMarginPayload(
  limitOrderObjectAddress: MoveObjectType,
  marginIncrease: number
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getIncreaseLimitOrderMarginPayload(
  "0x123...",     // Limit order address
  1000            // Add 1000 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

decreaseLimitOrderMargin

Removes margin from a pending limit order.

async getDecreaseLimitOrderMarginPayload(
  limitOrderObjectAddress: MoveObjectType,
  marginDecrease: number
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getDecreaseLimitOrderMarginPayload(
  "0x123...",     // Limit order address
  500             // Remove 500 mUSD margin
)
await wallet.signAndSubmitTransaction(txPayload)

Take Profit / Stop Loss

placeTpsl

Places take-profit and stop-loss orders for a position.

async getPlaceTpslPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  takeProfitPrice: number,
  stopLossPrice: number
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getPlaceTpslPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position address
  110000,         // Take profit at $110,000
  95000           // Stop loss at $95,000
)
await wallet.signAndSubmitTransaction(txPayload)

updateTpsl

Updates existing take-profit and stop-loss orders.

async getUpdateTpslPayload(
  perpSymbol: string,
  marginSymbol: string,
  tpslObjectAddress: MoveObjectType,
  takeProfitPrice: number,
  stopLossPrice: number
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getUpdateTpslPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // TPSL order address
  112000,         // New take profit at $112,000
  94000           // New stop loss at $94,000
)
await wallet.signAndSubmitTransaction(txPayload)

cancelTpsl

Cancels existing take-profit and stop-loss orders.

async getCancelTpslPayload(
  tpslObjectAddress: MoveObjectType
): Promise<InputEntryFunctionData>

Example:

const txPayload = await mirageClient.market.transactions.getCancelTpslPayload(
  "0x123..."      // TPSL order address
)
await wallet.signAndSubmitTransaction(txPayload)

cleanupTpsl

Cleans up a TPSL object after execution or cancellation, recovering gas costs.

getCleanupTpslPayload(
  tpslObjectAddress: MoveObjectType
): InputEntryFunctionData

Example:

const txPayload = mirageClient.market.transactions.getCleanupTpslPayload(
  "0x123..."      // TPSL object address
)
await wallet.signAndSubmitTransaction(txPayload)

Keeper Functions

Keeper functions are used to enforce protocol rules and maintain system health. They can be called by anyone when certain conditions are met.

triggerLimitOrder

Executes a limit order when the market price meets the trigger conditions. The triggerer receives a reward for executing the order.

async getTriggerLimitOrderPayload(
  perpSymbol: string,
  marginSymbol: string,
  limitOrderObjectAddress: MoveObjectType,
  triggererAddress: string
): Promise<InputEntryFunctionData>

Example:

// Trigger a limit order when conditions are met
const txPayload = await mirageClient.market.transactions.getTriggerLimitOrderPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Limit order address
  "0x789..."      // Keeper address that will receive the reward
)
await wallet.signAndSubmitTransaction(txPayload)

triggerTpsl

Executes a take-profit or stop-loss order when the price conditions are met. The triggerer receives a reward for execution.

async getTriggerTpslPayload(
  perpSymbol: string,
  marginSymbol: string,
  tpslObjectAddress: MoveObjectType,
  triggererAddress: string
): Promise<InputEntryFunctionData>

Example:

// Trigger a TPSL order when conditions are met
const txPayload = await mirageClient.market.transactions.getTriggerTpslPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // TPSL order address
  "0x789..."      // Keeper address that will receive the reward
)
await wallet.signAndSubmitTransaction(txPayload)

liquidatePosition

Liquidates a position when it becomes under-collateralized. The triggerer receives a reward for performing the liquidation.

async getLiquidatePositionPayload(
  perpSymbol: string,
  marginSymbol: string,
  positionObjectAddress: MoveObjectType,
  triggererAddress: string
): Promise<InputEntryFunctionData>

Example:

// Liquidate an under-collateralized position
const txPayload = await mirageClient.market.transactions.getLiquidatePositionPayload(
  "BTCPERP",      // Perpetual symbol
  "mUSD",         // Margin symbol
  "0x123...",     // Position address
  "0x789..."      // Keeper address that will receive the reward
)
await wallet.signAndSubmitTransaction(txPayload)
QueriesUtilities