Pricing

The Pricing API is used to provide users with access to real-time pricing from the BidFX platform. Although the API can be used independently of trading, it is recommended that pricing be accessed via the top-level Session class of the BidFX API.

PricingAPI

class bidfx.PricingAPI(config_parser)

Pricing is the top-level API interface for accessing the real-time pricing services of BidFX. It implements two PriceProvider implementations: one for exclusive pricing that uses the Pixie protocol, and one for shared pricing that uses the Puffin protocol.

Parameters

config_parser (configparser.ConfigParser) – The API configuration.

start()

Starts the pricing threads which connect to and manage real-time price services asynchronously.

subscribe(subject)

Subscribes to real-time price publications on a given Subject representing an instrument.

Parameters

subject (Subject) – The price subject to subscribe to.

unsubscribe(subject)

Un-subscribes from a previously subscribed price Subject.

Parameters

subject (Subject) – The price subject to unsubscribe from.

property build

Provides a handle to a the subject builder interface that provides a convenient way to construct a well-formed and validated price Subject by using a blend of method-chaining and the builder pattern. The method-chains guide the user to find a correct subject for common classes of instrument, and the builder then validates the resulting subject. For example:

# Create an indicative FX spot subject
pricing.build.fx.indicative.spot.currency_pair("GBPAUD").create_subject()

# Create a tradable FX OTC spot subject
pricing.build.fx.stream.spot.liquidity_provider("DBFX").currency_pair("USDJPY").currency("USD").quantity(5000000).create_subject()
Returns

A method-chain that should lead to the creation a valid Subject.

property callbacks

Accessor for setting callbacks for pricing related events.

Returns

The set of Callbacks that determine which user-functions get called for each type of event.

Return type

Callbacks

static create_price_provider(config_section, callbacks, protocol)

Creates a price provider for a given protocol. Allowed values are ‘Pixie’ or ‘Puffin’. Most applications will not use this method directly as the PricingAPI will create the required price providers.

Parameters
  • config_section (configparser.ConfigParser[section]) – Provider section of the API configuration.

  • callbacks (Callbacks) – The callback functions to handle events.

  • protocol (str) – The protocol implementation for the provider. Defaults to ‘Pixie’.

Returns

A new price provider instance.

Return type

PriceProvider

Raises

PricingError – if the protocol is not supported.

PriceProvider

class bidfx.PriceProvider

A PriceProvider is an interface that encapsulates the operations of an underlying price provider implementation.

abstract start()

Starts the pricing threads which connect to and manage real-time price services asynchronously.

abstract subscribe(subject)

Subscribes to real-time price publications on a given Subject representing an instrument.

Parameters

subject (Subject) – The price subject to subscribe to.

abstract unsubscribe(subject)

Un-subscribes from a previously subscribed price Subject.

Parameters

subject (Subject) – The price subject to unsubscribe from.

Callbacks

class bidfx.Callbacks

This class provides a set of callback functions that can be overridden by the API user to handle the different types of event that are published by the Pricing API.

price_event_fn

The callback function to be used for handling price events.

Type

def function(event: PriceEvent)

subscription_event_fn

The callback function to be used for handling subscription events.

Type

def function(event: SubscriptionEvent)

provider_event_fn

The callback function to be used for handling provider events.

Type

def function(event: ProviderEvent)

Subject

class bidfx.Subject(components)

A subject is an immutable, multi-component identifier used to identify instruments that may be subscribed to via the pricing API. Subjects are represented as tuples of many nested tuple pairs, where each pair provides a component key and value. Subject components are alphabetically ordered by key.

Example subjects are:

  • AssetClass=Fx,BuySideAccount=ABC,Currency=EUR,DealType=Spot,Level=1,LiquidityProvider=DBFX,    Quantity=100000.00,RequestFor=Stream,Symbol=EURUSD,Tenor=Spot,User=smartcorp_api

  • AssetClass=Fx,Exchange=OTC,Level=1,Source=Indi,Symbol=USDJPY

Subject are safe to compare for equality and to use as the keys of a dictionary. Subjects can be converted to string using str(subject) for display purposes. Instances of the subject class can be used much like a dict to pull out the individual component parts. For example:

>>> subject = Subject(...)
>>> ccy_pair = subject[Subject.CURRENCY]

A number of common subject component keys are provided as constants of the Subject class for this purpose.

Parameters

