FXall Relationship Trading Customer Adapter

Introduction

The TIBCO StreamBase® Adapter for FXall Relationship Trading Customer allows a StreamBase application to create trades (or deals) that can then be executed in the FXall Request for Quote (RFQ) trading environment. The StreamBase application acts as the Taker in this environment

Transactions at FXall are negotiated among several parties and executed between two parties. In both the quoting and negotiation phases, a transaction has two sides: a Customer or Taker who wishes to perform a particular transaction, and a Provider or Maker who responds by offering terms. During the negotiation phase of a transaction, there is one Taker and one or more Makers. During execution there is one Taker and one Maker.

The adapter appears on the EventFlow canvas in StreamBase Studio as two icons, which share a connection to the FXall server. The EventFlow canvas icons for this adapter are:

  • FXallOutput — a StreamBase output adapter that submits deals and accepts or rejects the resulting quotes. Responds to queries for information, such as the available set of accounts, providers, currencies, and tenors.

  • FXallInput — a StreamBase input adapter that emits tuples in response to FXall-generated events, such as quotes received in response to submitted deals.

Each FXall Relationship Trading Customer adapter icon has its own set of ports, the fields for which are defined later in this document. In addition, each icon has its own properties that configure the connection to the FXall server. The connection properties for each adapter icon must be configured identically to be able to start StreamBase.

The FXall Relationship Trading Customer output adapter icon has five input ports and two output ports. The input ports are used, respectively, to submit deals, accept deals, cancel deals, chat with a provider that has generated a quote in response to a submitted deal, and to query information from the adapter. The first output port emits status tuples when the state of the connection to the FXall server changes, when the adapter is suspended or resumed, and when an input tuple is rejected. The second output port emits tuples in response to query requests.

The FXall Relationship Trading Customer input adapter icon has no input ports and two output ports. The first output port emits status tuples when the state of the connection to the FXall server changes and when the adapter is suspended or resumed. The second output port emits tuples in FXall-generated events, such as quotes received in response to submitted deals.

A typical interaction with the FXall Relationship Trading Customer adapter is:

  • The StreamBase application submits an RFQ (deal) to multiple providers by enqueuing a tuple to the output adapter's SubmitDeal port.

  • Streamed quotes from multiple providers are received, resulting in tuples emitted on the input adapter's FXallEvents port.

  • The StreamBase application accepts a quote from a specific provider by enqueuing a tuple to the output adapter's AcceptDeal port.

Adapter Properties

Property Description
Host Name The URI used to connect to the FXall server.
User Name The username for logging in to the FXall server.
Password The password for logging in to the FXall server.
Certificate Directory The absolute path of the directory containing the FXall keystore files.
Reconnect Interval The time, in seconds, between attempts to (re)connect the FXall server.
Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Using the Adapter in a StreamBase Application

This section describes how to use the FXall Relationship Trading Customer adapter in a StreamBase application. As shown in this adapter's sample application, the adapter appears as two icons on the EventFlow canvas.

Note

In this adapter's sample application, the adapter's input and output ports are connected directly to externally-visible input and output streams. However, in more complex applications these ports will typically be connected to internal StreamBase operators.

Adding the Adapter to an EventFlow Application

Add an instance of the adapter to a new StreamBase EventFlow application as follows:

  1. In StreamBase Studio, create a project, including an empty StreamBase EventFlow application file to host the adapter.

  2. From the Operators and Adapter drawer, drag an FXall Relationship Trading Input component to the canvas.

  3. From the Operators and Adapter drawer, drag an FXall Relationship Trading Output component to the canvas.

  4. Select the Parameters tab at the bottom of the EventFlow editor. In the Parameters tab, create parameters named fxall_host, fxall_username, fxall_password, certificate_directory, and reconnect_interval Enter your site-specific values for each parameter.

  5. Select the Editor tab at the bottom of the EventFlow editor.

  6. Select the FXall Relationship Trading Customer Input adapter icon, and in the Properties view, select the Adapter Settings tab.

  7. Enter ${fxall_host}, ${fxall_username}, ${fxall_password}, ${certificate_directory}, and ${reconnect_interval} in the corresponding text entry box for each parameter.

  8. Repeat the previous two steps for the FXall Relationship Trading Customer Output adapter adapter icon.

  9. Connect Input and Output Streams to the adapters' input and output ports.

  10. Configure the schemas of the input streams with the fields listed in the sections below that describe the output adapter's input ports. Note that the adapter will generate typecheck errors when the input streams are missing required fields, when unexpected fields are present, or when fields are of the wrong type. StreamBase Systems recommends you start with the FXall Relationship Trading Customer adapter sample as the basis for creating your application, since it already has the input schemas defined.

