traderion2.client.TraderionClient¶

class traderion2.client.TraderionClient(username, password, room_id, bot, connect_to_ws=True)¶

Main API interface.

__init__(username, password, room_id, bot, connect_to_ws=True)¶

Initialize Traderion client.

On instantiation, the client will authenticate with the provided credentials. You can then use this client to send commands (e.g. add an electronic broker order) or get information about the game state (e.g. get the market price at some point).

Parameters:	username (str) -- traderion username password (str) -- traderion password room_id (str) -- id of the current playing room bot (`TraderionBot`) -- bot associated with this client
Raises:	LoginError -- if the credentials are not correct BadRequest -- this most likely means a non-existent room id ServerError -- if some other error occured on the server

Methods

`__init__`(username, password, room_id, bot[, ...])	Initialize Traderion client.
`get_room_status`()	Returns the room status.
`get_swifts`()	Returns the swifts for this scenario.
`get_room_params`()	Return the room parameters for this scenario.
`get_dp_orders`([swift_id, direction])	Returns your current (pending) DP (dark pool) orders.
`get_eb_orders`([swift_id, direction])	Returns your current (pending) EB orders.
`get_eb_depth`([swift_id, direction])	Returns the current electronic broker depth.
`get_market_prices`([swift_id])	Returns the current market prices.
`get_price_curves`([swift_id])	Returns the current price curves.
`get_positions`([swift_id])	Returns your current positions.
`accept_client_call`(call_id)	Call this method to accept a client call.
`decline_client_call`(call_id)	Call this method to decline a client call.
`dp_add_order`(swift_id, direction, amount[, ...])	Call this method to add an order in the dark pool.
`dp_cancel_all_orders`(swift_id)	Call this method to cancel all dark pool orders for a swift.
`dp_cancel_order`(order_id)	Call this method to cancel a dark pool order.
`eb_add_order`(swift_id, direction, amount, price)	Call this method to add an order in the electronic broker.
`eb_cancel_all_orders`(swift_id)	Call this coroutine to cancel all electronic broker orders for a swift.
`eb_cancel_order`(order_id)	Call this method to cancel an electronic broker order.
`hit_ib_call`(call_id, direction)	Call this method to hit the bid or ask price of an answered IB outgoing call.
`hit_price`(swift_id, direction, amount[, ...])	Call this method to hit orders in the electronic broker.
`make_ib_call`(swift_id, amount)	Call this method to make an IB call.
`ntg_ib_call`(call_id)	Call this method to respond with NTG to an answered outgoing IB call.
`quote_client_call`(call_id, quote)	Call this method to quote a client call.
`quote_ib_call`(call_id, bid, ask)	Call this method to quote an IB call.

get_room_status()¶

Returns the room status.

Returns:	one of `'pending'` \| `'playing'` \| `'paused'` \| `'finished'`
Return type:	str

get_swifts()¶

Returns the swifts for this scenario.

Returns:	a list of swift objects
Return type:	list

Swift object structure:

swift_id (int): swift id
code (str): swift code (e.g. 'EUR/USD')
name (str): swift name (e.g. 'EUR/USD')
asset_class (str): one of 'FX' | 'EQ' | 'FI'
reporting_currency (str): currency used for reporting PnL (e.g. 'USD')
basis_point (str): basis point as string (e.g. '0.0001') (is always equal to 10^(-decimal_places))
decimal_places (int): number of decimals used when reporting the price
tick (int): minimum upward or downward movement in the price
ticket_unit (int): smallest amount that can be traded (all amounts are multiples of this amount)
extra (dict): dictionary with extra information for 'FI':
- issue_date
- years
- frequency
- coupon
- face_value

get_room_params()¶

Return the room parameters for this scenario.

Returns:	room parameters as a dictionary
Return type:	dict

Room parameters dictionary structure:

{
    'general': {                 # general parameters
        'param1': value
        ...
    },
    'swift_id1': {               # swift1 parameters
        'swift1_param1': value
        ...
    }
    'swift_id2': {               # swift2 parameters
        'swift1_param1': value
        ...
    }
    ...
}

General parameters:

IB_CALLS_ENABLED: 0/1 (False/True)
IB_CALLS_SECONDS: number of seconds after which an IB call expires
CLIENT_CALLS_ENABLED: 0/1 (False/True)
CLIENT_CALL_SECONDS: number of seconds after which a client call expires
IMPACT_VOTE_SECONDS: duration of an impact vote (in seconds)

Per swift parameters:

PLAYERS_MIN_TICKET: minimum amount a player can trade on a single deal
PLAYER_MAX_TICKET: maximum amount a player can trade on a single deal
PLAYERS_POSITION_LIMIT: maximum position a player should have at any point
PLAYERS_IB_MAX_SPREAD: maximum spread on IB calls quotes

get_dp_orders(swift_id=None, direction=None)¶

Returns your current (pending) DP (dark pool) orders.

If swift_id and direction are not specified, orders for all swifts and both directions (BID and ASK) are returned. If only the swift_id is specified, orders for both directions are returned for that swift. If direction is also specified, only the orders for that direction (and that swift) are returned.

Parameters:	swift_id (None or int) -- swift id (default is None) direction (None or int) -- None or one of 0/1 (`BID`/`ASK`) (default is None). Must be None if swift_id is None.
Returns:	the requested DP orders
Return type:	dict

Returned object structure:

swift_id is specified, direction is specified:
```
list of DP orders
```

swift_id is specified, direction is None

{
    BID: list of DP orders,
    ASK: list of DP orders
}

swift_id is None, direction is None

{
    swift_id1: {
        BID: list of DP orders,
        ASK: list of DP orders
    },
    swift_id2: {
        BID: list of DP orders,
        ASK: list of DP orders
    }
    ...
}

DP order object 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): order amount
price (None or float): order price for limit orders. For market orders, this is always None.
status (str): one of 'pending' | 'completed' | 'cancelled'

get_deals()¶

Returns the history of trades made by the bot's user.

Returns: history of trades

Return type:

dict

{

swift_id1: {: list of deals for swift_id1

}, swift_id2: {

list of deals for swift_id2

}

Deal object structure:

id (int): deal id
room_id (id): room id
room_time (int): room time when the deal was done
swift_id (int): swift id
market_maker_id (id*): uuid of the market maker. In case of EB, it is the user placing the order
market_maker_name (str*): name of the market maker. In case of EB, it is the user placing the order
market_taker_id (id*): uuid of the market taker.
market_taker_name (id*): name of the market taker.
direction (int): 0/1 (BID/ASK) (you buy/you sell). 0 means the market taker bought from the market maker. 1 means the market taker sold to the market maker.
amount (int): deal amount
price (float): deal price
deal_source (str): one of 'INTERBANK' | 'CLIENT' | 'EB' | 'LB' | 'DP'

get_eb_orders(swift_id=None, direction=None)¶

Returns your current (pending) EB orders.

If swift_id and direction are not specified, orders for all swifts and both directions (BID and ASK) are returned. If only the swift_id is specified, orders for both directions are returned for that swift. If direction is also specified, only the orders for that direction (and that swift) are returned.

Parameters:	swift_id (None or int) -- swift id (default is None) direction (None or int) -- None or one of 0/1 (`BID`/`ASK`) (default is None). Must be None if swift_id is None.
Returns:	the requested EB orders
Return type:	dict

Returned object structure:

swift_id is specified, direction is specified:
```
list of EB orders
```

swift_id is specified, direction is None

{
    BID: list of EB orders,
    ASK: list of EB orders
}

swift_id is None, direction is None

{
    swift_id1: {
        BID: list of EB orders,
        ASK: list of EB orders
    },
    swift_id2: {
        BID: list of EB orders,
        ASK: list of EB orders
    }
    ...
}

EB order object 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): order amount
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' | 'cancelled'

get_eb_depth(swift_id=None, direction=None)¶

Returns the current electronic broker depth.

If swift_id and direction are not specified, depths for all swifts and both directions (BID and ASK) are returned. If only the swift_id is specified, depths for both directions are returned for that swift. If direction is also specified, only the depth for that direction (and that swift) is returned.

Be mindful that your own orders also appear in the EB depth. In the case of Iceberg orders, only the visible amount of the order will be considered in the EB depth.

Parameters:	swift_id (None or int) -- swift id (default is None) direction (None or int) -- None or one of 0/1 (`BID`/`ASK`) (default is None). Must be None if swift is None.
Returns:	the requested EB depths
Return type:	dict

Returned object structure:

swift_id is specified, direction is specified
```
an EB depth object
```

swift_id is specified, direction is None

{
    BID: EB depth object,
    ASK: EB depth object
}

swift_id is None, direction is None

{
    swift_id1: {
        BID: EB depth object,
        ASK: EB depth object
    },
    swift_id2: {
        BID: EB depth object,
        ASK: EB depth object
    }
    ...
}

EB depth object structure:

list of EB depth orders (dictionaries) with the 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 be made up of 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.

get_market_prices(swift_id=None)¶

