Version: 0.2.1-SNAPSHOT

Get started

Overview

Trading API (TAPI) is a part of the standard Consorsbank trading application ActiveTrader / ActiveTrader Pro. It allowes to write user managed application for the specific trading activities. TAPI support pull / push requests and based on the Google Remote Procedure Call (GRPC) technology.

With help of the TAPI you have an access to the accounts, orders, depots and market data information.

Important

This documentation is the description of the early version of Trading API. It’s not final and it’s subject to change. With the lookback to the new BaFin regulation it’s especially important to understand that the ordering part of the TAPI can be partially changed to fullfil new law directives.

Additional information and discussions can be found there. Please contact to the support team to get access to this part of the community.

Requirements

  • Active Trader / Active Trader Pro with Java 8 64 bits, minimum 8Gb RAM

  • Client CSharp / .NET Framework 4.7.x or higher / .Net Core SDK 2.1 or higher (Visual Studio Community Edition 2017)

License

Trading-API is licensed under Apache 2.0 license.

The license and notice texts can be found in the delivered LICENSE and NOTICE.TXT files.

Communication

GRPC technology uses one connection to transfer all necessary data beetwen client and ActiveTrader. As developer you don’t need to care about communication. All low level communication, security and converting functions takes TAPI engine. You can concentrate on the high level functions and bussines logic of the application.

client tapi

Security

TAPI uses HTTP/2 protocol with RSA protection. RSA self signed certificate can be generated directly in the ActiveTrader application. Typical use case is to use user application from same PC, but it’s also possible to connect from the remote machine.

Important

To accept self signed certificate from the user application is necessary to use trusted part of the RSA keys (Trust Certificate) by the connection initialization in the client application. This certificate can be exported from the ActiveTrading application.
generate key

To provide users access control can be used secret string. That’s an equivalent of password. Secret is defined in the Active Trader and used only for validation. User application sends secret to the ActiveTrader. If the validation in the ActiveTrader is passed then ActiveTrader generates a session access token and returns it to the user application. With this token is possible to execute other requests. After end of processing the token should be invalidated.

token usage
Important

We don’t keep secret data in the configuration. Only double MD5 hash of the secret + solt is stored in the configuration. As result we can’t restore the secret. For more information see Defense against rainbow tables

Configuration

To activate TAPI is need to complete next steps:

Config
1 Select Trading-API settings in the configuration
2 Activate TAPI checkbox
3 Optional: if key exists, press [GENERATE NEW KEY] button

In the opened dialog

GenerateKey
1 Enter or correct key settings
2 Press [GENERATE NEW KEY] button and wait unil new key is generated
3 Press [OK] button to accept new settings

After confirmation of the new settings TAPI will be activated.

Warning

In some cases if any initialization errors are appear, the TAPI activation indication in the status bar of the application will be red. To check activation problems move mouse cursor over this indication and check tooltip for the error.

Before to start using client application, it’s need to export trusted certificate from ActiveTrader.

ExportCertificate
1 Set secret for an access control. Longer string is better.
2 Press [EXPORT TRUST CERTIFICATE] and store file (for example with name: roots.pem) to the location where client application can use it.

Session TAN

Some operations of the TAPI can be used without TAN. All activities with the necessity of the autorisation are need to use of the session TAN.

Important

Do not forget to activate session TAN. It’s not possible to use individual TAN’s with TAPI

Usage of the Trading API

Source code

An example aplication is delivered with precompiled GRPC libraries. If you want to generate source code by youself you can use protobuf files from protobuf directory. Please refer to the C# Quickstart.

Initialization

To initialize client application and connect to the ActiveTrader with help of TAPI you have to process next steps:

initialize grpc csharp
Important

All examples are avialable as a sorce code and can be found in the specific folders.

Input point is the file Program.cs

To start an appication you have to define location of the trust certificate and set secret. See properties item of the contect menu of the
CSharpParameters
CSharpParameters2

Initialize the root GRPC engine with trusted certificate, exported from configuration dialog of the ActiveTrader.

Example C#: Initaialize GRPC

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


  
using System;
using System.Collections.Generic;
using System.IO;
using Grpc.Core;
using Com.Consorsbank.Module.Tapi.Grpc;
using System.Threading.Tasks;
using System.Threading;
using Microsoft.CSharp.RuntimeBinder;


class Program : IDisposable
{
    private static readonly Empty empty = new Empty();

    private readonly Channel channel;
    private readonly StockExchangeService.StockExchangeServiceClient stockExchangeServiceClient;
    private readonly DepotService.DepotServiceClient depotServiceClient;
    private readonly SecurityService.SecurityServiceClient securityServiceClient;
    private readonly OrderService.OrderServiceClient orderServiceClient;

    private readonly string _accessToken = "";

    public Program(string host, int port, string trustCertificate, string secret)
    {
        SslCredentials channelCredentials = new SslCredentials(trustCertificate);  (1)
        channel = new Channel(host + ":" + port, channelCredentials); (2)

        this._accessToken = Login(secret);
        if (this._accessToken == null)
        {
            throw new RuntimeBinderException("Error by login");
        }

        stockExchangeServiceClient = new StockExchangeService.StockExchangeServiceClient(channel);
        depotServiceClient = new DepotService.DepotServiceClient(channel);
        securityServiceClient = new SecurityService.SecurityServiceClient(channel);
        orderServiceClient = new OrderService.OrderServiceClient(channel);
    }

    public void Dispose()
    {
        Logout();
        channel?.ShutdownAsync().Wait(); (3)
    }

    public static void Main(string[] args)
    {
        if (args.Length<2)
        {
            Console.WriteLine("Please generate key in AT and" +
                "put location of the trust certificate and secret as an argument");
            return;
        }

        string trustCertificate = File.ReadAllText(args[0]); (4)
        using (Program program = new Program("localhost", 40443,
            trustCertificate, args[1])) { (5)

            // ...

        }
    }

}
1 Create creditionals
2 Create comminication channel
3 Close comminication channel
4 Get trusted certificate location as a parameter of the command line
5 Create an instance of the program

Services and functions definition

After an initialization is GRPC ready and it can be used for the building service stubs to operate with TAPI services. Stubs are sets of service functions with help of then is possible to access data and execute user actions. They are very similar to the normal programming functions with small differences.

  • Each remote function can have one (and only one) input parameter.

  • Each remote function can have one (and only one) result parameter.

  • The function can send data asynchronically

Functions can be simple (one request → one reply), server sends events (one request from client → many replies from server), client sends events (many requests from client → one reply from server) or server and clients sends events (many requests from client → many replies from server). TAPI uses only first and second types of functions. First type of the function used for the simple user activity (pull) and second type for subcriptions or streaming (push).

Services and functions are defined in the special files as protobuf protocol v.3

Example Protobuf: RPC definition

  
1
2
3
4


  
service ServiceName { (1)
  rpc SimpleFunction(ClientParameterType1) returns (ServerParameterType1); (2)
  rpc PushFunction(ClientParameterType2) returns (stream ServerParameterType2); (3)
 }
1 ServiceName is service stub name. This name will used for the access to the service functions
2 SimpleFunction is simple request / reply function.
3 PushFunction is push function with one request and streams data from the server. Please check stream keyword before ServerParameterType2
Important

You don’t need to use protobuf files directly, but it’s good idea to know a syntax of the the protocol. These files are need if you want to use TAPI with other progaming languages. grpc.io conatains all necessary infomation about code generation and usage for all supported programming languages.

Create services

There are two types of the service functions: blocking and unblocking service functions. Blocking service functions are used for the synchronical answer from the function and similar to the typical program functions. By call of the blocking functions, program waits until a result of the function is arrived. It can produce timeouts by the execution. Unblocking function are used for the background processing. In this case a program don’t wait until result is arrived and listen for the result asynchronically. This type of the stubs is used for the push functions. For more information please refer to the grpc.io web site.

Blocking calls can be used directly. For asynchronical calls are defined helper classes to simplify an access logic.

Example C#: StreamObserver for push streams

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


  
using System;
using System.Collections.Generic;
using Grpc.Core;
using System.Threading.Tasks;
using System.Threading;

public abstract class StreamObserver<TClient, TRequest, TReply> where TClient :
    ClientBase<TClient>
{
    // Define delegates
    public delegate void ResultListener(TReply reply); (1)
    public delegate AsyncServerStreamingCall<TReply>
        Call(TRequest request, CancellationToken token); (2)

    private readonly TClient _client;
    private readonly Call _caller;

    protected StreamObserver(TClient client, Call caller)
    {
        this._client = client;
        this._caller = caller;
    }

    public async Task Stream(TRequest request, ResultListener listener,
        CancellationToken token = default(global::System.Threading.CancellationToken))
    {
        try
        {
            using (AsyncServerStreamingCall<TReply> call = _caller(request, token)) (3)
            {
                var responseStream = call.ResponseStream; (4)
                while (!token.IsCancellationRequested && await responseStream.MoveNext()) (5)
                {
                    {
                        TReply reply = responseStream.Current; (6)
                        listener?.Invoke(reply); (7)
                    }
                }
            }
        }
        catch (RpcException e)
        {
            if (e.StatusCode!=StatusCode.Cancelled)
            {
                Console.WriteLine(e); (8)
                throw;
            }
        }
        catch (Exception e)
        {
            Console.WriteLine(e); (8)
            throw;
        }
    }
}
1 Define delegate for the listener
2 Define deligate for the function call
3 Create streaming call
4 Get response stream
5 Wait for the next event asyncronically
6 Get result
7 Sent result to the listener
8 Process error

Objects creation

Objects in the GRPC world are immutable (or not changable). All fields of the object are filled by object creation.

Example C#: Create object

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16


  
SecurityMarketDataRequest marketDataRequest = new SecurityMarketDataRequest() (1)
{
    SecurityWithStockexchange = new SecurityWithStockExchange (2)
    {
        SecurityCode = new SecurityCode (3)
        {
            Code = "710000",
            CodeType = SecurityCodeType.Wkn
        };
        StockExchange = new StockExchange (4)
        {
            Id = stockExchangeId,
            Issuer = ""
        };
    }
}
1 Create security market data request
2 Initialize security code with stock exchange field
3 Initialize security code as field of the security code with stock exchange
4 Initialize stock exchange as field of the security code with stock exchange
Important

Please refer to the protobuf3 protocol to check fields mapping and default values for the parameters.
Important

It’s necessary to fill only parameters that need for the function call. All other parameters should stay untouched or should have default values.

Pull and push functions

There is two possibilites to call remote function.

Pull requests

The first one is using blocking service stub. In this case an operation blocks program execution until results are arrived.

pull call
Example C#: Blocking execution

  
1
2
3
4
5
6
7
8
9
10
11
12


  
private static readonly Empty empty = new Empty();

public TradingAccounts GetTradingAccounts()
{
    var accountServiceClient =
        new AccountService.AccountServiceClient(channel); (1)
    var accessToken = new AccessTokenRequest()
    {
        AccessToken = this._accessToken (2)
    };
    return accountServiceClient.GetTradingAccounts(accessToken); (3)
}
1 Create account service client
2 Set access token
3 Request trading accounts and wait the result
Useful

Typical use case is to get clients once and keep it during one connection session.

Push requests

Other possibility is not to wait for the results, but listen for then asynchronically.

push call
Example C#: Noblocking execution

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18


  
private static readonly Empty empty = new Empty();

public Task<TradingAccounts> GetTradingAccountsAsync()
{
    var accountServiceClient =
        new AccountService.AccountServiceClient(channel); (1)
    var accountStreamer = new AccountsStreamer(accountServiceClient); (2)
    CancellationTokenSource tokenSorce = new CancellationTokenSource(); (3)
    var accessTokenRequest = new AccessTokenRequest()
    {
        AccessToken = _accessToken
    };
    var backgroundTask = accountStreamer.Process(accessTokenRequest,
        accounts => Console.WriteLine(accounts), (4)
        tokenSorce.Token);

    return backgroundTask; (5)
}
1 Create service client (can be done once)
2 Create help streamer (can be done once)
3 Create cancel source to control execution
4 Set delegate to process results. Called after processing end. No new result are comming anymore. The task is finished.
5 Return task back. Can be used for await

The results are comming only once. The operation will be automatically completed. A cancel token is optional parameter. To execute this example are additional classes need.

Example C#: AccountsStreamer

  
1
2
3
4
5
6
7
8


  
public class AccountsStreamer :
        AsyncObserver<AccountService.AccountServiceClient, AccessTokenRequest, TradingAccounts> (1)
{
    public AccountsStreamer(AccountService.AccountServiceClient client) : (2)
        base(client, (request, token) =>
            client.GetTradingAccountsAsync(request, null, null, token))
    { }
}
1 Account streamer takes 3 parameters to execute: client, request and reply
2 Implementation of the asyncronical request (overloaded function)

AsyncObserver is helper class to process asyncronical requests.

Example C#: AsyncObserver

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


  
public abstract class AsyncObserver<TClient, TRequest, TReply> where TClient : ClientBase<TClient>
{
    // Define delegates
    public delegate void ResultListener(TReply reply); (1)
    public delegate AsyncUnaryCall<TReply> Call(TRequest request, CancellationToken token); (2)

    private readonly TClient _client;
    private readonly Call _caller;

