Links

Instrument Escort

The Instrument Escort window

The Instrument Escort is a tool that helps you to manage instruments and instrument lists. In order to receive data for particular instruments and to be able to trade with them, the necessary instruments must be imported into the Instrument Escort.
Use the Instrument Escort to:
  • edit
  • select instruments and instrument lists.
In order to open the Instruments window use one of the options:
  1. 1.
    Select Instrument Escort by using Tools -> Settings or
  2. 2.
    left click the symbol
    in the application toolbar within the main window.
This window consists of the following parts:
  • Search for a symbol/name:
    • enter the symbol (e.g. GOOG), the full name (Google Inc.) or the ISIN number (US38259P5089).
    • double-click on the search result to select the instrument and bring up the Instrument details tab.
    • enter type of symbol (e.g. future, stocks, index etc)
    • enter exchange (e.g. Nyse)
  • Selection list tree:
    • Choose single instruments or whole instrument lists for further editing.
  • Details tab:
    • Add new instruments or edit existing instruments within the details tab.
  • Instrument lists tab:
    • Add or manage instrument lists within this tab.
Note: Fractals are only available for Futures. It is default setting in the right area of the window, yet disappears when you have chosen an instrument other than futures.

Static lists, dynamic lists und screener presets

The Instrument Escort selection list tree displays 3 additional lists:
  • Static Lists: lists created or edited by a user. Using the Configuration Escort you can connect chart groups with the static instrument lists if necessary. This means that changing values within the list chart group or the tab chart group will automatically change your static lists and vice versa.
  • Dynamic Lists: pre-defined lists that are updated automatically (if there is an internet connection).
  • Screener Presets: lists that refresh automatically based on scanning activities (if there is an internet connection). These lists can be created using the Stock EOD Screener.
The context menu of the selection list tree section can be accessed by right clicking and allows the following
  • Reset checkboxes: deletes all checkbox markers.
  • Reload: reloads the Instrument Escort. This may be necessary after a new instrument has been added.

From chart to Instrument Escort

Left clicking on the instrument name within the chart opens the Instrument Escort window.

Opening a new instrument inside the chart

To add a new instrument to a chart follow these steps:
  1. 1.
    "Activate" the chart by left clicking on it.
  2. 2.
    Once you start typing letters using the keyboard, the instrument search window will be opened.
  3. 3.
    After selecting the instrument needed and pressing 'Enter' (or double-clicking) the new chart will be displayed.

Selecting instruments / instrument lists

If you open the Instrument Escort to choose instruments/instrument lists (tick record, Forex pad, etc.) then only the section with the selection list will appear. Press the Select button or double-click to choose a single instrument or whole instrument list.

Import and export of instruments

The following actions can be carried out using the Import/Export button within the Instruments window:
Description of the functions:
Select Markets + Mappings menu item: more information in the section Instruments: Markets and Mappings
  • Import from File: imports instruments from a CSV file
  • Import from Dialog: inserts symbols that satisfy the same criteria.
  • Import Mappings: imports mappings from a CSV file.
  • Import Instrument Lists: imports instrument lists from a CSV file.
The name of the *.csv file will be suggested as the instrument list name. Importing will not overwrite existing lists but will simply add instruments from the *.csv file that are not included in the instrument list. However, importing will overwrite existing instruments (details will be updated).

Import formats - Instruments & Mappings

This section explains which formats are supported when importing instruments and mappings from a CSV file.

Instruments imported from a CSV file