This Adapter's Ports and Schemas

The FXall Relationship Trading Customer Adapter includes both input and output adapters. Each adapter has a specific set of input and output ports to communicate with the surrounding application. As with other StreamBase adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.

Output Adapter Ports

The FXall Relationship Trading Customer output adapter submit deals, accepts or rejects the resulting quotes, chats with providers and responds to queries for information. It has five input ports and two output ports:

Output Adapter, Input Port 1: SubmitDeal

SubmitDeal: Tuples are enqueued on this port to submit deals to the FXall server

  • UserId, string: a StreamBase application-generated unique ID for the deal. Note that the FXall sample application appends a sequence number to the user ID entered in Studio to ensure its uniqueness.

  • TwoWay, boolean: true if the deal is being submitted as a two-way and false otherwise. In two-way deals, the FXall server withholds the direction information from the provider.

  • Providers, list(string): one or more provider names to which the deal is passed. If null, the deal is passed to all available providers.

  • Order, tuple: the order to submit. The Order tuple has the following schema:

    Field Data Type Description
    CustomerID string The ID of the order within the Taker's (StreamBase application's) Electronic Trading System.
    PortfolioID string The ID of the portfolio containing this order for custom Taker (StreamBase application) use.
    OrderBatchId int The ID of the order batch containing this order, for custom Taker (StreamBase application) use.
    OrderBatchCount int The number of orders in the order batch, for custom Taker (StreamBase application) use.
    AutoTradable bool This flag is set to false by the Taker (StreamBase application) if the Taker wants to trade with a human trader (Maker). For example: the Taker may want to chat with the Maker about the order. The default is true.
    TakerOrderReference string The reference to the order within the Taker's (StreamBase application's) back-office system.
    TakerOrderConfirmation string A confirmation of (or reference to) the completed deal within the Taker's (StreamBase application's) back-office system.
    TakerOrderCustom string Field for custom-use by the Taker (StreamBase application).
    DealRemarks tuple Zero or more remarks associated with the deal. Each deal remark has the following fields:
    • DealRemarkLines, list(string): up to ten deal remark strings associated with the order.

    InstrumentOrders list(tuple) One or more more instrument orders associated with the deal. Each instrument order tuple has the schema described in the following table.

    Each member of the InstrumentOrders list has the following schema:

    Field Data Type Description
    Type string The order type, one of: SPOT, FORWARD, SWAP, or BLOCK.
    BaseCurrency string The base currency for the order.
    TermsCurrency string The terms currency for the order.
    DealtCurrency string The currency that the amounts are specified in.
    Legs List(tuple) One or more leg records in the order. Each tuple member of the Legs list has the schema described in the following table.

    Each member of the Legs list has the following schema:

    Field Data Type Description
    ValueDate string The Value Date of all requirements within this leg. The date is in YYYYMMDD format. By providing a non-null value in this field, the value date type and spot date is automatically calculated. If the value date is not recognized as a tenor then the value date type is set as BROKEN. If the value date is not recognized, then nothing is set.
    ValueDateType string The Shorthand Value Date Type of all requirements in this leg, such as 1M (in the case of a one month value date). By providing a non-null value in this field, the value date and spot date is automatically calculated. If the value date type is not recognized as a valid tenor then nothing is set. BROKEN is a valid value for this field in addition to the tenors, but the field cannot be assigned as BROKEN.
    Requirements list(tuple) One or more requirement records within this FX leg. Each requirement record has the schema described in the following table.

    Each member of the Requirements list has the following schema:

    Field Data Type Description
    TakerBuysBase bool True if the Taker (StreamBase application) is buying the base currency and false otherwise. A null value prevents the direction from being disclosed.
    Account string The account that is being traded against.
    DealtAmount string The amount of the dealt currency being bought or sold.
    TakerCustom string Field for custom use by the Taker (the StreamBase application).
    SourceId string Field for custom use by the Taker (the StreamBase application).
    SettlementDetails list(tuple) One or more settlement detail records associated with the requirement. Each settlement detail record has the schema described in the following table.

    Each member of the SettlementDetails list has the following schema:

    Field Data Type Description
    Type string The type of settlement instructions to be used:
    • STANDARD — represents standard settlement instructions.

    • SPECIAL — represents special, non-standard settlement instructions.

    Lines list(string) A list of lines in the settlement details.