    public AsyncObserver(TClient client, Call caller)
    {
        this._client = client;
        this._caller = caller;
    }

    public async Task<TReply> Process(TRequest request, ResultListener listener,
        CancellationToken token = default(global::System.Threading.CancellationToken))
    {
        try
        {
            using (AsyncUnaryCall<TReply> call = _caller(request, token)) (3)
            {
                var responseStream = call.ResponseAsync; (4)
                await responseStream; (5)
                if (!responseStream.IsCanceled)
                {
                    listener?.Invoke(responseStream.Result); (6)
                }
                return responseStream.Result;
            }
        }
        catch (RpcException e)
        {
            if (e.StatusCode != StatusCode.Cancelled)
            {
                Console.WriteLine(e); (7)
                throw;
            } else
            {
                return default(TReply);
            }
        }
        catch (Exception e)
        {
            Console.WriteLine(e); (8)
            throw;
        }

    }
}
1 Define delegate for the listener
2 Define deligate for the function call
3 Create streaming call
4 Get response stream
5 Wait for the event asyncronically
6 Get result and send it to the listener
7 Process rpc error
8 Process application error

Push subscriptions

In some cases server can sent more then one answer or streams the data. This case is simular t requests, but has some differences.

  • It can come more then one results answer back

  • Server can send "break" notification to the client if no data is exist anymore

  • Client can send "break" notification to the server if no data is need anymore. See ServerSubs

push subscription

Push subscriptions can be done with help of StreamObserver. This absract class can be used to build real streamer classes. Next example shows how to use it to get market data information.

Example C#: MarketDataStreamer

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22


  
public class MarketDataStreamer : (1)
            StreamObserver<SecurityService.SecurityServiceClient, SecurityMarketDataRequest, SecurityMarketDataReply>
{
    public SecurityMarketDataRequest GetRequestWithWknAndStockId(
        string accessToken, string wkn, string stockId) (2)
    {
        SecurityMarketDataRequest marketDataRequest = new SecurityMarketDataRequest() (3)
        {
            AccessToken = accessToken,
            SecurityWithStockexchange = new SecurityWithStockExchange (4)
            {
                SecurityCode = TestUtils.GetSecurityCode(wkn, SecurityCodeType.Wkn),
                StockExchange = TestUtils.GetStockExchange(stockId, null)
            }
        };
        return marketDataRequest;
    }

    public MarketDataStreamer(SecurityService.SecurityServiceClient client) : (5)
        base(client, (request, token) => client.StreamMarketData(request, null, null, token))
    { }
}
1 Define class with client, request and reply types
2 Help function to simplify creation of the request
3 Create request
4 Fill request fields
5 Request data from server

Market data streamer allowes to subscribe for quotes for many securities

Example C#: MarketDataStreamer

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

private async Task StreamMarketDataAsync()
{

    MarketDataStreamer marketDataStreamer =
        new MarketDataStreamer(securityServiceClient); (1)

    SecurityMarketDataRequest marketDataRequestTRG = (2)
        marketDataStreamer.GetRequestWithWknAndStockId(_accessToken, "710000", "TRG");

    CancellationTokenSource tokenSource1 = new CancellationTokenSource(); (3)
    Task tickerTask1 = marketDataStreamer.Stream( (4)
       marketDataRequestTRG,
        reply => Console.WriteLine("Source (1): " + reply), (5)
        tokenSource1.Token);

    SecurityMarketDataRequest marketDataRequestOTC = (6)
        marketDataStreamer.GetRequestWithWknAndStockId(_accessToken, "710000", "OTC");

    CancellationTokenSource tokenSource2 = new CancellationTokenSource();
    Task tickerTask2 = marketDataStreamer.Stream( (7)
       marketDataRequestOTC,
        reply => Console.WriteLine("Source (2): " + reply),
        tokenSource2.Token);

    await Task.Delay(10000); (8)
    tokenSource1.Cancel(); (9)

    await Task.Delay(20000);
    tokenSource2.Cancel();
}
1 Create market data streamer (can be reused)
2 Create request on ETR
3 Create cancelation token
4 Stream data
5 Process quote tick
6 Create request on OTC
7 Stream data
8 Wait a while. Events from both subscription should be processed
9 Cancel subscription for ETR
Useful

You can modify existing code or write another code to simplify access to the service functions.

Services and functions

Access service

Access service provides functionality to validation / invalidation of the client.

Table 1. AccessService
Function Description

LoginReply = Login(LoginRequest)

Validates client by the TAPI and gets access data

LogoutReply = Logout(LogoutRequest)

Invalidates client by the TAPI and gets logout result

Client validation

Client validation should be a first request after connection initalization. To validate client you have to set a secret that was set in the ActiveTrader configuration and process a login function. As result of this function returned session access token. This token is necessary to set to each request that will be send by TAPI.

Example C#: Login

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


  
private readonly string _accessToken = "";

public string Login(string secret)
{
    var accessServiceClient =
        new AccessService.AccessServiceClient(channel); (1)
    var loginRequest = new LoginRequest()
    {
        Secret = secret (2)
    };
    var loginReply = accessServiceClient.Login(loginRequest); (3)

    if (loginReply.Error != null)
    {
        // Error handling
        Console.WriteLine(loginReply.Error);
        return null;
    }
    else
    {
        return loginReply.AccessToken; (4)
    }
}
1 Create service client
2 Set secret
3 Process validation
4 Return access token

Client invalidation

After finishing of usage of the TAPI is necessary to invalidate session. That can be done with help of the logout function.

Example C#: Logout

  
1
2
3
4
5
6
7
8
9
10
11
12
13


  
public void Logout()
{
    if (this._accessToken != "")
    {
        var accessServiceClient =
            new AccessService.AccessServiceClient(channel); (1)
        var logoutRequest = new LogoutRequest()
        {
            AccessToken = _accessToken (2)
        };
        accessServiceClient.Logout(logoutRequest); (3)
    }
}
1 Create service client
2 Set token
3 Process invalidation

Account service

Account service provides access to the trading accounts and gives possibility to access to the accounts data and transactions.

Table 2. AccountService
Function Description

TradingAccounts = GetTradingAccounts(AccessTokenRequest)

Gets trading accounts

@return TradingAccounts List of trading accounts

TradingAccountInformation ⇐ StreamTradingAccount(TradingAccountRequest)

Subscribes one trading account for updates

@param TradingAccount Trading account for push

@stream TradingAccountInformation Specific information for subscribed account (balance, kredit line, etc.)

TradingAccountTransactions ⇐ StreamTradingAccountTransactions(TradingAccountRequest)

Subscribes one trading account for the transactions updates

@param TradingAccount Trading account for push

@stream TradingAccountInformation Transactions list for subscribed account

To subscribe for the account and transactions changes you have to get trading accounts and subscribe each account with help of steam functions for data changes independently.

account process

Get list of trading accounts

Many activites need information about an account data. Most important information is a trading account number. To get list of all avialable trading accounts you have to use Get Trading Accounts function.

Example C#: GetTradingAccounts

  
1
2
3
4
5
6
7
8
9
10
11
12


  
private static readonly Empty empty = new Empty();

public TradingAccounts GetTradingAccounts()
{
    var accountServiceClient =
        new AccountService.AccountServiceClient(channel); (1)
    var accessToken = new AccessTokenRequest()
    {
        AccessToken = this._accessToken (2)
    };
    return accountServiceClient.GetTradingAccounts(accessToken); (3)
}
1 Create account service client
2 Request trading accounts and wait the result
Important

Not all accounts in the pro version of the ActiveTrader can be used for the trading functionality. Please refer to the TradingAccount and check for the access avialibility of the selected account (flag: tradable).
Useful

Typical use case is to get this information once and keep it during one connection session.

Stream account information changes

To get pushed trading account information is need to subscribe an account for the trading account stream.

Example C#: GetTradingAccounts

  
1
2
3
4
5
6
7
8
9
10


  
public TradingAccounts GetTradingAccounts()
{
    var accountServiceClient =
        new AccountService.AccountServiceClient(channel); (1)
    var accessToken = new AccessTokenRequest()
    {
        AccessToken = this._accessToken (2)
    };
    return accountServiceClient.GetTradingAccounts(accessToken); (3)
}
1 Create service client
2 Set access token
3 Process remote request

Stream account transactions changes

To get pushed trading account transactions list is need to subscribe account for trading account transactions stream.

Example C#: StreamTradingAccountInformation

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


  
public void StreamTradingAccountInformation()
{
    TradingAccounts tradingAccounts = GetTradingAccounts(); (1)
    var accountServiceClient = (2)
        new AccountService.AccountServiceClient(channel);
    AccountInformationStreamer streamer = (3)
        new AccountInformationStreamer(accountServiceClient);
    foreach (var account in tradingAccounts.Accounts) (4)
    {
        var tradingAccountRequest = new TradingAccountRequest()
        {
            AccessToken = _accessToken,
            TradingAccount = account
        };
        Task task = streamer.Stream(tradingAccountRequest, (5)
            accountInfomation =>
            {
                TradingAccount recievedAccount = accountInfomation.Account; (6)
                double balance = accountInfomation.Balance;
                // ...
                Console.WriteLine(accountInfomation);
            });
    }
}
1 Get trading accounts
2 Create client (it can be resused)
3 Create account infomation streamer
4 Iterate over each account
5 Subscribe account
6 Process account information events with help of the delegator

AccountsStreamer is the help class to encapsulate typical processing with the stream data.

Example C#: AccountsStreamer

  
1
2
3
4
5
6
7
8


  
public class AccountsStreamer :
        AsyncObserver<AccountService.AccountServiceClient, AccessTokenRequest, TradingAccounts> (1)
{
    public AccountsStreamer(AccountService.AccountServiceClient client) : (2)
        base(client, (request, token) =>
            client.GetTradingAccountsAsync(request, null, null, token))
    { }
}
1 Define class with client, request and reply types
2 Request data from server

In some cases is need to stop data streaming. In this case it can be used CancellationTokenSource that will used by stream creation.

Example C#: GetTradingAccounts

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


  
public void StreamTradingAccountInformationWithStop(TradingAccount account)
{
    var accountServiceClient = (1)
        new AccountService.AccountServiceClient(channel);
    AccountInformationStreamer streamer = (2)
        new AccountInformationStreamer(accountServiceClient);
    var tradingAccountRequest = new TradingAccountRequest()
    {
            AccessToken = _accessToken,
            TradingAccount = account
    };
    CancellationTokenSource tokenSource = new CancellationTokenSource(); (3)

    Task task = streamer.Stream(tradingAccountRequest, (4)
        accountInfomation =>
        {
                TradingAccount recievedAccount = accountInfomation.Account; (5)
                double balance = accountInfomation.Balance;
                // ...
                Console.WriteLine(accountInfomation);
        },
        tokenSource.Token); (6)

    tokenSource.Cancel(); (7)
}
1 Get trading accounts
2 Create client (it can be resused)
3 Create CancellationTokenSource
4 Create account infomation streamer
5 Subscribe account
6 . . . with cancelation token
7 Cancel stream processing

Stock exchange service

StockExchange service provides access to the stock exchanges.

Table 3. StockExchangeService
Function Description

StockExchangeDescriptions = GetStockExchanges(AccessTokenRequest)

Gets predefined stockexchages

@return StockExchangeDescriptions list of stock exchange informations

StockExchangeDescription = GetStockExchange(StockExchangeRequest)

Gets specific stock exchange

@param StockExchange Requested stock exchange

@return StockExchangeDescription Stock exchange information

Get information about all stock exchanges

TAPI has list of predefined stock exchanges that can be fetched directly. Each stock exchange has id and optional issuer. Some stock exchanges have identical id’s, but different issuers. For examples:

id issuer shortcut id stock exchange name

ETR

ETR

Xetra

OTC

BAAD

BAA

Baada bank on OTC

OTC

7649

LUS

Lang und Schwarz

OTC

7004

Commerzbank

OTC

OTC

Any issuer on OTC
Useful

It’s possible to use shortcut id, if it exists, to access to the same stock exchange. For example stock exchange ("OTC", "BAAD") equivalent to the stock exchange ("BAA","")

These stock exchanges can be requested with help of Get Stock Exchanges function. As a result will delivered stock exchanges with names.

Example C#: getStockExchanges()

  
1
2
3
4
5
6
7
8
9
10


  
private readonly StockExchangeService.StockExchangeServiceClient stockExchangeServiceClient;

public StockExchangeDescriptions GetStockExchanges()
{
    AccessTokenRequest request = new AccessTokenRequest() (1)
    {
        AccessToken = _accessToken
    };
    return stockExchangeServiceClient.GetStockExchanges(request); (2)
}
1 Prepare request
2 Call remote function
Useful

This information can be stored and reused in the user application.

Get information about specific stock exchange

It’s also possible to get information about one specific stock exchange. Next example shows how to request stock exchange information about Baada issuer on the OTC:

Example C#: GetBaadaStockExchangeInformation()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16


  
private readonly StockExchangeService.StockExchangeServiceClient stockExchangeServiceClient;

