Skip to main content

Open position

Overview​

Opening a position allows users to enter into a trading position within a specific ChromaticMarket contract. The openPosition function facilitates the creation of a new position by specifying various parameters such as market, quantity, leverage, margin amounts and maximum allowable trading fee.

ChromaticRouter Interface​

The IChromaticRouter interface serves as the primary interface for interacting with the ChromaticRouter contract. It provides access to the openPosition function, enabling users to open new positions.

interface IChromaticRouter {
    /**
     * @dev Opens a new position in a ChromaticMarket contract.
     * @param market The address of the ChromaticMarket contract.
     * @param qty The quantity of the position.
     * @param leverage The leverage of the position.
     * @param takerMargin The margin amount for the taker.
     * @param makerMargin The margin amount for the maker.
     * @param maxAllowableTradingFee The maximum allowable trading fee.
     * @return position The new position.
     */
    function openPosition(
        address market,
        int224 qty,
        uint32 leverage,
        uint256 takerMargin,
        uint256 makerMargin,
        uint256 maxAllowableTradingFee
    ) external returns (Position memory);
}

Position Parameters​

The openPosition function requires several parameters to define the characteristics of the position being opened:

  • market: The address of the ChromaticMarket contract in which the position will be opened.
  • qty: The quantity of the position. This value can be positive for long positions or negative for short positions.
  • leverage: The leverage to be applied to the position. Leverage determines the position's exposure to price movements.
  • takerMargin: The margin amount reserved for the taker (the trader initiating the position).
  • makerMargin: The margin amount reserved for the maker (the counterparty providing liquidity to the position).
  • maxAllowableTradingFee: The maximum allowable trading fee that can be charged for the position.

Account Requirements​

Before opening a position, it is essential to ensure that the user's account has sufficient settlement tokens specific to the market where the position is being opened. The settlement token is the currency used for settling trades within each ChromaticMarket contract. Users need to transfer an appropriate amount of the specific market's settlement tokens to their account address before initiating the openPosition function call.

To deposit settlement tokens into the account, users can utilize the token's transfer function, specifying their account address as the recipient. This transfer operation ensures that the account has an adequate settlement token balance to meet the taker margin and trading fee requirements of the specific market.

Entry Price Determination​

When a position is opened, it enters a pending state along with the current oracle version information. The entry price of the position is determined by the price feed of the next oracle version. The Chromatic Protocol saves the position details, including the current oracle version, and waits for the next oracle version's price feed update. Once the next oracle version updates the price feed, the entry price of the position is set based on the new price, reflecting the most up-to-date market conditions.

Opening a Position​

To open a position, users need to call the openPosition function of the ChromaticRouter contract, providing the required parameters as described above. It is crucial to ensure that the user's account has sufficient settlement token balance for the specific market to cover the taker margin and trading fee requirements.

Upon successful execution of the openPosition function, a Position object representing the newly opened position is returned.