Objects

Defines fundamental value objects for the trading domain.

class AccountBalance

Bases: object

AccountBalance(Money total, Money locked, Money free) -> None

Represents an account balance denominated in a particular currency.

• Parameters:
  • total (Money) – The total account balance.
  • locked (Money) – The account balance locked (assigned to pending orders).
  • free (Money) – The account balance free for trading.
• Raises:
  • ValueError – If money currencies are not equal.
  • ValueError – If any money is negative (< 0).
  • ValueError – If total - locked != free.

currency

The currency of the account.

• Returns: Currency

free

The account balance free for trading.

• Returns: Money

static from_dict(dict values)

Return an account balance from the given dict values.

• Parameters: values (dict *[*str , object ]) – The values for initialization.
• Return type: AccountBalance

locked

The account balance locked (assigned to pending orders).

• Returns: Money

to_dict(self)

Return a dictionary representation of this object.

• Return type: dict[str, object]

total

The total account balance.

• Returns: Money

class Currency

Bases: object

Currency(unicode code, uint8_t precision, uint16_t iso4217, unicode name, CurrencyType currency_type) -> None

Represents a medium of exchange in a specified denomination with a fixed decimal precision.

Handles up to 9 decimals of precision.

• Parameters:
  • code (str) – The currency code.
  • precision (uint8_t) – The currency decimal precision.
  • iso4217 (uint16) – The currency ISO 4217 code.
  • name (str) – The currency name.
  • currency_type (CurrencyType) – The currency type.
• Raises:
  • ValueError – If code is not a valid string.
  • OverflowError – If precision is negative (< 0).
  • ValueError – If precision greater than 9.
  • ValueError – If name is not a valid string.

code

str

Return the currency code.

• Return type: str
• Type: Currency.code

currency_type

CurrencyType

Return the currency type.

• Return type: CurrencyType
• Type: Currency.currency_type

static from_internal_map(unicode code)

Return the currency with the given code from the built-in internal map (if found).

• Parameters: code (str) – The code of the currency.
• Return type: Currency or None

static from_str(unicode code, bool strict=False)

Parse a currency from the given string (if found).

• Parameters:
  • code (str) – The code of the currency.
  • strict (bool , default False) – If not strict mode then an unknown currency will very likely be a Cryptocurrency, so for robustness will then return a new Currency object using the given code with a default precision of 8.
• Return type: Currency or None

static is_crypto(unicode code)

Return whether a currency with the given code is CRYPTO.

• Parameters: code (str) – The code of the currency.
• Returns: True if CRYPTO, else False.
• Return type: bool
• Raises: ValueError – If code is not a valid string.

static is_fiat(unicode code)

Return whether a currency with the given code is FIAT.

• Parameters: code (str) – The code of the currency.
• Returns: True if FIAT, else False.
• Return type: bool
• Raises: ValueError – If code is not a valid string.

iso4217

int

Return the currency ISO 4217 code.

• Return type: str
• Type: Currency.iso4217

name

str

Return the currency name.

• Return type: str
• Type: Currency.name

precision

int

Return the currency decimal precision.

• Return type: uint8
• Type: Currency.precision

static register(Currency currency, bool overwrite=False)

Register the given currency.

Will override the internal currency map.

• Parameters:
  • currency (Currency) – The currency to register
  • overwrite (bool) – If the currency in the internal currency map should be overwritten.

class MarginBalance

Bases: object

MarginBalance(Money initial, Money maintenance, InstrumentId instrument_id=None) -> None

Represents a margin balance optionally associated with a particular instrument.

• Parameters:
  • initial (Money) – The initial (order) margin requirement for the instrument.
  • maintenance (Money) – The maintenance (position) margin requirement for the instrument.
  • instrument_id (InstrumentId , optional) – The instrument ID associated with the margin.
• Raises:
  • ValueError – If margin_init currency does not equal currency.
  • ValueError – If margin_maint currency does not equal currency.
  • ValueError – If any margin is negative (< 0).

currency

The currency of the margin.

• Returns: Currency

static from_dict(dict values)

Return a margin balance from the given dict values.

• Parameters: values (dict *[*str , object ]) – The values for initialization.
• Return type: MarginAccountBalance

initial

The initial margin requirement.

• Returns: Money

instrument_id

The instrument ID associated with the margin.

• Returns: InstrumentId or None

maintenance

The maintenance margin requirement.

• Returns: Money

to_dict(self)

Return a dictionary representation of this object.

• Return type: dict[str, object]

class Money

Bases: object

Money(value, Currency currency) -> None

Represents an amount of money in a specified currency denomination.

• MONEY_MAX = 9_223_372_036
• MONEY_MIN = -9_223_372_036

• Parameters:
  • value (integer , float , string or Decimal) – The amount of money in the currency denomination.
  • currency (Currency) – The currency of the money.
• Raises:
  • ValueError – If value is greater than 9_223_372_036.
  • ValueError – If value is less than -9_223_372_036.

as_decimal(self)

Return the value as a built-in Decimal.

• Return type: Decimal

as_double(self)

Return the value as a double.

• Return type: double

currency

Currency

Return the currency for the money.

• Return type: Currency
• Type: Money.currency

static from_raw(int64_t raw, Currency currency)

Return money from the given raw fixed precision integer and currency.

• Parameters:
  • raw (int64_t) – The raw fixed precision money amount.
  • currency (Currency) – The currency of the money.
• Return type: Money

WARNING

Small raw values can produce a zero money amount depending on the precision of the currency.