Each instrument traded or analyzed within AgenaTrader must exist in the Instrument Escort. Currently the AgenaTrader database contains approx. 7000 instruments of all types (stocks, futures, etc.).
The following attributes can be imported into AgenaTrader: - <Symbol> - The instrument's exchange symbol - <Name> - Instrument name - <Margin> - %-margin for a leveraged instrument (see below) - <PointValue> - Value per point - <TickSize> - Tick size - <MainSector> - Sector of economy (for stocks) - <DetailSector> - Industry (for stocks) - <InstrumentType> - Instrument type (see selection list in the Details tab) - <Exchange> - Exchange (see selection list in the Details tab) - <ETF> - Exchange Traded Fund: true / false - <Currency> - Currency (see selection list in the Details tab) - <Expiry> - The instrument's expiration date (futures) – Format example: 06.2014 (mm.yyyy) - <ISIN> - tbd - <DefaultOrdersize> - tbd
If a margin is different for various brokers, you can edit it using the Mapped symbol column in the Details tab.
The following formatting is required for a CSV file:
  1. 1.
    The first cell must contain the tag <Import Instrumens>
  2. 2.
    Below this tag there are <Attributes> and <Instrument> rows.
  3. 3.
    The <Attributes> row causes a change of attributes for the following <Instrument> rows.
  4. 4.
    The <Instrument> row may also include attributes.
Sample data:
<Import instruments>
<Attributes>
<Exchange>Nasdaq
<Instrumenttype>Stock
<ETF>false
<PointValue>1
<TickSize>0,01
<Currency>USD
<Instrument>
<Symbol>AA
<Name>AA Name
<Margin>25
<MainSector>AAS
<DetailSector>ADS
<Expiry>03.2012
<Instrument>
<Symbol>BB
<Name>BB Name
<Margin>20
<MainSector>BBS
<DetailSector>BDS
<Expiry>04.2012
...
<Attributes>
<Exchange>FromYahoo
<Name>FromYahoo
<Instrumenttype>Stock
<ETF>false
<PointValue>1
<TickSize>0,01
<Currency>USD
<Expiry>06.2014
<Instrument>
<Symbol>CC
<Margin>25
<MainSector>CCS
<DetailSector>CDS
<Instrument>
<Symbol>DD
<Margin>15
<MainSector>DDS
<DetailSector>DDS
...
To download examples please click here.
Using "FromYahoo": you may often face situations in which you have an instrument list and know its base currency, instrument type etc. but are missing information such as the traded exchange or a symbol name. You can solve this problem by simply retrieving the required information from the internet. When you enter <Name>FromYahoo or <Exchange>FromYahoo this information will be imported from the Yahoo database.
CAUTION! Should you need to import a large number of values, then this may take quite a long time. Importing 1000 instruments will take approximately 10 minutes.

Instrument lists imported from a CSV file

There is a difference between importing instruments and instrument lists. Instrument lists are lists of symbols that have been assembled for a specific purpose e.g. long lists/short lists etc. When you import a list such as this, the corresponding symbols must already exist in AgenaTrader.
The following formatting is required for a CSV file:
  1. 1.
    The first cell must contain the tag <Import Instrument list>
  2. 2.
    Below this tag all symbols needed must be listed.
Sample data:
<Import Instrumentlist>
А
АА
AAPL
ABC
2323
3343
If symbols are not identified correctly, a popup will display the following message:
To download other examples please click here.
Additional information is available on our forum (in german only).

Mappings from a CSV file

An example of the format for the import of mappings from a CSV file:
<InstrumentMapping>
<Provider>BarChart
<mappedSymbol>AUDCAD
<Name>AUDCAD
<Symbol>AUDCAD
<Instrumenttype>Currency
<mappedSymbol>AUDCHF
<Name>AUDCHF
<Symbol>AUDCHF
<Instrumenttype>Currency
<mappedSymbol>AUDJPY
<Name>AUDJPY
<Symbol>AUDJPY
<Instrumenttype>Currency
To download examples please click here.

Creating and managing instrument lists

Creating an instrument list

Inside the tab Instrument lists of the Instrument Escort you can create or edit existing instrument lists.
In order to create a new instrument list follow these steps:
  1. 1.
    Assign the name for a new list manually.
  2. 2.
    Add instruments using one of the following methods:
  • Manual entry in the "Symbol" cell
Important note. You can also create a blank list by leaving this cell empty. However, you can only use a blank list as an LCG (list chart group).
  • Drag and drop:
    • from the instrument search section
    • from the list selection tree:
      • single values
      • instrument lists.
