Accounting

The accounting subpackage defines both different account types and account management machinery.

There is also an ExchangeRateCalculator for calculating the exchange rate between FX and/or Crypto pairs. The AccountManager is mainly used from the Portfolio to manage accounting operations.

The AccountFactory supports customized account types for specific integrations. These custom account types can be registered with the factory and will then be instantiated when an AccountState event is received for that integration.

Cash Account

class CashAccount ( AccountState event , bool calculate_account_state=False )

Bases: nautilus_trader.accounting.accounts.base.Account

Provides a cash account.

Parameters
  • event ( AccountState ) – The initial account state event.

  • calculate_account_state ( bool , optional ) – If the account state should be calculated from order fills.

Raises

ValueError – If event.account_type is not equal to CASH .

apply ( self , AccountState event ) void

Apply the given account event to the account.

Parameters

event ( AccountState ) – The account event to apply.

Raises
  • ValueError – If event.account_type is not equal to self.type .

  • ValueError – If event.account_id is not equal to self.id .

  • ValueError – If event.base_currency is not equal to self.base_currency .

Warning

System method (not intended to be called by user code).

balance ( self , Currency currency=None ) AccountBalance

Return the current account balance total.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

AccountBalance or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_free ( self , Currency currency=None ) Money

Return the account balance free.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_locked ( self , Currency currency=None ) Money

Return the account balance locked.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_total ( self , Currency currency=None ) Money

Return the current account balance total.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balances ( self ) dict

Return the account balances totals.

Returns

dict[Currency, Money]

balances_free ( self ) dict

Return the account balances free.

Returns

dict[Currency, Money]

balances_locked ( self ) dict

Return the account balances locked.

Returns

dict[Currency, Money]

balances_total ( self ) dict

Return the account balances totals.

Returns

dict[Currency, Money]

base_currency

The accounts base currency ( None for multi-currency accounts).

Returns

Currency or None

calculate_account_state

If the accounts state should be calculated by Nautilus.

Returns

bool

calculate_balance_locked ( self , Instrument instrument , OrderSide side , Quantity quantity , Price price , bool inverse_as_quote=False ) Money

Calculate the locked balance.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • side (OrderSide { BUY , SELL }) – The order side.

  • quantity ( Quantity ) – The order quantity.

  • price ( Price ) – The order price.

  • inverse_as_quote ( bool ) – If inverse instrument calculations use quote currency (instead of base).

Returns

Money

calculate_commission ( self , Instrument instrument , Quantity last_qty , Price last_px , LiquiditySide liquidity_side , bool inverse_as_quote=False ) Money

Calculate the commission generated from a transaction with the given parameters.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • last_qty ( Quantity ) – The transaction quantity.

  • last_px ( Price ) – The transaction price.

  • liquidity_side (LiquiditySide { MAKER , TAKER }) – The liquidity side for the transaction.

  • inverse_as_quote ( bool ) – If inverse instrument calculations use quote currency (instead of base).

Returns

Money

Raises

ValueError – If liquidity_side is None .

calculate_pnls ( self, Instrument instrument, Position position: Optional[Position], OrderFilled fill ) list

Return the calculated PnL.

The calculation does not include any commissions.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • position ( Position , optional ) – The position for the calculation (can be None).

  • fill ( OrderFilled ) – The fill for the calculation.

Returns

list[Money] or None

clear_balance_locked ( self , InstrumentId instrument_id ) void

Clear the balance locked for the given instrument ID.

Parameters

instrument_id ( InstrumentId ) – The instrument for the locked balance to clear.

commission ( self , Currency currency ) Money

Return the total commissions for the given currency.

Parameters

currency ( Currency ) – The currency for the commission.

Returns

Money or None

commissions ( self ) dict

Return the total commissions for the account.

currencies ( self ) list

Return the account currencies.

Returns

list[Currency]

event_count

Return the count of events.

Returns

int

events

Return all events received by the account.

Returns

list[AccountState]

id

The accounts ID.

Returns

AccountId

is_cash_account

If the account is a type of CASH account.

is_margin_account

If the account is a type of MARGIN account.

last_event

Return the accounts last state event.

Returns

AccountState

starting_balances ( self ) dict