static from_str(unicode value)

Return money parsed from the given string.

Must be correctly formatted with a value and currency separated by a whitespace delimiter.

Example: “1000000.00 USD”.

• Parameters: value (str) – The value to parse.
• Return type: Money
• Raises:
  • ValueError – If inferred currency precision is greater than 9.
  • OverflowError – If inferred currency precision is negative (< 0).

raw

int64_t

Return the raw memory representation of the money amount.

• Return type: int64_t
• Type: Money.raw

to_formatted_str(self)

Return the formatted string representation of the money.

• Return type: str

class Price

Bases: object

Price(double value, uint8_t precision) -> None

Represents a price in a market.

The number of decimal places may vary. For certain asset classes, prices may have negative values. For example, prices for options instruments can be negative under certain conditions.

Handles up to 9 decimals of precision.

• PRICE_MAX = 9_223_372_036
• PRICE_MIN = -9_223_372_036

• Parameters:
  • value (integer , float , string or Decimal) – The value of the price.
  • precision (uint8_t) – The precision for the price. Use a precision of 0 for whole numbers (no fractional units).
• Raises:
  • ValueError – If value is greater than 9_223_372_036.
  • ValueError – If value is less than -9_223_372_036.
  • ValueError – If precision is greater than 9.
  • OverflowError – If precision is negative (< 0).

as_decimal(self)

Return the value as a built-in Decimal.

• Return type: Decimal

as_double(self)

Return the value as a double.

• Return type: double

static from_int(int value)

Return a price from the given integer value.

A precision of zero will be inferred.

• Parameters: value (int) – The value for the price.
• Return type: Price

static from_raw(int64_t raw, uint8_t precision)

Return a price from the given raw fixed precision integer and precision.

Handles up to 9 decimals of precision.

• Parameters:
  • raw (int64_t) – The raw fixed precision price value.
  • precision (uint8_t) – The precision for the price. Use a precision of 0 for whole numbers (no fractional units).
• Return type: Price
• Raises:
  • ValueError – If precision is greater than 9.
  • OverflowError – If precision is negative (< 0).

WARNING

Small raw values can produce a zero price depending on the precision.

static from_str(unicode value)

Return a price parsed from the given string.

Handles up to 9 decimals of precision.

• Parameters: value (str) – The value to parse.
• Return type: Price

WARNING

The decimal precision will be inferred from the number of digits following the ‘.’ point (if no point then precision zero).

• Raises:
  • ValueError – If inferred precision is greater than 9.
  • OverflowError – If inferred precision is negative (< 0).

precision

int

Return the precision for the price.

• Return type: uint8_t
• Type: Price.precision

raw

int64_t

Return the raw memory representation of the price value.

• Return type: int64_t
• Type: Price.raw

to_formatted_str(self)

Return the formatted string representation of the price.

• Return type: str

class Quantity

Bases: object

Quantity(double value, uint8_t precision) -> None

Represents a quantity with a non-negative value.

Capable of storing either a whole number (no decimal places) of ‘contracts’ or ‘shares’ (instruments denominated in whole units) or a decimal value containing decimal places for instruments denominated in fractional units.

Handles up to 9 decimals of precision.

• QUANTITY_MAX = 18_446_744_073
• QUANTITY_MIN = 0

• Parameters:
  • value (integer , float , string , Decimal) – The value of the quantity.
  • precision (uint8_t) – The precision for the quantity. Use a precision of 0 for whole numbers (no fractional units).
• Raises:
  • ValueError – If value is greater than 18_446_744_073.
  • ValueError – If value is negative (< 0).
  • ValueError – If precision is greater than 9.
  • OverflowError – If precision is negative (< 0).

as_decimal(self)

Return the value as a built-in Decimal.

• Return type: Decimal

as_double(self)

Return the value as a double.

• Return type: double

static from_int(int value)

Return a quantity from the given integer value.

A precision of zero will be inferred.

• Parameters: value (int) – The value for the quantity.
• Return type: Quantity

static from_raw(int64_t raw, uint8_t precision)

Return a quantity from the given raw fixed precision integer and precision.

Handles up to 9 decimals of precision.

• Parameters:
  • raw (int64_t) – The raw fixed precision quantity value.
  • precision (uint8_t) – The precision for the quantity. Use a precision of 0 for whole numbers (no fractional units).
• Return type: Quantity
• Raises:
  • ValueError – If precision is greater than 9.
  • OverflowError – If precision is negative (< 0).

WARNING

Small raw values can produce a zero quantity depending on the precision.

static from_str(unicode value)

Return a quantity parsed from the given string.

Handles up to 9 decimals of precision.

• Parameters: value (str) – The value to parse.
• Return type: Quantity
• Raises:
  • ValueError – If inferred precision is greater than 9.
  • OverflowError – If inferred precision is negative (< 0).

WARNING

The decimal precision will be inferred from the number of digits following the ‘.’ point (if no point then precision zero).

precision

int

Return the precision for the quantity.

• Return type: uint8_t
• Type: Quantity.precision

raw

uint64_t

Return the raw memory representation of the quantity value.

• Return type: uint64_t
• Type: Quantity.raw

static raw_to_f64(raw)

to_formatted_str(self)

Return the formatted string representation of the quantity.

• Return type: str

static zero(uint8_t precision=0)

Return a quantity with a value of zero.

precision : The precision for the quantity.

• Return type: Quantity
• Raises:
  • ValueError – If precision is greater than 9.
  • OverflowError – If precision is negative (< 0).

WARNING

The default precision is zero.