Clicking or double-clicking the checkbox will select an instrument / instrument list, after which you can drag it into a new instrument list.checkbox will select an instrument / instrument list, after which you can drag it into a new instrument list.
3. Click the Save button to add the new list to the list selection tree. Once finished, the list will be available for editing within the static lists in AgenaTrader.
If you wish to create a new list (for example, from the scanner), then the name of the instrument list will be pre-initialized with <New List> or empty. The instrument list cannot be saved in either of these states. If you choose an existing name, this instrument list will be overwritten.
Additional functions are available under the Instrument lists tab:
  • Delete All: Clicking the arrow next to "Delete All" opens a drop-down menu where you can choose between Delete All Instruments or Instrument Lists. Delete All Instruments removes all instruments from the Instrument manager. Delete All Instrument Lists removes all instrument lists from the Instrument manager.
  • Remove List: deletes only the list
  • Export list: exports the symbol names into a CSV file
  • Exp. Instruments: exports the symbol names and all corresponding data into a CSV file
  • Save: saves the instrument list
  • Remove: removes one or more marked instruments from the list (this can also be achieved by clicking the Delete button)
  • Synchronize: opens a new settings window that enables you to assign the same value to all entries in the list according to the specific instrument properties
  • Clear: removes all instruments from the list

Changes outside the Instrument Escort

You can edit Instrument lists outside the Instrument Escort using the following functionalities:
  • Click the Instrument list buttons in the action bar to make the necessary changes. These buttons will be displayed once you add them from the Action bar settings under the menu item Instrument List. Once an instrument's symbol is red, the instrument from the current chart will be added to the list. By clicking the button it can be added to as well as deleted from the corresponding list.
  • Add an instrument to an instrument list with the
    icon in the chart toolbar.
  • The scanner has a multi-select function that allows you to add several instruments to a list in one go.

Favorite instrument list

You can define your favorite instrument list by selecting the corresponding icon in the chart toolbar and checking the Fav. checkbox in the popup. The favorite instrument list will be offered as the first option whenever a new LCG/TCG is created.

Creating and editing of instruments

A large amount of instruments are already mapped in AgenaTrader. If a certain instrument does not exist in the Instrument Escort then you can add it manually.
To add a new instrument, select an instrument of the same type (stock, Future, etc.).
Usually it is sufficient to:
  1. 1.
    enter the symbol, name of the instrument or its ISIN number.
  2. 2.
    select the exchange:
    1. 1.
      the correct exchange input is highly important in order to access the appropriate trading hours (Marketplace Escort and tab Trading hours) and organize charts.
  3. 3.
    Adjust the def. ordersize in the Configuration Escort. Any value higher than 0 replaces the default setting for the order size.
  4. 4.
    Adjust the mappings for a new instrument using mapped symbol (see examples in the forum below) (available in german only).
Additional fields are:
  • Instrument type: allows you to define a new instrument as one of the following types:
  • Currency: pertains to the currency in which the instrument is traded. It is necessary to perform currency conversions in AgenaTrader for the correct P&L display.
  • Margin (security %): must be entered for leveraged products, and represents the general margin for the instrument. This value may vary depending on the broker. If this is the case, the margin must be entered in broker-specific list (in the Instrument Escort window within the Details tab).
  • Tick size and point value are necessary for various calculations such as: stop price, P&L calculation etc.
  • If the main sector or detail sector is entered, an instrument will be displayed inside the appropriate submenu of the selection tree in the InstrumentEscort.
Press the Add/Save button to register a new instrument in the system or edit the existing instrument.

Inconsistent information from a broker / data feed provider

Different brokers / data feed providers may use different symbol names and offer different margins for leveraged instruments.
You can enter their specific characteristics manually in the list within the details tab.
Name
Meaning
Provider
Broker's or datafeed provider name
Symbol
Mapping for each datafeed or broker symbol
Cont.
Contract for broker future symbol
Comm.
Commision
Margin
Broker's margin to purchase securities
Min Qty
Minimum order size
Max Qty
Maximum order size
Min Qty Step
Minimum order size step
Stop Distance
Distance for trading stops orders to be met when trading
Point Value
Mapped point value
Price Multiplier
Some broker platform uses multiplier to calculate the price of a symbol.
In addition, you may set commission manually by adding this info in the InstrumentEscort in the Mapping Area using the "C" Button:
The mapped symbols entered within the details tab will be used internally by AgenaTrader. If the same symbol is used by other brokers / data feed providers, this mapping will not take place. The name (symbol) AAPL (Apple Inc. stocks ) is used by the majority of brokers and does not need an additional label / identification in the list. Different labels / names exist primarily in the Futures and Forex markets.

