Instruments

The term "instrument" denotes a tradable value such as a stock, ETF, future etc.

An instrument has various properties that can be used in AgenaScripts created by the user:

Instrument.Compare

Instrument.Currency

Instrument.Digits

Instrument.ETF

Instrument.Exchange

Instrument.Expiry

Instrument.GetCurrencyFactor

Instrument.InstrumentType

Instrument.MainSector

Instrument.Margin

Instrument.Name

Instrument.PointValue

Instrument.Round2TickSize

Instrument.Symbol

Instrument.TickSize

With the OnCalculate() method you can use any properties you wish without having to test for a null reference. As soon as the OnCalculate() function is called up by AgenaScript, an object will become available. If you wish to use these properties outside of OnCalculate(), you should first perform a test for null references using if (Bars != null)

Instrument.Compare

Description

The Instrument.Compare function compares two market prices whilst taking into account the correct number of decimal points. The smallest possible price change is displayed by the value TickSize. This function simplifies the otherwise time-consuming comparison using floating-point operations.

Parameter

double value1 double value2

Return value

Type int

1 - value1 is bigger than value2 -1 - value1 is smaller than value2 0 - value1 and value2 are equal

Usage

Instrument.Compare(double Value1, double Value2)

More Information

Be aware this function compares prices based on TickSize. If the ticksize of your instrument is 0.01 these prices will be rounded and compared on 2 decimal digits. If you want a regular comparation of two numbers, you should use the operator "greater than" (>) or the operator "smaller than" (<).

More infomation about math.round()

If the tick size is 0,00001 – as it usually is with FX values – then the following will be displayed:

Compare(2, 1.99999) a 1, meaning 2 is bigger than 1.99999 Compare(2, 2.000001) a 0, meaning the values are equal Compare(2, 1.999999) a 0, meaning the values are equal Compare(2, 2.00001) a -1, meaning 2 is smaller than 2.00001

Example

Print(Instrument.Compare(2, 1.999999));

Instrument.Currency

Description

Instrument.Currency outputs a currency object that contains the corresponding currency in which the instrument is traded.

Parameter

None

Return Value

A constant of the type "public enum currencies"

Usage

Instrument.Currency

More Information

The common currencies are: AUD, CAD, EUR, GBP, JPY or USD.

Example

Print(Instrument.Name + " is traded in " + Instrument.Currency);

Instrument.Digits

Description

Instrument.Digits outputs the number of decimal points in which the market price of the instrument is traded.

Parameter

none

Return Value

int Digits

Usage

Instrument.Digits

More Information

Stocks are usually traded to two decimal points. Forex can be traded (depending on the data provider) with 4 or 5 decimal places.

This function is especially useful when formatting the output of various instruments that need rounding. Also see TickSize and Instrument.Round2Ticks, Instrument.Round2TickSize.

More information can be found here: Formatting of Numbers.

Example

Print("The value of " +Instrument.Name + " is noted with a precision of " + Instrument.Digits +" Decimal points.");

Instrument.ETF

Description

Instrument.ETF is used to differentiate between a stock and an ETF. This is necessary since ETFs are considered to be „stocks" by some exchanges.

Parameter

none

Return Value

Type bool

Usage

Instrument.ETF

More Information

What is an ETF?

Wikipedia: http://de.wikipedia.org/wiki/Exchange-traded_fund

Example

if (Instrument.InstrumentType == InstrumentType.Stock)
if (Instrument.ETF)
Print("The value is an ETF.");
else
Print("The value is a stock.");

Instrument.Exchange

Description

Instrument.Exchange outputs the description/definition of the current exchange for the current instrument.

Parameter

none

Return Value

An exchange object of the type "public enum exchanges"

Usage

Instrument.Exchange

More Information

An overview of various exchange: https://en.wikipedia.org/wiki/List_of_stock_exchanges

Example

Print("The instrument " + Instrument.Name +" is traded on the " + Instrument.Exchange + " exchange.");

Instrument.Expiry

Description

Instrument.Expiry outputs the date (month and year) of the expiry of a financial instrument. Only derivative instruments such as options or futures will have an expiry date.

Parameter

None

Return Value

Type DateTime

For instruments without an expiry date the returned value is set to DateTime.MaxValue(= 31.12.9999 23.59:59)

Usage

Instrument.Expiry

More Information

The expiry date (expiry) can also be seen within the Instrument Escort:

Example

Print("The instrument " + Instrument.Name +" will expire on " + Instrument.Expiry);

Instrument.GetCurrencyFactor

Description

Instrument.GetCurrencyFactor returns a conversion factor that can be used to convert an instrument's currency to the account's currency.

Parameter

Type Currencies

Return Value

Type double

Usage

Instrument.GetCurrencyFactor(Currencies)

More Information

