API Reference

ritc - A Python library for interactions with Rotman Interactive Trader Market Simulator Client Application via REST exchange API

class ritc.Asset(*args, **kwargs)

Bases: Protocol

This class is for assets.

class History(*args, **kwargs)

Bases: Protocol

This class is for asset histories.

action: str

convert_from: Sequence[Quantity]

convert_from_price: Sequence[Price]

convert_to: Sequence[Quantity]

convert_to_price: Sequence[Price]

cost: float

tick: int

ticker: str

class Lease(*args, **kwargs)

Bases: Protocol

This class is for asset leases.

containment_usage: int

convert_from: Sequence[Quantity]

convert_to: Sequence[Quantity]

id: int

next_lease_period: int

next_lease_tick: int

start_lease_period: int

start_lease_tick: int

ticker: str

type: Type

class Type(value)

Bases: str, Enum

This class is for asset types.

CONTAINER: str = 'CONTAINER'

PIPELINE: str = 'PIPELINE'

POWER_PLANT: str = 'POWER_PLANT'

PRODUCER: str = 'PRODUCER'

REFINERY: str = 'REFINERY'

SHIP: str = 'SHIP'

available_quantity: int

containment: Ticker.Quantity

convert_from: Sequence[Ticker.Quantity]

convert_to: Sequence[Ticker.Quantity]

description: str

is_available: bool

lease_price: float

start_period: int

stop_period: int

ticker: str

ticks_per_conversion: int

ticks_per_lease: int

total_quantity: int

type: Type

class ritc.CancellationResult(*args, **kwargs)

Bases: Protocol

This class is for cancellation requests.

cancelled_order_ids: Sequence[int]

class ritc.Case(*args, **kwargs)

Bases: Protocol

This class is for cases.

class Status(value)

Bases: str, Enum

This class is for case statuses.

ACTIVE: str = 'ACTIVE'

PAUSED: str = 'PAUSED'

STOPPED: str = 'STOPPED'

is_enforce_trading_limits: bool

name: str

period: int

status: Status

tick: int

ticks_per_period: int

total_periods: int

class ritc.Error(*args, **kwargs)

Bases: Protocol

This class is for error data.

code: str

message: str

wait: float

class ritc.Limit(*args, **kwargs)

Bases: Protocol

This class is for limits.

gross: float

gross_fine: float

gross_limit: int

name: str

net: float

net_fine: float

net_limit: int

class ritc.News(*args, **kwargs)

Bases: Protocol

This class is for news.

body: str

headline: str

news_id: int

period: int

tick: int

ticker: str

class ritc.Order(*args, **kwargs)

Bases: Protocol

This class is for orders.

class Action(value)

Bases: str, Enum

This class is for order actions.

BUY: str = 'BUY'

SELL: str = 'SELL'

class Status(value)

Bases: str, Enum

This class is for order statuses.

CANCELLED: str = 'CANCELLED'

OPEN: str = 'OPEN'

TRANSACTED: str = 'TRANSACTED'

class Type(value)

Bases: str, Enum

This class is for order types.

LIMIT: str = 'LIMIT'

MARKET: str = 'MARKET'

action: Action

order_id: int

period: int

price: float

quantity: float

quantity_filled: float

status: Status

tick: int

ticker: str

trader_id: str

type: Type

vwap: float

class ritc.RIT(x_api_key: str, hostname: str = 'localhost', port: int = 9999)

Bases: object

This class contains various methods that interact with the RIT Client Application.

The method names reflect the request method used, and the request path used. The positional arguments are used as part of the path, while the keyword arguments are used as parameters to the request.

For example RIT.get_case() sends a GET request to the /case path.

delete_leases(id: int) → SuccessResult

Unlease an asset.

>>> rit = RIT('G4DNIZ5D')
>>> result = rit.delete_leases(3)
>>> result
{'success': True}

Parameters:: id – The Asset.Lease.id of the asset lease.
Returns:: The success result.

delete_orders(id: int) → SuccessResult

Cancel an open order.

>>> rit = RIT('G4DNIZ5D')
>>> result = rit.delete_orders(563)
>>> result
{'success': True}
>>> result.success
True
>>> result['success']
True

Parameters:: id – The Order.id of the order.
Returns:: The newly posted order.

delete_tenders(id: int) → SuccessResult

Decline the tender.