public StockExchangeDescription GetBaadaStockExchangeInformation()
{
    StockExchange stockExchange = new StockExchange() (1)
    {
        Id = "OTC",
        Issuer = "BAAD"
    };
    StockExchangeRequest request = new StockExchangeRequest() (2)
    {
        AccessToken = _accessToken,
        StockExchange = stockExchange
    };
    return stockExchangeServiceClient.GetStockExchange(request); (3)
}
1 Prepare Baada on OTC stock exchange
2 Prepare request
3 Request information about stock exchange

Depot service

With help of the depot service is possible to stream information about depot entries. Depot service has next functions:

Stream depot changes

Table 4. DepotService
Function Description

DepotEntries ⇐ StreamDepot(TradingAccountRequest)

Subscribes one trading account for the depot data updates

@param TradingAccount Trading account for push

@stream DepotEntries depot entries linked to the account

Empty = UpdateDepot(TradingAccountRequest)

Initiates depot update action. All changes come by the StreamDepot subscription. This function doesn’t wait for the action result.

@param TradingAccount Trading account for update
Example C#: StreamDepotData()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


  
private readonly DepotService.DepotServiceClient depotServiceClient;

private async Task StreamDepotData()
{
    var tradingAccounts = GetTradingAccounts(); (1)
    DepotStreamer depotStreamer = new DepotStreamer(depotServiceClient); (2)
    List<CancellationTokenSource> cancellationTokens = new List<CancellationTokenSource>();
    foreach (var tradingAccount in tradingAccounts.Accounts) (3)
    {
        var tradingAccountRequest = new TradingAccountRequest() (4)
        {
            AccessToken = _accessToken,
            TradingAccount = tradingAccount
        };

        CancellationTokenSource tokenSource = new CancellationTokenSource(); (5)
        cancellationTokens.Add(tokenSource);
        var stream = depotStreamer.Stream(tradingAccountRequest, (6)
            depotEntries => Console.WriteLine( (7)
                "Account:" + depotEntries.Account + ", Data:" + depotEntries),
            tokenSource.Token);
    }

    await Task.Delay(10000); (8)

    foreach (var cancellationTokenSource in cancellationTokens) (9)
    {
        cancellationTokenSource.Cancel();
    }
}
1 Get trading accounts
2 Greate depot streamer
3 Iterate throw all trading accounts
4 Create request
5 Create cancelation source (to stop streams)
6 Subscribe for stream, but don’t wait for results
7 Process callback by data change (listen callback)
8 Wait, for tests proposals
9 Cancel all streams

Update events are delivered on each depot entry change and contain information about whole depot.

Example C#: DepotObserver

  
1
2
3
4
5
6
7
8
9


  
public class DepotStreamer :
    StreamObserver<DepotService.DepotServiceClient, TradingAccountRequest, DepotEntries> (1)
{
    public DepotStreamer(DepotService.DepotServiceClient client) : (2)
        base(client, (request, token) =>
            client.StreamDepot(request, null, null, token))
    {
    }
}
1 Define class with client, request and reply types
2 Request data from server

Update depot

Sometime is necessary to update depot manually. To initiate this update you have to call UpdateDepot function. This function takes trading account as input parameter and doesn’t deliver any results. It’s also don’t wait for the results. All changes are delivered directly to the depot listeners in the background.

Warning

This function used for the compatibility proposals and can be removed in the future versions of the TAPI.

Security service

Securities access

All securities can be accessed with help of security codes. Typical trading securities codes are WKN and ISIN. TAPI is able to operate with additional security code types:

Security code type Tradable Description

WKN

Yes

WKN

ISIN

Yes

ISIN

ID_NOTATION

No

FactSet id notation

ID_OSI

No

FactSet id osi

ID_INSTRUMENT

No

FactSet id instrument

MNEMONIC

No

German short id

MEMONIC_US

No

US short id (only for us instruments)

Security code can be created with help of next code.

Example C#: GetSecurityCode()

  
1
2
3
4
5
6
7
8


  
public SecurityCode GetSecurityCode(string code, SecurityCodeType codeType)
{
    return new SecurityCode() (1)
    {
        Code = code, (2)
        CodeType = codeType (3)
    };
}
1 Create SecurityCode object
2 Set security code
3 Set security code type (WKN, ISIN, . . .). If type is not defined or unknown then please use NoCodeType
Important

In some cases TAPI can guess security code type by input security code value. In this case the security code type should be set to NO_CODE_TYPE value. Please care that’s not guaranty right detection of the security code. The good practice is to use security code type by the building of the security code object.

Security service contains next functions:

Table 5. SecurityService
Function Description

SecurityInfoReply = GetSecurityInfo(SecurityInfoRequest)

Gets security information about security

@param SecurityInfoRequest Request object with interested security

@return SecurityInfoReply Complete information about security

SecurityMarketDataReply ⇐ StreamMarketData(SecurityMarketDataRequest)

Subscribes security with stock exchange for market data updates

@param SecurityMarketDataRequest Market data request with interested security and stock exchange

@stream SecurityMarketDataReply Reply with all market data values

SecurityOrderBookReply ⇐ StreamOrderBook(SecurityOrderBookRequest)

Subscribes security with stock exchange for orderbook updates

@param SecurityOrderBookRequest Orderbook data request with interested security and stock exchange

@stream SecurityOrderBookReply Reply with all orderbook values

CurrencyRateReply ⇐ StreamCurrencyRate(CurrencyRateRequest)

Subscribes for currency rate from one currency to another currency.

@param SecurityOrderBookRequest currency rate request with interested currencies from/to

@stream CurrencyRateReply reply with currency rate

SecurityPriceHistoryReply = GetSecurityPriceHistory(SecurityPriceHistoryRequest)

Requests history data for one security on one stockexchange in intraday or historical format

@param SecurityPriceHistoryRequest Data with security, stockexchange, how many days and resolution

@return SecurityPriceHistoryReply List of the historical quotes or an error

Get security information

Security information can be requested with help of GetSecurityInfo function. As a result will delivered security name, class, codes and stock exchanges with trading possibilites. This information can be used by the ordering. It also contains data about tradabity on the different markets and by different issuers. The flags LimitToken with values QUOTE_ONLY and LIMIT_AND_QUOTE show if for the security is possible to use quote buy and sell on the selected market by the selected issuer. For more information please see GetQuote and AcceptQuote functions.

Example C#: RequestSecurityInfo()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

public SecurityInfoReply RequestSecurityInfo(string code, SecurityCodeType codeType)
{
    SecurityCode securityCode = new SecurityCode() (1)
    {
        Code = code,
        CodeType = codeType
    };

    SecurityInfoRequest request = new SecurityInfoRequest() (2)
    {
        AccessToken = _accessToken,
        SecurityCode = securityCode
    };

    return securityServiceClient.GetSecurityInfo(request); (3)
}
1 Create security code object
2 Create SecurityInfoRequest request
3 Request security information

Stream market data information

To get pushed market data (push courses) is need to subscribe security and stock exchange for this information with help of StreamMarketData function. SecurityMarketDataReply contains all values, which were changed.

Example C#: StreamMarketData()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

public CancellationTokenSource StreamMarketData(string code, SecurityCodeType codeType,
    string stockExchange, string currency)
{
    SecurityWithStockExchange securityWithStockExchange = new SecurityWithStockExchange() (1)
    {
        SecurityCode = new SecurityCode() (2)
        {
            Code = code,
            CodeType = codeType
        },
        StockExchange = new StockExchange() (3)
        {
            Id = stockExchange
        }
    };

    SecurityMarketDataRequest request = new SecurityMarketDataRequest() (4)
    {
        AccessToken = _accessToken,
        SecurityWithStockexchange = securityWithStockExchange,
        Currency = currency == null ? "" : currency
    };

    MarketDataStreamer marketDataStreamer =
        new MarketDataStreamer(securityServiceClient); (5)

    CancellationTokenSource tokenSource = new CancellationTokenSource(); (6)
    var task = marketDataStreamer.Stream( (7)
        request,
        reply => Console.WriteLine("Process tick: " + reply), (8)
        tokenSource.Token);

    return tokenSource; (9)
}
1 Create security with stock exchange object
2 Create security code object
3 Create stock exchange
4 Create request
5 Create streamer
6 Create cancel token source
7 Start processing in background
8 Process tick
9 Return cancel token source

An example how it can be called is to see in the next example:

Example C#: ProcessMarketDataExample()

  
1
2
3
4
5
6
7
8
9


  
public void ProcessMarketDataExample()
{
    CancellationTokenSource tokenSource = (1)
        StreamMarketData("710000", SecurityCodeType.Wkn, "OTC", "");

    System.Threading.Thread.Sleep(1000); (2)

    tokenSource.Cancel(); (3)
}
1 Call function syncronically and get cancel token source
2 Wait a while. Events from subscription should be processed
3 Cancel streaming

Update events deliver changed market data values.

To subscribe for the market data information it is necessary to create SecurityWithStockExchange object.

Example C#: GetSecurityWithStockExchange()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17


  
public SecurityWithStockExchange GetSecurityWithStockExchange(string code, SecurityCodeType codeType,
    string stockExchange, string issuer = "")
{
    return new SecurityWithStockExchange() (1)
    {
        SecurityCode = new SecurityCode() (2)
        {
            Code = code,
            CodeType = codeType
        },
        StockExchange = new StockExchange() (3)
        {
            Id = stockExchange,
            Issuer = issuer == null ? "" : issuer
        }
    };
}
1 Create security with stock exchange object
2 Create security code object
3 Create stock exchange

Stream orderbook data

To get pushed orderbook data (second level push courses) is need to subscribe security and stockexchange for this information with help of StreamOrderBook function. SecurityOrderBookReply contains actual orderbook values. To create SecurityOrderBookRequest is need to create SecurityWithStockExchange object first. Currently order book data supported only on Xetra stock exchange.

Example C#: StreamOrderBook()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

public CancellationTokenSource StreamOrderBook(string code, SecurityCodeType codeType,
    string stockExchange, string currency)
{
    SecurityWithStockExchange securityWithStockExchange = new SecurityWithStockExchange() (1)
    {
        SecurityCode = new SecurityCode() (2)
        {
            Code = code,
            CodeType = codeType
        },
        StockExchange = new StockExchange() (3)
        {
            Id = stockExchange
        }
    };

    SecurityOrderBookRequest request = new SecurityOrderBookRequest() (4)
    {
        AccessToken = _accessToken,
        SecurityWithStockexchange = securityWithStockExchange,
        Currency = currency == null ? "" : currency
    };

    OrderBookStreamer orderBookStreamer =
        new OrderBookStreamer(securityServiceClient); (5)

    CancellationTokenSource tokenSource = new CancellationTokenSource(); (6)
    var task = orderBookStreamer.Stream( (7)
        request,
        reply => Console.WriteLine("Process tick: " + reply), (8)
        tokenSource.Token);

    return tokenSource; (9)
}
1 Create security with stock exchange object
2 Create security code object
3 Create stock exchange
4 Create request
5 Create streamer
6 Create cancel token source
7 Start processing in background
8 Process tick
9 Return cancel token source
Example C#: ProcessOrderBookExample()

  
1
2
3
4
5
6
7
8
9


  
public void ProcessOrderBookExample()
{
    CancellationTokenSource tokenSource = (1)
        StreamOrderBook("710000", SecurityCodeType.Wkn, "ETR", "");

    System.Threading.Thread.Sleep(1000); (2)

    tokenSource.Cancel(); (3)
}
1 Call function syncronically and get cancel token source
2 Wait a while. Events from subscription should be processed
3 Cancel streaming
Example C#: OrderBookStreamer

  
1
2
3
4
5
6
7
8


  
class OrderBookStreamer : (1)
    StreamObserver<SecurityService.SecurityServiceClient, SecurityOrderBookRequest, SecurityOrderBookReply>
{

    public OrderBookStreamer(SecurityService.SecurityServiceClient client) : (2)
        base(client, (request, token) => client.StreamOrderBook(request, null, null, token))
    { }
}
1 Define class with client, request and reply types
2 Request data from server

Stream currency rate

It is possible to get pushed currency rate from one currency to other. This information can be used for the realtime convertation of the money values.

Important

For the market data quotes / order books it is possible to define target currency. It this case the convertation will be processed automatically.
Example C#: StreamCurrencyRate()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

public CancellationTokenSource StreamCurrencyRate(string currencyFrom, string currencyTo)
{
    CurrencyRateRequest request = new CurrencyRateRequest() (1)
    {
        AccessToken = _accessToken,
        CurrencyFrom = currencyFrom,
        CurrencyTo = currencyTo
    };

    CurrencyRateStreamer currencyRateStreamer =
        new CurrencyRateStreamer(securityServiceClient); (2)

    CancellationTokenSource tokenSource = new CancellationTokenSource(); (3)
    var task = currencyRateStreamer.Stream( (4)
        request,
        reply => Console.WriteLine("Process tick: " + reply), (5)
        tokenSource.Token);

    return tokenSource; (6)
}
1 Create request
2 Create streamer
3 Create cancel token source
4 Start processing in background
5 Process tick
6 Return cancel token source
Example C#: CurrencyRateDataObserver

  
1
2
3
4
5
6
7
8


  
class CurrencyRateStreamer : (1)
    StreamObserver<SecurityService.SecurityServiceClient, CurrencyRateRequest, CurrencyRateReply>
{

    public CurrencyRateStreamer(SecurityService.SecurityServiceClient client) : (2)
        base(client, (request, token) => client.StreamCurrencyRate(request, null, null, token))
    { }
}
1 Define class with client, request and reply types
2 Request data from server

