POST
/trade-review
OPTIONS
Trade analysis for a collection of option trades

Example URI

Live

https://api.livevol.com/v1/live/trade-review

Delayed

https://api.livevol.com/v1/delayed/trade-review

Request Information

Body Parameters

Collection of InputOptionTrade

Name Description Type Additional information
buy_or_sell

Trade operation

string

Allowed values are [ BUY, SELL, UNKNOWN ]

Default value is: UNKNOWN

trade_price

Trade price, may be omitted if seq_number specified

decimal number

Default value is: 0

Range: inclusive between 0 and 1.79769313486232E+308

trade_size

Trade size, may be omitted if seq_number specified

integer

Default value is: 0

Range: inclusive between 0 and 2147483647

seq_number

Exchange sequence number of trade. Can be used instead of trade_price/trade_size.

integer

Default value is: 0

Range: inclusive between 0 and 2147483647

expiry

Expiration date

string

Required

Date in yyyy-MM-dd format. (i.e. 2019-01-18)

time_stamp

Timestamp (Eastern Standard Time)

string

Required

DateTime in yyyy-MM-dd HH:mm:ss.fff format. (i.e. 2021-06-11 20:13:36.994)

market_width_scale

The user override for the default 1x-Wide limit to allow for Xx-Wide quote width limits when identifying “Valid” markets for use in calculating a theoretical price.

unsigned integer

Default value is: 1

Range: inclusive between 1 and 100

root

Option root

string

Required

strike

Option strike

decimal number

Required

Range: inclusive between 0.01 and 1.79769313486232E+308

option_type

Option type

string

Required

Allowed values are [ C, P ]

Request Formats

application/json, text/json

Sample:
[
  {
    "buy_or_sell": "UNKNOWN",
    "trade_price": 8.9,
    "trade_size": 18,
    "seq_number": 282836659,
    "expiry": "2019-01-18",
    "time_stamp": "2019-01-18 11:45:23.467",
    "market_width_scale": 1,
    "root": "AMZN",
    "strike": 1702.5,
    "option_type": "C"
  },
  {
    "buy_or_sell": "BUY",
    "trade_price": 23.35,
    "trade_size": 2,
    "seq_number": 292133,
    "expiry": "2019-03-15",
    "time_stamp": "2019-01-18 09:30:00.670",
    "market_width_scale": 2,
    "root": "AAPL",
    "strike": 180.0,
    "option_type": "P"
  }
]

application/xml, text/xml

Sample:
<ArrayOfinput_option_trade xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <input_option_trade>
    <option_type>C</option_type>
    <root>AMZN</root>
    <strike>1702.5</strike>
    <time_stamp>2019-01-18 11:45:23.467</time_stamp>
    <buy_or_sell>UNKNOWN</buy_or_sell>
    <market_width_scale>1</market_width_scale>
    <seq_number>282836659</seq_number>
    <trade_price>8.9</trade_price>
    <trade_size>18</trade_size>
  </input_option_trade>
  <input_option_trade>
    <option_type>P</option_type>
    <root>AAPL</root>
    <strike>180</strike>
    <time_stamp>2019-01-18 09:30:00.670</time_stamp>
    <buy_or_sell>BUY</buy_or_sell>
    <market_width_scale>2</market_width_scale>
    <seq_number>292133</seq_number>
    <trade_price>23.35</trade_price>
    <trade_size>2</trade_size>
  </input_option_trade>
</ArrayOfinput_option_trade>

Response Information

Resource Description

Collection of TradeReviewDetailedResponse

Name Description Type Additional information SIP Provider

Used input for trade review

InputOptionTrade

None

None

InputOptionTrade

Name Description Type Additional information SIP Provider
buy_or_sell

Trade operation

string

Allowed values are [ BUY, SELL, UNKNOWN ]

Default value is: UNKNOWN

None

trade_price

Trade price, may be omitted if seq_number specified

decimal number

Default value is: 0

Range: inclusive between 0 and 1.79769313486232E+308

None

trade_size