components (tuple) – A tuple of subject components, key-value pairs as tuples.

flatten()

Flattens the subject into a simple list of the subject’s key and value pairings.

Returns

A flattened list of strings.

Return type

list

static parse_string(s)

Creates a new Subject by parsing the string form of subject.

Parameters

s (str) – The string to be parsed.

Returns

A new Subject

Return type

Subject

static from_dict(d)

Creates a new Subject from a dictionary.

Parameters

d (dict) – The dictionary to convert.

Returns

A new Subject

Return type

Subject

get(key, default)

Gets the value of a Subject component. The component value is returned if the component is present in the subject, otherwise the default value is returned.

Parameters
  • key (str) – The key of the subject component to get.

  • default (str) – The default value to be returned if the key is not present in the subject.

Returns

A the value of the component mapped from the key, or the default value.

Return type

str

__contains__(key)

Checks if this Subject contains a component with the given key.

__len__()

Gets the length of the Subject in terms of components.

__str__()

Gets a string representation of the Subject.

__eq__(other)

Tests the subject for equality with another Subject.

__hash__()

Provides a hash code of the Subject.

ASSET_CLASS = 'AssetClass'
BUY_SIDE_ACCOUNT = 'BuySideAccount'
CURRENCY = 'Currency'
CURRENCY_PAIR = 'Symbol'
DEAL_TYPE = 'DealType'
EXCHANGE = 'Exchange'
EXPIRY_DATE = 'ExpiryDate'
FAR_CURRENCY = 'FarCurrency'
FAR_FIXING_DATE = 'FarFixingDate'
FAR_QUANTITY = 'FarQuantity'
FAR_SETTLEMENT_DATE = 'FarSettlementDate'
FAR_TENOR = 'FarTenor'
FIXING_CCY = 'FixingCcy'
FIXING_DATE = 'FixingDate'
LEVEL = 'Level'
LIQUIDITY_PROVIDER = 'LiquidityProvider'
ON_BEHALF_OF = 'OnBehalfOf'
PUT_CALL = 'PutCall'
QUANTITY = 'Quantity'
REQUEST_TYPE = 'RequestFor'
ROUTE = 'Route'
ROWS = 'Rows'
SETTLEMENT_DATE = 'SettlementDate'
SOURCE = 'Source'
STRIKE = 'Strike'
SYMBOL = 'Symbol'
TENOR = 'Tenor'
USER = 'User'

Tenor

class bidfx.Tenor

Tenor values for defining the settlement period in a Subject for FX futures and swaps.

BROKEN_DATE = 'BD'

Broken data tenor implied that an explicit settlement date is provided.

TODAY = 'TOD'

Today or same day settlement.

TOMORROW = 'TOM'

Tomorrow or next day settlement. Next good business day after today.

SPOT = 'Spot'

Spot date settlement. Spot is T+1 or T+2 depending of the currency pair.

SPOT_NEXT = 'S/N'

Spot/next settlement. The next good business day after spot.

IN_1_WEEK = '1W'

Settlement in one week.

IN_2_WEEKS = '2W'

Settlement in two weeks.

IN_3_WEEKS = '3W'

Settlement in three weeks.

IN_1_MONTH = '1M'

Settlement in one month.

IN_2_MONTHS = '2M'

Settlement in two months.

IN_3_MONTHS = '3M'

Settlement in three months.

IN_4_MONTHS = '4M'

Settlement in four months.

IN_5_MONTHS = '5M'

Settlement in five months.

IN_6_MONTHS = '6M'

Settlement in six months.

IN_7_MONTHS = '7M'

Settlement in seven months.

IN_8_MONTHS = '8M'

Settlement in eight months.

IN_9_MONTHS = '9M'

Settlement in nine months.

IN_10_MONTHS = '10M'

Settlement in ten months.

IN_11_MONTHS = '11M'

Settlement in eleven months.

IN_18_MONTHS = '18M'

Settlement in eighteen months.

IN_30_MONTHS = '30M'

Settlement in thirty months.

IN_1_YEAR = '1Y'

Settlement in one year.

IN_2_YEARS = '2Y'

Settlement in two years.

IN_3_YEARS = '3Y'

Settlement in three years.

IN_4_YEARS = '4Y'

Settlement in four years.

IN_5_YEARS = '5Y'

Settlement in five years.

IMM_MARCH = 'IMMH'

