POST trade-review

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

Used input for trade review

InputOptionTrade

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

supporting_evidence

Supporting evidence

string

None

course_of_action

Recommended course of action

string

None

detailed_log

Detailed analysis log

string

None

trade_condition

Trade condition information

string

None

parity

Parity information

string

None

notional_value

Notional value

decimal number

None

underlying_bid

Underlying symbol bid at trade time

decimal number

None

underlying_ask

Underlying symbol ask at trade time

decimal number

None

sequence_number

Exchange sequence number of a reviewed trade

integer

None

trade_size

Size of a reviewed trade

integer

None

trade_price

Price of a reviewed trade

decimal number

None

trade_time

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

time interval

None

trade_exchange

Exchange id of a reviewed trade

byte

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

record_number

Record number of a reviewed trade

integer

None

market_state_at_trade_time

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

string

None

nbbo_bid_at_trade

Nbbo bid at trade

decimal number

None

nbbo_ask_at_trade

Nbbo ask at trade

decimal number

None

nbbo_bid_size_at_trade

Nbbo bid size at trade

integer

None

nbbo_ask_size_at_trade

Nbbo ask size at trade

integer

None

tr_nbbo_bid

Used for trade review Nbbo ask

decimal number

None

tr_nbbo_ask

Used for trade review Nbbo ask

decimal number

None

intrinsic_value

Intrinsic value

decimal number

None

parity_type

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

string

None

delivery_code

Delivery code for nonstandard options

string

None

threshold

Used threshold

decimal number

None

adjustment_modifier

Used adjustment modifier

decimal number

None

price_adjustment

Used price adjustment

decimal number

None

theo_price_generation

Theoretical market details

TheoCalcResult

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

first_sibling

First sibling market info

SiblingInfo

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

Second sibling market information

SiblingInfo

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

target

Market information for the target trade

SiblingInfo

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

method

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

error_message

Error message

string

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>