Output Adapter, Input Port 2: AcceptDeal

AcceptDeal: Tuples are enqueued on this port to accept a quote received in response to a previously-submitted deal.

  • QuoteId, string: the ID from the quote within the NewPrice tuple emitted from the input adapter's FXallEvents port.

  • TakerBuysBase, bool: true if the Taker (StreamBase application) is buying the base currency and false otherwise. If the direction was not disclosed when the deal was submitted, it must be disclosed when the deal is accepted. Otherwise, this field can be set to null.

Output Adapter, Input Port 3: NothingDone

NothingDone: Tuples are enqueued on this port to cancel a previously submitted deal.

  • Id, string: the user ID specified when the deal was submitted or the FxallId from a tuple received on the input adapter's FXallEvents port.

Output Adapter, Input Port 4: Chat

Chat: Tuples are enqueued on this port to send chat messages to negotiating providers. A provider can only receive chat once it has picked up the deal, and until a deal is accepted, a deal is cancelled, or a quote is denied.

  • Id, string: the user ID specified when the deal was submitted or the FxallId from a tuple received on the input adapter's FXallEvents port.

  • Provider, string: the provider whom the chat is directed at, or null to chat with all negotiating providers.

  • Message, string: the chat message text to send.

Output Adapter, Input Port 5: QueryRequest

QueryRequest: Tuples are enqueued on this port to retrieve information from the adapter. Each accepted query request tuple results in the emission of a response tuple emitted on the output adapter's QueryResponse port. The input schema contains a number of tuple fields, each of which can be set to a non-null to retrieve the corresponding information. The output adapter's QueryResponse output schema has a tuple field corresponding to each tuple field in the QueryRequest schema. When an input field is null, the corresponding output field is null.

  • Tag, string: an opaque value echoed in the query respone tuple

  • IsAccountApproved, tuple: Used to determine whether an account can be used to trade with a specific provier.

    • Account, string: the account name

    • Provider, string: the provider name

  • GetQuoteWindowTime, tuple: used to obtain the total time in seconds the specified deal remains active.

    • Id, string: the UserId value specified when the deal was submitted or the FxallId value returned in one of the event tuples for the deal.

    • IsComp, bool: true if the deal is in competition and false otherwise.

  • GetQuoteWindowTimeRemaining, tuple: used to obtain the remaining time in seconds the specified deal remains active.

    • Id, string: the UserId value specified when the deal was submitted or the FxallId value returned in one of the event tuples for the deal.

  • GetTradeDate, tuple: used to obtain the current trading date for a currency pair.

    • CurrencyPair, string: the currency pair for which the trade date is required, such as EUR.USD

  • GetValueDate, tuple: used to obtain the value date of a tenor on a currency pair based on the current trade date, allowing for holidays.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • Tenor, string: the tenor in question, such as SPOT or 1M

  • GetTenorFromValueDate, tuple: used to obtain a Tenor name for a given value date on a currency pair based on the current trade date.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • ValueDate, string: the value date to translate, such as 20011201

  • IsValueDateHoliday, tuple: used to check whether the given value date is a holiday for either currency within the specified currency pair.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • ValueDate, string: the value date to check, such as 20011201

  • GetLogStatus, tuple: used to obtain the deal-logging outcome for accepted deals where the connection was broken before a DealLogged or DealLogError tuple is emitted on the FXallEvents port.

    • FxallId, string: the FXall identifier of the deal request in question.

  • IsTruncationCurrency, tuple: used to check if the given currency, if used as a contra currency, will require contra amount truncation as opposed to rounding.

    • Currency, string: the currency in question.

  • DoesProviderSupportTrucation, tuple: used to determine whether a provider supports truncation.

    • Provider, string: the provider in question.

