ABI Interaction

Here you can find information on how to interact with our contracts directly

Introduction

KTX.Finance operates as a decentralised perpetual exchange, where all functions are publicly accessible through corresponding RPCs. This guide provides insights on how to interact directly with the smart contracts responsible for executing trading functions on KTX.Finance.

Opening a Trade – Market and Limit Orders (Arbitrum / Mantle)

Open a position and/or set limit orders within the same transaction.

Find ABI of ComplexOrderRouter.sol on corresponding chains:

  • Call createComplexOrder with following parameters:

    • _path(address[]):

      • [collateralToken] or [tokenIn, collateralToken] if a swap is needed

      • without swap:

        • for long orders, collateral token must be the same as index token

        • for short orders, collateral token must be stable token

        • e.g.

          • long BTC with BTC as collateral, _path = ["BTC address"]

          • long ETH with ETH as collateral, _path = ["ETH address"]

          • short BTC with USDT as collateral, _path = ["USDT address"]

      • with swap:

        • tokenIn will be swapped into collateralToken before creates position. This is not recommended as swap fee applies

      • required field

    • _amountIn(uint256):

      • collateral token amount

      • always fill in amount of token as in collateral token, e.g.

        • if _path = ["ETH address"], 3*10^18 means 3 ETH

        • if _path = ["USDT address", "ETH address"], 3*10^6 means 3 USDT because USDT has 6 decimals

      • required field

    • _minOut(uint256):

      • swap minimum out

      • 0 if no swap required

      • required field

    • _isLong(bool):

      • true: long order

      • false: short order

      • required field

    • _referralCode(bytes32):

      • depreciated, fill in 0x0000000000000000000000000000000000000000000000000000000000000000

      • required field

    • _sizeDelta(uint256[]):

      • _sizeDelta[0]: position size

      • _sizeDelta[1]:

        • decrease position size when take profit happens

        • normally _sizeDelta[1] = _sizeDelta[0], because you may want to close the entire position when take profit happens

        • 0 if you do not want to create take profit order

      • _sizeDelta[2]:

        • decrease position size when stop loss happens

        • normally _sizeDelta[2] = _sizeDelta[0], because you may want to close the entire position when stop loss happens

        • 0 if you do not want to create stop loss order

      • leverage = _sizeDelta[0]/_amountIn, and please keep leverage at 2 - 100 to avoid unexpected liquidation.

      • e.g.

        • [6**10^18, 0, 0]* for ETH means you simply want to open a position with size = 3ETH

        • [610^18, 610^18, 6*10^18] for ETH means you want to open a position with size = 3ETH and fully close it when take profit or stop loss order happens.

    • _price(uint256[]):

      • _price[0]: acceptable price for position increase

        • 30 decimal precision (1*10^30 means price at $1)

        • price is changing every moment and we use this price as your acceptable price, normally you can calculate this price using: current_mark_price * (1 - acceptable_slippage) for long order and current_mark_price * (1 + acceptable_slippage) for short order. KTX by default uses 0.3% as acceptable_slippage on our website.

        • _price[1]:

          • trigger price for take profit order

          • for long order, take profit price must be greater than _price[0]

          • for short order, take profit price must be smaller than _price[0]

          • 0 if you do not want to create take profit order

        • _price[2]:

          • trigger price for stop loss order

          • for long order, stop loss price must be smaller than _price[0]

          • for short order, stop loss price must be greater than _price[0]

          • 0 if you do not want to create stop loss order

    • _token(address[]):

      • _token[0]:

        • index token

      • _token[1]:

        • take-back token when take profit happens

      • _token[2]:

        • take-back token when stop loss happens

      • normally _token[0] = _token[1] = _token[2] to avoid swap fees

      • e.g.["ETH address", "ETH address", "ETH address"] for creating long ETH position

    • _executionFee(uint256[]):

      • _executionFee[0]:

        • 10^17 for mantle, 2*10^14 for arbitrum

      • _executionFee[1]:

        • for take profit order

        • 10^17 for mantle, 2*10^14 for arbitrum

        • 0 if you do not want to create take profit order

      • _executionFee[2]:

        • for stop loss order

        • 10^17 for mantle, 2*10^14 for arbitrum

        • 0 if you do not want to create stop loss order

    • value: value of this transaction

      • if order contains both take profit and stop loss order:

        • 310^17 for mantle, 610^14 for arbitrum

      • if order contains one of take profit or stop loss order:

        • 210^17 for mantle, 410^14 for arbitrum

      • if order has no take profit or stop loss order:

        • 10^17 for mantle, 2*10^14 for arbitrum

  • After this transaction is sent a keeper will execute the request, the request will either be executed or cancelled

  • If the position cannot be increased for reasons such as the _acceptablePrice not being fulfillable then the value will be refunded to user