Get security historic data

Security historic data can be requested with help of getSecurityPriceHistory() function. As a result will delivered security with stock exchange, currency, historic data list. The parameter days defines how many trading day will be requested. For intraday types of the time resolution this value should be 15 or less. Be careful the amount of the data can be very big, especialy for intraday data with tick resolution.

Example C#: GetSecurityPriceHistory()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17


  
private readonly SecurityService.SecurityServiceClient securityServiceClient;

public SecurityPriceHistoryReply GetSecurityPriceHistory(string code, SecurityCodeType codeType,
    string stockExchange, int days, TimeResolution timeResolution)
{
    var securityWithStockExchange = (1)
        GetSecurityWithStockExchange(code, codeType, stockExchange);
    SecurityPriceHistoryRequest request = new SecurityPriceHistoryRequest() (2)
    {
        AccessToken = _accessToken,
        SecurityWithStockexchange = securityWithStockExchange,
        Days = days,
        TimeResolution = timeResolution
    };

    return securityServiceClient.GetSecurityPriceHistory(request); (3)
}
1 Create security with stock exchange object
2 Create request
3 Call function
Important

Last example will block program execution until the result is returned. Sometimes to avoid timeouts by the listening it’s better to use non blocking calls.

Order service

With help of the order service is possible to execute, change, activate, deactivate or cancel orders. It’s also allow to listen for the orders and to control them asyncronically.

Order types and parameters

TAPI allowes to execute different order types on the stock exchanges with different parameters. Next tables shows what parameters are necessary (x) and optional (o) depends from selected stock exchange and order model. The full list of order possibilites is delivered by the GetSecurityInformation function.

Parameter \ Order model Market Limit StopMarket StopLimit OneCancelsOtherMarket OneCancelsOtherLimit TrailingStopMarket TrailingStopLimit

account_number

x

x

x

x

x

x

x

x

security_with_stockexchange

x

x

x

x

x

x

x

x

order_type

x

x

x

x

x

x

x

x

amount

x

x

x

x

x

x

x

x

order_supplement

o, 1)

o, 1)

validity_date

x

x

x

x

x

x

x

x

limit

x

x

x

stop

x

x

x

x

x

x

stop_limit

x

x

trailing_distance

x

x

trailing_notation

x

x

trailing_limit_tolerance

x, 2)

dripping_quantity

o, 3)

o, 3)

position_id

o, 4)

o, 4)

o, 4)

o, 4)

o, 4)

o, 4)

o, 4)

o, 4)

validation

o ,5)

o ,5)

o ,5)

o ,5)

o ,5)

o ,5)

o ,5)

o ,5)

cash_quotation

o, 6)

o, 6)

o, 6)

o, 6)

o, 6)

o, 6)

o, 6)

o, 6)

risk_class_override

o

o

o

o

o

o

o

o

target_market_override

o

o

o

o

o

o

o

o

tax_nontransparent_override

o

o

o

o

o

o

o

o

accept_additional_fees

o

o

o

o

o

o

o

o

closed_realestate_fond_override

o

o

o

o

o

o

o

o
1 Stock exchange: ETR only, values: IMMIDIATE_OR_CANCEL, FILL_OR_KILL, ICEBERG
2 Stock exchange: TRG only
3 Stock exchange: ETR only, when order_supplement equals ICEBERG, pro only
4 Position id is optional field by the order action with existing depot position
5 Default value: WITHOUT_VALIDATION. Order is routed directly to market
6 Cash quotation:
Stock exchange NOTHING KASSA AUCTION OPENING INTRADAY CLOSING

ETR

x

x

x

x

x

x

German

x

x

Other

x

The full list of the order service functions can be checked in the next list. Some functionality avialable only in pro version of the ActiveTrader.

Important

To execute new order is need at least to fill all madatory fields. See x values in the each column for selected order model.

Stream orders

To get information about current orders ist need to subscribe for this information with help of StreamOrders function. All order changes will come asynchronically as a list of the all avialable orders.

Useful

An amount of the updated orders can be configured in the ActiveTrader general settings.
Example C#: StreamOrders()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public CancellationTokenSource StreamOrders(TradingAccount tradingAccount)
{
    TradingAccountRequest request = new TradingAccountRequest() (1)
    {
        AccessToken = _accessToken,
        TradingAccount = tradingAccount
    };

    OrdersStreamer ordersStreamer = new OrdersStreamer(orderServiceClient); (2)

    CancellationTokenSource tokenSource = new CancellationTokenSource(); (3)

    var task =ordersStreamer.Stream( (4)
        request,
        reply => Console.WriteLine("Process orders: " + reply), (5)
        tokenSource.Token);

    return tokenSource; (6)
}
1 Create request
2 Create streamer
3 Create cancel token source
4 Start processing in background
5 Process tick
6 Return cancel token source
Example C#: OrdersStreamer

  
1
2
3
4
5
6
7


  
class OrdersStreamer : (1)
    StreamObserver<OrderService.OrderServiceClient, TradingAccountRequest, Orders>
{
    public OrdersStreamer(OrderService.OrderServiceClient client) : (2)
        base(client, (request, token) => client.StreamOrders(request, null, null, token))
    { }
}
1 Define class with client, request and reply types
2 Request data from server
Important

In the pro version of the ActiveTrader order number value can be changed (for example after activation / deactivation of the order). To match saved in the client application orders with the orders from update is need to use unique_id field from the Order object.

Update orders

Sometime is necessary to update orders manually. To initiate this update you have to call UpdateOrders function. This function takes trading account as input parameter and doesn’t deliver any results. It’s also don’t wait for the results. All changes are delivered directly to the orders listeners in the background.

Warning

This function used for the compatibility proposals and can be removed in the future versions of the TAPI.

Get securities quotes

Before to execute order add action is often necessary to get actual quote information for the selected security. This information can be subscribed in the security service or requested in the order service. It’s not a matter where this information is requested for the normal order add action, but it’s important in case if you want to process accept quote on the short term market. In this case is necessary to use get quote function from order service.

Important

Please call get quote function before to call of the accept order action.
Example C#: RequestQuotesDirect()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public void RequestQuotesDirect(string code, SecurityCodeType codeType)
{
    QuoteRequest request = new QuoteRequest() (1)
    {
        AccessToken = _accessToken,
        OrderType = OrderType.Buy,
        SecurityCode = new SecurityCode()
        {
            Code = code,
            CodeType = codeType
        },
        Amount = 10,
        StockExchanges =
        {
            GetStockExchange("BAA"), (2)
            GetStockExchange("OTC"),
            GetStockExchange("TRG")
        }
    };

    QuoteReply quoteReply = orderServiceClient.GetQuote(request); (3)

    if (quoteReply.Error == null) (4)
    {
        foreach (var quoteEntry in quoteReply.PriceEntries) (5)
        {
            if (quoteEntry.Error == null) (6)
            {
                Console.Write("Quote: " + quoteEntry);
            }
            else
            {
                Console.Write("Error: "+quoteEntry.Error);
            }

        }
    }
}
1 Prepare request
2 Set requested stock exchanges
3 Process request
4 Check requests errors
5 Iterate results
6 Check results errors

Other difference between quotes from the security service and order service is that it’s depended from user rights. An order service can have limited amount of the requests for the long terms stockexchanges. You can request data more then from one stock exchange for one security at once. In this case function returns all results for all requested stock exchanges after processing of all data for each stock exchange. That can follow to the timeouts by the functions calls. You can use asychronical requests if to don’t have timeouts is important. It’s also possible to process many get quote requests in parallel and pack to each request only one stockexchange. The results from the requests can be processed in background.

Example C#: RequestQuotesAsynchronically()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public QuoteReply RequestQuotesAsynchronically(string code, SecurityCodeType codeType)
{
    SecurityCode securityCode = new SecurityCode() (1)
    {
        Code = code,
        CodeType = codeType
    };
    StockExchange[] stockExchanges = (2)
    {
        GetStockExchange("BAA"),
        GetStockExchange("OTC"),
        GetStockExchange("TRG")
    };

    CountdownEvent countdown = new CountdownEvent(3); (3)
    object resultsLock = new object();
    QuoteReply reply = null;

    foreach (var stockExchange in stockExchanges) (4)
    {
        QuoteRequest request = new QuoteRequest() (5)
        {
            AccessToken = _accessToken,
            OrderType = OrderType.Buy,
            Amount = 10,
            SecurityCode = securityCode,
            StockExchanges = {stockExchange}
        };

        var taskAwaiter = orderServiceClient.GetQuoteAsync(request).GetAwaiter(); (6)
        taskAwaiter.OnCompleted(() => (7)
        {
            QuoteReply currentReply = taskAwaiter.GetResult(); (8)
            lock (resultsLock)
            {
                if (currentReply != null &&
                    currentReply.Error == null &&
                    currentReply.PriceEntries.Count>0)
                {
                    // Find lowest buy price
                    if (reply == null ||
                        currentReply.PriceEntries[0].BuyPrice < reply.PriceEntries[0].BuyPrice)
                    {
                        reply = currentReply;
                    }
                }
            }
            countdown.Signal();
        });
    }
    countdown.WaitHandle.WaitOne(); (9)
    return reply;
}
1 Prepare security code
2 Prepare stock exchanges
3 Prepare count down counter (to process 3 requests)
4 Iterate all stock exchanges
5 Create request
6 Start request in background and get awaiter to listen for the results
7 Create continuation to process results
8 Get result, select one with lowest buy price, send signal to the countdown to reduce amount of the active requests
9 Listen for the countdown.

Main execution thread starts requests to process them in the background and wait for the results. It’s possible to modify the code to provide fully background processing.

quotebackground grpc csharp

Accept quote

To place an order on the short term market is necessary to request quote first. If QuoteEntry will contain filled quote_reference field then it’s possible to place order with help of accept quote function to the short term market. Otherwise accept quote is not possible. By the calling of the accept quote function you have to use same parameters as you used for the get quote. Otherwise the request parameters will be denied and the action will be finished with an error.

Example C#: AcceptQuote()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply AcceptQuote(string code, SecurityCodeType codeType)
{
    var stockExchange = GetStockExchange("OTC");
    var securityCode = new SecurityCode()
    {
        Code = code,
        CodeType = codeType
    };
    QuoteRequest request = new QuoteRequest() (1)
    {
        AccessToken = _accessToken,
        OrderType = OrderType.Buy,
        SecurityCode = securityCode,
        Amount = 10,
        StockExchanges =
        {
            stockExchange,
        }
    };

    QuoteReply quoteReply = orderServiceClient.GetQuote(request); (2)
    if (quoteReply != null &&
        quoteReply.Error != null)
    {
        var quoteReplyPriceEntry = quoteReply.PriceEntries[0];
        if (quoteReplyPriceEntry.Error != null && (3)
            quoteReplyPriceEntry.QuoteReference != null)
        {
            AcceptQuoteRequest acceptQuoteRequest = new AcceptQuoteRequest() (4)
            {
                AccessToken = _accessToken,
                AccountNumber = "123456789",
                OrderType = OrderType.Buy,
                SecurityWithStockexchange = new SecurityWithStockExchange()
                {
                    SecurityCode = securityCode,
                    StockExchange = stockExchange
                },
                Amount = 10,
                Validation = Validation.ValidateOnly,
                Limit = quoteReplyPriceEntry.BuyPrice, (5)
                QuoteReference = quoteReplyPriceEntry.QuoteReference (6)
            };
            return orderServiceClient.AcceptQuote(acceptQuoteRequest); (7)
        }
    }
    return null;
}
1 Prepare get quote request
2 Call get quote function
3 Check quote result (it should be only one quote) and we have quote reference
4 Create accept quote request
5 Set limit with the data from quote reply
6 Set quote reference from quote reply
7 Process accept quote request
Warning

By default validation parameter equals WITHOUT_VALIDATION and accept quote request will directly routed to the market. If you want only check a validity of the request, then you need to set validation parameter to VALIDATE_ONLY. An order will validated by the backend system, but will not be routed to the market. It’s very useful for the test goals. Order number in the reply in this case is undefined.

Add order

To put new order to the long term marken is necessary to use AddOrder function. This function takes AddOrderRequest as an input parameter and returns OrderReply as a result. Typically this function is called with blocked stub, but it can also used with non blocking stub if more then one order need to executed in parallel.

The possible parameter combinations can be fetched from security information reply. There are defined order possibilities for defined markets.

Pro version of the ActiveTrader allowes to use additional flag inactive. If this flag set to the value true then order is placed to the system, but isn’t routed to the market. With the help of ActivateOrder function an order can be activated.

Important

It’s important to fill only parameters that need for the order execution
Example C#: AddOrder()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public Date GetTodayDate()
{
    DateTime localDate = DateTime.Now;
    return new Date()
    {
        Day = localDate.Day,
        Month = localDate.Month,
        Year = localDate.Year
    };
}

