맞춤형 매개 변수 유형

C#은 강력한 타입 언어이기 때문에, cBot, 지표 및 플러그인에서 변수와 클래스 속성을 선언할 때 데이터 유형을 지정해야 합니다. 반면, Python은 동적 타입 언어이므로 변수 유형이 자동으로 추론됩니다. 그러나 cTrader API를 사용하여 cBot을 개발할 때는 두 언어 간의 일관성을 위해 동일한 개념적 유형이 유지됩니다.

cTrader Algo API는 모든 데이터 유형을 맞춤형 매개 변수로 사용할 수 없으므로 알고리즘 개발자가 지원되는 유형을 이해하고 신중하게 탐색하는 것이 중요합니다.

참고

Python cBot, 지표 및 플러그인은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

매개변수 사용 사례 및 UI

cTrader는 아래 표에 반영된 주요 사용 사례 및 관련 UI 요소와 함께 이러한 매개변수 유형만 지원합니다.

C#	Python	사용 사례	UI 요소
`int`	`int`	주문 거래량, 바 수, 기간 수 등	숫자 입력 필드(스텝퍼 포함)
`double`	`float`	가격 값, 주문 거래량 등	숫자 입력 필드(스텝퍼 포함)
`string`	`str`	사용자 정의 메시지, 포지션 레이블 등	텍스트 입력 필드
`bool`	`bool`	보호 메커니즘, 트레이딩 허용, 이메일 허용 등	드롭다운 예/아니오
`DataSeries`	`api.DataSeries`	시장 가격 소스 등	드롭다운 목록
`TimeFrame`	`api.TimeFrame`	선택한 시간 프레임 등	기간 선택기
`enum`	`Enum`	차트 그림 정렬, 개별 위험 수준 등	드롭다운 목록
`Color`	`Color`	차트 그림, 기술 분석 도구의 색상, 사용자 정의 요소 등	색상 선택기
`DateTime`	`DateTime`	알고리즘 시간대에서 강력한 타입의 날짜 및 시간 가져오기	날짜 및 시간 선택기
`DateOnly`	`DateOnly`	강력한 타입의 날짜 가져오기	날짜 선택기
`TimeSpan`	`TimeSpan`	강력한 타입의 시간 간격 또는 하루 중 시간 가져오기	시간 선택기
`Symbol`	`Symbol`	강력한 타입의 단일 심볼 가져오기	심볼 선택기
`Symbol[]`	`Symbol[]`	강력한 타입의 여러 심볼을 배열로 가져오기	다중 심볼 선택기
`Enum[]`	`Enum[]`	강력한 타입의 여러 `Enum` 유형 값을 배열로 가져오기	다중 Enum 값 선택기
`TimeFrame[]`	`TimeFrame[]`	강력한 타입의 여러 `TimeFrame` 값을 배열로 가져오기	다중 기간 선택기

경고

cTrader 또는 Algo API의 이전 버전을 사용 중인 경우, 위의 일부 매개변수 유형을 사용할 수 없을 수 있습니다.

예를 들어, cTrader UI는 C#의 bool, double, int 및 Python의 bool, float, int 유형을 다음과 같이 반영합니다.

다음 세 가지 예제는 C#의 DataSeries, 사용자 정의 enum, string 및 Python의 api.DataSeries, Enum, str 데이터 유형을 보여줍니다(이 가이드에서 전체 코드도 제공합니다).

DataSeriesEnumString

아래와 같이, C#의 Color 및 Python의 Color 매개변수 유형은 색상 선택기로 표시됩니다.

마지막으로, C#의 TimeFrame 및 Python의 api.TimeFrame 데이터의 UI는 Trade 애플리케이션 내의 트레이딩 차트에서 사용 가능한 기간 옵션을 반영합니다.

cBot 예시

포지션 레이블은 다음 cBot에서 C#의 string 및 Python의 str 매개변수입니다.

