Java API
© 2022 BidFX Systems Ltd. 2 of 11
BidFX Systems Limited
Legal Notices
This document and all portions thereof are the exclusive property of BidFX Systems Ltd. This document is protected
by copyright law and international treaties. Unauthorized possession, reproduction, duplication, or dissemination of
this document, or any portion of it, is illegal and may result in severe civil and criminal penalties. Prosecution will be
to the maximum extent possible under the law.
All BidFX computer programs and all BidFX source code are the exclusive property of BidFX. All such programs,
regardless of distributed form, are protected by copyright law and international treaties. Unauthorized reproduction
of such programs and/or code, or any portions thereof, may result in severe civil and criminal penalties, and will be
prosecuted to the maximum extent possible under the law.
This document is provided “as is”, without warranty of any kind, either express or implied, including, but not limited
to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. Information in
this document is subject to change without notice. Technical updates are periodically added to the information
herein. BidFX may make improvements and/or changes to the product(s) and/or the program(s) described in this
publication at any time.
Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document
may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without
the express written permission of BidFX.
Java API
© 2022 BidFX Systems Ltd. 3 of 11
About BidFX .................................................................................................................................. 4
Introduction ................................................................................................................................. 4
Related APIs ................................................................................................................................. 4
Programming Language .............................................................................................................. 4
Programming Language .............................................................................................................. 5
Guides on Usage .......................................................................................................................... 5
Creating a Session ................................................................................................................... 5
Pricing ....................................................................................................................................... 6
Get the Price Manager ............................................................................................................ 6
Registering for Price Updates from Subscriptions ......................................................... 6
Registering for Status Updates from Subscriptions ....................................................... 7
Registering for Status Updates from the Price Provider ............................................... 7
Wait for the Pricing Connections to be Ready ................................................................ 7
Creating a Subject .............................................................................................................. 8
Price Update Events ........................................................................................................... 9
Price Maps ....................................................................................................................... 9
Subscription Status Events................................................................................................ 9
Connection Status Events................................................................................................ 10
Accessing provider properties ........................................................................................ 10
Stop the price session ...................................................................................................... 10
Miscellaneous ........................................................................................................................ 11
Logging ............................................................................................................................... 11
Points of Presence ..................................................................................................................... 11
Production ............................................................................................................................. 11
Test environments ................................................................................................................ 11
Java API
© 2022 BidFX Systems Ltd. 4 of 11
About BidFX
BidFX is the market leading provider of electronic trading solutions for the global FX
marketplace. BidFX has addressed the challenges of the FX market head on by introducing a
complete suite of negotiation protocols which include: auto-routing, streaming, request-for-
quote, voice and algo trading via a cloud-based trading platform incorporating best-execution.
Clients have access to cutting edge, broker neutral, Execution Management System (EMS)
backed by a hub to all major bank's algo suites. Read about all of our
products www.bidfx.com.
Introduction
This document describes the usage of the BidFX product offering for Java.
Liquidity Providers (LP) publish their price quotes into the BidFX platform using the FIX
protocol. The platform ingress flow involves billions for FIX messages per day. BidFX provision
for this purpose high-bandwidth, cross-connect circuits in the key FX data centres: London
(LD4), New York (NY4) and Tokyo (TY3). The BidFX Java API makes use of highly optimised,
bespoke binary protocols to deliver realtime quotes from your LPs directly to you in a
workable format. The BidFX delivery mechanism is approximately 80 times more efficient than
the FIX protocol and we publish to you only those quotes that are requested via a publish and
subscribe paradigm.
On the order routing side, BidFX Java can be used to stage orders into the BidFX EMS, from
where they can either be:
• worked using our TradeSmart® GUI
• auto-routed to a strategy engine that manages synthetic order types for best
execution, including: market and limit orders.
Related APIs
Other API offerings from BidFX include:
• REST APIs for order routing, and trade reports over simple web requests.
• Microsoft® Excel Add-In for FX quotes, top-of-book, indicative FX pricing, FX & Futures
trading.
• C++ and C# API for tradable FX quotes, top-of-book, futures pricing, indicative FX
pricing and order routing.
Programming Language
The Java API is written purely in Java. All of the coded examples below are also presented in
Java.
Java API
© 2022 BidFX Systems Ltd. 5 of 11
The API makes use of a publish-subscribe paradigm in which clients register for price updates
by subscribing on subjects. Subjects identify individual products. Liquidity providers publish
streams of real-time prices against large numbers of subjects. The BidFX price service
matches client's subscription subjects against published subjects and forwards on to each
client only those price updates that match their subscriptions.
The namespace BidFX.Public.API.Price contains all of the classes, methods and events that are
necessary to subscribe to pricing from a number of prices services. The API allows users to:
• Create a connection to our externally accessible pricing service
• Subscribe to instruments for multiple price providers
• Receive status and/or real-time price updates on each subscription
• Unsubscribe from price updates
Programming Language
Guides on Usage
Creating a Session
When using the API the main class you create is called a Session, this can then be configured
to work with your username, password and host etc.
Session session = PublicApi.createSession()
.setHost("api.ny.bidfx.biz")
.setUsername("demo_username")
.setPassword("password123")
.setProductSerial("aaabbbccc123123")
.setDefaultAccount("FX_ACCT");
It doesn't matter what order you configure your details, but do ensure you set all those fields
listed as required in the following table:
Name
Description
Type
Required
Default
Value
Host
The host name of the BidFX point-of-
presence (see below) you want to
connect to.
String
yes
api.ld.bidfx.biz
Username
The username to authenticate with.
This will have to be a valid user for
the environment / host.
String
yes
-
Password
The password of the selected user.
String
yes
-
Java API
© 2022 BidFX Systems Ltd. 6 of 11
Name
Description
Type
Required
Default
Value
ProductSerial
The serial key supplied by BidFX.
String
yes
-
DefaultAccount
The default buy side account use for
booking FX orders.
String
yes
-
Pricing
Get the Price Manager
Once you have created your Session with the correct properties you can create a Pricing
object which you can use to setup callbacks.
mSubscriber = session.pricing()
.setPriceMapConsumer(this::onPriceUpdate)
.setSubscriptionStatusConsumer(this::onSubscriptionStatus)
.setProviderStatusConsumer(this::onProviderStatus)
.mergePriceUpdates()
.waitForSubscriber();
This will initiate the connection to the price services and await subscriptions from you. If you
encounter an error at this point then this is most likely a result of a mis-configuration of one
of more of the above properties.
onPriceUpdate, onSusbcriptionStatus, and onProviderStatus are user-defined call-backs to
handle various events.
Registering for Price Updates from Subscriptions
Real-time price updates are forwarded to the client application via Java function pointers. To
register for price updates, you create a callback method to handle the published events. The
method signature should be as follows:
void onPriceUpdate(PriceMapEvent event);
You then associate your callback with the event mechanism by creating a pointer to that
function and passing that function pointer as an argument to the pricing manager. For
example:
Java API
© 2022 BidFX Systems Ltd. 7 of 11
// Define an event delegate for handling price update events.
private void onPriceUpdate(PriceMapEvent event)
{
log.info("price update {}", event.describe());
final Subject subject = event.getSubject();
final MapPrice update = event.priceUpdate();
String bid = update.get("Bid");
String ask = update.get("Ask");
log.info("B: {}, A: {}"), bid, ask);
}
Registering for Status Updates from Subscriptions
If the price service cannot provide a price for a subject for some reason, it will publish a
subscription status event against the problem subject. To register for status updates, you
create a callback method to handle the event. The method signature should be as follows:
void onSubscriptionStatus(SubscriptionStatusEvent event);
We recommend that all applications register for subscription status events. For example:
// Define an event delegate for handling status updates.
private void onSubscriptionStatus(SubscriptionStatusEvent event)
{
log.info("subscription status: {}", event.describe());
}
Registering for Status Updates from the Price Provider
The provider of pricing can encounter state changes, such as if the internet were to go down.
These events will trigger a ProviderStatusEvent which can be received from a callback you can
register.
// Define an event delegate for handling status updates.
private void onProviderStatus(ProviderStatusEvent event)
{
log.info("provider status: {}", event.describe());
}
Wait for the Pricing Connections to be Ready
It is not necessary to wait until the pricing connections are ready before making subscriptions
but some applications need this capability. Should you wish to wait until the pricing
connections are ready, then you can call the method waitForSubscriber on the price session.
This method by default sets 10 seconds as a timeout interval. If the pricing connections does
not become ready within the given time interval it throws an TimeoutException. In the case of
Java API
© 2022 BidFX Systems Ltd. 8 of 11
failure you might then take the opportunity to output the status of each connection -
accessible via getProviderProperties - to find out why that connection failed to ready itself.
For example:
try
{
mSubscriber = session.pricing().waitForSubscriber();
}
catch (TimeoutException e)
{
}
Creating a Subject
A Subject is immutable and therefore cannot be edited once created - we have therefore
provided a builder class to allow for easy subject creation. The builder is accessed from the
subscriber. This is so that the default account property can be used:
mSubscriber.subjects().fx().stream().spot()
.liquidityProvider(lp)
.currencyPair(ccyPair)
.currency(ccy)
.quantity(1230080.11)
.createSubject()
The Tenor enum can be used to provide access to standard tenors.
Subscribing and Unsubscribing
To subscribe or unsubscribe from prices you can call the Subscribe and Unsubscribe methods
of the price subscriber. These both accept a Subject to operate on.
Subject subject = mSubscriber.subjects().fx().stream().forward()
.liquidityProvider("RBCFX")
.currencyPair("EURUSD")
.currency("EUR")
.quantity(1000000)
.tenor(Tenor.ofMonth(1))
.createSubject())
// Subscribe to a subject
mSubscriber.subscribe(subject);
// Unsubscribe from the subject.
mSubscriber.unsubscribe(subject);
Subscriptions are made asynchronously in the background. The Subscribe method will
provide no immediate feedback on the success of otherwise of its action. The client will
Java API
© 2022 BidFX Systems Ltd. 9 of 11
however quickly receive feedback on the subscription via one of the event delegate callback
methods. If there is a problem then you will receive a SubscriptionStatus event. If a price was
obtained then you will receive a PriceUpdate event. Price updates have an implied status of
SubscriptionStatus.OK. Note that it is not uncommon for some price feeds to initially publish
SubscriptionStatus.PENDING, to notify the receipt of a subscription, soon followed by a price
update once the data becomes available from its own remote feed.
Subscribe has an optional argument, refresh. Setting this to true will cause the subscription to
simulate unsubscribing and resubscribing if the subscription is currently subscribed. This can
help with refreshing an expired Quote subscription.
Price Update Events
Upon receiving a price update in the form of PriceMapEvent, you'll want to access the data
inside of it. There are three available properties:
• A Subject from subject() equal to the subject passed to Subscribe, indicating the
instrument you have received an update for.
• A MapPrice from priceUpdate() that will contain only the fields received from the server
in the last update.
• An Optional<MapPrice> from mergedPrice containing only those fields which changed
in this most recent update.
By default, mergedPrice() will always return Optional.empty(). To enable full price maps, call
mergePriceUpdates() when settings up the Pricing object. This is done because many GUI
programs only care about the fields that changed, and merging the new update with the
existing fields would be a waste of cycles.
Price Maps
MapPrices are a map from Field to Value. Values are always returned as strings. The
FieldName enum contains a list of commonly used fields.
Subscription Status Events
Upon receiving a status update in the form of a SubscriptionStatusEvent, you'll want to access
the data inside of it. There are three properties:
• A Subject from getSubject() gives the subject of the subscription the status update
refers to.
• A SubscriptionStatus from getStatus() containing an enum value that defines the status
of the subscription.
• A String from getExplanation() containing a more detailed reason of the change in
status.
Most subscription status' result from temporary issues that can be resolved by the price
service. For example, if a connection goes down and fails over then the API will publish a
Java API
© 2022 BidFX Systems Ltd. 10 of 11
recoverable status code such as SubscriptionStatus.STALE and then quickly reconnect and
resume publishing prices again.
Other status codes are more serious and tend to be semi-permanent in nature; examples are,
bad symbols, invalid price source, user authentication or authorisation error. These are
normally unrecoverable without some admin user intervention followed by re-subscribing.
Connection Status Events
When the price session is started it will create and start connections to each of it's providing
services. Each service connection will be initially in a down state with the status
ProviderStatus.TemporarilyDown. As connections come online or go offline they send status
updates in the form of ProviderStatusEvents. Clients can register callbacks to receive
notification of these events.
// define a callback for handling ProviderStatusEvents
void onProviderStatus(ProviderStatusEvent event)
{
ProviderProperties properties = event.getProviderProperties()
String description = event.describe();
}
// register callback with the Pisa session
mSubscriber = session.pricing().setProviderStatusConsumer(this::onProviderStatus)
Accessing provider properties
It is possible to access the current properties of each provider by calling
GetProviderProperties on the price session. This gives the current status of each provider. For
example:
for (ProviderProperties properties : session.pricing().getProviderProperties())
{
log.info("{}", properties.describe());
}
Stop the price session
When you are finished with the pricing session you should stop the session to free up its
resources by calling Stop. For example:
// Stop the session.
session.pricing().stop()
Java API
© 2022 BidFX Systems Ltd. 11 of 11
Miscellaneous
Logging
The API makes use of the logging framework SLF4J for logging important activity and errors.
As a guide we log high volume messages, such as price ticks, at debug level so they are easily
disabled via configuration. Server connection attempts are logged at info level, as are
subscriptions. Connections failures are logged at warn level.
We suggest setting the log level to info in a production system to keep the level of logging
manageable. If you choose to enable debug logging in production then there will be a
performance impact when prices update quickly.
Points of Presence
BidFX provide a number of points-of-presence (POPs) around the world via which clients may
connect to our global price service:
Production
Clients are encouraged to connect to their geographically closest access point for minimum
latency.
City
Environment
DNS name
IP
Port
London
PROD
api.ld.bidfx.com
64.52.164.90
443
New York
PROD
api.ny.bidfx.com
64.52.165.90
443
Tokyo
PROD
api.ty.bidfx.com
64.52.166.90
443
Singapore
PROD
api.sg.bidfx.com
64.52.167.90
443
Test environments
We provide a test environment, feeding UAT market data. POPs for the test environments are
available in New York and London, so some clients may experience additional latency.
City
Environment
DNS name
IP
Port
London
UAT
api.ld.bidfx.biz
64.52.164.80
443
Tokyo
UAT
api.ty.bidfx.biz
64.52.166.80
443
