The FX Integration API

The FX Integration API is a back-end Java library which you can use to easily integrate the FX Sales Motif with your existing systems. The library consists of a set of APIs that provide the data expected by the FX Sales Motif in the exact format required.

Features

These APIs fully support the core features of FX Sales, including (but not limited to):

  • Streaming FX rates

  • RFS (Request For Stream) trading

  • Trading on behalf of others (TOBO) functionality with the ability to control margins on the fly (MOTF) on trade tickets

  • Integrated group and client blotter

Messages and fields

When using the Motif back-end system - Caplin Platform - to integrate with your existing back-end systems and stream real-time data to your client applications via the internet, the server-side APIs that you interact with are generally based on receiving requests and sending messages made up of fields. These fields are simple key/value pairs. The FX Integration API enforces a contract with the FX Sales Motif that enables developers to implement DataSource Integration Adapters conforming to the pricing/trading workflow that the Motif expects, without being overly concerned with field and message specifications.

Thus the FX Integration API enables you to fully utilise all of the FX Sales Motif features. It greatly reduces the amount of time developing integration adapters by writing a small amount of high level domain-specific integration code rather than writing a lot of low-level boilerplate code to build up raw messages and manually set fields.

See the following sections on how this is achieved.

Standard architecture for integrating external systems

The back-end technology of the Motif is powered by Caplin Platform; this allows for integration with any back-end system to stream real-time data to your client applications over the internet using Liberator. The bottom diagram shows how you would typically use the Caplin Platform architecture to integrate with an external Trading System and Pricing System to send data to a front-end (client) application.

Two DataSource Integration Adapters are illustrated in the diagram above; one for sending streaming prices to the client application and one to handle trading.

For each coloured layer:

  • Blue layers represent Caplin libraries and components.

  • Grey layers represent code that you would write as a developer working on the integration.

  • Yellow layers represent third-party libraries and components.

For the Pricing Integration Adapter

It has a simple three-layer structure.

  • The top layer represents the DataSource for Java library. This library allows you to listen to requests that have been sent from a client application across the internet to your Adapter via Liberator. For this Adapter, a request could be for streaming FX rates on a particular currency pair.

  • The middle layer consists of your own custom code, which would be responsible for transforming the request into a format that your Pricing System can understand, and then passing it to the bottom layer.

  • The bottom layer — Pricing System API — represents whichever library or custom code is required to communicate with the Pricing System. As an example, if your Pricing System is a FIX engine then the bottom layer might be a library such as QuickFIX/J.

When the Pricing System responds to the request, the flow is simply reversed. The bottom layer will call into your custom code with a price update for the requested currency pair and tenor. Your custom code is then responsible for transforming the update into an equivalent message that it can pass into DataSource for Java. The DataSource for Java library will then send the message to the Liberator, which will then distribute it to all of the subscribed client applications across the internet.

For the Trading Integration Adapter

This Adapter is very similar, except that it makes use of one of the higher level helper APIs which sits on top of DataSource for Java. In this case it uses the Trading Integration API, which takes care of some of the lower-level message parsing and also allows you to define a state model for each type of trade using XML; where the model will be enforced by the library.

  • When one of the client applications sends a trade message to the Adapter it will be received by DataSource for Java as normal, parsed into a trade event by the Trading Integration API, and then passed to your custom code in the middle layer.

  • Your custom code is responsible for transforming the trade event into a form that can be understood by your Trading System, and then submitting it.

  • When your Trading System responds with a confirmation or rejection, your custom code must build a suitable trade event and pass it into the Trading Integration API, so that it can be turned into a DataSource for Java message and sent back to the client application via Liberator.

In this example, although your custom code in the Trading Integration Adapter is only interacting with the Trading Integration API, it still has access to the underlying DataSource for Java instance. So you are free to send non-trade related messaging directly through DataSource for Java from your custom code in addition to handling trades - if you wish to do so.

Using the FX Integration API

Supplied with the FX Integration API is an Adapter Suite containing the source code for a number of example Integration Adapters, which demonstrate best practises on how to use the API.

  • NovoRatesAdapter - shows how to send streaming executable FX rates to the FX Sales Motif, for use in quick-trade tiles.

  • NovoTradingAdapter - shows how to handle RFS (Request for Stream) trading.

  • NovoCalendarAdapter - shows how to send tenor dates (also called value dates) and valid settlement dates.

  • NovoPermissioningAdapter - shows how to send all of the permissions required by the FX Sales Motif into Liberator.