Trade size, may be omitted if seq_number specified

integer

Default value is: 0

Range: inclusive between 0 and 2147483647

None

seq_number

Exchange sequence number of trade. Can be used instead of trade_price/trade_size.

integer

Default value is: 0

Range: inclusive between 0 and 2147483647

None

expiry

Expiration date

string

Required

Date in yyyy-MM-dd format. (i.e. 2019-01-18)

None

time_stamp

Timestamp (Eastern Standard Time)

string

Required

DateTime in yyyy-MM-dd HH:mm:ss.fff format. (i.e. 2021-06-11 20:13:36.994)

None

market_width_scale

The user override for the default 1x-Wide limit to allow for Xx-Wide quote width limits when identifying “Valid” markets for use in calculating a theoretical price.

unsigned integer

Default value is: 1

Range: inclusive between 1 and 100

None

root

Option root

string

Required

None

strike

Option strike

decimal number

Required

Range: inclusive between 0.01 and 1.79769313486232E+308

None

option_type

Option type

string

Required

Allowed values are [ C, P ]

None

is_obvious_error

Obvious error indication

boolean

None

None

supporting_evidence

Supporting evidence

string

None

None

course_of_action

Recommended course of action

string

None

None

detailed_log

Detailed analysis log

string

None

None

trade_condition

Trade condition information

string

None

None

parity

Parity information

string

None

None

notional_value

Notional value

decimal number

None

None

underlying_bid

Underlying symbol bid at trade time

decimal number

None

None

underlying_ask

Underlying symbol ask at trade time

decimal number

None

None

sequence_number

Exchange sequence number of a reviewed trade

integer

None

None

trade_size

Size of a reviewed trade

integer

None

None

trade_price

Price of a reviewed trade

decimal number

None

None

trade_time

Trade time. HH:MM:SS.SSS (Eastern Standard Time) Actual time when trade happened.

time interval

None

None

trade_exchange

Exchange id of a reviewed trade

byte

None

None

market_width_scale

The user override for the default 1x-Wide limit to allow for Xx-Wide quote width limits when identifying “Valid” markets for use in calculating a theoretical price.

unsigned integer

None

None

record_number

Record number of a reviewed trade

integer

None

None

market_state_at_trade_time

Market state at trade time: - WIDE - CROSSED - NOT_VALID - LEGAL - ADJUSTED_FROM_LEVEL2

string

None

None

nbbo_bid_at_trade

Nbbo bid at trade

decimal number

None

None

nbbo_ask_at_trade

Nbbo ask at trade

decimal number

None

None

nbbo_bid_size_at_trade

Nbbo bid size at trade

integer

None

None

nbbo_ask_size_at_trade

Nbbo ask size at trade

integer

None

None

tr_nbbo_bid

Used for trade review Nbbo ask

decimal number

None

None

tr_nbbo_ask

Used for trade review Nbbo ask

decimal number

None

None

intrinsic_value

Intrinsic value

decimal number

None

None

parity_type

Market state at trade time: - ABOVE_PARITY - BELOW_PARITY - AT_PARITY

string

None

None

delivery_code

Delivery code for nonstandard options

string

None

None

threshold

Used threshold

decimal number

None

None

adjustment_modifier

Used adjustment modifier

decimal number

None

None

price_adjustment

Used price adjustment

decimal number

None

None

Theoretical market details

TheoCalcResult

None

None

TheoCalcResult

Name Description Type Additional information SIP Provider
time_stamp

Trade date in yyyy-MM-dd HH:mm:ss.fff format (Eastern Standard Time)

string

None

None

First sibling market info

SiblingInfo

None

None

SiblingInfo

Name Description Type Additional information SIP Provider
strike

Option strike

decimal number

None

None

option_type

Option type

string

None

None

mid_iv

Calculated option volatility

decimal number

None

None

bid

Option bid price

decimal number

None

None

ask

Option ask price

decimal number

None

None

theo

Option theo price

decimal number

None

None

time_stamp

Date time of this snapshot in yyyy-MM-dd HH:mm:ss.fff format (Eastern Standard Time)