Settlement coinciding with the IMM cash futures contract for March.

IMM_JUNE = 'IMMM'

Settlement coinciding with the IMM cash futures contract for June.

IMM_SEPTEMBER = 'IMMU'

Settlement coinciding with the IMM cash futures contract for September.

IMM_DECEMBER = 'IMMZ'

Settlement coinciding with the IMM cash futures contract for December.

classmethod of_week(week: int)

Gets the weekly tenor of the given number of weeks. :param week: number of weeks :return: the tenor value

classmethod of_month(month: int)

Gets the monthly tenor of the given number of months. :param month: number of months :return: the tenor value

classmethod of_year(year: int)

Gets the yearly tenor of the given number of years. :param year: number of months :return: the tenor value

classmethod of_imm_month(month)

Gets the IMM monthly contract tenor of the given month. :param month: months number in year 1..12 :return: the tenor value

PriceEvent

class bidfx.PriceEvent(subject, price, full)

This class defines a Price Event that gets published for each price tick received on a subscription. Price events should be handled by setting a callback function via PricingAPI.callbacks. The callback function could be implemented and used as follows.

def on_price_event(event):
    if event.price:
        print("price update {} {} / {})".format(
            event.subject[Subject.CURRENCY_PAIR],
            event.price.get(Field.BID, ""),
            event.price.get(Field.ASK, "")))

def main():
    session = Session.create_from_ini_file()
    session.pricing.callbacks.price_event_fn = on_price_event
Notice from above that you can use the constants provided by:
  • Subject to access the components of the subject

  • Field to access the fields of the price update.

Parameters
  • subject (Subject) – The unique subject of the price subscription.

  • price (dict) – The price as a map for fields.

  • full (bool) – Flag indicating if this is a full or partial price update.

subject

The Subject of the price event.

Type

Subject

price

The map of updated price field.

Type

dict

full

A boolean flag indicating if the update represents a full or partial update. The value is set to True for a full price image and False for a partial update.

Type

bool

SubscriptionEvent

class bidfx.SubscriptionEvent(subject, status, explanation)

This class defines a Subscription Event that gets published whenever the status of subscription changes. Subscription events should be handled by setting a callback function via PricingAPI.callbacks. The callback function could be implemented and used as follows.

def on_subscription_event(event):
    print(f"Subscription to {event.subject} is {event.status.name}")

def main():
    session = Session.create_from_ini_file()
    pricing.callbacks.subscription_event_fn = on_subscription_event
Parameters
  • subject (Subject) – The unique subject of the price subscription.

  • status (SubscriptionStatus) – The subscription status.

  • explanation (str) – An explanation of the status reason.

subject

The Subject of the price event.

Type

Subject

status

The SubscriptionStatus associated with the event.

Type

SubscriptionStatus

explanation

An optional explanation message for the status event.

Type

str

ProviderEvent

class bidfx.ProviderEvent(provider, status, explanation)

This class defines Provider Event that gets published whenever the status of price provider changes. Provider events should be handled by setting a callback function via PricingAPI.callbacks. The callback function could be implemented and used as follows.

def on_provider_event(event):
    print(f"Provider {event.provider} is {event.status.name}")

def main():
    session = Session.create_from_ini_file()
    pricing.callbacks.provider_event_fn = on_provider_event
Parameters
  • provider (str) – The unique name of the price provider.

  • status (ProviderStatus) – The provider status.

  • explanation (str) – An explanation of the status reason.

provider

The name of the price provider that issued the event.

Type

str

status

The ProviderStatus associated with of the event.

Type

ProviderStatus

explanation

An optional explanation message for the status event.

Type

str

SubscriptionStatus

class bidfx.SubscriptionStatus

This enum defines the number of different statuses that can be applied to a pricing subscription.

OK = 1

The subscription is OK. This state is not normally published, it is implied by any price update.

PENDING = 2

The subscription is pending an update from an upstream service or provider.

STALE = 3

The subscription is stale, possibly due to a connection issue.

CANCELLED = 4

The subscription has been cancelled.

DISCONTINUED = 5

The subscription has been discontinued by the provider (common on RFQ subscriptions).

PROHIBITED = 6

The subscription is prohibited by entitlements.

UNAVAILABLE = 7

The subscription is unavailable perhaps due to routing issues or setup.

REJECTED = 8

The subscription has been rejected by the provider.

TIMEOUT = 9

