traderion2.bot.TraderionBot

class traderion2.bot.TraderionBot(username, password, room_id, loop_sleep=1, show_info=False)

Base class to create a custom trading bot.

__init__(username, password, room_id, loop_sleep=1, show_info=False)

Initialize Traderion bot.

On instantiation it will create a TraderionClient with the provided credentials and will store it in a member called api. Through this member you will call the API methods.

After creating a TraderionBot object, you should call its run method in your main event loop. See the example for more details.

Parameters:
  • username (str) -- traderion username
  • password (str) -- traderion password
  • room_id (str) -- id of the current playing room
  • loop_sleep (float) -- the frequency (in seconds) of the main loop, defaults to 1
Raises:
  • LoginError -- if the credentials are not correct
  • BadRequest -- this most likely means an incorrect room id
  • ServerError -- if some error occured on the server

Methods

__init__(username, password, room_id[, ...]) Initialize Traderion bot.
main_loop() Bot main loop.
on_client_call_accepted(client_call) Client call accepted callback.
on_client_call_declined(client_call) Client call declined callback.
on_client_call_expired(client_call) Client call expired callback.
on_eb_depth_change(swift_id, direction, ...) EB depth change callback.
on_eb_order_hit(market_taker, hit_amount, ...) EB order hit callback.
on_ib_call_answered(ib_call) IB call answered callback.
on_ib_call_expired(ib_call) IB call expired callback.
on_ib_call_hit(ib_call) IB call hit callback.
on_ib_call_ntg(ib_call) IB call NTG callback.
on_macro_event(macro_event) Macro event callback.
on_market_price_change(old_price, new_price) Market price change callback.
on_new_client_call(client_call) New client call callback.
on_new_ib_call(ib_call) New IB call callback.
on_position_change(old_position, new_position) Player position change callback.
on_room_param_change(category, name, ...) Room parameter change callback.
on_room_status_change(old_status, new_status) Room status change callback.
run() Starts the bot.
stop() Stops the bot early, before the room is finished.
on_room_status_change(old_status, new_status)

Room status change callback. Implement this method to receive notifications when the room status changes. Take notice that this is not a coroutine.

Parameters:
  • old_status (str) -- one of 'pending' | 'playing' | 'paused' | 'finished'
  • new_status (str) -- one of 'pending' | 'playing' | 'paused' | 'finished'
stop()

Stops the bot early, before the room is finished.

You should not override this method.

Upon calling this method, the run method will complete and the bot main_loop will no longer be called. However, event callbacks will still get called if your python script continues to run.

await main_loop()

Bot main loop. Implement this method to add some custom logic that should be run periodically.

This method will run every self.loop_sleep seconds while the room is playing. The first execution of the main loop will happen immediately (after the client connects to the room).

Check the example for more details.

await on_client_call_accepted(client_call)

Client call accepted callback. Implement this method to receive notifications when clients accept your quotes.

Parameters:client_call (dict) -- a dictionary with information about the call
Client call structure:
  • id (int): call id
  • client (str): name of the client
  • swift_id (int): swift id
  • direction (int): 0/1 (BID/ASK) (client buys/client sells)
  • amount (int): amount the client bought/sold
  • client_max_spread (int): the maximum spread you can quote to the client (can be None)
  • client_price (float): always None
  • trader_quote (float): the price you previously offered to the client
await on_client_call_declined(client_call)

Client call declined callback. Implement this method to receive notifications when clients decline your quotes.

Parameters:client_call (dict) -- a dictionary with information about the call
Client call structure:
  • id (int): call id
  • client (str): name of the client
  • swift_id (int): swift id
  • direction (int): 0/1 (BID/ASK) (client buys/client sells)
  • amount (int): amount the client wanted to buy/sell
  • client_max_spread (int): the maximum spread you can quote to the client (can be None)
  • client_price (float): always None
  • trader_quote (float): the price you previously offered to the client
await on_client_call_expired(client_call)

Client call expired callback. Implement this method to receive notifications when client calls expire.

Parameters:client_call (dict) -- a dictionary with information about the call

See on_new_client_call for the structure of the client_call object.

await on_deal_done(swift_id, deal)

Deal done callback. Implement this method to receive notifications whenever a deal is finalized, regardless of its source.

Parameters:
  • swift_id (int) -- swift id of the deal
  • deal -- the data of the deal
await on_dp_order_hit(other_party, hit_amount, price, dp_order)

Dark pool order hit callback. Implement this method to receive notifications when one of your DP orders is hit.

Parameters:
  • other_party (str) -- name of the other party
  • hit_amount (int) -- hit amount
  • price (float) -- price at which the order was executed
  • eb_order (dict) -- a dictionary with information about the DP order that was hit