Return the account starting balances.

Returns

dict[Currency, Money]

type

The accounts type.

Returns

AccountType

update_balance_locked ( self , InstrumentId instrument_id , Money locked ) void

Update the balance locked for the given instrument ID.

Parameters
  • instrument_id ( InstrumentId ) – The instrument ID for the update.

  • locked ( Money ) – The locked balance for the instrument.

Raises

ValueError – If margin_init is negative (< 0).

Warning

System method (not intended to be called by user code).

update_balances ( self , list balances , bool allow_zero=True ) void

Update the account balances.

There is no guarantee that every account currency is included in the given balances, therefore we only update included balances.

Parameters
  • balances ( list [ AccountBalance ] ) – The balances for the update.

  • allow_zero ( bool , default True ) – If zero balances are allowed (will then just clear the assets balance).

Raises

ValueError – If balances is empty.

update_commissions ( self , Money commission ) void

Update the commissions.

Can be negative which represents credited commission.

Parameters

commission ( Money ) – The commission to update with.

Warning

System method (not intended to be called by user code).

Margin Account

class MarginAccount ( AccountState event , bool calculate_account_state=False )

Bases: nautilus_trader.accounting.accounts.base.Account

Provides a margin account.

Parameters
  • event ( AccountState ) – The initial account state event.

  • calculate_account_state ( bool , optional ) – If the account state should be calculated from order fills.

Raises

ValueError – If event.account_type is not equal to MARGIN .

apply ( self , AccountState event ) void

Apply the given account event to the account.

Parameters

event ( AccountState ) – The account event to apply.

Raises
  • ValueError – If event.account_type is not equal to self.type .

  • ValueError – If event.account_id is not equal to self.id .

  • ValueError – If event.base_currency is not equal to self.base_currency .

Warning

System method (not intended to be called by user code).

balance ( self , Currency currency=None ) AccountBalance

Return the current account balance total.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

AccountBalance or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_free ( self , Currency currency=None ) Money

Return the account balance free.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_locked ( self , Currency currency=None ) Money

Return the account balance locked.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balance_total ( self , Currency currency=None ) Money

Return the current account balance total.

For multi-currency accounts, specify the currency for the query.

Parameters

currency ( Currency , optional ) – The currency for the query. If None then will use the default currency (if set).

Returns

Money or None

Raises

ValueError – If currency is None and base_currency is None .

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

balances ( self ) dict

Return the account balances totals.

Returns

dict[Currency, Money]

balances_free ( self ) dict

Return the account balances free.

Returns

dict[Currency, Money]

balances_locked ( self ) dict

Return the account balances locked.

Returns

dict[Currency, Money]

balances_total ( self ) dict

Return the account balances totals.

Returns

dict[Currency, Money]

base_currency

The accounts base currency ( None for multi-currency accounts).

Returns

Currency or None

calculate_account_state

If the accounts state should be calculated by Nautilus.

Returns

bool

calculate_commission ( self , Instrument instrument , Quantity last_qty , Price last_px , LiquiditySide liquidity_side , bool inverse_as_quote=False ) Money

Calculate the commission generated from a transaction with the given parameters.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • last_qty ( Quantity ) – The transaction quantity.

  • last_px ( Price ) – The transaction price.

  • liquidity_side (LiquiditySide { MAKER , TAKER }) – The liquidity side for the transaction.

  • inverse_as_quote ( bool ) – If inverse instrument calculations use quote currency (instead of base).

Returns

Money

Raises

ValueError – If liquidity_side is NONE.

calculate_margin_init ( self , Instrument instrument , Quantity quantity , Price price , bool inverse_as_quote=False ) Money

Calculate the initial (order) margin.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • quantity ( Quantity ) – The order quantity.

  • price ( Price ) – The order price.

  • inverse_as_quote ( bool ) – If inverse instrument calculations use quote currency (instead of base).

Returns

Money

calculate_margin_maint ( self , Instrument instrument , PositionSide side , Quantity quantity , Price price , bool inverse_as_quote=False ) Money

Calculate the maintenance (position) margin.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • side (PositionSide { LONG , SHORT }) – The currency position side.

  • quantity ( Quantity ) – The currency position quantity.

  • price ( Price ) – The positions current price.

  • inverse_as_quote ( bool ) – If inverse instrument calculations use quote currency (instead of base).