Closing / Decreasing a Position

Find ABI of PositionRouter.sol on corresponding chains:

  • Arbitrum

  • Mantle

  • Call PositionRouter.createDecreasePosition with parameters:

    • _path(address[]):

      • [collateralToken] or [collateralToken, tokenOut] if a swap is needed

    • _indexToken:

      • the index token of the position

    • _collateralDelta:

      • the amount of collateral in USD value to withdraw

    • _sizeDelta:

      • the USD value of the change in position size

    • _isLong:

      • whether the position is a long or short

    • _receiver:

      • the address to receive the withdrawn tokens

    • _acceptablePrice:

      • the USD value of the min (for longs) or max (for shorts) index price acceptable when executing the request

    • _minOut:

      • the min output token amount

      • set to 0 if no swap is required

    • _executionFee:

      • 10^17 for mantle, 2*10^14 for arbitrum

    • _withdrawETH:

      • only applicable if WETH will be withdrawn, the WETH will be unwrapped to ETH if this is set to true

    • _callbackTarget:

      • an optional callback contract, this contract will be called on request execution or cancellation

  • After this transaction is sent a keeper will execute the request, the request will either be executed or cancelled

  • If the position cannot be decreased for reasons such as the _acceptablePrice not being fulfillable then the request will be cancelled and there will be no change to the position

Finding your Open Trades

Fetch open trades through subgraph query.

Request URL:

Request body:

query MyQuery {

activePositions(

orderBy: timestamp

orderDirection: desc

where: {status: "active", account: "your_address_in_lower_case"}

) {

		account
		
		collateral
		
		collateralToken
		
		isLong
		
		size
		
		timestamp
		
		indexToken
		
		averagePrice
	
	}

}

Finding your Limit Orders

Fetch open limit orders through subgraph query.

Request URL:

Request body:

query MyQuery {

orders(

where: {status: open, account: "your_address_in_lower_case"}

orderBy: createdTimestamp

orderDirection: desc

) {

		account
		
		status
		
		type
		
		triggerPrice
		
		triggerAboveThreshold
		
		size
		
		isLong
		
		indexToken
		
		index
		
		id
		
		createdTimestamp
		
		}

}

Swap

Find ABI of Router.sol on corresponding chains:

To execute a swap:

  • Approve the Router contract for the token and amount you would like to swap

  • Call Router.swap with parameters:

    • _path: [tokenIn, tokenOut]

    • _amountIn: amount of tokenIn to swap

    • _minOut: minimum expected output amount

    • _receiver: address of the receiver of tokenOut

  • The function will revert if the amount of tokenOut sent to the receiver is less than _minOut

To get swap amounts before execution:

  • Call Reader.getMaxAmountIn with parameters:

    • _vault: address of the vault

    • _tokenIn: address of token that will be given

    • _tokenOut: address of token to be received

  • The max amount of tokenIn that can be swapped will be returned

  • Call Reader.getAmountOut with parameters:

    • _vault: address of the vault

    • _tokenIn: address of token that will be given

    • _tokenOut: address of token to be received

    • _amountIn: amount of tokenIn to swap

  • Two values will be returned, the first is the amount out after fees, and the second is the fee amount

  • The fee amount will be in terms of tokenOut

PreviousPrice OraclesNextSecurity Audits

Last updated