API Objects =========== There are several entities that you will work with during the simulation. These are: * Room status * Room parameters * Market prices * Price curve * Trading position * Client calls * Electronic Broker orders * Electronic Broker depth Room status ----------- The room is either *playing*, *paused*, or *finished*. The bot's *run* method will run until the room is finished. The bot's *main_loop* method will be called only when the room is playing. You won't be able to make API calls if the room is not playing. You can get notifications about status updates by implementing :meth:`traderion.bot.TraderionBot.on_room_status_change`. Room parameters --------------- These provide information about what type of session you are playing and your ticket limits. You can get the parameters by calling :meth:`traderion.client.TraderionClient.get_room_parameters` from your bot. The parameters are: **asset_class**: the name of the asset class (ex: FX, EQ, FI) * FX - forex * EQ - equities/stocks * FI - fixed income/bonds **swift**: the name of the asset you are dealing (ex: EUR/USD, TSLA, US10Y) **ticket_unit**: the full amount of a ticket of value 1 (ex: 1000000 for FX, 1 for EQ, 1000000 for FI) **Note**: Most of the amounts in the API are expressed as **short amounts**. For example, in FX, an amount of 50000000 is expressed as 50. To get the full amount you'll have to multiply by the *ticket_unit*. In EQ, the *ticket_unit* will be 1 (you can theoretically buy one stock) so the short amount will equal the full amount. **min_ticket**: the minimum dealing ticket (in short amount, ex: 1 for FX) **max_ticket**: the maximum dealing ticket (in short amount, ex: 10 for FX) **price_decimals**: the number of decimals in a quotation (ex: 4 for FX, 2 for EQ) Market prices ------------- **bid**: the current market bid **ask**: the current market ask **open**: the open price of the session You can get the prices by calling :meth:`traderion.client.TraderionClient.get_market_prices` from your bot. You can get notifications about market price updates by implementing :meth:`traderion.bot.TraderionBot.on_market_price_change`. Price curve ----------- The price curve is a list of tuples. Each tuple represents a point on the chart and has two values: the **date** of the price and the actual **price** (market ask). You can get the prices by calling :meth:`traderion.client.TraderionClient.get_price_curve` from your bot. You can get notifications about price curve updates by implementing :meth:`traderion.bot.TraderionBot.on_price_curve_change`. Trading position ---------------- This is an object with all the info about your position. All the amounts in this object are **full amounts**. The most important pieces of information here are the **amount** and the **rate**. **amount**: full amount of the position **rate**: average rate of the position **pnl**: the PnL expressed in the reporting currency of the swift **converted_pnl**: the PnL expressed in USD **pnl_percentage**: the PnL relative to the position limit **return_on_volume**: the PnL relative to the total traded volume **limit**: position limit (full amount) **mat**: management action trigger (1% of the position limit) **risk**: the absolute amount over the position limit **limit_utilization**: (percent) position amount from position limit **headroom**: the available amount to trade before the position limit is broken You can get the position by calling :meth:`traderion.client.TraderionClient.get_position` from your bot. You can get notifications about position updates by implementing :meth:`traderion.bot.TraderionBot.on_position_change`. Client calls ------------ There are two types of client calls: * Calls that need quotation - client wants to buy/sell and you'll have to offer a quote. * Calls that need confirmation - client had already set the price and you'll have to either accept or decline the offer. When quoting to the client, you'll have to take a reasonable spread from the market, otherwise the client won't accept your offer. There are some clients with *binding contract* that sets a *max spread* from the market that will be accepted. The BUY/SELL directions (or BID/ASK) are encoded as integers 0/1. A client call has the following structure: **id**: call id **client**: name of the client **date**: call date **amount**: call amount (short amount) **direction**: 0/1 (BID/ASK, client buys/client sells) **is_hedging**: whether the client is a hedge fund or not **is_binding**: whether there is a binding contract with the client or not **max_spread**: the maximum spread you can quote to the client (None if is_binding is False) **client_price**: the price at which the client wants to buy or sell (None if the client requests quote) **trader_quote**: the quote offered by the trader (None if client_price is not None or the trader hasn't quoted yet) You can get the pending client calls by calling :meth:`traderion.client.TraderionClient.get_client_calls` from your bot. You can get notifications about new clients by implementing :meth:`traderion.bot.TraderionBot.on_new_client_call`. To quote a client, call :meth:`traderion.client.TraderionClient.quote_client_call` from your bot. To accept a client, call :meth:`traderion.client.TraderionClient.accept_client_call` from your bot. To decline a client, call :meth:`traderion.client.TraderionClient.decline_client_call` from your bot. To get notified when a client accepts your quote (or you accept his offer) implement :meth:`traderion.bot.TraderionBot.on_client_deal`. To get notified when a client rejects your quote (or you decline his offer) implement :meth:`traderion.bot.TraderionBot.on_client_reject`. Electronic Broker orders ------------------------ An eb order has the following structure: **id**: order id **amount**: order amount (short amount) **direction**: 0/1 (= BID/ASK) **price**: order price **date**: date added You can get your pending orders by calling :meth:`traderion.client.TraderionClient.get_orders` from your bot. You can get notifications about orders updates by implementing :meth:`traderion.bot.TraderionBot.on_orders_change`. To add order, call :meth:`traderion.client.TraderionClient.add_order` from your bot. To cancel an order, call :meth:`traderion.client.TraderionClient.cancel_order` from your bot. To cancel all of your orders, call :meth:`traderion.client.TraderionClient.cancel_all_orders` from your bot. To hit a price in electronic broker, call :meth:`traderion.client.TraderionClient.hit_price` from your bot. Electronic Broker depth ----------------------- This is the depth of the market. You will get the depth for both BID (0) and ASK (1), and the entries will be sorted with regard to the best price to hit (on each direction). Each entry consists of an amount, the price, and the number of orders. **price**: the price of the orders **amount**: the total amount of the orders with that price (short amount) **count**: the total number of orders with that price You can get the eb depth by calling :meth:`traderion.client.TraderionClient.get_eb_depth` from your bot. You can get notifications about eb depth updates by implementing :meth:`traderion.bot.TraderionBot.on_eb_depth_change`.