Key Concepts

SecurityIdentifier objects have several public properties to uniquely identify each asset. The following table describes these properties:

We encode the preceding properties to create Symbol objects. We do our best to hide the details of this process from your algorithm, but you'll occasionally see it come through as an encoded hash like AAPL R735QTJ8XC9X. The first half of the encoded string represents the first ticker AAPL was listed under. The other letters at the end of the string represent the serialized form of the preceding SecurityIdentifier properties. You may also see an encoded has like AAPL XL7X5I241SO6|AAPL R735QTJ8XC9X for a derivative contract. In this case, the part before the | is contract hash and the part after the | is the underlying hash. This serialization approach lets LEAN assign a short, unique string to octillions of different security objects.

LEAN assumes the ticker you pass to the AddEquityadd_equity method is the current ticker of the Equity asset. To access this ticker, use the Valuevalue property of the Symbol object.

# Add equity for "GOOG" and print symbol id value, symbol value and encoded symbol id.
self._symbol = self.add_equity("GOOG").symbol
self.debug(self._symbol.id.value) # Prints "GOOCV"
self.debug(self._symbol.value)    # Prints "GOOG"
self.debug(str(self._symbol.id))  # Prints "GOOCV VP83T1ZUHROL"

// Add equity for "GOOG" and print symbol id value, symbol value and encoded symbol id.
var symbol = AddEquity("GOOG").Symbol;
Debug(symbol.ID.Value);       // Prints "GOOCV"
Debug(symbol.Value);          // Prints "GOOG"
Debug(symbol.ID.ToString());  // Prints "GOOCV VP83T1ZUHROL"

If you create the security subscription with a universe selection function, the Valuevalue property of the Symbol object is the point-in-time ticker.

When a SecurityIdentifier is serialized to a string, it looks something like SPY R735QTJ8XC9X. This two-part string is a base64 encoded set of data. Encoding all of the properties into a short format allows dense communication without requiring a third-party list or look-up. Most of the time, you will not need to work with these encoded strings. However, to deserialize the string into a Symbol object, call the Symbolsymbol method.

// Extract the market, security type, and value from the symbol with ID "GOOCV VP83T1ZUHROL".
var symbol = Symbol("GOOCV VP83T1ZUHROL");
symbol.ID.Market;     // => "USA"
symbol.SecurityType;  // => SecurityType.Equity
symbol.Value;         // => "GOOCV"

# Extract the market, security type, and value from the symbol with ID "GOOCV VP83T1ZUHROL".
symbol = self.symbol("GOOCV VP83T1ZUHROL")
symbol.id.market      # => "USA"
symbol.security_type  # => SecurityType.EQUITY
symbol.value          # => "GOOCV"

Tickers are a string shortcode representation for an asset. Some examples of popular tickers include "AAPL" for Apple Corporation and "IBM" for International Business Machines Corporation. These tickers often change when the company rebrands or they undergo a merger or reverse merger.

The ticker of an asset is not the same as the Symbol. Symbol objects are permanent and track the underlying entity. When a company rebrands or changes its name, the Symbol object remains constant, giving algorithms a way to reliably track assets over time.

Tickers are also often reused by different brokerages. For example Coinbase, a leading US Crypto Brokerage lists the "BTCUSD" ticker for trading. Its competitor, Bitfinex, also lists "BTCUSD". You can trade both tickers with LEAN. Symbol objects allow LEAN to identify which market you reference in your algorithms.

To create a Symbol object for a point-in-time ticker, call the GenerateEquitygenerate_equity method to create the security identifier and then call the Symbol constructor. For example, Heliogen, Inc. changed their ticker from ATHN to HLGN on December 31, 2021. To convert the ATHN ticker to the Equity Symbol, type:

# Generate an Equity security identifier for a ticker and then create a symbol with it.
ticker = "ATHN"
security_id = SecurityIdentifier.generate_equity(ticker, Market.USA, mapping_resolve_date=datetime(2021, 12, 1))
symbol = Symbol(security_id, ticker)

// Generate an Equity security identifier for a ticker and then create a symbol with it.
var ticker = "ATHN";
var securityID = SecurityIdentifier.GenerateEquity(ticker, Market.USA, mappingResolveDate:new DateTime(2021, 12, 1));
var symbol = new Symbol(securityID, ticker);

In the preceding code snippet, the mappingResolveDatemapping_resolve_date must be a date when the point-in-time ticker was trading.

To make using the API easier, we have built the Symbol Cache technology, which accepts strings and tries to guess which Symbol object you might mean. With the Symbol Cache, many methods can accept a string such as "IBM" instead of a complete Symbol object. We highly recommend you don't rely on this technology and instead save explicit references to your securities when you need them.

# Example 1: Relying On Symbol Cache:
self.add_equity("IBM")          # Add by IBM string ticker, save reference to Symbol Cache.
self.market_order("IBM", 100)   # Determine refering to IBM Equity from Symbol Cache.
self.history("AAPL", 14)        # Makes a guess referring to AAPL Equity.

# Example 2: Correctly Using Symbols: 
self.ibm = self.add_equity("IBM").symbol   # Add IBM Equity string ticker, save Symbol.
self.market_order(self.ibm, 100)           # Use IBM Symbol in future API calls.

self.aapl = Symbol.create("AAPL", SecurityType.EQUITY, Market.USA)
self.history(self.aapl, 14)

// Example 1: Relying On Symbol Cache:
AddEquity("IBM");          // Add by IBM string ticker, save reference to Symbol Cache.
MarketOrder("IBM", 100);   // Determine refering to IBM Equity from Symbol Cache.
History("AAPL", 14);       // Guess referring to AAPL Equity.

// Example 2: Correctly Using Symbols: 
var ibm = AddEquity("IBM").Symbol;   // Add IBM Equity string ticker, save Symbol.
MarketOrder(ibm, 100);               // Use IBM Symbol in future API calls.

var aapl = Symbol.Create("AAPL", SecurityType.Equity, Market.USA);
History(aapl, 14);

The Marketmarket property distinguishes between tickers that have the same string value but represent different underlying assets. A prime example of this is the various market makers who have different prices for EURUSD. We store this data separately and as they have different fill prices, we treat the execution venues as different markets.

The following table shows the available markets for each security type:

You can convert industry-standard security identifiers like CUSIP, FIGI, ISIN, and SEDOL to Symbol objects and you can convert Symbol objects to industry-standard security identifiers.

CUSIP

To convert a Committee on Uniform Securities Identification Procedures (CUSIP) number to a Symbol or a Symbol to a CUSIP number, call the CUSIPcusip method.

# Get the CUSIP for the symbol and vice versa.
symbol = self.cusip("03783310") # AAPL Symbol
cusip = self.cusip(symbol) # AAPL CUSIP (03783310)