Skip to content
Log inRegister

Algorithm SDK

openPosition

Opens a position at the market on the instrument your algorithm runs on, or on another instrument.

Trading on margin can lose you more than you put in. Past results, including backtests, do not predict future results. Cloud9Trader provides tools and education, not financial advice.

declare function openPosition(side: Side, options: OpenPositionOptions): void;
declare function openPosition(instrument: InstrumentAPI | string, side: Side, options: OpenPositionOptions): void;


interface OpenPositionOptions {
    /** Size in units of the base currency. */
    quantity?: number;
    /** Size in lots of 100,000 units. */
    lots?: number;
    /** Size worked out so that hitting the stop loses this percentage of your equity. */
    riskPercentage?: number;
    /** Size worked out so that hitting the stop loses this amount of your account currency. */
    riskAmount?: number;
    /** Stop-loss price. */
    stopLoss?: number;
    /** Stop-loss distance in pips. */
    stopLossPips?: number;
    /** Trailing-stop price. */
    trailingStop?: number;
    /** Trailing-stop distance in pips. */
    trailingStopPips?: number;
    /** Take-profit price. */
    takeProfit?: number;
    /** Take-profit distance in pips. */
    takeProfitPips?: number;
}


type Side = "BUY" | "SELL" | "LONG" | "SHORT";

Parameters

Section titled “Parameters”
  • side: "BUY" or "LONG" buys at the ask and opens a long position; "SELL" or "SHORT" sells at the bid and opens a short one.
  • instrument (second form): an entry of INSTRUMENTS or its identifier as a literal string, such as "EUR_USD:OANDA". INSTRUMENTS["EUR_USD:OANDA"].openPosition(side, options) does the same.
  • options: give exactly one size and any of the exits.
Option Meaning
quantity Size in units of the base currency. 10,000 on EUR/USD buys or sells €10,000.
lots Size in lots of 100,000 units.
riskPercentage Size worked out so that hitting your stop loses about this percentage of your equity. Needs a stop.
riskAmount Size worked out so that hitting your stop loses about this amount of your account currency. Needs a stop.
stopLoss or stopLossPips Close the position if the price moves against you to this price, or this many pips.
trailingStop or trailingStopPips A stop that follows the price as it moves in your favour.
takeProfit or takeProfitPips Close the position at this price, or this many pips in your favour.

Pips are measured from the price the position opens at: below the ask for a long stop, above the bid for a short one. A risk-based size is approximate: slippage, and the conversion rate when your account currency is not the quote currency, move the result.

Returns

Section titled “Returns”

Nothing. The order goes to your broker, or the backtest’s simulated broker, and the position appears in OPEN_POSITIONS once it is filled.

Errors

Section titled “Errors”

The order is rejected, and the reason logged, when:

  • no size is given: “Must set position size as one of quantity, lots, riskPercentage or riskAmount”;
  • two sizes are given: “Ambiguous position size: Specify either quantity, lots, riskPercentage or riskAmount”;
  • a risk-based size has no stop: “Must specify stopLoss or trailingStop if amount expressed as riskPercentage or riskAmout”;
  • an option is not one of those above: “Key not recognised: ‘amount’”.

The run stops if it asks for 50 positions within one minute (“Aborted due to unsafe volume of positions requested: 50 in under a minute”) or more than 500 in all (“Aborted after max positions limit reached (500 per session)”). At ten requests within a minute it logs a warning.

Example

Section titled “Example”
function onIntervalClose() {
  if (OPEN_POSITIONS_COUNT > 0) return;


  if (sma(20) > sma(50)) {
    openPosition("BUY", { riskPercentage: 1, stopLossPips: 25, takeProfitPips: 50 });
  } else {
    openPosition("EUR_USD:OANDA", "SELL", { lots: 0.1, stopLoss: ASK + 0.0015, trailingStopPips: 20 });
  }
}
Section titled “Related”