The subscription has timed out.

INACTIVE = 10

The subscription has been detected as being inactive.

EXHAUSTED = 11

The subscription is has exhausted a usage limit or resource.

CLOSED = 12

The subscription has been closed (normally by the client API). This is a terminal state.

ProviderStatus

class bidfx.ProviderStatus

This enum defines the number of different statuses that can be applied to a price provider.

READY = 1

The price provider is ready for use.

DISABLED = 2

The price provider is has been disabled.

DOWN = 3

The price provider is down and attempting to reconnect.

UNAVAILABLE = 4

The price provider is unavailable.

INVALID = 5

The price provider is invalid most likely due to misconfiguration.

CLOSED = 6

The price provider has been closed. This is the terminal state.

Field

class bidfx.Field

Fields provides constants for the most commonly used price field names.

ASK = 'Ask'

Price field containing the ask price.

ASK_END_SIZE = 'AskEndSize'

Price field containing the ask size of the end leg of a swap or NDS.

ASK_EXCHANGE = 'AskExchange'

Price field containing the exchange code from where the ask price has originated.

ASK_FORWARD_POINTS = 'AskForwardPoints'

Price field containing the ask forward points of an FX forward.

ASK_ID = 'AskID'

Price field containing the price ID of a quote of the ask side of an quote book.

ASK_LEVELS = 'AskLevels'

Price field containing the number of market-depth levels of the ask side of an order book.

ASK_FIRM = 'AskFirm'

Price field containing the firm (company) offering on the ask side of an order book.

ASK_SIZE = 'AskSize'

Price field containing the ask size.

ASK_SPOT = 'AskSpot'

Price field containing the ask spot rate associated with an FX forward.

ASK_TICK = 'AskTick'

Price field containing the tick direction for the ask price relative to the previous price.

ASK_TIME = 'AskTime'

Price field containing the time of the last change in the ask price.

BID = 'Bid'

Price field containing the bid price.

BID_END_SIZE = 'BidEndSize'

Price field containing the bid size of the end leg of a swap or NDS.

BID_EXCHANGE = 'BidExchange'

Price field containing the exchange code from where the bid price has originated.

BID_FORWARD_POINTS = 'BidForwardPoints'

Price field containing the bid forward points of an FX forward.

BID_ID = 'BidID'

Price field containing the price ID of a quote of the bid side of an quote book.

BID_LEVELS = 'BidLevels'

Price field containing the number of market-depth levels of the bid side of an order book.

BID_FIRM = 'BidFirm'

Price field containing the firm (company) offering on the bid side of an order book.

BID_SIZE = 'BidSize'

Price field containing the bid size.

BID_SPOT = 'BidSpot'

Price field containing the bid spot rate associated with an FX forward.

BID_TICK = 'BidTick'

Price field containing the tick direction for the bid price relative to the previous price.

BID_TIME = 'BidTime'

Price field containing the time of the last change in the bid price.

BROKER = 'Broker'

Price field containing the name of the broker quoting the price.

CLOSE = 'Close'

Price field containing the previous market close price.

HIGH = 'High'

Price field containing the market high price for the current day or session.

LAST = 'Last'

Price field containing the last traded price.

LAST_SIZE = 'LastSize'

Price field containing the size of the last trade.

LAST_TICK = 'LastTick'

Price field containing the tick direction of the last trade relative to the previous trade.

LOW = 'Low'

Price field containing the market low price for the current day or session.

NET_CHANGE = 'NetChange'

Price field containing the net change in price between the last price and the open price.

NUM_ASKS = 'NumAsks'

Price field containing the number of participants offering at the ask price.

NUM_BIDS = 'NumBids'

Price field containing the the number of participants bidding at the bid price.

OPEN = 'Open'

Price field containing the market price at the open.

OPEN_INTEREST = 'OpenInterest'

Price field containing the open interest in a future.

ORIGIN_TIME = 'OriginTime'

Price field containing the time of a price tick as measured at the originating source.

PERCENT_CHANGE = 'PercentChange'

Price field containing the percentage change between the last price and the market open.

PRICE_ID = 'PriceID'

Price field containing the ID used by an LP to identify a tradable quote.

STRIKE = 'Strike'

Price field containing the strike price of an option.

VOLUME = 'Volume'

Price field containing the volume.

VWAP = 'VWAP'

Price field containing the volume weighted average price.