>>> rit = RIT('G4DNIZ5D')
>>> result = rit.delete_tenders(563)
>>> result
{'success': True}
>>> result.success
True

Parameters:: id – The Tender.tender_id of the tender.
Returns:: The success result.

get_assets(*, ticker: str | None = None) → Sequence[Asset]

Gets a list of available assets.

>>> rit = RIT('G4DNIZ5D')
>>> assets = rit.get_assets()
>>> assets
[{'ticker': 'ETF-Creation', 'type': 'REFINERY', ...}, ...]
>>> assets = rit.get_assets(ticker='ETF-Creation')
>>> assets
[{'ticker': 'ETF-Creation', 'type': 'REFINERY', ...}]
>>> assets[0].type
'REFINERY'
>>> assets[0]['type']
'REFINERY'

Parameters:: ticker – The optional asset ticker. A full list of assets is returned if unspecified.
Returns:: The list of available assets.

get_assets_history(*, ticker: str | None = None, period: int | None = None, limit: int | None = None) → Sequence[History]

Get the activity log for assets.

This API was introduced in RIT REST API v1.0.3.

The way limit parameter is interpreted is RIT REST API version dependent.

In v1.0.3, the limit is interpreted as the result set limit, counting backwards from the most recent tick. This defaults to retrieving the entire period.

In v1.0.4, the limit is interpreted as the result set limit, counting backwards from the most recent item. This defaults to 20.

>>> rit = RIT('G4DNIZ5D')
>>> histories = rit.get_assets_history()
>>> histories
[{'tick': 100, 'ticker': 'ETF-Redemption', ...}, ...]
>>> histories[0].tick
100
>>> histories[0]['tick']
100

Parameters:

ticker – The optional asset ticker. If unspecified, a full list of assets is retrieved.
period – Period to retrieve data from. Defaults to the current period.
limit – Result set limit. How this value is interpreted is RIT REST API version dependent.

Returns:

The activity log for assets.

get_case() → Case

Get an information about the current case.

>>> rit = RIT('G4DNIZ5D')
>>> case = rit.get_case()
>>> case
{'name': 'RITC 2023 Algo Case - practice', 'period': 1, ...}
>>> case.tick
83
>>> case['tick']
83
>>> case.status == Case.Status.ACTIVE
True

Returns:: The current case.

get_leases() → Sequence[Lease]

get_leases(id: int) → Lease

List all assets currently being leased or being used or get a single leased or used asset.

if id is specified, a single lease is returned instead of a list of leases.

>>> rit = RIT('G4DNIZ5D')
>>> leases = rit.get_leases()
>>> leases
[{'id': 3, 'ticker': 'ETF-Creation', 'type': 'REFINERY', ...}, ...]
>>> leases[0].type
'REFINERY'

Parameters:: id – The optional Asset.Lease.id of the asset lease.
Returns:: The list of all assets or a single asset currently being leased or used.

get_limits() → Sequence[Limit]

Get trading limits for the current case.

>>> rit = RIT('G4DNIZ5D')
>>> limits = rit.get_limits()
>>> limits
[{'name': 'LIMIT-STOCK', 'gross': 32500.0, 'net': -32500.0, ...}, ...]
>>> limits[0].name
'LIMIT-STOCK'
>>> limits[0]['name']
'LIMIT-STOCK'

Returns:: The trading limits.

get_news(*, since: int | None = None, limit: int | None = None) → Sequence[News]

get_news(*, after: int | None = None, limit: int | None = None) → Sequence[News]

Gets the most recent news.

The parameter named since was renamed to after in RIT REST API v1.0.4.

For RIT Client applications with REST API v1.0.3 or lower, the user must use since instead of after if he/she wishes to use that parameter, and vice versa.

>>> rit = RIT('G4DNIZ5D')
>>> news = rit.get_news()
>>> news
[{'news_id': 1, 'period': 1, 'tick': 0, 'ticker': '', ...}, ...]
>>> news[0].headline
'Welcome to RITC 2022 Algo Case - Practice Case'
>>> news[0]['headline']
'Welcome to RITC 2022 Algo Case - Practice Case'

Parameters:

since – Retrieve only news items after a particular News.news_id. Renamed to after in v1.0.4.
after – Retrieve only news items after a particular News.news_id. Introduced in v1.0.4.
limit – Result set limit, counting backwards from the most recent news item. Defaults to 20.