Output Adapter, Output Port 1: FXallOutputStatus

FXallOutputStatus: The output adapter emits tuples on this port in response to important adapter events such as connection transitions, adapter suspend and resume activity, and rejected input tuples.

  • type, string: the type of event:

    • Connection

    • SuspendResume

    • User Input

  • action, string: the action associated with the event:

    • Up — connection to FXall server is up

    • Down — connection to FXall server is down

    • Suspending — adapter is being suspended

    • Resumed — adapter has been resumed

    • Rejected — an input tuple has been rejected

  • object, string: the connection information when a connection goes up or down, the adapter icon name when the adapter is suspended or resumed, or the input tuple that was rejected.

  • message, string: a human-readable version of the event.

Output Adapter, Output Port 2: QueryResponse

QueryResponse: The output adapter emits tuples on this port in response query requests received on the QueryRequest stream.

  • Tag, string: the tag value from the QueryRequest tuple.

  • MaxProviders, int: the maximum number of providers a deal may be submitted to concurrently in an in-competition deal.

  • RFQConcurrencyCount, int: the maximum number of concurrent deals the FXall trading engine connection may keep in negotiation.

  • RFQConcurrencyLimit, int: the number of RFQs currently in negotiation and count towards the RFQ Concurrency Limit.

  • AcceptDelay, int: the number of seconds delay that the FXall trading engine must wait between successive calls to the AcceptDeal method without breaching the inter-Accept delay time. Note: this value, although generally zero, may change at any time.

  • CanAcceptNow, bool: true if the delay time is clear and therefore AcceptDeal will not breach the inter-accept delay time rule, false otherwise.

  • Accounts, list(tuple): returns a list of the available accounts, along with the valid providers for each account.

    • Account, string: the account name.

    • Providers, list(string): the providers that can be traded with the account.

  • Providers, list(tuple): returns a list of the available providers, along with the valid accounts for each provider.

    • Provider, string: the provider name.

    • SupportsTruncation, bool: true if the provider supports truncation and false otherwise.

    • Accounts, list(string): the accounts that can be traded with the provider.

  • Currencies, list(tuple): returns a list of the available currencies along with an indicator of whether each is a truncation currency

    • Currency, string: the currency name.

    • TruncationCurrency, bool: true if the currency is a truncation currency and false otherwise.

  • Tenors, list(string): a list of the available tenors.

  • IsAccountApproved, tuple: indicates whether an account can be used to trade with a specific provider.

    • Account, string: the account name.

    • Provider, string: the provider name.

    • Approved, string: true if the account can be used to trade with a specific provider and false otherwise.

  • GetQuoteWindowTime, tuple: returns the total time in seconds the specified deal remains active.

    • Id, string: the UserId value specified when the deal was submitted or the FxallId value returned in one of the event tuples for the deal.

    • IsComp, bool: true if the deal is in competition and false otherwise.

    • QuoteWindowTime, int: the total time in seconds the specified deal remains active.

  • GetQuoteWindowTimeRemaining, tuple: returns the remaining time in seconds the specified deal remains active.

    • Id, string: the UserId value specified when the deal was submitted or the FxallId value returned in one of the event tuples for the deal.

    • QuoteWindowTimeRemaining, int: the remaining time in seconds the specified deal remains active.

  • GetTradeDate, tuple: returns the current trading date for a currency pair.

    • CurrencyPair, string: the currency pair for which the trade date is required, such as EUR.USD

    • TradeDate, string: the current trading date for a currency pair.

  • GetValueDate, tuple: returns the value date of a tenor on a currency pair based on the current trade date, allowing for holidays.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • Tenor, string: the tenor in question, such as SPOT or 1M

    • ValueDate, string: the value date of a tenor on a currency pair based on the current trade date, allowing for holidays.

  • GetTenorFromValueDate, tuple: returns a Tenor name for a given value date on a currency pair based on the current trade date.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • ValueDate, string: the value date to translate, such as 20011201

    • Tenor, string: the a Tenor name for the given value date on the currency pair based on the current trade date.

  • IsValueDateHoliday, tuple: indicates whether the given value date is a holiday for either currency within the specified currency pair.

    • CurrencyPair, string: the currency pair in question, such as EUR.USD

    • ValueDate, string: the value date to check, such as 20011201

    • IsHoliday, bool: true if the given value date is a holiday for either currency in the specified currency currency pair.

    • HolidayCurrency, string: if IsHoliday is true, contains the holiday currency that makes the value date a holiday. If both currencies are holiday, then only the second currency is returned.

  • GetLogStatus, tuple: returns the deal-logging outcome for accepted deals where the connection was broken before a DealLogged or DealLogError tuple is emitted on the FXallEvents port.

    • FxallId, string: the FXall identifier of the deal request in question.

    • LogStatus, string: the deal-logging outcome for accepted deal:

      • LOGGED — deal logged OK

      • UNCONFIRMED — waiting confirmation

      • NOT_FOUND — no evidence of deal. That is, the deal was not logged.

      • DENIED — deal denied

  • IsTruncationCurrency, tuple: indicates whether the given currency, if used as a contra currency, will require contra amount truncation as opposed to rounding.

    • Currency, string: the currency in question.

    • TruncationCurrency, bool: true if the currency is a truncation currency and false otherwise.

  • DoesProviderSupportTrucation, tuple: indicates whether a provider supports truncation.

    • Provider, string: the provider in question.

    • SupportsTruncation, bool: true if the provider supports truncation and false otherwise.