DP order structure:
  • id (int): order id
  • room_time (int): room time when the order was added
  • swift_id (int): swift id
  • order_type (str): one of 'limit' | 'market'
  • direction (int): 0/1 (BID/ASK) (you buy/you sell) order direction
  • amount (int): left order amount (if 0, the order status will be 'completed')
  • price (None or float): order price for limit orders. For market orders, this is always None.
  • status (str): one of 'pending' | 'completed'
await on_eb_depth_change(swift_id, direction, old_depth, new_depth)

EB depth change callback. Implement this method to receive notifications when the EB depth changes.

Parameters:
  • swift_id (int) -- swift id of the depth
  • direction (int) -- 0/1 (BID/ASK) depth direction
  • old_depth (list) -- old depth (list of EB depth order objects)
  • new_depth (list) -- new depth (list of EB depth order objects)
EB depth order structure:
  • count (int): the number of atomic orders at this price
  • amount (int): total amount at this price
  • price (float): price

Note: An EB depth order can contain several atomic orders having the same price. A price appears only once in the depth and the amounts of all the atomic orders at that price are summed up. Prices are decreasing for BID depth and increasing for ASK depth.

await on_eb_order_hit(market_taker, hit_amount, price, eb_order)

EB order hit callback. Implement this method to receive notifications when one of your EB orders is hit.

Parameters:
  • market_taker (str) -- name of the market taker
  • hit_amount (int) -- hit amount
  • price (float) -- price at which the order was executed (this might not be equal to the order price for plus orders)
  • eb_order (dict) -- a dictionary with information about the EB order that was hit
EB order structure:
  • id (int): order id
  • room_time (int): room time when the order was added
  • swift_id (int): swift id
  • order_type (str): one of 'limit' | 'iceberg' | 'limit_plus' | 'iceberg_plus'
  • direction (int): 0/1 (BID/ASK) (you buy/you sell) order direction
  • amount (int): left order amount (if 0, the order status will be 'completed')
  • chunk (None or int): visible chunk for an Iceberg order. Is None if the order is not an Iceberg
    one.
  • visible_amount (int): the visible amount of the order. For Limit orders, this is equal to the order
    amount. For Iceberg orders, this will always be min(amount, chunk).
  • price (float): order price
  • status (str): one of 'pending' | 'completed'
await on_ib_call_answered(ib_call)

IB call answered callback. Implement this method to receive notifications when your outgoing IB calls are answered. This coroutine will be called once for every offer you receive after you make an IB call.

You can respond to the offer in 2 ways:

If you don't respond to an offer, it will expire on its own after some time, but you will be unable to make other IB calls until that happens.

Parameters:ib_call (dict) -- a dictionary with information about the call
IB call structure:
  • id (int): call id
  • market_taker (str): name of the market taker (which is always your username)
  • market_maker (str): name of the market maker
  • swift_id (int): swift id
  • amount (int): amount you wanted to buy/sell
  • direction: always None
  • bid (float): the bid offer
  • ask (float): the ask offer
await on_ib_call_expired(ib_call)

IB call expired callback. Implement this callback to receive notifications when an IB call expires.

You will receive this notification in 4 cases:
  1. you haven't quoted an incoming call
  2. you have quoted an incoming call, but the other party din't respond (by hitting or NTG)
  3. some other trader didn't quote your outgoing call
  4. some other trader quoted your outgoing call, but you didn't respond (by hitting or NTG)

You can differentiate between these cases by checking the parameters in the following way:

1. market_maker == your_username and bid is None
2. market_maker == your_username and bid is not None
3. market_taker == your_username and bid is None
4. market_taker == your_username and bid is not None
Parameters:ib_call -- a dictionary with information about the call
IB call structure:
  • id (int): call id
  • market_taker (str): name of the market taker
  • market_maker (str): name of the market maker
  • swift_id (int): swift id
  • amount (int): amount
  • direction: always None
  • bid (None or float): the bid offer (can be None if the call wasn't quoted)
  • ask (None or float): the ask offer (can be None if the call wasn't quoted)
await on_ib_call_hit(ib_call)

IB call hit callback. Implement this method to receive notifications when a client bank hits your offer.

You can determine which one of bid or ask price was hit based on the direction parameter.

Parameters:ib_call (dict) -- a dictionary with information about the call
IB call structure:
  • id (int): call id
  • market_taker (str): name of the market taker
  • market_maker (str): name of the market maker (which is always your username)
  • swift_id (int): swift id
  • amount (int): amount the client bank bought/sold
  • direction (int): which price the client bank hit: 0/1 (BID/ASK) (client bank sells/buys)
  • bid (float): your bid offer
  • ask (float): your ask offer
await on_ib_call_ntg(ib_call)

IB call NTG callback. Implement this method to receive notifications when a client bank responds with NTG on your offer.

Parameters:ib_call (dict) -- a dictionary with information about the call
IB call structure:
  • id (int): call id
  • market_taker (str): name of the market taker
  • market_maker (str): name of the market maker (which is always your username)
  • swift_id (int): swift id
  • amount (int): amount the client bank wanted to buy/sell
  • direction: always None
  • bid: your bid offer
  • ask: your ask offer
await on_macro_event(macro_event)

Macro event callback. Implement this callback to receive notifications when macro events happen.

Parameters:macro_event (dict) -- details about the macro event
Macro event structure:
  • event_type (str): type of the event. It is either 'news' or 'forecast'
  • event_data (dict): dictionary with extra details about the event (depends on the event type)
News event data:
  • headline (str): event headline text (a brief description of what happened)
  • body (str): event body text (a more detailed description of what happened)
Forecast event data:
  • country (str): country in question
  • indicator (str): forecast indicator (e.g. 'Average Weekly Hours')
  • description (str): detailed description of the indicator
  • previous (str): previous value of the indicator (as string)
  • forecast (str): forecasted value of the indicator (as string) (can be '')
  • actual (str): actual value of the indicator (current value) (as string)
  • unit (str): unit of measurement for the indicator (e.g. '%', 'K') (can be '')
await on_market_price_change(old_price, new_price)

Market price change callback. Implement this method to receive notifications when market prices change.

Parameters:
  • old_price (dict) -- old state of the prices (market price object)
  • new_price (dict) -- new state of the prices (market price object)
Market price object structure:
  • swift_id (int): swift id for which the price changed (has the same value for old_prices and new_prices)
  • open (float): the open price of the scenario
  • bid (float): market bid price
  • ask (float): market ask price
  • price (float): market mid price (average of bid and ask)
await on_market_price_chart_updated(swift_id, new_price)
Market price chart update callback. Implement this callback to receive notifications when the price chart
is updated.
Parameters:
  • swift_id -- The ID of the swift that has an update in the prie chart.
  • new_price -- New price that is added in the price chart.
await on_new_client_call(client_call)

New client call callback. Implement this method to receive notifications when a new client call is available.

If the client_price attribute in the client_call is None, then the client needs a quote, otherwise you have to either accept or decline the call. In the first case, you should call self.api.quote_client_call. In the second case, you should call one of self.api.accept_client_call or self.api.decline_client_call.

If you don't respond to the call, it will expire after some time.

Parameters:client_call (dict) -- a dictionary with information about the call
Client call structure:
  • id (int): call id
  • client (str): name of the client
  • swift_id (int): swift id
  • direction (int): 0/1 (BID/ASK) (client buys/client sells)
  • amount (int): amount the client wants to buy/sell
  • client_max_spread (int): the maximum spread you can quote to the client (can be None)
  • client_price (float): the price at which the client wants to buy/sell (None if the client requests quote)
  • trader_quote: always None
await on_new_ib_call(ib_call)

New IB call callback. Implement this method to receive notifications when a new IB call is available.

You will only receive notifications about calls where you are the market maker (some bank asks you for bid and ask prices). For responding to the call, you should call self.api.quote_ib_call.

Parameters:ib_call (dict) -- a dictionary with information about the call
IB call structure:
  • id (int): call id
  • market_taker (str): name of the market taker
  • market_maker (str): name of the market maker (which is always your username)
  • swift_id (int): swift id
  • amount (int): amount the client bank wants to buy/sell
  • direction: always None
  • bid: always None
  • ask: always None
await on_position_change(old_position, new_position)

Player position change callback. Implement this callback to receive notifications when your position changes.

Parameters:
  • old_position (dict) -- old state of the position (position object)
  • new_position (dict) -- new state of the position (position object)
Position object structure:
  • swift_id (int): swift id for which the position changed (has the same value for old_position and new_position)
  • amount (int): amount of the position
  • rate (float): average rate of the position
  • pnl (int): the PnL expressed in the reporting currency of the swift
  • converted_pnl (int): the PnL expressed in USD
  • pnl_percentage (float): the PnL relative to the position limit
  • return_on_volume (float): the PnL relative to the total traded volume
  • max_position (int): maximum position (amount) you had since the beginning of the game
  • total_volume (int): total traded volume
  • yield (float or None): bond yield (None if the asset type is not FI)
  • dv01 (int or None): bond DV01 (None if the asset type is not FI)
  • day_change (float): difference between the current market price and the open price
await on_room_param_change(category, name, old_value, new_value)

Room parameter change callback. Implement this method to receive notifications when a room parameter changes.

Parameters:
  • category (str) -- category of the parameter (is either 'general' or a swift id (as string))
  • name (str) -- parameter name
  • old_value (int) -- parameter old value
  • new_value (int) -- parameter new value
await run()

Starts the bot. Call this method in your main event loop to start the bot (check the example for more details).

You should not override this method.

The bot will run until the room is finished. If the room is already finished, it will return immediately. You can still query the API after the room is finished (for example to get your final PnL), but some methods will obviously not work (for example, you cannot make an IB call in a finished room).

If you need to stop the bot early, use the stop method.