Returns

Money

calculate_pnls ( self, Instrument instrument, Position position: Optional[Position], OrderFilled fill ) list

Return the calculated PnL.

The calculation does not include any commissions.

Parameters
  • instrument ( Instrument ) – The instrument for the calculation.

  • position ( Position , optional ) – The position for the calculation.

  • fill ( OrderFilled ) – The fill for the calculation.

Returns

list[Money] or None

clear_margin ( self , InstrumentId instrument_id ) void

Clear the maintenance (position) margins for the given instrument ID.

Parameters

instrument_id ( InstrumentId ) – The instrument for the maintenance margin to clear.

Warning

System method (not intended to be called by user code).

clear_margin_init ( self , InstrumentId instrument_id ) void

Clear the initial (order) margins for the given instrument ID.

Parameters

instrument_id ( InstrumentId ) – The instrument for the initial margin to clear.

Warning

System method (not intended to be called by user code).

clear_margin_maint ( self , InstrumentId instrument_id ) void

Clear the maintenance (position) margins for the given instrument ID.

Parameters

instrument_id ( InstrumentId ) – The instrument for the maintenance margin to clear.

Warning

System method (not intended to be called by user code).

commission ( self , Currency currency ) Money

Return the total commissions for the given currency.

Parameters

currency ( Currency ) – The currency for the commission.

Returns

Money or None

commissions ( self ) dict

Return the total commissions for the account.

currencies ( self ) list

Return the account currencies.

Returns

list[Currency]

default_leverage

The accounts default leverage setting.

Returns

Decimal

event_count

Return the count of events.

Returns

int

events

Return all events received by the account.

Returns

list[AccountState]

id

The accounts ID.

Returns

AccountId

is_cash_account

If the account is a type of CASH account.

is_margin_account

If the account is a type of MARGIN account.

last_event

Return the accounts last state event.

Returns

AccountState

leverage ( self , InstrumentId instrument_id )

Return the leverage for the given instrument (if found).

Parameters

instrument_id ( InstrumentId ) – The instrument ID for the leverage.

Returns

Decimal or None

leverages ( self ) dict

Return the account leverages.

Returns

dict[InstrumentId, Decimal]

margin ( self , InstrumentId instrument_id ) MarginBalance

Return the current margin balance.

Parameters

instrument_id ( InstrumentId ) – The instrument ID for the query.

Returns

MarginBalance or None

Warning

Returns None if there is no applicable information for the query, rather than MarginBalance with zero amounts.

margin_init ( self , InstrumentId instrument_id ) Money

Return the current initial (order) margin.

Parameters

instrument_id ( InstrumentId ) – The instrument ID for the query.

Returns

Money or None

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

margin_maint ( self , InstrumentId instrument_id ) Money

Return the current maintenance (position) margin.

Parameters

instrument_id ( InstrumentId ) – The instrument ID for the query.

Returns

Money or None

Warning

Returns None if there is no applicable information for the query, rather than Money of zero amount.

margins ( self ) dict

Return the initial (order) margins for the account.

Returns

dict[InstrumentId, Money]

margins_init ( self ) dict

Return the initial (order) margins for the account.

Returns

dict[InstrumentId, Money]

margins_maint ( self ) dict

Return the maintenance (position) margins for the account.

Returns

dict[InstrumentId, Money]

set_default_leverage ( self , leverage : Decimal ) void

Set the default leverage for the account (if not specified by instrument).

Parameters

leverage ( Decimal ) – The default leverage value

Returns

  • TypeError – If leverage is not of type Decimal .

  • ValueError – If leverage is not >= 1.

set_leverage ( self , InstrumentId instrument_id , leverage: Decimal ) void

Set the leverage for the given instrument.

Parameters
  • instrument_id ( InstrumentId ) – The instrument for the leverage.

  • leverage ( Decimal ) – The leverage value

Returns

  • TypeError – If leverage is not of type Decimal .

  • ValueError – If leverage is not >= 1.

starting_balances ( self ) dict

Return the account starting balances.

Returns

dict[Currency, Money]

