The Trading API for C allows the creation of Trading adapters and client Trading applications using a C API.

A Trading Adapter sits between Caplin Liberator and an external trading system, handling the trade messages that flow between Caplin Platform client applications and the trading system when an end-user trades.

The Trading Integration API is built on top of the Caplin DataSource for C API It allows Trading Adapters to communicate with Liberator using the DataSource protocol, but without the need to write code at the DataSource API level.

The Trading Client API is built on top of the Caplin StreamLink for C API. It allows applications to communication with Liberator using the StreamLink protocol, but without the need to write code at the StreamLink API level.

CreatingTrade Model configuration XML files

You must create a configuration XML file that represents the Trade Model to be used. If your Trading Adapter uses more than one Trade Model, create a separate XML file for each model.

An example of an ESP trade model is shown below. The conf directory of the kit contains further examples of trade models that are used with Caplin Trader.

<?xml version="1.0" encoding="UTF-8" ?>
<tradeModels>
   <tradeModel name="ESP" initialState="Initial">
      <state name="Initial">
         <transition target="OpenSent" trigger="Open" source="client"/>
      </state>
      <state name="Timeout"/>
      <state name="OpenSent" timeout="10" timeoutState="Timeout">
         <transition target="Opened" trigger="OpenAck" source="server"/>
      </state>
      <state name="Opened" timeout="10" timeoutState="Timeout">
         <transition target="TradeConfirmed" trigger="TradeConfirmation" source="server"/>
         <transition target="TradePassed" trigger="Pass" source="server"/>
         <transition target="TradeExpired" trigger="Expired" source="server"/>
      </state>
      <state name="TradeConfirmed"/>
      <state name="TradePassed"/>
      <state name="TradeExpired"/>
   </tradeModel>
</tradeModels>

Concepts

The Trading Provider: ctl_provider

All Trading DataSource applications must create an instance of this. The Trading Provider allows your application to:

Creates the TradeChannels over which trade messages flow. Validates all trade messages against a trade model that is configured in XML. Handles communication using the Caplin platform.

The Trade Channel: ctl_tradechannel

The TradeChannel encapsulates a subscription by a client to the Trading Adapter. It provides a bi-directional channel allowing messages to be sent by both client and the Trading Adapter.

The Trade: ctl_trade

A single Trade active in the system.

A Trade is initiated by a client and is tied to a TradeChannel. The lifecycle of a Trade consists of a number of messages, represented by ctl_tradeevent, being sent between the client and the Trading System in both directions. These messages cause the Trade to transition between a number of predefined states.

The TradeEvent: ctl_tradeevent

A single event acting on a Trade.

The event may be client generated and received through the ctl_trade_listener interface or it may be generated by custom code to be sent to the client using the ctl_trade_process_event() function.

A ctl_tradeevent is created using the ctl_trade it relates to by calling the ctl_trade_create_tradeevent() with the appropriate ctl_trade parameter.

Threading

The Trading API spawns a thread and all operations take place on this thread, as a result the callbacks associated with the various listener interfaces are invoked on the Trading API thread.

All calls into the API which take a ctl_provider perform cross thread messaging to reach the Trading API thread and such may potentially block. It should be noted that if you call into the library holding a resource that is required by a callback (for example a mutex) then a deadlock in your application code will result. Thus, you are strongly advised not to call into the Trading API with any locks.

Recommended Liberator configuration options

Objects used to represent Trade Channels should be configured in the Liberator with some particular settings to ensure that they behave correctly. These options are used to map objects (so that unique channels are created for every user session), to disable throttling (conflation) and to ensure that the objects are discarded immediately following a user un-subscription or logout.

To ensure that each channel is allocated a uniquely object name for each session, the object-map option with the U parameter should be used for each Trade channel object name. This gives a unique per-session suffix to the requested object.

The following settings are applied within add-object sections of the rttpd.conf configuration file:

To disable throttling, the throttle-times option should be set to 0. To cause immediate discards, the discard-timeout option should be set to 0. For example:

#trade channel object map
object-map /FT/TRADE/FX /FT/TRADE/FX/%U

...

#trade channels
add-object
        name    /FT/TRADE
        type    20
        throttle-times 0
        discard-timeout 0
end-object