These example Adapters implement two notional business names by convention. Novo is short for Novo Bank, and represents a bank that wants to provide an online trading facility for internal sales traders to trade on behalf of the bank’s customers using the Caplin FX Sales Motif. Typically, the developers at Novo Bank would be responsible for writing the Integration Adapters using the FX Integration API, in order to link the bank’s systems with the Motif.

The other name we use in the example Adapters is BTS, which stands for Best Trading System. This represents a trading system or OMS used by the bank, for example Refinitiv Electronic Trading. The BTS code provided is intended to provide just enough canned data and mock behaviour to make the FX Sales Motif work. For example, it will generate canned FX rates and confirm trades. This allows most of the functionality in the Motif to work when running against the Novo Adapters, such as streaming rates and basic trading.

The example Adapters consist of a thin layer of code between the BTS system and the FX Integration API. When you look at the example adapters, you should treat the BTS code as a black box and concentrate on the Novo code in the middle layer, because this is the code you would typically write as a developer working on the FX Sales Motif integration.

By starting with the FX Integration API you gain a number of advantages over developing a DataSource Integration Adapter using the generic DataSource for Java library. You also lose none of the freedom to augment the messaging with your own custom fields or send your own streaming data; which is completely custom to your application.

Architecturally, you can think of the FX Integration API as a higher level helper library that sits on top of DataSource for Java and its own helper libraries. The FX Integration API is specifically tailored to serving the FX Sales Motif. It alters the structure of your Integration Adapters by adding an extra layer, see diagram below:

salesmotif archdiagram2

You can now see how the Integration Adapters communicate primarily with the FX Integration API. Since the FX Integration API takes care of much of the low level message parsing code, the amount of custom code you need to write in the middle layer is significantly reduced.

You will notice from the above diagram that the underlying DataSource for Java instance used by the FX Integration API is still exposed and available to your custom code to call into directly. This means that the FX Integration API does not prevent you sending any custom messages to the front end. As a general rule you should use the FX Integration API if you want to provide functionality supported in the FX Sales Motif, such as RFS trades. Although, you are free to bypass the FX Integration API when you wish to implement your own, new features which are not supported out of the box.

Using the Adapters with the FX Sales Motif

Once you have deployed the FX Sales Motif, you can then begin customising the Novo Adapters, or simply use them as a reference to build your own Integration Adapters from scratch. The provided suite of Novo Adapters deliver the functionality required to use the following features:

  • TOBO (Trading on Behalf Of) - this facilitates FX trading on behalf of end-users

  • MOTF (Margin on The Fly) - as part of TOBO, this enables you to control margins on trade tickets in real-time

See the FX Sales Motif Architectural Overview for more details on its features and concepts.

Benefits of the FX Integration API

Here are the main benefits to using the FX Integration API to integrate with the FX Sales Motif rather than the lower-level message parsing APIs like DataSource for Java:

Writing less code

Writing a DataSource Integration Adapter involves writing some low level code to handle things like building and sending messages, or providing the latest data from a cache if you receive a request from a new peer. We have identified the common boilerplate code that is written when creating adapters to integrate with various external systems, and moved it into the FX Integration API. This all means your custom code becomes smaller, faster to write, and easier to test.

Compatibility with the Caplin FX Sales Motif

As the FX Sales Motif has a contract with the FX Integration API rather than a single set of custom integration adapters, any back-end systems that integrate with the FX Integration API are guaranteed to work with the FX Sales Motif. This then allows us to build a library of pre-built, reusable FX Sales Motif front-end blades and components from which you can pick and choose to conveniently slot into your web trading application.

Freedom to extend, customise and bypass the FX Integration API

Although the FX Integration API is specifically built to meet the exact requirements of the FX Sales Motif, it is fully extensible and customisable. As an example, if you wish to customise the Motif to send some extra fields on an RFS trade, you will find that the object representing an RFS Submit event allows you to read fields by name in addition to calling the built-in getter methods.

Developers are provided with the ability to side-step the default behaviour of the FX Sales Motif - at no point should the FX Integration API lock you into doing anything a certain way. You are free to bypass the FX Integration API altogether and send your own custom messages, as the underlying DataSource for Java instance used by the FX Integration API is freely accessible, and not hidden.