type

The accounts type.

Returns

AccountType

update_balances ( self , list balances , bool allow_zero=True ) void

Update the account balances.

There is no guarantee that every account currency is included in the given balances, therefore we only update included balances.

Parameters
  • balances ( list [ AccountBalance ] ) – The balances for the update.

  • allow_zero ( bool , default True ) – If zero balances are allowed (will then just clear the assets balance).

Raises

ValueError – If balances is empty.

update_commissions ( self , Money commission ) void

Update the commissions.

Can be negative which represents credited commission.

Parameters

commission ( Money ) – The commission to update with.

Warning

System method (not intended to be called by user code).

update_margin ( self , MarginBalance margin ) void

Update the margin balance.

Parameters

margin ( MarginBalance ) –

Warning

System method (not intended to be called by user code).

update_margin_init ( self , InstrumentId instrument_id , Money margin_init ) void

Update the initial (order) margin.

Parameters
  • instrument_id ( InstrumentId ) – The instrument ID for the update.

  • margin_init ( Money ) – The current initial (order) margin for the instrument.

Raises

ValueError – If margin_init is negative (< 0).

Warning

System method (not intended to be called by user code).

update_margin_maint ( self , InstrumentId instrument_id , Money margin_maint ) void

Update the maintenance (position) margin.

Parameters
  • instrument_id ( InstrumentId ) – The instrument ID for the update.

  • margin_maint ( Money ) – The current maintenance (position) margin for the instrument.

Raises

ValueError – If margin_maint is negative (< 0).

Warning

System method (not intended to be called by user code).

Calculators

class ExchangeRateCalculator

Bases: object

Provides exchange rate calculations between currencies.

An exchange rate is the value of one asset versus that of another.

get_rate ( self , Currency from_currency , Currency to_currency , PriceType price_type , dict bid_quotes , dict ask_quotes ) double

Return the calculated exchange rate for the given price type using the given dictionary of bid and ask quotes.

Parameters
  • from_currency ( Currency ) – The currency to convert from.

  • to_currency ( Currency ) – The currency to convert to.

  • price_type ( PriceType ) – The price type for conversion.

  • bid_quotes ( dict ) – The dictionary of currency pair bid quotes dict[Symbol, double].

  • ask_quotes ( dict ) – The dictionary of currency pair ask quotes dict[Symbol, double].

Returns

Decimal

Raises
  • ValueError – If bid_quotes length is not equal to ask_quotes length.

  • ValueError – If price_type is LAST .

Notes

If insufficient data to calculate exchange rate then will return 0.

class RolloverInterestCalculator ( data : pd.DataFrame )

Bases: object

Provides rollover interest rate calculations.

If rate_data_csv_path is empty then will default to the included short-term interest rate data csv (data since 1956).

Parameters

data ( str ) – The short term interest rate data.

calc_overnight_rate ( self , InstrumentId instrument_id , date date )

Return the rollover interest rate between the given base currency and quote currency.

Parameters
  • instrument_id ( InstrumentId ) – The forex instrument ID for the calculation.

  • date ( date ) – The date for the overnight rate.

Returns

Decimal

Raises

ValueError – If instrument_id.symbol length is not in range [6, 7].

Notes

1% = 0.01 bp

get_rate_data ( self )

Return the short-term interest rate dataframe.

Returns

pd.DataFrame

Factory

class AccountFactory

Bases: object

Provides a factory for creating different account types.

static create ( AccountState event ) Account

Create an account based on the events account type.

Parameters

event ( AccountState ) – The account state event for the creation.

Returns

Account

static register_account_type ( unicode issuer , type account_cls )

Register the given custom account type for the issuer.

Parameters
  • issuer ( str ) – The issuer for the account.

  • account_cls ( type ) – The custom account type.

Raises

KeyError – If issuer has already registered a custom account type.

static register_calculated_account ( unicode issuer )

Register for account state of the given issuer to be calculated from order fills.

Parameters

issuer ( str ) – The issuer for the account.

Raises

KeyError – If an issuer has already been registered for the issuer .

Manager

class AccountsManager ( CacheFacade cache , LoggerAdapter log , Clock clock )

Bases: object

Provides account management functionality.

Parameters