Pricing Formulas

Updated by Kyle McRoberts

Molecule's trade valuation supports the computation of prices (for trade prices, marks, underlying values, and more) using a formula parser. This article describes the syntax it expects.

The Basics

Price formulas are a combination of numerical constants, mathematical operators, and functions.

Constants

Constants are simple, numerical values such as 0.25. Constants are typically used to capture a premium or discount value.

Operators

Operators are the typical mathematical functions such as addition (+), subtraction (-), multiplication (*), division (/) and power (^).

Functions

Functions take inputs and perform specialized tasks to return an output. They provide the majority of the horsepower for the formula parser.

Many of the examples below use constants as inputs to provide a simple illustration, however, a mark or list of marks can be provided to any function by using the mark lookup function described below.

Basic

  • average - Returns the mathematical average of the input values
    • average(1.5, 2.5, 3.5, 4.5) yields a value of 3.0
  • min - Returns the minimum value of the input values
    • min(1.5, 2.5, 3.5, 4.5) yields a value of 1.5
  • max - Returns the maximum value of the input values
    • max(1.5, 2.5, 3.5, 4.5) yields a value of 4.5
  • round - Returns the input value, rounded to the precision specified
    • round(1.2345, 2) yields a value of 1.23
  • roundup - Returns the input value, rounded up, based on the precision specified
    • roundup(1.2345, 2) yields a value of 1.24
  • rounddown - Returns the input value, rounded down, based on the precision specified
    • rounddown(1.2345, 2) yields a value of 1.23
  • if - The if function evaluates an input expression and returns the value of another depending on if the predicate expression is evaluated as true or false. Typical comparisons such as equal (= or ==), not equal (!=), less than (<), less than or equal (<=), greater than (>) and greater than or equal (>=) can be leveraged in the predicate expression.

Advanced

Mark Lookup

This is a special Molecule function used for looking up mark values. Unlike other functions which are referenced by a specific name, this one is used by referencing a Molecule ticker, such as CL or LO. Additional inputs, such as contract dates and as_of dates, are supported for explicitly defining the mark(s) to be queried.

The full syntax of the mark lookup function is TICKER[call/put strike](contract date as_of date).

  • CL(2023-12-01, 2023-10-13) yields a value of 86.35, the mark for a December 2023 CL contract on 10/13/2023.
  • LO[call 95.0](2023-12-01, 2023-10-13) yields a value of 2.02, the mark for a December 2023 $95 LO call on 10/13/2023.
Context

In many situations, additional context is automatically provided to the formula resolver to alleviate the need to explicitly define all of the inputs to the mark function. For example, when running valuations for a specific trade entry, the contract date and the as_of date are provided to the formula resolver from the entry. This means that a simple ticker, such as CL, is a perfectly valid formula to be used on a trade. Using the example of a simple formula like CL on a trade, the formula resolver will resolve a value by looking for a mark for product CL where the contract date and as_of date equal those of the entry being valued.

Tickers can also be defined with a few special notations to reference points on a curve relative to the contract of the formula being resolved. Here are some examples:

  • :n - Following a ticker with a colon and an optional integer, such as CL:2, will result in a mark lookup for the nth contract on the specified product's curve, where the first contract is that which is provided by the formula. For example, when valuing an entry with a contract date of 2023-12-01 and a formula of CL:2, the formula resolver will return the value from the January 2024 CL contract. Likewise, CL:3 results in the value from the February 2024 CL contract.
  • !n - Following a ticker with an exclamation point and an optional integer, such as CL!, will result in a mark lookup for the nth contract on the specified product's curve, where the first contract is the prompt contract on the entry's settlement date. For example, to value a December 2023 Crude swap that settles on the last business day of December, 2023, based on the prompt contract of the CL curve, the formula CL! is your answer. This will return the value from the February 2024 CL contract which would be the prompt contract on December 29th, 2023.
Spot

The spot function is used to query marks over a range of as_of dates and return only those where the as_of date equals the contract date. This is typically used with daily products and nested inside of an aggregate function, like average, to find the average of daily prices over a period.

spot(PDP(2023-10-01..2023-10-31)) will return all of the marks for product PDP between October 1st and October 31st where the as_of date equals the contract date. This formula can be nested inside of the average function, like average(spot(PDP(2023-10-01..2023-10-31))), to yield the average of all of the PDP settlement marks in October.

Best

The best function accepts multiple mark lookup expressions as inputs, evaluates each of them, and returns what is evaluated as the best mark. To determine the best mark, the function first looks at the mark level of each. In the case of multiple marks having the same mark level, the leftmost input is returned.

The best function is often used to value trades that will settle against a specific mark that is not available until settlement date. The best function allows an additional mark input to use to value the trade until the settlement mark becomes available.

best(M.XXXX, H + PAN) + 0.02 is an example of how to price a trade of ICE's XIM product. In this example, M.XXXX represents a Molecule product used for capturing the final settlement price. This product will only have a price available on the settlement date of the contract. On the days prior to settlement date, the trade will value using a price that is resolved by adding the price of ticker H to the price of ticker PAN.

Dates

Date inputs can be either single dates or ranges. Ranges are specified the same way as with Molecule's REST API, where an input value of 2023-10-01..2023-10-31 represents the range of days between October 1st and 31st of 2023.

How did we do?