string

None

None

stock

Stock price used for IV calculations

decimal number

None

None

Second sibling market information

SiblingInfo

None

None

SiblingInfo

Name Description Type Additional information SIP Provider
strike

Option strike

decimal number

None

None

option_type

Option type

string

None

None

mid_iv

Calculated option volatility

decimal number

None

None

bid

Option bid price

decimal number

None

None

ask

Option ask price

decimal number

None

None

theo

Option theo price

decimal number

None

None

time_stamp

Date time of this snapshot in yyyy-MM-dd HH:mm:ss.fff format (Eastern Standard Time)

string

None

None

stock

Stock price used for IV calculations

decimal number

None

None

Market information for the target trade

SiblingInfo

None

None

SiblingInfo

Name Description Type Additional information SIP Provider
strike

Option strike

decimal number

None

None

option_type

Option type

string

None

None

mid_iv

Calculated option volatility

decimal number

None

None

bid

Option bid price

decimal number

None

None

ask

Option ask price

decimal number

None

None

theo

Option theo price

decimal number

None

None

time_stamp

Date time of this snapshot in yyyy-MM-dd HH:mm:ss.fff format (Eastern Standard Time)

string

None

None

stock

Stock price used for IV calculations

decimal number

None

None

The Calculation Method to get a volatility: 0 - Butterfly1; 1 - Butterfly2; 2 - Extrapolation; 3 - Sibling market; 4 - Previous day volatility; 5 - User defined volatility; 6 - Intraday lookback.

CalculationMethod

Range: inclusive between 0 and 6

None

CalculationMethod

Possible enumeration values:

Value Description

0

1

2

3

4

5

6

method_name

The Calculation Method name: 0 - Butterfly1; 1 - Butterfly2; 2 - Extrapolation; 3 - Sibling market; 4 - Previous day volatility; 5 - User defined volatility; 6 - Intraday lookback.

string

None

None

error_message

Error message

string

None

None

Response Formats

application/json, text/json

Sample:
[
  {
    "used_input": {
      "buy_or_sell": "UNKNOWN",
      "trade_price": 8.9,
      "trade_size": 18,
      "seq_number": 282836659,
      "expiry": "2019-01-18",
      "time_stamp": "2019-01-18 11:45:23.467",
      "market_width_scale": 1,
      "root": "AMZN",
      "strike": 1702.5,
      "option_type": "C"
    },
    "is_obvious_error": false,
    "supporting_evidence": null,
    "course_of_action": null,
    "detailed_log": null,
    "trade_condition": null,
    "parity": null,
    "notional_value": 0.0,
    "underlying_bid": 0.0,
    "underlying_ask": 0.0,
    "sequence_number": 0,
    "trade_size": 0,
    "trade_price": 0.0,
    "trade_time": "00:00:00",
    "trade_exchange": 0,
    "market_width_scale": 2,
    "record_number": 0,
    "market_state_at_trade_time": "LEGAL",
    "nbbo_bid_at_trade": 0.0,
    "nbbo_ask_at_trade": 0.0,
    "nbbo_bid_size_at_trade": 0,
    "nbbo_ask_size_at_trade": 0,
    "tr_nbbo_bid": 0.0,
    "tr_nbbo_ask": 0.0,
    "intrinsic_value": 0.0,
    "parity_type": "BELOW_PARITY",
    "delivery_code": "sample string 3",
    "threshold": 0.0,
    "adjustment_modifier": 0.0,
    "price_adjustment": 0.0,
    "theo_price_generation": {
      "time_stamp": "2016-11-17 10:12:33.000",
      "first_sibling": {
        "strike": 150.0,
        "option_type": "C",
        "mid_iv": 0.02,
        "bid": 3.2,
        "ask": 4.5,
        "theo": 4.0,
        "time_stamp": "2016-11-17 10:12:33.000",
        "stock": 4.0
      },
      "second_sibling": {
        "strike": 150.0,
        "option_type": "C",
        "mid_iv": 0.02,
        "bid": 3.2,
        "ask": 4.5,
        "theo": 4.0,
        "time_stamp": "2016-11-17 10:12:33.000",
        "stock": 4.0
      },
      "target": {
        "strike": 150.0,
        "option_type": "C",
        "mid_iv": 0.02,
        "bid": 3.2,
        "ask": 4.5,
        "theo": 4.0,
        "time_stamp": "2016-11-17 10:12:33.000",
        "stock": 4.0
      },
      "method": 0,
      "method_name": "BUTTERFLY_1",
      "error_message": "Sibling strike expected."
    }
  }
]