public OrderReply AddOrder(TradingAccount tradingAccount)
{
    if (tradingAccount != null)
    {
        AddOrderRequest request = new AddOrderRequest()
        {
            AccessToken = _accessToken,
            AccountNumber = tradingAccount.AccountNumber, (1)
            SecurityWithStockexchange = new SecurityWithStockExchange() (2)
            {
                SecurityCode = new SecurityCode()
                {
                    Code = "710000",
                    CodeType = SecurityCodeType.Wkn
                },
                StockExchange = GetStockExchange("OTC")
            },
            Validation = Validation.ValidateOnly, (3)
            Amount = 1,
            OrderModel = OrderModel.Limit, (4)
            Limit = 1,
            OrderType = OrderType.Buy, (5)
            CashQuotation = CashQuotation.Kassa,
            ValidityDate = GetTodayDate() (6)
        };
        return orderServiceClient.AddOrder(request); (7)
    }

    return null;
}
1 Set trading account
2 Set security with stock exchange
3 Set validation flag
4 Set order model
5 Set order type
6 Set validity date
7 Process order add
Warning

By default validation parameter equals WITHOUT_VALIDATION and accept quote request will directly routed to the market. If you want only check a validity of the request, then you need to set validation parameter to VALIDATE_ONLY. An order will validated by the backend system, but will not be routed to the market. It’s very useful for the test goals. Order number in the reply in this case is undefined.

Change order

To change order is necessary to have order number of existing order and an account with this order linked to. The order can be changed if the status of the orders allowes that and new state is allowed by the markt.

Useful

Sometimes can happens that order is changed / executed on the market, but status information is not delivered into the application.
Example C#: ChangeOrder()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply ChangeOrder(Order order, TradingAccount tradingAccount)
{
    if (order != null && tradingAccount != null)
    {
        string orderNumber = order.OrderNumber;
        if (orderNumber != null && !orderNumber.Equals(""))
        {
            ChangeOrderRequest request = new ChangeOrderRequest() (1)
            {
                AccessToken = _accessToken,
                AccountNumber = tradingAccount.AccountNumber, (2)
                OrderNumber = orderNumber, (3)
                Validation = Validation.ValidateOnly, (4)
                OrderModel = OrderModel.Limit, (5)
                Limit = 2
            };

            return orderServiceClient.ChangeOrder(request); (6)
        }
    }
    return null;
}
1 Create request
2 Set account number
3 Set order number
4 Set validation flag
5 Set new limit
6 Process change order
Warning

By default validation parameter equals WITHOUT_VALIDATION and accept quote request will directly routed to the market. If you want only check a validity of the request, then you need to set validation parameter to VALIDATE_ONLY. An order will validated by the backend system, but will not be routed to the market. It’s very useful for the test goals.

Cancel order

To cancel order is necessary to have order number of existing order and an account with this order linked in. The order can be canceled if the status of the orders allowes that.

Example C#: CancelOrder()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply CancelOrder(Order order, TradingAccount tradingAccount)
{
    if (order != null && tradingAccount != null)
    {
        string orderNumber = order.OrderNumber;
        if (orderNumber != null && !orderNumber.Equals(""))
        {
            CancelOrderRequest request = new CancelOrderRequest() (1)
            {
                AccessToken = _accessToken,
                AccountNumber = tradingAccount.AccountNumber, (2)
                OrderNumber = orderNumber, (3)
                Validation = Validation.ValidateOnly, (4)
            };

            return orderServiceClient.CancelOrder(request); (5)
        }
    }
    return null;
}
1 Create request
2 Set account number
3 Set order number
4 Set validation flag
5 Process change order
Warning

By default validation parameter equals WITHOUT_VALIDATION and accept quote request will directly routed to the market. If you want only check a validity of the request, then you need to set validation parameter to VALIDATE_ONLY. An order will validated by the backend system, but will not be routed to the market. It’s very useful for the test goals.

Activate order

Activate order function used to activate inactive order and route an order to the market. This function available only in pro version of the ActiveTrader.

Example C#: ActivateOrder()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply ActivateOrder(Order order, TradingAccount tradingAccount)
{
    if (order != null && tradingAccount != null)
    {
        string orderNumber = order.OrderNumber;
        if (orderNumber != null && !orderNumber.Equals(""))
        {
            ActivateOrderRequest request = new ActivateOrderRequest() (1)
            {
                AccessToken = _accessToken,
                AccountNumber = tradingAccount.AccountNumber, (2)
                OrderNumber = orderNumber, (3)
                Validation = Validation.ValidateOnly, (4)
            };

            return orderServiceClient.ActivateOrder(request); (5)
        }
    }
    return null;
}
1 Create request
2 Set account number
3 Set order number
4 Set validation flag
5 Process change order

Deactivate order

Deactivate order function used to deactivate active order and remove an order from the market. This function available only in pro version of the ActiveTrader.

Example C#: DeactivateOrder()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply DeactivateOrder(Order order, TradingAccount tradingAccount)
{
    if (order != null && tradingAccount != null)
    {
        string orderNumber = order.OrderNumber;
        if (orderNumber != null && !orderNumber.Equals(""))
        {
            DeactivateOrderRequest request = new DeactivateOrderRequest() (1)
            {
                AccessToken = _accessToken,
                AccountNumber = tradingAccount.AccountNumber, (2)
                OrderNumber = orderNumber, (3)
                Validation = Validation.ValidateOnly, (4)
            };

            return orderServiceClient.DeactivateOrder(request); (5)
        }
    }
    return null;
}
1 Create request
2 Set account number
3 Set order number
4 Set validation flag
5 Process change order

Order costs

BaFin Rules

The law allowes to execute orders only after requesting of the order costs with a possibility to decline order in the case if order costs are not accepted. That follows to request order cost before order execution. The order execution without requesting of the order costs is not allowed.

Processing of the order costs

You can request an information about estimated order costs in AddOrderRequest and AcceptQuoteRequest.

Warning

OrderCost contains only estimated values. The real values are depended from real execution quotes, time of the execution and other parameters.

To request cost information is need to execute orders requests with Validation values VALIDATE_WITH_TOTAL_COSTS, TOTAL_COST_ONLY or VALIDATE_WITH_DETAIL_COSTS. In first and second cases only total or aggregated costs are calculated. In second case detail information about costs is delivered. In all cases only validation of the request is happened, without real execution. To execute order you have to repeat same request with Validation WITHOUT_VALIDATION type.

Important

During prepartion phase TOTAL_COST_ONLY validation type can be replaced with VALIDATE_WITH_TOTAL_COSTS type.

All order costs can be checked in the online archive.

order costs
Error handling

If no costs are avialable or costs information is outdated then by the order execution will be return ORD_COSTS_ABSENT_ERR error. In such cases is necessary to repeat order costs request and order execution request.

order costs repat
Useful

To speed up order execution and save time by the order placement it’s possible to prepare and validate order with VALIDATE_WITH_TOTAL_COSTS or TOTAL_COST_ONLY flags and some time later execute the same order with WITHOUT_VALIDATION flag. The host system will recognize parameters of the order and will forward order directly to the market. Otherwise to fullfil all BaFin requirements host system will request order costs before the order execution. In the each case the information about order costs will be placed into online archive before the order execution.
Warning

This request doesn’t send order to the market, but validates only. As the result no real order is placed into the system.
Example C#: GetOrderCosts()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


  
private readonly OrderService.OrderServiceClient orderServiceClient;

OrderReply GetOrderCosts(TradingAccount tradingAccount)
{
    AddOrderRequest request = new AddOrderRequest()
    {
        AccessToken = _accessToken,
        AccountNumber = tradingAccount.AccountNumber, (1)
        SecurityWithStockexchange = new SecurityWithStockExchange() (2)
        {
            SecurityCode = new SecurityCode()
            {
                Code = "710000",
                CodeType = SecurityCodeType.Wkn
            },
            StockExchange = GetStockExchange("OTC")
        },
        Validation = Validation.ValidateWithTotalCosts, (3)
        // Validation = Validation.ValidateWithDetailCosts,
        Amount = 1,
        OrderModel = OrderModel.Limit, (4)
        Limit = 1,
        OrderType = OrderType.Buy, (5)
        CashQuotation = CashQuotation.Kassa,
        ValidityDate = GetTodayDate() (6)
    };
    OrderReply orderReply = orderServiceClient.AddOrder(request); (7)

    if (orderReply.Error != null)
    {
        OrderCosts orderCosts = orderReply.OrderCosts; (8)
        double estimatedCosts = orderCosts.EstimatedTotalCosts;
        foreach (var categorieCost in orderCosts.CategorieCosts) (9)
        {
            double totalSubAbsolute = categorieCost.TotalSumAbsolute;
            // ...
        }
    }

    Console.WriteLine("Costs reply:"+orderReply);
    return orderReply;
}
1 Set account number
2 Set security with stock exchange
3 Set validation (It should be ValidateWithTotalCosts or ValidateWithDetailCosts)
4 Set order model
5 Set order type
6 Set validity date
7 Process request
8 Extract order costs
9 Check costs by the categorie
Early request of the order costs
Useful

It’s possible to prepare an order for the execution and keep an infomation about order costs for the future execution without additional checks. This information will be cached in the application and reused by the real order execution. No additional steps will be performed. All data about order costs will be (additionally) avialible in the online archive.

It’s important to understand that sometime costs information can be absolette. In this case an order execution will be failed with the error ORD_COSTS_NOT_REQUESTED. In such cases is need to repeat order costs request and order execution request.
Example C#: AddOrderWithCostsRequest()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply AddOrderWithCostsRequest(TradingAccount tradingAccount)
{
    if (tradingAccount != null)
    {
        AddOrderRequest costsRequest = new AddOrderRequest() (1)
        {
            AccessToken = _accessToken,
            AccountNumber = tradingAccount.AccountNumber,
            SecurityWithStockexchange = new SecurityWithStockExchange() (2)
            {
                SecurityCode = new SecurityCode()
                {
                    Code = "710000",
                    CodeType = SecurityCodeType.Wkn
                },
                StockExchange = GetStockExchange("OTC")
            },
            Validation = Validation.TotalCostsOnly, (3)
            Amount = 1,
            OrderModel = OrderModel.Limit,
            Limit = 1,
            OrderType = OrderType.Buy, (4)
            CashQuotation = CashQuotation.Kassa,
            ValidityDate = GetTodayDate()
        };

        OrderReply costsReply = orderServiceClient.AddOrder(costsRequest); (5)
        if (costsReply.Error != null) (6)
        {
            Console.WriteLine(costsReply.Error);
            return costsReply;
        }

        AddOrderRequest request = new AddOrderRequest() (7)
        {
            AccessToken = _accessToken,
            AccountNumber = tradingAccount.AccountNumber,
            SecurityWithStockexchange = new SecurityWithStockExchange()
            {
                SecurityCode = new SecurityCode()
                {
                    Code = "710000",
                    CodeType = SecurityCodeType.Wkn
                },
                StockExchange = GetStockExchange("OTC")
            },
            Validation = Validation.WithoutValidation, (8)
            Amount = 1,
            OrderModel = OrderModel.Limit,
            Limit = 1,
            OrderType = OrderType.Buy,
            CashQuotation = CashQuotation.Kassa,
            ValidityDate = GetTodayDate()
        };
        return orderServiceClient.AddOrder(request); (9)
    }

    return null;
}
1 Prepare costs request
2 Prepare stock exchange
3 Use total costs only
4 Set order parameters
5 Process costs calulation request
6 Check errors
7 Prepare execution request
8 Prepare real order add request (Warning real execution)
9 Process order execution
Example C#: AcceptQuoteWithCostsRequest()

  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


  
private readonly OrderService.OrderServiceClient orderServiceClient;

public OrderReply AcceptQuoteWithCostsRequest(string code, SecurityCodeType codeType)
{
    var stockExchange = GetStockExchange("OTC");
    var securityCode = new SecurityCode()
    {
        Code = code,
        CodeType = codeType
    };
    AcceptQuoteRequest acceptQuoteCostsRequest = new AcceptQuoteRequest() (1)
    {
        AccessToken = _accessToken,
        AccountNumber = "123456789",
        OrderType = OrderType.Buy,
        SecurityWithStockexchange = new SecurityWithStockExchange()
        {
            SecurityCode = securityCode,
            StockExchange = stockExchange
        },
        Validation = Validation.TotalCostsOnly, (2)
        Amount = 10, (3)
    };
    OrderReply costsReply = orderServiceClient.AcceptQuote(acceptQuoteCostsRequest); (4)

    if (costsReply.Error != null) (5)
    {
        Console.WriteLine(costsReply.Error);
        return costsReply;
    }

    // Sometimes later
    QuoteRequest request = new QuoteRequest() (6)
    {
        AccessToken = _accessToken,
        OrderType = OrderType.Buy,
        SecurityCode = securityCode,
        Amount = 10,
        StockExchanges =
        {
            stockExchange,
        }
    };


    QuoteReply quoteReply = orderServiceClient.GetQuote(request); (7)
    if (quoteReply != null &&
        quoteReply.Error != null)
    {
        var quoteReplyPriceEntry = quoteReply.PriceEntries[0];
        if (quoteReplyPriceEntry.Error != null &&
            quoteReplyPriceEntry.QuoteReference != null)
        {
            AcceptQuoteRequest acceptQuoteRequest = new AcceptQuoteRequest() (8)
            {
                AccessToken = _accessToken,
                AccountNumber = "123456789",
                OrderType = OrderType.Buy,
                SecurityWithStockexchange = new SecurityWithStockExchange()
                {
                    SecurityCode = securityCode,
                    StockExchange = stockExchange
                },
                Amount = 10,
                Validation = Validation.WithoutValidation, (9)
                Limit = quoteReplyPriceEntry.BuyPrice, (10)
                QuoteReference = quoteReplyPriceEntry.QuoteReference (11)
            };
            return orderServiceClient.AcceptQuote(acceptQuoteRequest); (12)
        }
    }
    return null;
}
1 Prepare costs request
2 Set validation only with total costs
3 Limit is optional, Quote reference can be empty
4 Process costs calulation request
5 Check errors
6 Prepare quote request
7 Process quote request
8 Prepare accept quote request
9 Set validation (Warning real execution)
10 Set order parameters
11 Set quote reference
12 Process order execution