Input Adapter Ports

The FXall Relationship Trading Customer input adapter emits tuples in response to events received from the FXall server, such as the receipt of quotes and logged deals. It has no input ports and two output ports:

Input Adapter, Output Port 1: FXallInputStatus

FXallInputStatus: The input adapter emits tuples on this port in response to important adapter events such as connection transitions and adapter suspend and resume activity.

  • type, string: the type of event:

    • Connection

    • SuspendResume

  • action, string: the action associated with the event:

    • Up — Connection to FXall server is up

    • Down — Connection to FXall server is down

    • Suspending — Adapter is being suspended

    • Resumed — Adapter has been resumed

  • object, string: the connection information when a connection goes up or down, or the adapter icon name when the adapter is suspended or resumed.

  • message, string: a human-readable version of the event.

Input Adapter, Output Port 2: FXallEvents

FXallEvents: Tuples are emitted on this port when events are received from the FXall server.

  • EventType, string: the type of FXall event received. Zero or more additional FXallEvents fields are populated based on the event type.

    • AdminUpdate — an aspect of the Trading Application’s user is altered or the reference data loaded. This may be trading authorizations or abuse management or the trading day changes. It allows the application to know that configuration has changed. For example the user may have been assigned another account to trade.

      Related fields: AdminEventType

    • ChatMessage — an in-deal chat message has been received from a provider in discussion over a deal.

      Related fields: UserId, FxallId, Provider, ChatMessage

    • CloseOfDay — the trading day has changed. All in-negotiation deals are lost. All deals for which an AcceptDeal tuple had previously been successfully processed will continue in the FXall to their natural outcomes. These deals must be inspected using a GetLogStatus query tuple.

      Related fields: EodCurrency

    • DealLogError — the provider has failed to a log a deal or the outcome of the deal is unconfirmed because, for example, the provider connection was lost in the process of logging.

      Related fields: UserId, FxallId, Provider, ErrorMessage

    • DealLogged — the provider has logged the deal.

      Related fields: UserId, FxallId, Provider

    • DealPickup — a provider has picked up a submitted deal. Note that if the StreamBase application submits an in-competition deal successfully to three providers, the application may see three OnDealPickup tuples as each provider chooses to pickup the deal.

      Related fields: UserId, FxallId, Provider

    • Disconnect — the connection to the FXall Server is broken. All in-negotiation deals are lost. All deals for which an AcceptDeal tuple had previously been successfully processed will continue in FXall to their natural outcomes. These deals must be inspected using a GetLogStatus query tuple.

      Related fields: None

    • NewPrice — the trading library has received a price update from a provider.

      Related fields: UserId, QuoteId, FxallId, Provider, Order

    • QuoteDenied — a provider chooses not to quote prices for a submitted deal. The provider sends this either in response to the original Request For Quote instead of a Pickup, or after the Pickup to indicate it is no longer quoting prices on this deal.

      Related fields: UserId, FxallId, Provider, Reason

    • QuoteWindowExpiry — a quote window time has expired. A timer in the FXall system starts when a deal is submitted (price negotiation starts). The deal must be accepted or rejected with AcceptDeal or NothingDone respectively before the timer expires to prevent this callback. This mechanism prevents deals from remaining in negotiation for longer that the FXall administrator has defined. The Quote Window time is a function of the currency pair and the order type and may be altered by the administrator prior to SubmitDeal.

      Related fields: UserId, FxallId

    • ServerMessage — an FXall administrator or server is sending a message to the StreamBase application (or to the application's customer group). The severity of the message is conveyed in the ServerMessageType field as INFORMATION, WARNING, or ERROR. Note: FXall system administrators can kick a StreamBase application off the FXall using ERROR, the connection is broken at the server end. This event may also be used by the FXall to provide additional notifications to the StreamBase application, such as for deal failure notifications.

      Related fields: ServerMessageType, ServerMessage

    • SubmitError — there is a problem at the FXall submitting a deal to one or more providers. The reason for failure is contained in the ErrorMessage and ErrorCode fields. If the Provider field is null, this indicates that the deal submit failed before sending to any providers. If the provider is not-null, this indicates the deal submit failed for that specific provider. The StreamBase application may receive a number of OnSubmitError events even if the deal has been submitted to some providers successfully, as indicated afterwards by one or more OnSubmitOk events.

      Related fields: UserId, Provider, ErrorMessage, ErrorCode

    • SubmitOk — the deal was successfully submitted to some or all of the requested providers.

      Related fields: UserId, FxallId

    • WithdrawPrice — a price has been withdrawn by a provider.

      Related fields: UserId, FxallId, Provider

  • AdminEventType, string: indicates the type of admin event:

    • PROVIDERS

    • ACCOUNTS

    • CONCURRENCEY

    • TENORS

    • CURRENCIES

    • USERFIELDS

    • QUOTEWINDOW

    • LOADED

  • UserId, string: the unique ID provided by the StreamBase application when the deal was submitted.

  • FxallId, string: UserId, string: the unique ID generated by FXall when the deal was submitted.

  • QuoteId, string: the unique ID of each quote received in response to a submitted deal.

  • Provider, string: the provider name.

  • ChatMessage, string: the contents of the chat message received from a provider.

  • ServerMessageType, string: the severity of the server message:

    • INFORMATION

    • WARNING

    • ERROR

  • ServerMessage, string: the contents of the message received from the FXall server.

  • ErrorMessage, string: the contents of the error message on a DealLogError or SubmitError event.

  • ErrorCode, string: the error code on a SubmitError event. Currently unused.

  • Reason, string: a reason possibly indicating why the RFQ was denied.

  • EodCurrency, string: the currency for with a CloseOfDay event is received.

  • Order, tuple: the order associated with a NewPrice event.

Typechecking and Error Handling

The FXall Relationship Trading Customer adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages for the following reasons:

  • A required property such as the FXall host name or username is missing.

  • One or more required fields in an input schema is missing or is of the wrong type.

  • One or more unexpected fields are present in an input schema.

The adapter generates warning messages during runtime under various conditions, including:

  • The adapter fails to connect or loses its connection to the FXall server.

  • A tuple is enqueued to the output adapter while the connection to the FXall server is down.

  • A tuple enqueued to the output adapter contains one or more missing or invalid arguments.

Suspend and Resume Behavior

When suspended, the adapter continues to receive and process FXall messages, but no longer emits tuples on its output ports.

When resumed, the adapter once again starts emitting tuples on its output ports.

Related Topics