application/xml, text/xml

Sample:
<trade_review_responses xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <obv_err_response>
    <adjustment_modifier>0</adjustment_modifier>
    <course_of_action i:nil="true" />
    <delivery_code>sample string 3</delivery_code>
    <detailed_log i:nil="true" />
    <intrinsic_value>0</intrinsic_value>
    <is_obvious_error>false</is_obvious_error>
    <market_state_at_trade_time>LEGAL</market_state_at_trade_time>
    <market_width_scale>2</market_width_scale>
    <nbbo_ask_at_trade>0</nbbo_ask_at_trade>
    <nbbo_ask_size_at_trade>0</nbbo_ask_size_at_trade>
    <nbbo_bid_at_trade>0</nbbo_bid_at_trade>
    <nbbo_bid_size_at_trade>0</nbbo_bid_size_at_trade>
    <notional_value>0</notional_value>
    <parity i:nil="true" />
    <parity_type>BELOW_PARITY</parity_type>
    <price_adjustment>0</price_adjustment>
    <record_number>0</record_number>
    <sequence_number>0</sequence_number>
    <supporting_evidence i:nil="true" />
    <theo_price_generation>
      <error_message>Sibling strike expected.</error_message>
      <first_sibling>
        <ask>4.5</ask>
        <bid>3.2</bid>
        <mid_iv>0.02</mid_iv>
        <option_type>C</option_type>
        <stock>4</stock>
        <strike>150</strike>
        <theo>4</theo>
        <time_stamp>2016-11-17 10:12:33.000</time_stamp>
      </first_sibling>
      <method>0</method>
      <method_name>BUTTERFLY_1</method_name>
      <second_sibling>
        <ask>4.5</ask>
        <bid>3.2</bid>
        <mid_iv>0.02</mid_iv>
        <option_type>C</option_type>
        <stock>4</stock>
        <strike>150</strike>
        <theo>4</theo>
        <time_stamp>2016-11-17 10:12:33.000</time_stamp>
      </second_sibling>
      <target>
        <ask>4.5</ask>
        <bid>3.2</bid>
        <mid_iv>0.02</mid_iv>
        <option_type>C</option_type>
        <stock>4</stock>
        <strike>150</strike>
        <theo>4</theo>
        <time_stamp>2016-11-17 10:12:33.000</time_stamp>
      </target>
      <time_stamp>2016-11-17 10:12:33.000</time_stamp>
    </theo_price_generation>
    <threshold>0</threshold>
    <tr_nbbo_ask>0</tr_nbbo_ask>
    <tr_nbbo_bid>0</tr_nbbo_bid>
    <trade_condition i:nil="true" />
    <trade_exchange>0</trade_exchange>
    <trade_price>0</trade_price>
    <trade_size>0</trade_size>
    <trade_time>PT0S</trade_time>
    <underlying_ask>0</underlying_ask>
    <underlying_bid>0</underlying_bid>
    <used_input>
      <option_type>C</option_type>
      <root>AMZN</root>
      <strike>1702.5</strike>
      <time_stamp>2019-01-18 11:45:23.467</time_stamp>
      <buy_or_sell>UNKNOWN</buy_or_sell>
      <market_width_scale>1</market_width_scale>
      <seq_number>282836659</seq_number>
      <trade_price>8.9</trade_price>
      <trade_size>18</trade_size>
    </used_input>
  </obv_err_response>
</trade_review_responses>