Common currencies are.B. AUD, CAD, EUR, GBP, JPY oder USD.

Example

Protected override void OnCalculate()
{
   double currFactor = Instrument.GetCurrencyFactor(Account.Currency);
   Print(Close[0] + " in " + Instrument.Currency.ToString() + " = " + (Close[0] * currFactor) + " in " + Account.Currency.ToString());
}

Instrument.InstrumentType

Description

Instrument.InstrumentType outputs a type object of the trading instrument.

Parameter

none

Return Value

Object of the type "public enum instrument"

Usage

Instrument.InstrumentType

More Information

Potential values are: future, stock, index, currency, option, CFD and unknown.

There is no ETF type. ETFs are considered to be of the type "stock" – see Instrument.ETF.

The instrument type can also be viewed within the Instrument Escort:

Example

Print("The instrument " + Instrument.Name + " is of the type " + Instrument.InstrumentType);

Instrument.MainSector

Description

Instrument.MainSector returns the main sector of the trading instrument.

Parameter

none

Return Value

String

Usage

Instrument.MainSector

More Information

The main sector is also visible in the instrument escort:

Example

Print("Das Instrument " + Instrument.Name + " ist im Sektor " + Instrument.MainSector + " tätig.");

Instrument.Margin

Description

Instrument.MainSector returns the required margin of the trading instrument.

Parameter

none

Return Value

int

Usage

Instrument.Margin

More Information

Margin is also visible in the instrument escort:

Example

Print("Das Instrument " + Instrument.Name + " has a margin of " + Instrument.Margin);

Instrument.Name

Description

Instrument.Name outputs the name/description of the trading instrument.

Parameter

none

Return Value

Type string

Usage

Instrument.Name

More Information

The instrument name can also be seen within the Instrument Escort:

Example

Print("The currently loaded instrument inside the chart is named " + Instrument.Name);

Instrument.PointValue

Description

Instrument.PointValue outputs the monetary value for a full point movement of the instrument.

Parameter

none

Return Value

double – point value

Usage

Instrument.PointValue

More Information

Example for various point values (per amount, CFD, futures contract, lot etc.)

Stock: generally 1.00 Euro or 1.00 USD. EUR/USD: 100,000 USD DAX future: 25.00 Euro

Tick Value

The tick value can be calculated by multiplying the point value with the tick size.

For example, the E-mini S&P 500 has a point value of $50. The tick size equals 0.25. This means that there are 4 ticks in one full point for the E-mini S&P 500. Since 50 * 0.25 = 50/4 this means that the tick value is $12.50.

The point value can also be viewed within the Instrument Escort:

Example

Print("When " + Instrument.Name + " rises for one full point then this is equal to " + Instrument.PointValue + " " + Instrument.Currency);

Instrument.Round2TickSize

Description

The function Instrument.Round2TickSize rounds the supplied market price to the smallest value divisible by the tick size of the instrument.

Parameter

double – market value

Return value

double

Usage

Instrument.Round2TickSize(double MarketPrice)

More Information

The number of decimal places to which the price is rounded depends on the instrument. If, for example, an instrument is a stock, then the rounding will be performed to 2 decimal places. For a Forex instrument, it may be carried out to 4 or 5 decimal places.

See TickSize and Instrument.Digits.

Example of professional Formatting, Formatting of Numbers.

Example

double Price = 12.3456789;
Print(Price + " rounded for a " + Instrument.Name + " valid value is " + Instrument.Round2TickSize(Price));

Instrument.Symbol

Description

Instrument.Symbol outputs the symbol that identifies the trading instrument within AgenaTrader. Depending on the symbol, the mappings for the various data feed providers and brokers will be managed in different ways.

Parameter

none

Return value

Type string

Usage

Instrument.Symbol

More Information

By using symbols, identical stocks being traded on different exchanges can be identified and separated from each other. The symbol BMW.DE is the BMW stock on the XETRA exchange. BMW.CFG is the CFD for the BMW stock.

The instrument symbol can also be viewed within the Instrument Escort:

Example

Print("The instrument currently loaded within the chart has the symbol: " + Instrument.Symbol);

Instrument.TickSize

Description

The tick size is the smallest measurable unit that a financial instrument can move. This is usually called 1 tick.

Parameter

none

Return Value

double

Usage

Instrument.TickSize or simply TickSize

More Information

The keyword TickSize is equivalent to Instrument.TickSize. Both information requests will produce the same value and are thus interchangeable.

Example

Stock: 0.01 ES future: 0.25 EUR/USD: 0.00001

See Instrument.PointValue and Instrument.Digits.

Examples of professional Formatting, Formatting of Numbers.

Example

Print("The value of " + Instrument.Name + " can change for a minimum of " + Instrument.TickSize + " Tick(s).");