Errors

Error code Target Description

ACC_NOT_TRADING_ERR

Ordering

Process order with not trading account

ACC_NOT_VALID_ERR

Ordering

Process order with invalid account

ORD_ACTIVE_ERR

Ordering

Inactivate order in non pro version

ORD_AMOUNT_ERR

Ordering

Orders amount is not changable for selected order

ORD_DRIPPING_QUANTITY_ERR

Ordering

Dripping quantity error

ORD_COSTS_ERR

Ordering

Order costs information unavialable

ORD_COSTS_ABSENT_ERR

Ordering

Order costs information is not cached.

ORD_LIMIT_ERR

Ordering

Limit field is invalid

ORD_MODEL_ERR

Ordering

Order model is wrong

ORD_NOT_CANCELABLE_ERR

Ordering

Order is not cancelable

ORD_NOT_KNOWN_ERR

Ordering

Order is not known by the system

ORD_STOP_ERR

Ordering

Order stop is not changable

ORD_STOP_LIMIT_ERR

Ordering

Stop limit is not changable

ORD_TRALING_DISTANCE_ERR

Ordering

Traling distance is not changable

ORD_TRALING_LIMIT_TOLERANCE_ERR

Ordering

Traling limit tolerance is not changable

ORD_VALIDITY_DATE_ERR

Ordering

Validity date is not changable

ORD_WRONG_PRICE_TICKET_ERR

Ordering

Price ticket is not correct for this accept quote

ORD_QUOTE_ERR

Ordering

Quote is not valid

ORD_VALIDATION_ERR

Ordering

Selected validation can not be use for this request

ORD_COSTS_NOT_REQUESTED

Ordering

Costs are not requested before order or costs information is old

STK_NOT_FOUND_ERR

Stocks

Stock exchange is unknown

INTERNAL_ERR

System

Internal engine error

SYSTEM_ERR

System

GRPC error

UNSUPPORTED_OPERATION_ERR

System

Operation is not supported

Objects and types description

AcceptQuoteRequest

Accept quote request represents information about one order that should be placed on the short term market

Field Type Description

access_token

string

Access token

account_number

string

Trading account number

security_with_stockexchange

SecurityWithStockExchange

Security code with stock exchange

order_type

OrderType

Order type. It should be relevant to the requested GetQuoteRequest

amount

double

Amount, It should be relevant to the requested GetQuoteRequest

limit

double

Limit

quote_reference

string

Quote reference from GetQuoteRequest

validation

Validation

Validation flag. If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market.
If value is VALIDATE_ONLY then backend system doesn’t send order actions to the market, but validate order parameters.
If value is VALIDATE_WITH_TOTAL_COSTS then order will validated by backend system and request total costs for the order.
If value is VALIDATE_WITH_DETAIL_COSTS then order will validated by backend system and request detail costs for the order.

risk_class_override

bool

Risk class override flag. If true then allowes override user risk class

target_market_override

bool

Target market override flag. If true then allowes override target market

tax_nontransparent_override

bool

Tax non trasparent override flag. If true then allowes override tax intransparesity

accept_additional_fees

bool

Accept additinal fees flag. If true then allowes accept non transparent fees

AccessTokenRequest

Access token request contains an access token data

Field Type Description

access_token

string

Access token

ActivateOrderRequest

Activate order request represents information for activation of one inactive order pro only

Field Type Description

access_token

string

Access token

account_number

string

Trading account number

order_number

string

Order number for that this changes should be accepted

validation

Validation

Validation flag. This request allowes only WITHOUT_VALIDATION and VALIDATE_ONLY values.
If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market.
If value is VALIDATE_ONLY then backend system doesn’t send order actions to the market, but validate order parameters.

AggregatedCosts

Aggregated costs contain an information about estimated costs for the selected order

Field Type Description

in_costs_absolute

double

In costs for the order

in_costs_relative

double

Percentage part of the in costs

in_costs_currency

string

Currency for the in costs

out_costs_absolute

double

Out costs for the order

out_costs_relative

double

Percentage part of the out costs

out_costs_currency

string

Currency for the out costs

instrument_costs_absolute

double

Instrument costs for the order

instrument_costs_relative

double

Percentage part of the instrument costs

instrument_costs_currency

string

Currency for the instrument costs

service_costs_absolute

double

Service costs for the order

service_costs_relative

double

Percentage part of the service costs

service_costs_currency

string

Currency for the servcie costs

subsidy_costs_absolute

double

Subsidy costs for the order

subsidy_costs_relative

double

Percentage part of the subsidy costs

subsidy_costs_currency

string

Currency for the subsidy costs

foreign_currency_costs_absolute

double

Foreign currency costs for the order

foreign_currency_costs_relative

double

Percentage part of the foreign currency costs

foreign_currency_costs_currency

string

Currency for the foreign currency costs

performance_impact_absolute

double

Performance impact for the order

performance_impact_relative

double

Percentage part of the performance impact

performance_impact_currency

string

Currency for the performance impact

expected_amount

double

Expected amount estimated for the order

expected_amount_currency

string

Currency for the expected amount

AddOrderRequest

Add order request represents order data for the long term markets

Field Type Description

access_token

string

Access token

account_number

string

Trading account number which used for the execution

security_with_stockexchange

SecurityWithStockExchange

Security code with stock exchange

order_type

OrderType

Order type

amount

double

Amount of the securities

order_model

OrderModel

Order model

order_supplement

OrderSupplement

Order supplement

cash_quotation

CashQuotation

Cach quotation

validity_date

Date

Order validity date

limit

double

Limit value

stop

double

Stop value. This value can be used only together with StopMarket, StopLimit and OneCancelOter order models.

stop_limit

double

Stop limit used in the StopLimit and OneCancelOther order models

trailing_distance

double

Traling distance in traling notation units or empty value

trailing_notation

TrailingNotation

Trailing notation for the trailing orders

trailing_limit_tolerance

double

Trailing limit tolerance for the trailing orders

dripping_quantity

double

Dripping quantity pro only

position_id

string

Position id of the depot position. It used only for sale certainly securities from depot

validation

Validation

Validation flag. If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market.
If value is VALIDATE_ONLY then backend system doesn’t send order actions to the market, but validate order parameters.
If value is VALIDATE_WITH_TOTAL_COSTS then order will validated by backend system and request total costs for the order.
If value is VALIDATE_WITH_DETAIL_COSTS then order will validated by backend system and request detail costs for the order.

risk_class_override

bool

Risk class override flag. If true then allowes override user risk class

target_market_override

bool

Target market override flag. If true then allowes override target market

tax_nontransparent_override

bool

Tax non trasparent override flag. If true then allowes override tax intransparesity

accept_additional_fees

bool

Accept additinal fees flag. If true then allowes accept non transparent fees

closed_realestate_fond_override

bool

Closed realestate fond override. If true then allowes sell fonds over fds

inactive

bool

Inactive order flag, pro only. If true then order market as inactive and don’t routed to the marker. To activate order please use ActivateOrder function

CancelOrderRequest

Cancel order request represents canceling information for one order on the market or one inactive order

Field Type Description

access_token

string

Access token

account_number

string

Trading account number

order_number

string

Order number for that this changes should be accepted

validation

Validation

Validation flag. This request allowes only WITHOUT_VALIDATION value.
If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market.
Otherwise request will fail.

CashQuotation

Cash quotation is additional parameter of the order

Field Description

NOTHING

Quotation is not defined

KASSA

Kassa quotation

AUCTION

Auction quotation

OPENING

Opening quotation

INTRADAY

Intraday quotation

CLOSING

Close quotation

CategoryCost

Represents one category cost.

Field Type Description

category_id

string

Category id

category_label

string

Human redable category label

total_sum_absolute

double

Total absolute sum of the children values

total_sum_relative

double

Total relative sum of the children values

currency

string

Currency for absolute sum

detail_costs

List of DetailCost

List of child values or detailed information.

ChangeOrderRequest

Change order request contains parameters for the order change. Be careful: not all combinations are possible.

Field Type Description

access_token

string

Access token

account_number

string

Trading account number

order_number

string

Order number for that this changes should be accepted

limit

double

New limit, shouldn’t filled for market order

stop

double

New stop value

stop_limit

double

New stop limit value

amount

double

New amount

validity_date

Date

New validity date

order_model

OrderModel

New order model

order_supplement

OrderSupplement

New order supplement

dripping_quantity

double

Dripping quantity pro only

validation

Validation

Validation flag. This request allowes only WITHOUT_VALIDATION and VALIDATE_ONLY values.
If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market.
If value is VALIDATE_ONLY then backend system doesn’t send order actions to the market, but validate order parameters.

trailing_distance

double

New trailing distance

trailing_limit_tolerance

double

New traling limit tolerance

CurrencyRateReply

Returns currency rate

Field Type Description

currency_from

string

Source currency

currency_to

string

Target currency

currency_rate

double

Currency rate

error

Error

Error information if occuirs

CurrencyRateRequest

CurrencyRateRequest used for the determination of the currency rate from one currency rate to second currency. Results depends from user market data aboniment and can be realtime or delayed.

Field Type Description

access_token

string

Access token

currency_from

string

Source currency

currency_to

string

Target currency

Date

Represents a whole calendar date, e.g. date of birth. The time of day and time zone are either specified elsewhere or are not significant. The date is relative to the Proleptic Gregorian Calendar. The day may be 0 to represent a year and month where the day is not significant, e.g. credit card expiration date. The year may be 0 to represent a month and day independent of year, e.g. anniversary date. Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and google.protobuf.Timestamp.

Field Type Description

year

int32

Year of date. Must be from 1 to 9999, or 0 if specifying a date without a year.

month

int32

Month of year. Must be from 1 to 12.

day

int32

Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a year/month where the day is not significant.

DeactivateOrderRequest

Deactivate order request represents information for deactivation of one active order pro only

Field Type Description

access_token

string

Access token

account_number

string

Trading account number

order_number

string

Order number for that this changes should be accepted

validation

Validation

Validation flag. This request allowes only WITHOUT_VALIDATION and VALIDATE_ONLY values. If value is WITHOUT_VALIDATION then backend system sends order actions directly to the market. If value is VALIDATE_ONLY then backend system doesn’t send order actions to the market, but validate order parameters

DepotEntries

Field Type Description

account

TradingAccount

Trading account

entries

List of DepotEntry

Depot entries list

error

Error

Error information if occuirs

DepotEntry

Depot entry contains information about one security in the depot. This entry combines data from one or more depot positions

Field Type Description

security_code

SecurityCode

Security code

positions

List of DepotPosition

List of linked depot positions. This list contains at least one element

effective_amount

double

Effective amount

scheduled_amount

double

Scheduled amount

total_amount

double

Total amount of the securities

sell_possible

bool

True if sell possible for this entry or false otherwise. This value can be true only if all child positions have sell_possible = true

unit_note

UnitNote

Unit note

blocked

bool

True if entry is blocked or false otherwise

purchase_quotation

double

Purchase quotation or NaN if not defined

purchase_currency

string

Purchase currency or empty value if not defined

purchase_currency_rate

double

Purchase currency rate or NaN if not defined

open_sales

double

Open sales

DepotPosition

Depot posiotion contains information about one position in the depot

Field Type Description

amount

double

Ammount of the securities

position_id

string

Position identification

sell_possible

bool

True if sell of the position is possible or false otherwise

unit_note

UnitNote

Unit note

blocked

bool

True if entry is blocked or false otherwise

purchase_quotation

double

Purchase quotation or NaN if not defined. Currently this field ALWAYS undefined, reserved for future use

purchase_currency

string

Purchase currency or empty value if not defined

purchase_currency_rate

double

Purchase currency rate or NaN if not defined

DetailCost

Detail cost contains one entry for the selected category

Field Type Description

detail_id

string

Detail id

detail_label

string

Human redable detail label

value_absolute

double

Absolute value for this entry

value_relative

double

Relative value for this entry

currency

string

Currency for this entry

detail_type

string

Specific entry type

Empty

Empty represents absent parameter or result

Field Type Description

Error

Error object

Field Type Description

code

string

Error code

message

string

Error message

LimitToken

Limit token represents a possibility to trade on the short term markets (AcceptQuote) and long term markets (AddOrder)

Field Description

LIMIT_AND_QUOTE