Returns:

The most recent news.

get_orders(*, status: Status | None = None) → Sequence[Order]

get_orders(id: int) → Order

Get a list of all orders or details of a specific order.

if id is specified, a single order is returned instead of a list of orders.

>>> rit = RIT('G4DNIZ5D')
>>> orders = rit.get_orders()
>>> len(orders)
5
>>> orders
[{'order_id': 714, 'period': 1, 'tick': 31, ...}, ...]
>>> orders[0].ticker
'BEAR'
>>> orders[0].price
15.04
>>> orders[0].action == Order.Action.SELL
True

Parameters:

status – The status of the orders to return. Defaults to Order.Status.OPEN.
id – The optional Order.order_id of the order.

Returns:

The list of all orders or a single order.

get_securities(*, ticker: str | None = None) → Sequence[Security]

Get a list of available securities and associated positions.

>>> rit = RIT('G4DNIZ5D')
>>> securities = rit.get_securities(ticker='RITC')
>>> securities[0]
{'ticker': 'RITC', 'type': 'STOCK', 'size': 1, ...}
>>> securities[0].ticker
'RITC'
>>> securities[0].bid
24.21
>>> securities[0]['ask']
24.36

Parameters:: ticker – The optional Security.ticker. If unspecified, a full list of securities is retrieved.
Returns:: The lists of available securites and associated positions.

get_securities_book(*, ticker: str, limit: int | None = None) → Book

Get the order book of a security.

>>> rit = RIT('G4DNIZ5D')
>>> book = rit.get_securities_book(ticker='RITC')
>>> len(book.bids)
20
>>> book.bids[:2]
[{'order_id': 2505, 'period': 1, 'tick': 132, ...}, ...]
>>> book.bids[0].ticker
'RITC'
>>> book.bids[0].price
25.06
>>> book.bids[0]['type']
'LIMIT'

Parameters:

ticker – The Security.ticker.
limit – Maximum number of orders to return for each side of the order book. Defaults to 20.

Returns:

The order book.

get_securities_history(*, ticker: str, period: int | None = None, limit: int | None = None) → Sequence[History]

Get the OHLC history for a security.

In v1.0.3 and previous versions, the limit is interpreted as the result set limit, counting backwards from the most recent tick. This defaults to retrieving the entire period.

In v1.0.4, the limit is interpreted as the result set limit, counting backwards from the most recent item. This defaults to 20.

>>> rit = RIT('G4DNIZ5D')
>>> histories = rit.get_securities_history(ticker='RITC')
>>> len(histories)
224
>>> histories[:2]
[{'tick': 224, 'open': 26.27, 'high': 26.42, 'low': 26.27, ...}, ...]
>>> histories[0].tick
224
>>> histories[0]['high']
26.42

Parameters:

ticker – The Security.ticker.
period – Period to retrieve data from. Defaults to the current period.
limit – Result set limit. How this value is interpreted is RIT REST API version dependent.

Returns:

The OHLC history.

get_securities_tas(*, ticker: str, after: int | None = None, period: int | None = None, limit: int | None = None) → Sequence[TAS]

Get time and sales history for a security.

Data is anonymized.

In v1.0.3 and previous versions, the limit is interpreted as the result set limit, counting backwards from the most recent tick. This defaults to retrieving the entire period.

In v1.0.4, the limit is interpreted as the result set limit, counting backwards from the most recent item. This defaults to 20.

For v1.0.3 and lower, there are two modes of retrieval for this endpoint.

If after is specified, then only data with an id value greater than after will be returned. This allows only incremental data to be retrieved by storing the last id value returned. Setting after to 0 will return all time and sales data.

Alternatively, specifying period and limit will fetch data from the corresponding period and tick window. For example, setting limit to 0 returns only data from the current period and current tick.

Both modes are simultaneously supported onwards from v1.0.4.

>>> rit = RIT('G4DNIZ5D')
>>> tas = rit.get_securities_tas(ticker='RITC')
>>> len(tas)
579
>>> tas[:2]
[{'id': 2099, 'period': 1, 'tick': 299, 'price': 26.33, ...}, ...]
>>> tas[0].id
2099
>>> tas[0].price
26.33

Parameters:

