Trading Contracts

Details how to interact with trading contracts

To interact with trading contracts, you should call the respective methods on the GNSMultiCollatDiamond contract. Each method within the facets can be accessed through this central contract, ensuring a streamlined approach to contract interactions. You can find network-specific GNSMultiCollatDiamond address in Active Contracts page

Addresses

For latest addresses, refer to: Active Contracts:

If you are using testnet, the Arbitrum Sepolia address for GNSMultiCollatDiamond is: 0xd659a15812064C79E189fd950A189b15c75d3186

Interactions

Below is a list of available actions, consisting of market & limit orders, as well as updates. Where possible, NatSpec documentation is linked to. For full reference, see Technical Reference.

  • Place a trade*

  • Place a limit order

  • Update a trade

  • Update a limit order

  • Cancel a limit order

  • Close a trade*

  • Update leverage (decrease/increase)

  • Increase position size

  • Decrease position size

*Requires order fulfillment. Integrators make requests, and oracles fulfill them.

Place a Trade

Place a trade using the following functions. Use tradeType = 0.

If an order hasn't been fulfilled in 60 seconds, collateral can be claimed back using the timeout function:

Place a Limit Order

Same as market order, but provided tradeType of 1 or 2.

Limit: To be used when you want to go long at a lower price than present, or to go short if the price reaches a higher price than present. Executes at exact price set if price reaches threshold + spread.

Stop: To be used when you want to go long if the price reaches a higher price than present, or to go short if the price reaches a lower price than present. You might want to use this to long a breakout, or short a breakdown. The execution price is the current market price + spread.

Update Active Trade

Support updating take profit (TP) and stop loss (SL).

Update Pending Limit Order

If a limit order hasn't been fulfilled yet, it can be updated

Cancel Pending Limit Order

If a limit order hasn't been fulfilled yet, it can be canceled

Close a Trade

Market close a trade

If the trade hasn't been closed in 60 seconds, a timeout may be initiated, allowing for another close attempt:

Update Leverage

Update leverage for a trade

Update Position Size

Decrease position size (by decreasing collateral amount or leverage)

Increase position size (by increasing collateral amount or leverage or both)

Events

Events are emitted to allow off-chain services to stay updated. You can subscribe to these directly, or review the Backendpage for instructions on receiving from a WebSocket stream. It is recommended to use the backend.

Core Events

For opening or closing a trade: MarketOrderInitiated -> MarketExecuted

For placing a limit order: OpenOrderPlaced

For updating a trade: TradeSlUpdated or TradeTpUpdated

For fulfilling a limit order (SL, TP, Open limit): LimitExecuted

For updating leverage: LeverageUpdateInitiated-> LeverageUpdateExecuted

For updating position size (increase): PositionSizeUpdateInitiated-> PositionSizeIncreaseExecuted

For updating position size (decrease): PositionSizeUpdateInitiated-> PositionSizeDeccreaseExecuted

All Lifecycle Events

Last updated