AcceptQuote and AddOrder possible

QUOTE_ONLY

AcceptQuote only possible

LIMIT_ONLY

AddOrder only possible

LoginReply

Login reply provides information that need for the access to the TAPI

Field Type Description

access_token

string

Access token is used in each request by the access to the TAPI.

error

Error

Error information if occuirs

LoginRequest

Login request provides data for initial access to the TAPI

Field Type Description

secret

string

Secret is user defined access string. It’s not possible to restore this secret directly. See double MD5 hash logic + salt

LogoutReply

Field Type Description

error

Error

Error information if occuirs

LogoutRequest

Field Type Description

access_token

string

Access token to invalidate.

Order

Order represent one order object

Field Type Description

security_with_stockexchange

SecurityWithStockExchange

Security with stock echange

order_type

OrderType

Order type

order_number

string

Order number

amount

double

Amount of the securities

order_model

OrderModel

Order model

order_supplement

OrderSupplement

Order supplement

cash_quotation

CashQuotation

Cache quotation

executed_amount

double

Executed amount

order_status

OrderStatus

Order status

status_timestamp

Timestamp

Date and time of the order status

validity_date

Date

Validity date of the order

limit

double

Limit value. Used as the order limit for all Limit order model with exception of the StopLimit order model. For this order model please use stop limit field.

stop

double

Stop value. This value can be used only together with StopMarket, StopLimit and OneCancelOter order models.

stop_limit

double

Stop limit value Can be used only tigether with the StopLimit order model. The meaning of the value is limit of the order after stop.

trailing_distance

double

Traling distance in traling notation units or empty value

trailing_notation

TrailingNotation

Trailing notation for the trailing orders

trailing_limit_tolerance

double

Trailing limit tolerance for the trailing orders

dripping_quantity

double

Dripping quantity pro only

trading_partner_name

string

Trading partner name

execution_quote

double

Execution quote for the executed amount

unique_id

string

Unique id of the order. Used for the order matching. In the pro version of the ActiveTrader order_number can be changed after activation / deactivation. All order activities need actual or delivered form the system order_number. Typical scenario is to map and update unique id to the order number delivered from the API.

OrderBookEntry

Orderbook entry contains data about one level of the order book. This is bid price, ask price, bid volume, ask volume. Entries with lower index have lower ask and higer bid prices.

Field Type Description

bid_price

double

Bid price

ask_price

double

Ask price

bid_volume

double

Bid volume

ask_volume

double

Ask volume

OrderCosts

Order costs represents information about order action estimated costs. This information is only estimated values and is depended from real execution quotes, time, etc.

Field Type Description

estimated_total_costs

double

Estimated total cost for order action

cost_id

string

Reference backend cost id

categorie_costs

List of CategoryCost

List of the cost categories. Filled only by validation request with detailed information.

aggregated_costs

AggregatedCosts

Aggregated costs for the order. Filled only by validation request with validation information.

OrderModel

Order model represents possible orders

Field Description

NO_ORDER_MODEL

Order model absent

MARKET

Market order

LIMIT

Limit order

STOP_MARKET

Stop market order.

STOP_LIMIT

Stop limit order

ONE_CANCELS_OTHER_MARKET

One cancels other market order

ONE_CANCELS_OTHER_LIMIT

One cancels other limit order

TRAILING_STOP_MARKET

Trailing stop market order

TRAILING_STOP_LIMIT

Trailing stop limit order

OrderReply

Order reply represents result of the add order or accept quote requests

Field Type Description

account

TradingAccount

Trading account

order

Order

Result order

order_costs

OrderCosts

Order costs. This field contains data if order costs are requested

error

Error

Error information if occuirs

Orders

Orders represent pushed information about orders from one trading accounts

Field Type Description

account

TradingAccount

Trading account

orders

List of Order

List of the orders

error

Error

Error information if occuirs

OrderStatus

Order status represents status of the order

Field Description

NO_ORDER_STATUS

Status is not defined

NEW

New order

OPEN

Open order

EXECUTED

Fully executed order

PARTIALLY_EXECUTED

Partially executed order

CANCELED

Canceled order

CANCELED_FORCED

Canceled forced order

CANCELED_NOTED

Canceling noted order

CANCELED_TIMEOUT

Canceling timeout order

CHANGED

Changed order

CHANGED_NOTED

Changing noted order

INACTIVE

Inactive order pro only

INACTIVE_NOTED

Inactivation noted order pro only

STORNO

Storno order

OrderSupplement

Order supplement is additional parameter by order definition

Field Description

NORMAL

Normal order supplement

IMMIDIATE_OR_CANCEL

Immidiate or cancel order supplement

FILL_OR_KILL

Fill or kill order supplement

ICEBERG

Icesberg order supplement. Allowes to delivery amount in portions. pro only

MARKET_PRICE

Market place order supplement

OrderType

Order type represents different buy / sell order possibilities

Field Description

NO_ORDER_TYPE

Order type is not defined

BUY

Buy order type

SELL

Sell order type

SHORT_SELL

Short sell order type

SHORT_COVER

Short cover order type. This type is not allowed as input parameter

FORCED_COVER

Rorced cover order type. This type is not allowed as input parameter

PriceEntry

Field Type Description

open_price

double

Open price

close_price

double

Close price

high_price

double

High price

low_price

double

Low price

volume

double

Volume, can not be filled

open_time

Timestamp

Open time

close_time

Timestamp

Close time

QuoteEntry

Quote entry represents one answer with quote information from one stock exchange This reply contains both buy and sell price. The quote reference can be used only with requested order type. Second value is present only for information goals.

order type: BUY ->  quote reference for buy price and reference,
                    sell price and reference are informative only
order type: SELL -> quote reference for sell price and reference,
                    buy price and reference are informative only
Field Type Description

stock_exchange

StockExchange

Stock exchange where infomation was requested

buy_price

double

Buy price

buy_volume

double

Buy volume

sell_price

double

Sell price

sell_volume

double

Sell volume

last_price

double

Last price

last_volume

double

Last volume

last_time

Timestamp

Date and time of the last price

currency

string

Currency

quote_reference

string

Quote reference. Used for the accept quite request. Can be empty if accept quote is not possible.

order_type

OrderType

Used by call order type

error

Error

Error information if occuirs

QuoteReply

Quote reply represents data with quote answers from requested markets

Field Type Description

security_code

SecurityCode

Security code

order_type

OrderType

Order type

price_entries

List of QuoteEntry

List of the quites

error

Error

Error information if occuirs

QuoteRequest

Quote request represents data to get information about actual quotes on the selected makets

Field Type Description

access_token

string

Access token

security_code

SecurityCode

Security code

order_type

OrderType

Order type. Only BUY or SELL are allowed

amount

double

Amount of securities. Relevant to the short term markets

stock_exchanges

List of StockExchange

List of stock exchanges

SecurityChangedField

SecurityChangedField represents information about changed fields during marked data event. Not all field can be initialized. There are only changed fields. Some fields can be changed, but have undefined state for example NaN.

Field Description

NONE

No data

LAST_PRICE

Price of the last trade

LAST_VOLUME

Volume last trade

LAST_DATE_TIME

Last quote date and time

TODAY_NUM_TRADES

Today number of tradings

TODAY_VOLUME

Today volume

ASK_PRICE

Last ask price

ASK_VOLUME

Volume last ask

ASK_TIME

Time of the last ask

BID_PRICE

Last bid price

BID_VOLUME

Volume last bid

BID_TIME

Time of the last bid

PREVIOUS_PRICE

Quote of the previous trading day

PREVIOUS_DATE

Date of the previous trading day

RELATIVE_DIFF

Relative difference to the previous day

ABS_DIFF

Absolute difference to the previous day

HIGH_PRICE

Highest price

LOW_PRICE

Lowest price

OPEN_PRICE

Price at opening

WEEK_HIGH_PRICE

Highest price of the previous week

DATE_WEEK_HIGH

Date of highest price of the previous week

WEEK_LOW_PRICE

Lowest price of the previous week

DATE_WEEK_LOW

Date of lowest price of the previous week

MONTH_HIGH_PRICE

Highest price of the previous month

DATE_MONTH_HIGH

Date of highest price of the previous month

MONTH_LOW_PRICE

Lowest price of the previous month

DATE_MONTH_LOW

Date of lowest price of the previous month

YEAR_HIGH_PRICE

Highest price of the current year

DATE_YEAR_HIGH

Date of the highest price of the current year

YEAR_LOW_PRICE

Lowest price of the current year

DATE_YEAR_LOW

Date of the lowest price of the current year

LAST_ADDENDUM

Addendum of the last price.

TRADING_PHASE

Trading phase

INDICATIVE_PRICE

Indicative price

PREVALENCE_VOLUME

Trading volume corresponding to the last price

SecurityClass

Represents information about security class

Field Description

NO_SECURITY_CLASS

Security class is undefined on unknown

STOCK

Stock security class

BOND

Bond security class

CERTIFICATE

Certificate security class

PRECIOUS_METAL

Precious metal security class

PARTICIPATION_CERTIFICATE

Participation certificate security class

FUNDS

Funds security class

MUTUAL_FUNDS

Mutual funds security class

WARRANT

Warrants security class

FUTURE

Futures security class

INDEX

Indexies security class

OTHERS

Other securities security class

FUTURE_C1

Future c1 security class

FUTURE_C2

Future c2 security class

FUTURE_C3

Future c3 security class

TRACKERS

Trackers security class

CURRENCY

Currency security class

COMMODITY

Commodity security class

SecurityCode

Field Type Description

code

string

Security code

code_type

SecurityCodeType

Security code type (WKN, ISIN, etc)

SecurityCodeType

Represents information about security code type Some of the types are refer to the market data provider (FactSet)

Field Description

NO_CODE_TYPE

Unknown code type

WKN

WKN code type

ISIN

ISIN code type

ID_NOTATION

Factset id notation

ID_OSI

Factset id osi

ID_INSTRUMENT

Factset id instrument

MNEMONIC

Mnemonic or symbol

MNEMONIC_US

US Mnemonic or symbol

SecurityInfoReply

Returns security information

Field Type Description

name

string

Security name

security_class

SecurityClass

Security class

security_codes

List of SecurityCode

Security codes with security type (WKN, ISIN, etc)

stock_exchange_infos

List of SecurityStockExchangeInfo

Stockexchange info (stock exchange, name)

unit_note

UnitNote

Unit note

error

Error

Error information if occuirs

SecurityInfoRequest

Requests security information for security code

Field Type Description

access_token

string

Access token

security_code

SecurityCode

Security code with security type (WKN, ISIN)

SecurityMarketDataReply

Returns market data information

Field Type Description

security_with_stockexchange

SecurityWithStockExchange

Security with stockExchange object (security code, stock exchange)

changed_fields

List of SecurityChangedField

Security fields, which were changed

currency

string

Currency

last_price

double

Fields Price of the last trade

last_volume

double

Volume last trade

last_date_time

Timestamp

Last quote date and time

today_num_trades

int32

Today number of tradings

today_volume

double

Today volume

ask_price

double

Last ask price

ask_volume

double

Volume last ask

ask_time

Timestamp

Time of the last ask

bid_price

double

Last bid price

bid_volume

double

Volume last bid

bid_time

Timestamp

Time of the last bid

previous_price

double

Quote of the previous trading day

previous_date

Date

Date of the previous trading day

relative_diff

double

Relative difference to the previous day

abs_diff

double

Absolute difference to the previous day

high_price

double

Highest price

low_price

double

Lowest price

open_price

double

Price at opening

week_high_price

double

Highest price of the previous week

date_week_high

Date

Date of highest price of the previous week

week_low_price

double

Lowest price of the previous week

date_week_low

Date

Date of lowest price of the previous week

month_high_price

double

Highest price of the previous month

date_month_high

Date

Date of highest price of the previous month

month_low_price

double

Lowest price of the previous month

date_month_low

Date

Date of lowest price of the previous month

year_high_price

double

Highest price of the current year

date_year_high

Date

Date of the highest price of the current year

year_low_price

double

Lowest price of the current year

date_year_low

Date

Date of the lowest price of the current year

last_addendum

string

Addendum of the last price.

trading_phase

TradingPhase

Trading phase

indicative_price

double

Indicative price

prevalence_volume

double

Trading volume corresponding to the last price

error

Error

Error information if occuirs

SecurityMarketDataRequest

Requests market data values for defined security with stockexchange

Field Type Description

access_token

string

Access token

security_with_stockexchange

SecurityWithStockExchange

Security with stockExchange object (security code, stock exchange)

currency

string

Currency

SecurityOrderBookReply

SecurityOrderBookReply represents information with orderbook market data. Currently this information is avialable for the Xetra stock exchange for the accepted for the second level market data instruments

Field Type Description

security_with_stockexchange

SecurityWithStockExchange

Security with stock exchange object (security code, stock exchange)

currency

string

Currency of the order book entries

order_book_entries

List of OrderBookEntry

List of the order book entries

error

Error

Error information if occuirs

SecurityOrderBookRequest

Requests orderbook data for security with stockexchange

Field Type Description

access_token

string

Access token

security_with_stockexchange

SecurityWithStockExchange

Security with stockExchange object (security code, stock exchange)

currency

string