ticker – The Security.ticker.
after – Retrieve only data with an Security.TAS.id value greater than this value.
period – Period to retrieve data from. Defaults to the current period.
limit – Result set limit. How this value is interpreted is RIT REST API version dependent.

Returns:

The time and sales history.

get_tenders() → Sequence[Tender]

Get a list of all active tenders.

>>> rit = RIT('G4DNIZ5D')
>>> tenders = rit.get_tenders()
>>> tenders
[{'tender_id': 1507, 'period': 1, 'tick': 104, ...}, ...]

Returns:: The list of all active tenders.

get_trader() → Trader

Get an information about the currently signed in trader.

>>> rit = RIT('G4DNIZ5D')
>>> trader = rit.get_trader()
>>> trader
{'trader_id': 'AussieSeaweed', 'first_name': 'Juho', ...}
>>> trader.trader_id
'AussieSeaweed'
>>> trader['trader_id']
'AussieSeaweed'

Returns:: The current trader.

hostname: str = 'localhost': The hostname of the RITC web server. Defaults to localhost.

port: int = 9999: The port of the RITC web server. Defaults to 9999.

post_commands_cancel(*, all: Literal[1]) → CancellationResult

post_commands_cancel(*, ticker: str) → CancellationResult

post_commands_cancel(*, ids: str) → CancellationResult

post_commands_cancel(*, query: str) → CancellationResult

Bulk cancel open orders.

Exactly one query parameter must be specified. If multiple query parameters are specified, only the first available parameter in the order below will be processed. Returns a result object that specifies which orders were actually cancelled.

The query parameter was removed in RIT REST API v1.0.4.

>>> rit = RIT('G4DNIZ5D')
>>> rit.post_commands_cancel(all=1)
{'cancelled_order_ids': [3791, 3793, 3836, 3837, 3790, 3792, ...]}

Parameters:

all – Set to 1 to cancel all open orders.
ticker – Cancel all open orders for a security.
ids – Cancel a set of orders referenced via a comma-separated list of Order.order_id. For example, '12,13,91,1'
query – Query string to select orders for cancellation. For example, "Ticker='CL' AND Price>124.23 AND Volume<0" will cancel all open sell orders for CL priced above 124.23.

Returns:

The cancellation result.

post_leases(id: int, *, from1: str, quantity1: float, from2: str | None = None, quantity2: float | None = None, from3: str | None = None, quantity3: float | None = None) → Lease

Lease or use an asset.

>>> rit = RIT('G4DNIZ5D')
>>> lease = rit.post_leases(ticker='ETF-Creation')
>>> lease
{'id': 3, 'ticker': 'ETF-Creation', 'type': 'REFINERY', ...}
>>> lease.type
'REFINERY'
>>> lease = rit.post_leases(
...     1,
...     from1='BULL',
...     quantity1=10000,
...     from2='BEAR',
...     quantity2=10000,
...     from3='USD',
...     quantity3=1500,
... )
>>> lease
{'id': 1, 'ticker': 'ETF-Creation', 'type': 'REFINERY', ...}

Depending on the type of asset, you will need to specify the fromN and quantityN parameters. Only specify subsequent fromN and quantityN parameters if needed.

Parameters:

id – The optional Asset.Lease.id of the asset lease.
ticker – Asset.Lease.ticker of the asset to lease or use.
from1 – Required for assets that can be used without leasing first (such as Asset.Type.REFINERY type assets). Specifies the source ticker.
quantity1 – Required for assets that can be used without leasing first (such as Asset.Type.REFINERY type assets). Specifies the source quantity.
from2 – Specifies the 2nd source ticker (if required).
quantity2 – Specifies the 2nd source quantity (if required).
from3 – Specifies the 3rd source ticker (if required).
quantity3 – Specifies the 3rd source quantity (if required).

Returns:

The leased or used asset.

post_orders(wait: bool = False, *, ticker: str, type: Type, quantity: float, action: Action, price: float | None = None, dry_run: int | None = None) → Order

Insert a new order.

Note that this endpoint is rate-limited. If the rate limit is exceeded, the ritc library will internally sleep and hang until the desired timeout has passed and try to post the order again.

