Asset#

An asset object represents securities such as stocks or options in Lumibot. Attributes that are tracked for assets are:

  • symbol(str): Ticker symbol representing the stock or underlying for options. So for example if trading IBM calls the symbol would just be IBM.

  • asset_type(str): Asset type can be either stock, option, future, forex. default: stock

  • name(str): Optional to add in the name of the corporation for logging or printout.

Options Only

  • expiration (str): Expiration of the options contract. Format is datetime.date().

  • strike(float): Contract strike price.

  • right(str): May enter call or put.

  • multiplier(float): Contract multiplier to the underlying. (default: 1)

Futures Only

Set up a futures contract using the following:

  • symbol(str): Ticker symbol for the contract, > eg: ES

  • asset_type(str): “future”

  • nexpiration(str): Expiry added as datetime.date() So June 2021 would be datetime.date(2021, 6, 18)`

Forex Only

  • symbol(str): Currency base: eg: EUR

  • currency(str): Conversion currency. eg: GBP

  • asset_type(str): “forex”

When creating a new security there are two options.

  1. Security symbol: It is permissible to use the security symbol only when trading stocks. Lumibot will convert the ticker symbol to an asset behind the scenes.

  2. Asset object: Asset objects may be created at anytime for stocks or options. For options, futures, or forex asset objects are mandatory due to the additional details required to identify and trade these securities.

Assets may be created using the Asset() method as follows: Asset(symbol, asset_type=option, **kwargs) * see attributes above.

Examples:

For stocks:

from lumibot.entities import Asset

asset = Asset('SPY', asset_type=Asset.AssetType.STOCK)
order = self.create_order(asset, 10, "buy")
self.submit_order(order)

For futures:

from lumibot.entities import Asset

asset = Asset(
'ES', asset_type=Asset.AssetType.FUTURE, expiration=datetime.date(2021, 6, 18)
)
order = self.create_order(asset, 10, "buy")
self.submit_order(order)

Documentation#

class lumibot.entities.asset.Asset(symbol: str, asset_type: str = AssetType.STOCK, expiration: date = None, strike: float = 0.0, right: str = None, multiplier: int = 1, leverage: int = 1, precision: str = None, underlying_asset: Asset = None, auto_expiry: str = None)

Bases: object

This is a base class for Assets including stocks, futures, options, forex, and crypto.

Parameters:

  • symbol (str) – Symbol of the stock or underlying in case of futures/options.

  • asset_type (str) – Type of the asset. Asset types are only ‘stock’, ‘option’, ‘future’, ‘forex’, ‘crypto’ default : ‘stock’

  • expiration (datetime.date) – Option or futures expiration. The datetime.date will be converted to broker specific formats. IB Format: for options “YYYYMMDD”, for futures “YYYYMM”

  • strike (str) – Options strike as string.

  • right (str) – ‘CALL’ or ‘PUT’ default : “”

  • multiplier (int) – Price multiplier. default : 1

  • underlying_asset (Asset) – Underlying asset for options.

symbol

The symbol used to retrieve stock quotes if stock. The underlying symbol if option. For Forex: The base currency.

Type:

string (required)

asset_type

One of the following: - ‘stock’ - ‘option’ - ‘future’ - ‘forex’ - ‘crypto’ - ‘multileg’

Type:

(string, default: stock)

expiration

Contract expiration dates for futures and options.

Type:

datetime.date (required if asset_type is ‘option’ or ‘future’)

strike

Contract strike price.

Type:

float (required if asset_type is ‘option’)

right

Option call or put.

Type:

str (required if asset_type is ‘option’)

multiplier

Contract leverage over the underlying.

Type:

int (required if asset_type is ‘forex’)

precision

Conversion currency.

Type:

str (required if asset_type is ‘crypto’)

_right

Acceptable values for right.

Type:

list of str

asset_type_must_be_one_of(@"asset_type")

validates asset types.

right_must_be_one_of(@"right")

validates rights types.

Example

>>> # Create an Asset object for a stock.
>>> from lumibot.entities import Asset
>>> asset = Asset(symbol="AAPL")

>>> # Create an Asset object for a futures contract with specific expiration.
>>> from lumibot.entities import Asset
>>> asset = Asset(symbol="ES", asset_type='future', expiration=datetime.date(2021, 12, 17))

>>> # Create an Asset object for a futures contract with auto-expiry (front month).
>>> from lumibot.entities import Asset
>>> asset = Asset(symbol="MES", asset_type=Asset.AssetType.FUTURE, auto_expiry=Asset.AutoExpiry.FRONT_MONTH)

>>> # Create an Asset object for a futures contract with auto-expiry (next quarter).
>>> from lumibot.entities import Asset
>>> asset = Asset(symbol="ES", asset_type=Asset.AssetType.FUTURE, auto_expiry=Asset.AutoExpiry.NEXT_QUARTER)

>>> # Create an Asset object for a continuous futures contract (recommended for backtesting).
>>> from lumibot.entities import Asset
>>> asset = Asset(symbol="MES", asset_type=Asset.AssetType.CONT_FUTURE)

>>> # Create an Asset object for an options contract.
>>> from lumibot.entities import Asset
>>> asset = Asset(
>>>     symbol="AAPL",
>>>     asset_type='option',
>>>     expiration=datetime.date(2021, 11, 26),
>>>     strike=155,
>>>     right= 'CALL',
>>> )

>>> # Create an Asset object for a FOREX contract.
>>> from lumibot.entities import Asset
>>> base_asset = Asset(symbol="USD", asset_type='forex')
>>> quote_asset = Asset(symbol="EUR", asset_type='forex')
>>> order = self.create_order(asset, 100, 'BUY', quote=quote_asset)
>>> self.submit_order(order)

>>> # Create an Asset object for crypto.
>>> from lumibot.entities import Asset
>>> base = Asset(symbol="BTC", asset_type='crypto')
>>> quote = Asset(symbol="USDT", asset_type='crypto')
>>> order = self.create_order(asset, 100, 'BUY', quote=quote)
>>> self.submit_order(order)
class AssetType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

CONT_FUTURE = 'cont_future'
CRYPTO = 'crypto'
CRYPTO_FUTURE = 'crypto_future'
FOREX = 'forex'
FUTURE = 'future'
INDEX = 'index'
MULTILEG = 'multileg'
OPTION = 'option'
STOCK = 'stock'
class AutoExpiry(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

AUTO = 'auto'
FRONT_MONTH = 'front_month'
NEXT_QUARTER = 'next_quarter'
class OptionRight(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

CALL = 'CALL'
PUT = 'PUT'
asset_type_must_be_one_of(v)
classmethod from_dict(data)
get_potential_futures_contracts(reference_date: datetime = None) → list

Get a list of potential futures contracts in order of preference.

This is useful for data sources or brokers that need to try multiple contract symbols to find available data.

Returns:

List of potential contract symbols in order of preference

Return type:

list

Raises:

ValueError – If called on a non-continuous futures asset

is_valid()
resolve_continuous_futures_contract(reference_date: datetime = None, year_digits: int = 2) → str

Resolve a continuous futures asset to a specific contract symbol with controllable year formatting.

Parameters:

  • reference_date (datetime, optional) – Reference date for contract resolution. Defaults to datetime.now().

  • year_digits (int, optional) – Number of digits to use for the year portion. Supported values: 1 (e.g., MNQZ5), 2 (default, e.g., MNQZ25), and 4 (e.g., MNQZ2025).

Returns:

Formatted futures contract symbol.

Return type:

str

Raises:

ValueError – If invoked on a non-continuous futures asset or if year_digits is unsupported.

resolve_continuous_futures_contract_variants(reference_date: datetime = None) → dict

Resolve a continuous futures contract and return multiple formatting variants.

Parameters:

reference_date (datetime, optional) – Reference date for contract resolution. Defaults to datetime.now().

Returns:

Dictionary containing contract variants keyed by the number of year digits (1, 2, 4) along with metadata keys base, target_year and target_month.

Return type:

dict

Raises:

ValueError – If invoked on a non-continuous futures asset.

right_must_be_one_of(v)
classmethod symbol2asset(symbol: str)

Convert a symbol string to an Asset object. This is particularly useful for converting option symbols.

Parameters:

symbol (str) – The symbol string to convert.

Returns:

The Asset object.

Return type:

Asset

to_dict()
class lumibot.entities.asset.AssetsMapping(mapping)

Bases: UserDict

class lumibot.entities.asset.StrEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

A string enum implementation that works with Python 3.9+

This class extends str and Enum to create string enums that: 1. Can be used like strings (string methods, comparison) 2. Are hashable (for use in dictionaries, sets, etc.) 3. Can be used in string comparisons without explicit conversion