Open Position

The openPosition function allows users to open a new position in the perpetual futures market.

Function Signature

openPosition(
  collateralToken: string,
  indexToken: string,
  leverage: number,
  collateral: number,
  positionConfig: IPositionConfig,
  coinObjects: string[],
  long: boolean,
  indexPrice: number,
  collateralPrice: number,
  pricesSlippage: number = 0.003,
  collateralSlippage: number = 0.5,
  isLimitOrder: boolean = false,
  isIocOrder: boolean = false,
  relayerFee: bigint = BigInt(1)
): Promise<Transaction>

Parameters

• collateralToken (string): The token used as collateral for the position

• indexToken (string): The token being traded

• leverage (number): The leverage multiplier for the position

• collateral (number): The amount of collateral to be used

• positionConfig (IPositionConfig): Configuration object for the position

• coinObjects (string[]): Array of coin object IDs to be used

• long (boolean): Whether this is a long (true) or short (false) position

• indexPrice (number): The market price or limit price of the index token. Refer to subOraclePrices on how you can get the token prices via Pyth using our provided API with a working example.

Note: For market order, the index price parameter will not be used. The smart contract internally will use Pyth to get the current index price. For limit order, the index price parameter will be used and set as the limited order price when the order is executed.

• collateralPrice (number): The market price of the collateral token. Refer to subOraclePrices on how you can get the token prices via Pyth using our provided API with a working example.

• pricesSlippage (number, default: 0.003): Maximum allowed slippage for prices

• collateralSlippage (number, default: 0.5): Maximum allowed slippage for collateral

• isLimitOrder (boolean, default: false): Whether this is a limit order

• isIocOrder (boolean, default: false): Whether this is an Immediate-or-Cancel order

Note: This parameter is currently a placeholder.

• relayerFee (bigint, default: BigInt(1)): Fee paid to the relayer

Returns

Promise<Transaction>: A promise that resolves to a transaction object.

Usage Example

const tx = await sudoAPI.openPosition(
  'USDC',           // collateralToken
  'SUI',            // indexToken
  5,                // 5x leverage
  1000,             // 1000 USDC as collateral
  myPositionConfig, // check getPositionConfig API
  ['0x123...', '0x456...'], // coinObjects
  true,             // long position
  2,                // indexPrice (SUI price in USD)
  1,                // collateralPrice (USDC price in USD)
  0.001,            // pricesSlippage (0.1%)
  0.1,              // collateralSlippage (10%)
  false,            // not a limit order
  false,            // not an IOC order
  BigInt(2)         // relayerFee
);

Notes

• Ensure you have sufficient balance and have approved the necessary permissions before calling this function.

• The function uses the current oracle prices for the tokens. Ensure your frontend is updated with the latest prices before calling this function.

• The pricesSlippage and collateralSlippage parameters allow you to control the maximum allowed price movement. Adjust these based on market volatility and your risk tolerance.

• For limit orders, set isLimitOrder to true.

• The relayerFee is paid in SUI. Adjust this value based on the current network conditions and relayer requirements.

Error Handling

This function may throw errors if:

• The input parameters are invalid

• There's insufficient balance

• The slippage tolerance is exceeded

• The position size is outside allowed limits

Always wrap the function call in a try-catch block and handle potential errors appropriately in your application.