>>> rit = RIT('G4DNIZ5D')
>>> order = rit.post_orders(
...     ticker='RITC',
...     type=Order.Type.MARKET,
...     quantity=5,
...     action=Order.Action.BUY,
... )
>>> order
{'order_id': 3135, 'period': 1, 'tick': 180, ...}
>>> order = rit.post_orders(
...     ticker='RITC',
...     type='LIMIT',
...     quantity=5,
...     action='SELL',
...     price=24.5,
... )
>>> order
{'order_id': 3835, 'period': 1, 'tick': 223, ...}

Parameters:

wait – Wait if rate limit is exceeded, defaults to False.
ticker – The ticker.
type – The order type.
quantity – The order quantity.
action – The order action.
price – The optional price. Required if type is Order.Type.LIMIT. Ignored otherwise.
dry_run – Only available if type is Order.Type.MARKET. Simulates the order execution and returns the result as if the order was executed.

Returns:

The newly posted order.

post_tenders(id: int, *, price: float | None = None) → SuccessResult

Accept the tender.

In RIT REST API v1.0.3 and lower, the parameter price is required only if the tender is not fixed-bid.

From RIT REST API v1.0.4, the bid price parameter is always required. If the tender is fixed-bid, the value must match the tender price.

>>> rit = RIT('G4DNIZ5D')
>>> result = rit.post_tenders(563)
>>> result
{'success': True}
>>> result.success
True

Parameters:

id – The Tender.tender_id of the tender.
price – Bid price of the tender. Its requirement is RIT REST API version dependent.

Returns:

The success result.

x_api_key: str: The X-API-Key of the RITC web server.

class ritc.Security(*args, **kwargs)

Bases: Protocol

This class is for securities.

class Book(*args, **kwargs)

Bases: Protocol

This class is for security books.

ask: Sequence[Order]

asks: Sequence[Order]

bid: Sequence[Order]

bids: Sequence[Order]

class History(*args, **kwargs)

Bases: Protocol

This class is for security histories.

close: float

high: float

low: float

open: float

tick: int

class Limit(*args, **kwargs)

Bases: Protocol

This class is for security limits.

name: str

units: float

class TAS(*args, **kwargs)

Bases: Protocol

This class is for security times and sales.

id: int

period: int

price: float

quantity: float

tick: int

class Type(value)

Bases: str, Enum

This class is for security types.

BOND: str = 'BOND'

CURRENCY: str = 'CURRENCY'

FORWARD: str = 'FORWARD'

FUTURE: str = 'FUTURE'

INDEX: str = 'INDEX'

OPTION: str = 'OPTION'

RATE: str = 'RATE'

SPOT: str = 'SPOT'

SPRE: str = 'SPRE'

STOCK: str = 'STOCK'

SWAP: str = 'SWAP'

SWAP_BOM: str = 'SWAP_BOM'

api_orders_per_second: int

ask: float

ask_size: float

base_security: str

bid: float

bid_size: float

bond_coupon: float

currency: str

description: str

display_unit: str

execution_delay_ms: int

fixing_ticker: str

interest_payments_per_period: int

interest_rate: float

interest_rate_ticker: float

is_shortable: bool

is_tradeable: bool

last: float

limit_order_rebate: float

limits: Sequence[Limit]

max_price: float

max_trade_size: float

min_price: float

min_trade_size: float

nlv: float

otc_price_range: float

position: float

quoted_decimals: int

realized: float

required_tickers: str

size: int

start_period: int

start_price: float

stop_period: int

ticker: str

total_volume: float

trading_fee: float

type: Type

underlying_tickers: Sequence[str]

unit_multiplier: int

unrealized: float

volume: float

vwap: float

class ritc.SuccessResult(*args, **kwargs)

Bases: Protocol

This class is for success results.

success: bool

class ritc.Tender(*args, **kwargs)

Bases: Protocol

This class is for tenders.

action: Action

caption: str

expires: int

is_fixed_bid: bool

period: int

price: float

quantity: float

tender_id: int

tick: int

ticker: str

class ritc.Ticker(*args, **kwargs)

Bases: Protocol

This class is for tickers.

class Price(*args, **kwargs)

Bases: Protocol

This class is for ticker prices.

price: float

ticker: str

class Quantity(*args, **kwargs)

Bases: Protocol

This class is for ticker quantities.

quantity: float

ticker: str

class ritc.Trader(*args, **kwargs)

Bases: Protocol

This class is for traders.

first_name: str

last_name: str

nlv: float

trader_id: str