Examples

IB
Adjusting the tick size for CFDs according to the current price
Please note that Interactive Brokers uses different tick size parameters according to the particular price range. When trading some European CFDs, it may occur that users receive the following error messages: 1. "The price does not conform to the minimum price variation for the contract". 2. "Instrument Tick-Size is not zet calculated or delivered". In order to continue the trade it is necessary to adjust the tick size for the instrument manually.
Please enter a ticker name in the search field on IB's website and check the price parameters for the selected instrument.
Then enter the tick size in the Instruments window according the the current price, and check the checkbox Fixed as shown in the figure below:

Futures contract rollover

Expiration date of a futures contract

In order to change the expiration date of a futures contract:
  1. 1.
    Open the Instrument Escort from the graph via clicking the instrument symbol or by using the main menu Tools -> Instrument Escort.
  2. 2.
    Find the desired instrument using the Symbol search cell ot the instrument selection tree.
  3. 3.
    Change the date in the Contract cell in the Details tab.
In addition user have possibility to change contract date in Future Calendar. Just Right Mouse click on a Contract field opposite interested symbol:
You can check the expiry date for each future contract beside the instument name in a chart toolbar.
Continious Contract is preset, if any of the three other options (see screenshot) was chosen, the number 1 to 3 will be added to the Mapped Symbol.
AgenaTrader allows you to set a futures rollover alert. More information about futures contracts can be found in the section Futures.
Definition for contracts:
Continuous CC = continuous contract FrontMonth FM = actual contract according to calendar only Next = upcoming contract according to calendar NextOn = contract after next according to calendar
Setting options are quite similar or even the same for Taipan.
As described in Taipan connection guide, you can choose in account settings, if you want "CC" or "FM". Whatever is chosen there, will be regarded as default setting afterwards.

Switching from one contract to another

Changing the expiration date
If you wish to extend the existing expiration date to the next expiration date for an FDAX instrument, you must disconnect all data feed and broker connections. After changing the expiration date and reconnecting you will see the data from the new futures contract.
The same instrument with a different expiration date
If you wish to see both expiration dates for a future contract for the same instrument follow these steps:
  1. 1.
    Find the desired futures contract in the Instrument Escort.
  2. 2.
    If, for example, you wish to see FDAX 09.JJJJ and FDAX 12.JJJJ simultaneously, change the name of one of these instruments (e.g. to "FDAX-NEXT") and set the new expiry date as 12.JJJJ, then click the Save button.
