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.

stop()¶: Stops the pricing threads.

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.

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`.

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.

start()¶: Starts the pricing threads which connect to and manage real-time price services asynchronously.

stop()¶: Stops the pricing threads.

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.

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.

Table of Contents

Previous topic