Requested currency. If not filled used default currency. Otherwise values will be converted to requested currency.

SecurityPriceHistoryReply

Returns history data for defined security

Field Type Description

security_with_stockexchange

SecurityWithStockExchange

Security with stockExchange object (security code, stock exchange)

currency

string

Currency

price_entries

List of PriceEntry

List of the price entries

error

Error

Error information if occuirs

SecurityPriceHistoryRequest

Requests history data for one security on one stockexchange in intraday or historical format

Field Type Description

access_token

string

Access token

security_with_stockexchange

SecurityWithStockExchange

Security with stockExchange object (security code, stock exchange)

days

int32

Amount of the day in the past. This value should be positive. Maximal value for the intraday resolution is 15.

time_resolution

TimeResolution

Time resolution for the data

SecurityStockExchangeInfo

Security stock exchange info represents trading information about one security on the one market

Field Type Description

stock_exchange

StockExchange

Stockexchange (id und issuer)

buy_limit_token

LimitToken

Possible limit token for buy orders

sell_limit_token

LimitToken

Possible limit token for sell orders

buy_trading_types

List of TradingPossibility

Buy trading data (order models, order supplements, trailing notations)

sell_trading_types

List of TradingPossibility

Sell trading data (order models, order supplements, trailing notations)

maximal_order_date

Date

Maximal order validity date

short_mode

ShortMode

Short selling mode

SecurityWithStockExchange

Field Type Description

security_code

SecurityCode

Security code object

stock_exchange

StockExchange

Stock exchange object
Table 6. AccessService
Function Description

LoginReply = Login(LoginRequest)

Validates client by the TAPI and gets access data

LogoutReply = Logout(LogoutRequest)

Invalidates client by the TAPI and gets logout result
Table 7. AccountService
Function Description

TradingAccounts = GetTradingAccounts(AccessTokenRequest)

Gets trading accounts

@return TradingAccounts List of trading accounts

TradingAccountInformation ⇐ StreamTradingAccount(TradingAccountRequest)

Subscribes one trading account for updates

@param TradingAccount Trading account for push

@stream TradingAccountInformation Specific information for subscribed account (balance, kredit line, etc.)

TradingAccountTransactions ⇐ StreamTradingAccountTransactions(TradingAccountRequest)

Subscribes one trading account for the transactions updates

@param TradingAccount Trading account for push

@stream TradingAccountInformation Transactions list for subscribed account
Table 8. DepotService
Function Description

DepotEntries ⇐ StreamDepot(TradingAccountRequest)

Subscribes one trading account for the depot data updates

@param TradingAccount Trading account for push

@stream DepotEntries depot entries linked to the account

Empty = UpdateDepot(TradingAccountRequest)

Initiates depot update action. All changes come by the StreamDepot subscription. This function doesn’t wait for the action result.

@param TradingAccount Trading account for update
Table 9. OrderService
Function Description

Orders ⇐ StreamOrders(TradingAccountRequest)

Subscribes one trading account for orders updates

@param TradingAccount Trading account for push

@stream Orders Orders list for seleted account

Empty = UpdateOrders(TradingAccountRequest)

Initiates orders update action. All changes come by the StreamOrders subscription. This function doesn’t wait for the action result.

@param TradingAccount Trading account for update

QuoteReply = GetQuote(QuoteRequest)

Request market quote for the selected security on the selected stock exchanges.

@param QuoteRequest quote request with interested security and stock exchanges

@return QuoteReply quote reply with quotes

OrderReply = AcceptQuote(AcceptQuoteRequest)

Sends accept quote order request to the short term market

@param AcceptQuoteRequest accept quote request with order parameters

@return OrderReply result order or error

OrderReply = AddOrder(AddOrderRequest)

Sends long term order to the market

@param AddOrderRequest order request with order parameters

@return OrderReply result order or error

OrderReply = ChangeOrder(ChangeOrderRequest)

Sends order change request to the market

@param ChangeOrderRequest changed order request with order parameters

@return OrderReply result order or error

OrderReply = CancelOrder(CancelOrderRequest)

Sends order cancel request to the market

@param CancelOrderRequest cancel order request with order reference

@return OrderReply result order or error

OrderReply = ActivateOrder(ActivateOrderRequest)

Sends order activate request to the market. pro only

@param ActivateOrderRequest activate order request with order parameters

@return OrderReply result order or error

OrderReply = DeactivateOrder(DeactivateOrderRequest)

Sends order deactivate request to the market. pro only

@param DeactivateOrderRequest deactivate order request with order parameters

@return OrderReply result order or error
Table 10. SecurityService
Function Description

SecurityInfoReply = GetSecurityInfo(SecurityInfoRequest)

Gets security information about security

@param SecurityInfoRequest Request object with interested security

@return SecurityInfoReply Complete information about security

SecurityMarketDataReply ⇐ StreamMarketData(SecurityMarketDataRequest)

Subscribes security with stock exchange for market data updates

@param SecurityMarketDataRequest Market data request with interested security and stock exchange

@stream SecurityMarketDataReply Reply with all market data values

SecurityOrderBookReply ⇐ StreamOrderBook(SecurityOrderBookRequest)

Subscribes security with stock exchange for orderbook updates

@param SecurityOrderBookRequest Orderbook data request with interested security and stock exchange

@stream SecurityOrderBookReply Reply with all orderbook values

CurrencyRateReply ⇐ StreamCurrencyRate(CurrencyRateRequest)

Subscribes for currency rate from one currency to another currency.

@param SecurityOrderBookRequest currency rate request with interested currencies from/to

@stream CurrencyRateReply reply with currency rate

SecurityPriceHistoryReply = GetSecurityPriceHistory(SecurityPriceHistoryRequest)

Requests history data for one security on one stockexchange in intraday or historical format

@param SecurityPriceHistoryRequest Data with security, stockexchange, how many days and resolution

@return SecurityPriceHistoryReply List of the historical quotes or an error
Table 11. StockExchangeService
Function Description

StockExchangeDescriptions = GetStockExchanges(AccessTokenRequest)

Gets predefined stockexchages

@return StockExchangeDescriptions list of stock exchange informations

StockExchangeDescription = GetStockExchange(StockExchangeRequest)

Gets specific stock exchange

@param StockExchange Requested stock exchange

@return StockExchangeDescription Stock exchange information

ShortMode

Short mode gives information amout security shortability on the selected market.

Field Description

NO_SHORT_MODE

Undefined short selling

YES

Short selling is possible

NO

No short selling

TEMPORARY_NO

Temporary no short selling

INTRADAY

Intraday short selling

OVERNIGHT

Overnight short selling

INTRADAY_AND_OVERNIGHT

Intraday and Overnight short selling

StockExchange

Stock exchange data

Field Type Description

id

string

Stock exchange id

issuer

string

Stock exchange issuer. Can be null

StockExchangeDescription

Field Type Description

stock_exchange_info

StockExchangeInfo

Stock exchange information

error

Error

Error information if occuirs

StockExchangeDescriptions

Field Type Description

stock_exchange_infos

List of StockExchangeInfo

List with stock exchange information

error

Error

Error

StockExchangeInfo

Field Type Description

stockExchange

StockExchange

Stock exchange object

name

string

Stock exchange name

StockExchangeRequest

Stock exchange request contains data that need to request stock exchange related data

Field Type Description

access_token

string

Access token

stock_exchange

StockExchange

Stock exchange

TimeResolution

Time resolution represents information about price aggregation

Field Description

NO_RESOLUTION

Undefined resolution

TICK

Tick resolution. intraday.

Be careful, in same cases there is a lot of data.

SECOND

Second resolution intraday

MINUTE

Minute resolution intraday

HOUR

Hour resolution intraday

DAY

Day resolution historic

Timestamp

A Timestamp represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time. It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from RFC 3339 date strings. See https://www.ietf.org/rfc/rfc3339.txt.

Examples

Example 1: Compute Timestamp from POSIX time().

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

Example 2: Compute Timestamp from POSIX gettimeofday().

struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime().

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

Example 4: Compute Timestamp from Java System.currentTimeMillis().

long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

Example 5: Compute Timestamp from current time in Python.

timestamp = Timestamp()
timestamp.GetCurrentTime()

JSON Mapping

In JSON format, the Timestamp type is encoded as a string in the RFC 3339 format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset).

For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017.

In JavaScript, one can convert a Date object to this format using the standard toISOString() method. In Python, a standard datetime.datetime object can be converted to this format using strftime with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time’s ISODateTimeFormat.dateTime() to obtain a formatter capable of generating timestamps in this format.

Timestamp represents date + time format

Field Type Description

seconds

int64

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

nanos

int32

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

TradingAccount

TradingAccount is trading account connected to the depot

Field Type Description

account_number

string

Account number

depot_number

string

Depot number

name

string

Name of the account owners

tradable

bool

If account is tradable then true or false otherwise

TradingAccountInformation

TradingAccountInformation contains specific for this account information

Field Type Description

account

TradingAccount

Trading account

balance

double

Account balance

credit_limit

double

Credit limit information

buying_power

double

Buying power

credit_limit_intraday

double

Credit limit intraday information, pro only

buying_power_intraday

double

Buyng power intraday, pro only

error

Error

Error information if occuirs

TradingAccountRequest

Trading account request contains trading account related data

Field Type Description

access_token

string

Access token

trading_account

TradingAccount

Trading account

TradingAccounts

TradingAccounts contains account information from current session

Field Type Description

accounts

List of TradingAccount

List of trading accounts

error

Error

Error information if occuirs

TradingAccountTransactions

TradingAccountTransactions contains account transactions

Field Type Description

account

TradingAccount

Trading account

transactions

List of Transaction

List of transactions

error

Error

Error information if happened

TradingPhase

Represents stock exchange trading phase. Some values are refer to the Xetra stock exchange

Field Description

NONE

Unknown trading phase

PRETRADE

Pretrade trading phase

POSTTRADE

Posttrade trading phase

START

Start trading phase

END

End trading phase

VOLA

Vola trading phase

OCALL

OCall trading phase

ICALL

ICall trading phase

CCALL

CCall trading phase

TRADE

Trade trading phase

TRADE_INDICATIVE

Trade indicative trading phase

TRADE_BEST_BID_ASK

Trade best bid / ask trading phase

TRADE_AUCTION_NO_INDICATIVE

Trade auction, but not indicative trading phase

TradingPossibility

Trading possibility represents allowed variants to trade on specific stock exchange. Each trading possibility is a combination of the parameters. The list of the order possibilites is all possible combinations:

MARKET;NORMAL;ABSOLUTE;{KASSA;AUCTION}
LIMIT;NORMAL;ABSOLUTE;{KASSA;AUCTION}
MARKET;NORMAL;RELATIVE;{KASSA;AUCTION}
LIMIT;NORMAL;RELATIVE;{KASSA;AUCTION}
...
Field Type Description

order_model

OrderModel

Order model

order_supplement

OrderSupplement

Order supplement

trailing_notation

TrailingNotation

Trailing notation

cash_quotations

List of CashQuotation

List of allowed cash_quatations

TradingState

Trading state represents information about tradability. Security can be tradable or not (ex. index)

Field Description

NO_TRADING_STATE

Trading state is not defined

TRADABLE

Tradable state

NOT_TRADABLE

Not tradable state

TrailingNotation

Trailing notation represent notation type by trailing orders

Field Description

NO_TRAILING_NOTATION

Trailing notation is not defined

ABSOLUTE

Absolute order notation

RELATIVE

Relative order notation

Transaction

Transaction contains onformation about one transaction

Field Type Description

transaction_date

Date

Transaction date

amount

double

Amount value

opponent

string

Transaction opponent

information

string

Information about transaction

value_date

Date

Value date

UnitNote

Unit node type

Field Description

NO_UNIT_NOTE

Unit note is not defined

PIECE

Piece unit note

PERCENT

Percent unit node. Pieces = Percent/100

PERMIL

Permile unit node. Pieces = Percent/1000

POINTS

Points unit node

MISK

Misk unit node

Validation

Validation type for the order actions

Field Description

WITHOUT_VALIDATION

Order action will routed directly to the market.

VALIDATE_ONLY

Order will checked by the backend system, but not will be routed to market

VALIDATE_WITH_TOTAL_COSTS

Order will checked by the backend system, but not will be routed to market. Additionally will be requested estimated order action total costs.

VALIDATE_WITH_DETAIL_COSTS

Order will checked by the backend system, but not will be routed to market. Additionally will be requested estimated order action detail costs.

TOTAL_COSTS_ONLY

For the order will be requested estimated order action total costs. No backend system validation is processed.

Questions and Answers

  1. Why is used GRPC engine?

    The GRPC is fastest engine for push and pull messaging with building security support. It allowes to reduce time for requests execution (ex. add order) and cares about low level communication.

  2. Is will be supported another languages?

    We delivery original protobuf protocol description. It can be used for the code generation for other programming languages like C++, Python, Go, Ruby, Node.js, Android Java, Objective-C, PHP, Dart and Web. For more information please refer to the grpc.io

  3. Is it planned to extend TAPI?

    If we see an interest from the customers to use additional functionality, then TAPI can be extended.

  4. Where I can ask questions / get additional information about TAPI?

    Please use next link or refer to the support team.