Returns the current market prices.

If swift_id is not specified (None), a dictionary containing market prices for all swifts is returned (keys are swift ids and values are market price objects). Otherwise, the market price object for the specified swift is returned.

Parameters:	swift_id (None or int) -- swift id (default is None)
Returns:	if swift_id is None, market prices for all swifts. Otherwise, the market price for the specified swift.
Return type:	dict

Returned object structure:

swift_id is specified
```
a market price object
```

swift_id is None

{
    swift_id1: market price object for swift1,
    swift_id2: market price object for swift2,
    ...
}

Market price object structure:

swift_id (int): swift id
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)

get_price_curves(swift_id=None)¶

Returns the current price curves.

If swift_id is not specified (None), a dictionary containing price curves for all swifts is returned (keys are swift ids and values are price curve objects). Otherwise, the price curve object for the specified swift is returned.

Parameters:	swift_id (None or int) -- swift id (default is None)
Returns:	if swift_id is None, price curves for all swifts. Otherwise, the price curve for the specified swift.
Return type:	list or dict

Returned object structure:

swift_id is specified
```
a price curve
```

swift_id is None

{
    swift_id1: price curve for swift1,
    swift_id2: price curve for swift2,
    ...
}

Structure of a price curve:

list of price curve points (dictionaries) with structure:

swift_id (int): swift id
room_time (int): room time when the price was reported
price (float): reported mid price (average of bid and ask at room_time)

get_positions(swift_id=None)¶

Returns your current positions.

If swift_id is not specified (None), a dictionary containing positions for all swifts is returned (keys are swift ids and values are position objects). Otherwise, the position for the specified swift is returned.

Parameters:	swift_id (int) -- swift id (default is None)
Returns:	if swift_id is None, positions for all swifts. Otherwise, the position for the specified swift.
Return type:	dict

Returned object structure:

swift_id is specified
```
a position object
```

swift_id is None

{
    swift_id1: position object for swift1,
    swift_id2: position object for swift2,
    ...
}

Position object structure:

swift_id (int): swift id
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 accept_client_call(call_id)¶

Call this method to accept a client call.

The client_price of this call must not be None.

Parameters:	call_id (int) -- call id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await decline_client_call(call_id)¶

Call this method to decline a client call.

The client_price of this call must not be None.

Parameters:	call_id (int) -- call id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await dp_add_order(swift_id, direction, amount, price=None)¶

Call this method to add an order in the dark pool.

Orders can have 2 types:

Market orders: orders that are executed at the market mid price. This is the default.
Limit orders: orders that are executed at a price equal or better than the specified price. You can add a limit order by setting the price parameter.

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) (you buy / you sell) order direction amount (int) -- order amount price (None or float) -- order price for a limit order (default is None). If None, the order will be a market order. Otherwise, it will be a limit order.
Returns:	a dictionary with error and data fields. If no error occured, error is None and data is the order id. Otherwise, error will be a dictionary with two string fields: code and detail.
Return type:	dict
Raises:	CommandTimeoutError: if the server took too long to respond

await dp_cancel_all_orders(swift_id)¶

Call this method to cancel all dark pool orders for a swift.

Parameters:	swift_id (int) -- swift id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Raises:	CommandTimeoutError -- if the server took too long to respond

await dp_cancel_order(order_id)¶

Call this method to cancel a dark pool order.

Parameters:	order_id (int) -- order id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Raises:	CommandTimeoutError -- if the server took too long to respond

await eb_add_foc(swift_id, direction, amount, price)¶

Add 'Fill-or-Kill' order in the electronic broker.

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) (you buy / you sell) order direction amount (int) -- order amount price (float) -- order price

await eb_add_ioc(swift_id, direction, amount, price)¶

Add 'Immediate-or-Cancel' order in the electronic broker.

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) (you buy / you sell) order direction amount (int) -- order amount price (float) -- order price

await eb_add_mo(swift_id, direction, amount)¶

Add market order in the electronic broker.

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) (you buy / you sell) order direction amount (int) -- order amount

await eb_add_order(swift_id, direction, amount, price, chunk=None, plus=False)¶

Call this method to add an order in the electronic broker.

Orders can have 4 types:

Limit orders: this is the default.
Iceberg orders: only a chunk of the full amount is visible in the electronic broker at any time. You can add an Iceberg order by setting the chunk parameter. Iceberg orders have an increased ticket limit.
Limit Plus orders: limit orders that can be executed in the dark pool as well (possibly at a better price).
Iceberg Plus orders: Iceberg orders that can be executed in the dark pool as well (possibly at a better price).

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) (you buy / you sell) order direction amount (int) -- order amount price (float) -- order price chunk (None or int) -- visible chunk for an Iceberg order (default is None). If None, the order will be a limit order. Otherwise, it will be an Iceberg order. plus (bool) -- whether the order should be a Plus order (default is False). A Plus order can be executed in the dark pool as well.
Returns:	a dictionary with error and data fields. If no error occured, error is None and data is the order id. Otherwise, error will be a dictionary with two string fields: code and detail.
Return type:	dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await eb_cancel_all_orders(swift_id)¶

Call this coroutine to cancel all electronic broker orders for a swift.

Parameters:	swift_id (int) -- swift id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Raises:	CommandTimeoutError -- if the server took too long to respond

await eb_cancel_order(order_id)¶

Call this method to cancel an electronic broker order.

Parameters:	order_id (int) -- order id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Raises:	CommandTimeoutError -- if the server took too long to respond

await hit_ib_call(call_id, direction)¶

Call this method to hit the bid or ask price of an answered IB outgoing call.

This method should be called only after the IB call was answered (quoted). The recommended way is to call it from TraderionBot.on_ib_call_answered.

Parameters:	call_id (int) -- call id direction (int) -- the price you hit: 0/1 (`BID`/`ASK`)
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await hit_price(swift_id, direction, amount, price=None, fill_or_kill=False)¶

Call this method to hit orders in the electronic broker.

This method will hit all orders with a price equal or better to the specified price up to the specfied amount. Orders with a better price are hit first. A better price means higher for BID and lower for ASK.

Parameters:	swift_id (int) -- swift id direction (int) -- 0/1 (`BID`/`ASK`) direction to hit amount (int) -- maximum hit amount (you might hit less than this amount in various conditions: for example, when there isn't enough volume at an acceptable price) price (None or float) -- price to hit. All orders with this price or a better price are considered (better prices are considered first). If unspecified, the best price (market price) for the specified direction is hit. fill_or_kill (bool) -- whether this is a Fill Or Kill hit (default is False). A Fill Or Kill hit will hit for the whole amount or none of it. In other words, if there isn't enough volume to fill the specified amount, nothing will happen (no orders will be hit).
Returns:	a dictionary with error and data fields. If no error occured, error is None and data is the amount that was hit. Otherwise, error will be a dictionary with two string fields: code and detail.
Return type:	dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await make_ib_call(swift_id, amount)¶

Call this method to make an IB call.

If this operation is successful, you should expect other banks to respond to your call, which means TraderionBot.on_ib_call_answered will get called (once for every offer you receive).

Note: this method will return an error if you have unanswered offers from previous ib calls you made.

Parameters:	swift_id (int) -- swift id amount (int) -- amount you want to buy/sell
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await ntg_ib_call(call_id)¶

Call this method to respond with NTG to an answered outgoing IB call.

This method should be called only after the IB call was answered (quoted). The recommended way is to call it from TraderionBot.on_ib_call_answered.

Parameters:	call_id (int) -- call id
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await quote_client_call(call_id, quote)¶

Call this method to quote a client call.

The client_price of this call must be None. If this operation is successful, you should expect the client to either accept or reject the offer, which means one of TraderionBot.on_client_call_accepted or TraderionBot.on_client_call_declined will get triggered.

Parameters:	call_id (int) -- call id quote (float) -- the price offered to the client
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await quote_ib_call(call_id, bid, ask)¶

Call this method to quote an IB call.

If this operation is successful, you should expect the client bank to either hit the offer (on bid or ask) or do nothing, which means one of TraderionBot.on_ib_call_hit or TraderionBot.on_ib_call_ntg will get triggered.

Parameters:	call_id (int) -- call id bid (float) -- your bid price ask (float) -- your ask price
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	None or dict
Raises:	CommandTimeoutError -- if the server took too long to respond

await request_orderbook_history(swift_id, last_n_seconds=None)¶

Call this method to request the orderbook history from the server. The server will respond with a message 'eb.cmd.order_book_history.sent' containing a snapshot for each game second.

Parameters:	swift_id (int) -- Pass the swift id of the market depth you want to access last_n_seconds (int) -- Filter the orderbook snapshots by room second. Default is None and will imply no filtering.
Returns:	None if no error occured. Otherwise, an error as a dictionary with two string fields: code and detail.
Return type:	dict
Raises:	CommandTimeoutError -- if the server took too long to respond

traderion2.client.TraderionClient¶

Traderion

Navigation

Related Topics