By doing so you create the FDAX with the Contract date 09.JJJJ and the FDAX-NEXT with the expiry date 12.JJJJ, both of which can now be found within the instruments.
Volume Based Rollover
For CME instruments, expiry with the most Volume settlements will be marked by yellow (in case you haven't set it yet for the selected instrument). With this data, the user may easily switch to the most popular expiry.
To manage this user should first import mappings for CME Manager.
Important! Volume Based Rollover will be available in AgenaTrader version 2.7

How to backup the instrument database

You can create an instrument database backup using the Instrument Escort.
Clicking the Import/Export button followed by the Export Instruments DB to XML Snapshot submenu will prompt you to select a directory, where the backup file will be saved in XML format. To restore, click the Import/Export button and select Import from Instruments DB XML Snapshot. After choosing the XML file the instruments will be imported.
Please note the following when importing the instruments:
  • Existing instruments will be updated.
  • Instruments in the Instrument Escort will not be overwritten if they are not included in the XML file.
  • Instruments from the XML file will be added if they are not included in the Instrument Escort.
  • All mappings and instrument lists from the Instrument Escort will be deleted and replaced with entries from the XML file.
CAUTION. Depending on the size of the instrument database the Import/Export process may take a while.

Create your instruments

AgenaTrader comes with a large number of instruments already recorded for you. If instruments are missing, they can be set up in the following way:
Select the right stock exchange: the correct stock exchange is very important, since the trading times of the marketplaces are determined based on the stock exchange (Marketplace Escort / trading times) and the charts are also oriented according to this.
After this, adjust the default order size (a value greater than 0 replaces the settings of the default order size in the Configuration Escort) and adjust the mappings for the new instrument:
You can find the right mapping for your instrument on the reference platform of your broker or data feed provider. Alternatively, of course, you can also contact them directly and request the mappings for the corresponding instruments. You also have the option to use the "feedback button" to request the relevant mapping. In addition, you should carry out a new import of the mappings from your broker and data feed provider at regular intervals.
You can find more information on creating and editing instruments here.

Practical examples

IB

Example 1
Adjusting the tick size for CFDs according to the current price
Please note that Interactive Brokers uses different tick size parameters according to the particular price range. When trading some European CFDs, it may occur that users receive the following error messages: 1. "The price does not conform to the minimum price variation for the contract". 2. "Instrument Tick-Size is not zet calculated or delivered". In order to continue the trade it is necessary to adjust the tick size for the instrument manually.
Please enter a ticker name in the search field on IB's website and check the price parameters for the selected instrument.
Then enter the tick size in the Instruments window according the the current price, and check the checkbox Pin Tick Size as shown in the figure below:
Example 2
Check symbol mappings for symbol FMCE"''
This example may be a little tricky because symbols name in AgenaTrader and IB mapping for this symbol totally differs.
1. Visit IB's website
2. Select Advanced Tab. Paste symbol Name (from Instrument Escort) to Description/Name input and click Search button
3.In open dialog click on button Details
4. After just copy Symbol and paste it to symbol field in Instrument Escort opposite IB datafeed.

Error: "No security definition found"

Definition of the problem
What has happened?
  1. 1.
    If an order is placed or an order is flattened, I receive the notification "NO DEFINITION FOUND" and the order is neither sent to the broker nor flattened.
  2. 2.
    After connecting to my broker for the first time, a trade was opened without my doing.
What does this mean?
  1. 1.
    The instrument for the corresponding market (symbol) is missing. If an instrument is present, the mapped symbol (mapping) for the corresponding broker and data feed is missing.
  2. 2.
    Trades that have been made with the broker platform will be inputted into AgenaTrader when the connection is established.
Possible solutions
Creating/setting up the instruments yourself
Open the Instrument Escort and carefully fill in all entry fields.
Trading times are taken from the respective stock exchange. Here in the example image, Providers and Mapped Symbol allow you to request data via TaiPan (a data feed account with the providers is required, and can lead to additional costs).
If further data feeds or brokers for which the user has an account are connected, then a further Mapped Symbol and Provider must be selected here (e.g. CapTrader, XTB, Dukascopy, FXCM and co.). You can ask the broker and data feed provider respectively which Mapped Symbol they use.
The changes need to be confirmed using the "Save" button. Reconnection to the data feed or broker is required for the changes to be applied.
Request instruments / mappings
With the "Submit corrected mapping"-button, you can request the mapping for an instrument right away: open the InstrumentEscort, enter the instrument in question and click "Submit corrected mapping". Then enter a short issue description in the window that pops up and click "Send":
Usually the mappings team take care in a timely manner and you get response shortly after. Simply re-import mappings and Instrument Lists to continue working with the updated mappings.
Instrument Lists and Mappings Import
Go to Tools -> Settings -> Instruments: Markets and Mappings. In the Mappings tab, select your data feed or broker (provider). Clicking on the Import field below starts the import. Only after a successful import of the mappings can Instrument Lists (general or broker-specific) be imported without errors.
If you accidentally delete Mappings and Instrument Lists, then you can repeat the import here and the data will be transferred.
Further sources of information
There is an detailed webinar on the topic of instruments and lists on our YouTube channel.