C#Python

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo.Robots
{
    [Robot(AccessRights = AccessRights.None)]
    public class NewcBot2 : Robot
    {
        [Parameter(DefaultValue = "my label")]
        public string PositionLabel { get; set; }

        protected override void OnStart()
        {
            ExecuteMarketOrder(TradeType.Buy, "XAGUSD", 1000, PositionLabel);
        }

        protected override void OnStop()
        {
            var positionToFind = Positions.Find(PositionLabel);
            positionToFind.Close();
        }
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

import clr

clr.AddReference("cAlgo.API")

from cAlgo.API import *
from robot_wrapper import *


class NewcBot2():
    def on_start(self):
        api.ExecuteMarketOrder(TradeType.Buy, "XAGUSD", 1000, api.PositionLabel)

    def on_stop(self):
        position_to_find = api.Positions.Find(api.PositionLabel)
        if position_to_find is not None:
            position_to_find.Close()

아래 알고리즘에서 C#의 DataSeries, int, bool 및 Python의 api.DataSeries, int, bool 데이터 유형이 예시되어 있습니다.

C#Python

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo
{
    [Robot(TimeZone = TimeZones.UTC, AccessRights = AccessRights.None)]
    public class SamplecBotReferenceSMA : Robot
    {
        [Parameter("Source")]
        public DataSeries Source { get; set; }

        [Parameter("SMA Period", DefaultValue = 14)]
        public int SmaPeriod { get; set; }

        [Parameter("Enable Trade", DefaultValue = true)]
        public bool EnableTrade { get; set; }

        private SimpleMovingAverage sma;

        protected override void OnStart()
        {
            sma = Indicators.SimpleMovingAverage(Source, SmaPeriod);
        }

        protected override void OnTick()
        {
            double currentSMA = sma.Result.LastValue;
            double currentPrice = Symbol.Bid;

            if (EnableTrade)
            {
                if (currentPrice > currentSMA)
                {
                    ExecuteMarketOrder(TradeType.Buy, Symbol, 1000, "Buy Order");
                }
                else if (currentPrice < currentSMA)
                {
                    ExecuteMarketOrder(TradeType.Sell, Symbol, 1000, "Sell Order");
                }
            }

            Print("Current Price: {0}, Current SMA: {1}", currentPrice, currentSMA);
        }
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

import clr

clr.AddReference("cAlgo.API")

from cAlgo.API import *
from robot_wrapper import *


class SamplecBotReferenceSMA():
    def on_start(self):
        self.sma = api.Indicators.SimpleMovingAverage(api.Source, api.SmaPeriod)

    def on_tick(self):
        currentSMA = self.sma.Result.LastValue
        currentPrice = api.Symbol.Bid

        if api.EnableTrade:
            if currentPrice > currentSMA:
                api.ExecuteMarketOrder(TradeType.Buy, api.Symbol, 1000, "Buy Order")
            elif currentPrice < currentSMA:
                api.ExecuteMarketOrder(TradeType.Sell, api.Symbol, 1000, "Sell Order")

        api.Print("Current Price: {0}, Current SMA: {1}".format(currentPrice, currentSMA))

이 cBot은 차트 영역에서 텍스트 시각화를 정의하기 위해 Color를 매개변수로 사용합니다:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo.Robots
{
    [Robot(AccessRights = AccessRights.None)]
    public class NewcBot : Robot
    {
        [Parameter(DefaultValue = "Yellow")]
        public Color TextColor { get; set; }

        protected override void OnBar() 
        {
            Chart.DrawStaticText("static", "cBot running!", VerticalAlignment.Center, HorizontalAlignment.Left, TextColor);
        }
    }
}

아래 예시에서 C#의 double 및 Python의 float 데이터 유형은 주문 거래량을 로트 단위로 입력하는 매개변수로 사용됩니다. 이 cBot은 연속된 세 개의 빨간색 캔들 후에 매수 시장가 주문을 실행합니다.

C#Python

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo
{
    [Robot(TimeZone = TimeZones.UTC, AccessRights = AccessRights.None)]
    public class RedBarsBot : Robot
    {
        [Parameter("Order Volume (Lots)", DefaultValue = 0.1)]
        public double OrderVolume { get; set; }

        private int redBarsCount = 0;

        protected override void OnBar()
        {
            if (IsRedBar())
            {
                redBarsCount++;
                if (redBarsCount == 3)
                {
                    PlaceMarketOrder(TradeType.Buy);
                    redBarsCount = 0;
                }
            }
            else
            {
                redBarsCount = 0;
            }
        }

        private bool IsRedBar()
        {
            var currentBar = MarketSeries.Close.Last(1);
            var previousBar = MarketSeries.Close.Last(2);

            return currentBar < previousBar;
        }

        private void PlaceMarketOrder(TradeType tradeType)
        {
            var symbol = Symbol;
            var volume = Symbol.QuantityToVolume(OrderVolume);

            ExecuteMarketOrder(tradeType, symbol, volume);
        }
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

import clr

clr.AddReference("cAlgo.API")

from cAlgo.API import *
from robot_wrapper import *

class RedBarsBot():
    def __init__(self):
        self.redBarsCount = 0

    def on_bar(self):
        if self.is_red_bar():
            self.redBarsCount += 1
            if self.redBarsCount == 3:
                self.place_market_order(TradeType.Buy)
                self.redBarsCount = 0
        else:
            self.redBarsCount = 0

    def is_red_bar(self):
        currentBar = api.MarketSeries.Close.Last(1)
        previousBar = api.MarketSeries.Close.Last(2)
        return currentBar < previousBar

    def place_market_order(self, tradeType):
        symbol = api.Symbol
        volume = api.Symbol.QuantityToVolume(api.OrderVolume)
        api.ExecuteMarketOrder(tradeType, symbol, volume)

아래 예시에서 DateTime, DateOnly 및 TimeSpan 데이터 유형이 매개변수로 사용됩니다.

C#Python

using System;
using cAlgo.API;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class TimeParameters : Robot
{
    [Parameter("DateTime Parameter", MinValue = "1970-01-01T00:00:00", MaxValue = "2025-11-01T00:00:00", DefaultValue = "2025-01-01T10:00:00")]
    public DateTime DateTimeParameter { get; set; }

    [Parameter("DateOnly Parameter", MinValue = "1970-01-01", MaxValue = "2025-11-01", DefaultValue = "2025-01-01")]
    public DateOnly DateOnlyParameter { get; set; }

    [Parameter("TimeSpan Parameter", MinValue = "00:00:00", MaxValue = "23:59:59", DefaultValue = "04:10:20")]
    public TimeSpan TimeSpanParameter { get; set; }

    protected override void OnStart()
    {
        Print($"DateTimeParameter: {DateTimeParameter:o}");
        Print($"DateOnlyParameter: {DateOnlyParameter:o}");
        Print($"TimeSpanParameter: {TimeSpanParameter}");
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

using System;
using cAlgo.API;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class TimeParameters : Robot
{
    [Parameter("DateTime Parameter", MinValue = "1970-01-01T00:00:00", MaxValue = "2025-11-01T00:00:00", DefaultValue = "2025-01-01T10:00:00")]
    public DateTime DateTimeParameter { get; set; }

    [Parameter("DateOnly Parameter", MinValue = "1970-01-01", MaxValue = "2025-11-01", DefaultValue = "2025-01-01")]
    public DateOnly DateOnlyParameter { get; set; }

    [Parameter("TimeSpan Parameter", MinValue = "00:00:00", MaxValue = "23:59:59", DefaultValue = "04:10:20")]
    public TimeSpan TimeSpanParameter { get; set; }
}

Python cBot에서 매개 변수 사용:

import clr

clr.AddReference("cAlgo.API")

# Import cAlgo API types
from cAlgo.API import *

# Import trading wrapper functions
from robot_wrapper import *

class TimeParameters():
    def on_start(self):
        print(f"DateTimeParameter: {api.DateTimeParameter}")
        print(f"DateOnlyParameter: {api.DateOnlyParameter}")
        print(f"TimeSpanParameter: {api.TimeSpanParameter}")

참고

DateTime 매개변수 값은 사용자의 플랫폼 시간대에서 알고리즘 시간대로 자동 변환되며, 수동 변환이 필요하지 않습니다.

아래 예시에서 Symbol 데이터 유형이 매개변수로 사용됩니다.

C#Python

using System;
using cAlgo.API;
using cAlgo.API.Internals;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class SymbolParameterTest : Robot
{
    [Parameter("Symbol Parameter", DefaultValue = "EURUSD")]
    public Symbol SymbolParameter { get; set; }

    protected override void OnStart()
    {
        Print($"Symbol Bid Price is: {SymbolParameter.Bid}");
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

using System;
using cAlgo.API;
using cAlgo.API.Internals;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class SymbolParameterTest : Robot
{
    [Parameter("Symbol Parameter", DefaultValue = "EURUSD")]
    public Symbol SymbolParameter { get; set; }
}

Python cBot에서 매개 변수 사용:

import clr

clr.AddReference("cAlgo.API")

# Import cAlgo API types
from cAlgo.API import *

# Import trading wrapper functions
from robot_wrapper import *

class SymbolParameterTest():
    def on_start(self):
        print(f"Symbol Bid Price is: {api.SymbolParameter.Bid}")

아래 예시에서는 C# 배열 유형으로 표현되는 다중 Enum, Symbol 및 TimeFrame 매개변수 유형을 사용합니다.

C#Python

using System;
    using cAlgo.API;
using cAlgo.API.Internals;
using System.Linq;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class MultiValueParametersTest : Robot
{
    [Parameter(DefaultValue = "EURUSD,GBPUSD")]
    public Symbol[] SymbolsParameter { get; set; }

    [Parameter(DefaultValue = "Sell")]
    public TradeType[] TradeTypesParameter { get; set; }

    [Parameter(DefaultValue = "Daily,Hour")]
    public TimeFrame[] TimeFramesParameter { get; set; }

    protected override void OnStart()
    {
        Print($"Selected symbols are: {string.Join(", ", SymbolsParameter.Select(symbol => symbol.Name))}");
        Print($"Selected trade types are: {string.Join(", ", TradeTypesParameter.Select(tradeType => tradeType.ToString()))}");
        Print($"Selected time frames are: {string.Join(", ", TimeFramesParameter.Select(timeFrame => timeFrame.ToString()))}");
    }
}

참고

Python cBot은 .cs 파일에 선언된 맞춤형 매개 변수를 사용합니다.

using System;
using cAlgo.API;
using cAlgo.API.Internals;

namespace cAlgo.Robots;

[Robot(AccessRights = AccessRights.None)]
public class MultiValueParametersTest : Robot
{
    [Parameter(DefaultValue = "EURUSD,GBPUSD")]
    public Symbol[] SymbolsParameter { get; set; }

    [Parameter(DefaultValue = "Sell")]
    public TradeType[] TradeTypesParameter { get; set; }

    [Parameter(DefaultValue = "Daily,Hour")]
    public TimeFrame[] TimeFramesParameter { get; set; }
}

Python cBot에서 매개 변수 사용:

import clr

clr.AddReference("cAlgo.API")

# Import cAlgo API types
from cAlgo.API import *

# Import trading wrapper functions
from robot_wrapper import *

class MultiValueParametersTest():
    def on_start(self):
        print(f"Selected symbols are: {[symbol.Name for symbol in api.SymbolsParameter]}")
        print(f"Selected trade types are: {[str(tradeType) for tradeType in api.TradeTypesParameter]}")
        print(f"Selected time frames are: {[str(timeFrame) for timeFrame in api.TimeFramesParameter]}")

지표 예시

다음 지표 코드는 TimeFrame 매개변수가 어떻게 사용되는지 보여줍니다:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo
{
    [Indicator(AccessRights = AccessRights.None)]
    public class NewIndicator4 : Indicator
    {
        private Bars _hourlyTimeFrameBars;
        private Bars _targetTimeFrameBars;

        [Parameter("Chosen Time Frame")]
        public TimeFrame TargetTimeFrame { get; set; }

        [Output("Main")]
        public IndicatorDataSeries Result { get; set; }

        protected override void Initialize()
        {
            _hourlyTimeFrameBars = MarketData.GetBars(TimeFrame.Hour);
            _targetTimeFrameBars = MarketData.GetBars(TargetTimeFrame);
        }

        public override void Calculate(int index)
        {
            Result[index] = _hourlyTimeFrameBars.HighPrices[index] - _targetTimeFrameBars.HighPrices[index];
        }
    }
}

차트에 그려진 수평선의 색상을 사용자가 결정할 수 있도록 enum 색상 시야 옵션(예: 일반, 색맹, 그레이스케일)을 제공하는 재미있는(색맹 테스트) 지표가 있습니다.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo
{

    public enum ColorVision
    {
        Normal,
        Colorblind,
        Greyscale
    }

    [Indicator(AccessRights = AccessRights.None)]
    public class ColorblindTest : Indicator
    {

        [Parameter("Color Vision", DefaultValue = ColorVision.Normal)]
        public ColorVision ColorVision { get; set; }

        public override void Calculate(int index) {}

        protected override void Initialize()
        {

            Color lineColor = Color.Green;

            switch (ColorVision) 
            {
                case ColorVision.Normal:
                    lineColor = Color.Red;
                    break;
                case ColorVision.Colorblind:
                    lineColor = Color.Yellow;
                    break;
                case ColorVision.Greyscale:
                    lineColor = Color.White;
                    break;

            }

            var trendLine = Chart.DrawHorizontalLine("line", Bars.HighPrices.Maximum(10), lineColor);
        }

    }

}

요약하자면, 선언된 변수와 클래스 속성에 적절한 데이터 유형을 선택함으로써 비표준 작업도 처리할 수 있는 cBot 및 지표를 만들 수 있습니다.