limebrokerage.trading.api

Interface Callback

public interface Callback

Interface via which the trading client reports asynchronous trading and connection events.

These callbacks are always called from a separate thread, and thus can be called at anytime. The trading client is not re-entrant and calling back into the client from any of these callbacks will result in unpredictable behavior.

None of these callbacks expect exceptions to be thrown from them. Letting an exception escape from any of these callbacks will result in unpredictable behavior.

Most callbacks contain an event-id. These ids are strictly monotonically increasing integers, but they may be discontinuous. When a trading client is created, the last event-id received from a previous client instance can be provided. This allows the trading-server to replay any events which may have occurred since the previous instance was logged in. Event-ids only sequence events within a single account, and automatically reset at the end of the day. Thus it is not possible to replay events across days.

See Also:

Client.Client(limebrokerage.trading.api.Callback, java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, long, boolean)

Method Summary

Methods

Modifier and Type	Method and Description
void	onBust(long eventId, long orderId, Side reversedSide, long bustedPrice, int quantityBusted, int quantityLeft, java.util.Date transactTime, java.lang.String symbol, FillOptions options) Called when a previous fill on an US-Equities order is busted (reversed).
void	onCancelAck(long eventId, long orderId) Called upon acknowledgement by the market of a successful cancel.
void	onCancelReject(long eventId, long orderId, java.lang.String reason) Called upon rejection of a cancel attempt by either the trading-server or the market.
void	onConnect() Called when the client successfully connects to the trading-server.
void	onCorrect(long eventId, long orderId, Side side, long newFillPrice, int newFilledQuantity, int quantityLeft, java.util.Date transactTime, java.lang.String symbol, FillOptions options) Called when a fill correction occurs on an US-Equities order.
void	onDisconnect(java.lang.String reason) Called if an existing connection to the trading-server is broken (whether intentionally or unexpectedly), or if a connection attempt to the trading-server fails.
void	onFill(long eventId, long orderId, Side side, int liquidity, long fillPrice, int quantityFilled, int quantityLeft, java.util.Date transactTime, java.lang.String symbol, FillOptions options) Called when a fill occurs on an US-Equities order.
void	onOrderAck(long eventId, long orderId, long limeOrderId, AckOptions options) Called upon acknowledgment by the market of a successful new order (not a cancel-replace).
void	onOrderEcho(long eventId, long orderId, Side side, long price, int quantity, java.lang.String route, java.lang.String symbol) Called when a new US-Equities order is placed via some alternative mechanism into the trading-server (for example, via Portal).
void	onOrderReject(long eventId, long orderId, java.lang.String reason) Called upon rejection of a new order (not cancel-replace) by either the trading-server or the market.
void	onPartialCancelAck(long eventId, long orderId, int quantityLeft) Called upon acknowledgement by the market of a successful partial cancel.
void	onReplaceAck(long eventId, long origOrderId, long orderId, long limeOrderId, AckOptions options) Called upon acknowledgement by the market of a successful cancel-replace.
void	onReplaceEcho(long eventId, long origOrderId, long orderId, long price, int quantity) Called when a cancel-replace is attempted via some alternative mechanism (for example, via Portal).
void	onReplaceReject(long eventId, long origOrderId, long orderId, java.lang.String reason) Called upon rejection of a cancel-replace by either the trading-server or the market.
void	onUSOptionsBust(long eventId, long orderId, Side reversedSide, long bustedPrice, int quantityBusted, int quantityLeft, java.util.Date transactTime, USOptionsSymbol symbol, FillOptions options) Called when a previous fill on an US-Options order is busted (reversed).
void	onUSOptionsCorrect(long eventId, long orderId, Side side, long newFillPrice, int newFilledQuantity, int quantityLeft, java.util.Date transactTime, USOptionsSymbol symbol, FillOptions options) Called when a fill correction occurs on an US-Options order.
void	onUSOptionsFill(long eventId, long orderId, Side side, int liquidity, long fillPrice, int quantityFilled, int quantityLeft, java.util.Date transactTime, USOptionsSymbol symbol, FillOptions options) Called when a fill occurs on an US-Options order.
void	onUSOptionsOrderEcho(long eventId, long orderId, Side side, long price, int quantity, PositionEffect positionEffect, java.lang.String route, USOptionsSymbol symbol) Called when a new US-Options order is placed via some alternative mechanism into the trading-server (for example, via Portal).

Method Detail

onConnect

void onConnect()

Called when the client successfully connects to the trading-server. Orders cannot be placed or cancelled until this callback is triggered.

onDisconnect

void onDisconnect(java.lang.String reason)

Called if an existing connection to the trading-server is broken (whether intentionally or unexpectedly), or if a connection attempt to the trading-server fails. In either case, the client is "dead" at this point and no more callbacks will be triggered.

Parameters:

reason - textual disconnect reason

See Also:

Client.disconnect()

onOrderAck

void onOrderAck(long eventId,
              long orderId,
              long limeOrderId,
              AckOptions options)

Called upon acknowledgment by the market of a successful new order (not a cancel-replace). The order is now live in the market and can be filled.

Parameters:

eventId - event identifier

orderId - client order identifier

limeOrderId - Lime-Brokerage order identifier

options - optional additional information

See Also:

Client.place(long, int, long, limebrokerage.trading.api.Side, java.lang.String, java.lang.String), Client.placeUSOptions(long, int, long, limebrokerage.trading.api.Side, limebrokerage.trading.api.PositionEffect, limebrokerage.trading.api.USOptionsSymbol, java.lang.String)

onReplaceAck

void onReplaceAck(long eventId,
                long origOrderId,
                long orderId,
                long limeOrderId,
                AckOptions options)

Called upon acknowledgement by the market of a successful cancel-replace. The previous order is now dead, and the replacement order is now live in the market and can be filled.

Parameters:

eventId - event identifier

origOrderId - client identifier of replaced order

orderId - client identifier of replacement order

limeOrderId - Lime-Brokerage replacement order identifier

options - optional additional information

See Also:

Client.replace(long, long, int, long), Client.replaceUSOptions(long, long, int, long)

onCancelAck

void onCancelAck(long eventId,
               long orderId)

Called upon acknowledgement by the market of a successful cancel. The order is now dead. Note that under certain circumstances, the market or the trading-server may asynchronously (without an explicit cancel request) cancel an order, in which case this callback would also be called.

Parameters:

eventId - event identifier

orderId - client order identifier

See Also:

Client.cancel(long), Client.cancelAll()

onPartialCancelAck

void onPartialCancelAck(long eventId,
                      long orderId,
                      int quantityLeft)

Called upon acknowledgement by the market of a successful partial cancel. The order is now partially canceled, with number of shares equal to the quantity left still open.

Parameters:

eventId - event identifier

orderId - client order identifier

quantityLeft - remaining shares open

See Also:

Client.partialCancel(long, int), Client.cancelAll()

onOrderReject

void onOrderReject(long eventId,
                 long orderId,
                 java.lang.String reason)

Called upon rejection of a new order (not cancel-replace) by either the trading-server or the market. In either case, the order is now dead.

The reason strings are provided for human consumption and should not be handled programmatically. They can change at any time without warning. Do not hard-code program behavior based on reason string contents.

Parameters:

eventId - event identifier

orderId - client order identifier

reason - reason for rejection.

See Also:

Client.place(long, int, long, limebrokerage.trading.api.Side, java.lang.String, java.lang.String), Client.placeUSOptions(long, int, long, limebrokerage.trading.api.Side, limebrokerage.trading.api.PositionEffect, limebrokerage.trading.api.USOptionsSymbol, java.lang.String)

onReplaceReject

void onReplaceReject(long eventId,
                   long origOrderId,
                   long orderId,
                   java.lang.String reason)

Called upon rejection of a cancel-replace by either the trading-server or the market. In either case, the replacement order is now dead. The original order is still live (if it was live to begin with).

The reason strings are provided for human consumption and should not be handled programmatically. They can change at any time without warning. Do not hard-code program behavior based on reason string contents.

Parameters:

eventId - event identifier

origOrderId - client identifier of attempted replaced order

orderId - client identifier of attempted replacement order

reason - reason for rejection

See Also:

Client.replace(long, long, int, long), Client.replaceUSOptions(long, long, int, long)

onCancelReject

void onCancelReject(long eventId,
                  long orderId,
                  java.lang.String reason)

Called upon rejection of a cancel attempt by either the trading-server or the market. If the order being cancelled was live to begin with, it continues to be.

Note that not all markets provide cancel-rejects in response to unsuccessful cancels. In that case, no response will be received for the cancel attempt.

The reason strings are provided for human consumption and should not be handled programmatically. They can change at any time without warning. Do not hard-code program behavior based on reason string contents.

Parameters:

eventId - event identifier

orderId - client order identifier

reason - reason for rejection

See Also:

Client.cancel(long), Client.partialCancel(long, int), Client.cancelAll()

onFill

void onFill(long eventId,
          long orderId,
          Side side,
          int liquidity,
          long fillPrice,
          int quantityFilled,
          int quantityLeft,
          java.util.Date transactTime,
          java.lang.String symbol,
          FillOptions options)

Called when a fill occurs on an US-Equities order. If the fill consumes the remaining open quantity of the order, than the order is dead. This can be determined using quantityLeft. Once zero, the order is dead.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

liquidity - Lime-Brokerage normalized liquidity code

fillPrice - execution price (scaled by Client.PRICE_SCALE)

quantityFilled - execution quantity

quantityLeft - number of shares left open in order

transactTime - market timestamp when the fill occurred

symbol - order's specified symbol

options - optional additional information

onBust

void onBust(long eventId,
          long orderId,
          Side reversedSide,
          long bustedPrice,
          int quantityBusted,
          int quantityLeft,
          java.util.Date transactTime,
          java.lang.String symbol,
          FillOptions options)

Called when a previous fill on an US-Equities order is busted (reversed). The bust can either be the result of a market action or a Lime-Brokerage administrative action.

A bust can occur for both live and dead orders. However, if the order was dead, it will remain dead after the bust. A bust cannot "resurrect" a dead order. Even if the order is dead, quantityLeft may still show a non-zero quantity, but this is for informational purposes only.

reversedSide, bustedPrice, quantityBusted, and symbol are provided for informational purposes, but will always match the values of the busted fill. The execution-id of the busted fill is provided in options.

Parameters:

eventId - event identifier

orderId - client order identifier

reversedSide - order's reversed side (buy becomes sell, sell becomes buy, etc)

bustedPrice - busted fill's execution price (scaled by Client.PRICE_SCALE)

quantityBusted - busted fill's execution quantity

quantityLeft - number of shares left open in order

transactTime - market or Lime-Brokerage timestamp when the bust occurred

symbol - order's specified symbol

options - optional additional information

onCorrect

void onCorrect(long eventId,
             long orderId,
             Side side,
             long newFillPrice,
             int newFilledQuantity,
             int quantityLeft,
             java.util.Date transactTime,
             java.lang.String symbol,
             FillOptions options)

Called when a fill correction occurs on an US-Equities order. A fill correction is either a new fill generated as a result of Lime-Brokerage administrative action, or to correct the parameters of a previous fill which was reported erroneously. In the later case, this callback will be preceeded by an onBust callback first to reverse out the erroneous fill. This callback will then give the corrected fill parameters.

The same caveats with busts regarding dead orders applies here. A correction will not make a dead order become live again.

side and symbol are provided for information purposes, but will always match the specified values in the order. The execution-id of the corrected fill is provided in options. This will be the execution-id of the original fill if this is an actual correction, or a new execution-id if this is an administrative fill.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

newFillPrice - new execution price (scaled by Client.PRICE_SCALE)

newFilledQuantity - new execution quantity

quantityLeft - number of shares left open in order

transactTime - market or Lime-Brokerage timestamp when the correct occurred

symbol - order's specified symbol

options - optional additional information

onUSOptionsFill

void onUSOptionsFill(long eventId,
                   long orderId,
                   Side side,
                   int liquidity,
                   long fillPrice,
                   int quantityFilled,
                   int quantityLeft,
                   java.util.Date transactTime,
                   USOptionsSymbol symbol,
                   FillOptions options)

Called when a fill occurs on an US-Options order. If the fill consumes the remaining open quantity of the order, than the order is dead. This can be determined using quantityLeft. Once zero, the order is dead.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

liquidity - Lime-Brokerage normalized liquidity code

fillPrice - execution price (scaled by Client.PRICE_SCALE)

quantityFilled - execution quantity

quantityLeft - number of shares left open in order

transactTime - market timestamp when the fill occurred

symbol - order's specified symbol

options - optional additional information

onUSOptionsBust

void onUSOptionsBust(long eventId,
                   long orderId,
                   Side reversedSide,
                   long bustedPrice,
                   int quantityBusted,
                   int quantityLeft,
                   java.util.Date transactTime,
                   USOptionsSymbol symbol,
                   FillOptions options)

Called when a previous fill on an US-Options order is busted (reversed). The bust can either be the result of a market action or a Lime-Brokerage administrative action.

A bust can occur for both live and dead orders. However, if the order was dead, it will remain dead after the bust. A bust cannot "resurrect" a dead order. Even if the order is dead, quantityLeft may still show a non-zero quantity, but this is for informational purposes only.

reversedSide, bustedPrice, quantityBusted, and symbol are provided for informational purposes, but will always match the values of the busted fill. The execution-id of the busted fill is provided in options.

Parameters:

eventId - event identifier

orderId - client order identifier

reversedSide - order's reversed side (buy becomes sell, sell becomes buy, etc)

bustedPrice - busted fill's execution price (scaled by Client.PRICE_SCALE)

quantityBusted - busted fill's execution quantity

quantityLeft - number of shares left open in order

transactTime - market or Lime-Brokerage timestamp when the bust occurred

symbol - order's specified symbol

options - optional additional information

onUSOptionsCorrect

void onUSOptionsCorrect(long eventId,
                      long orderId,
                      Side side,
                      long newFillPrice,
                      int newFilledQuantity,
                      int quantityLeft,
                      java.util.Date transactTime,
                      USOptionsSymbol symbol,
                      FillOptions options)

Called when a fill correction occurs on an US-Options order. A fill correction is either a new fill generated as a result of Lime-Brokerage administrative action, or to correct the parameters of a previous fill which was reported erroneously. In the later case, this callback will be preceeded by an onUSOptionsBust callback first to reverse out the erroneous fill. This callback will then give the corrected fill parameters.

The same caveats with busts regarding dead orders applies here. A correction will not make a dead order become live again.

side and symbol are provided for information purposes, but will always match the specified values in the order. The execution-id of the corrected fill is provided in options. This will be the execution-id of the original fill if this is an actual correction, or a new execution-id if this is an administrative fill.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

newFillPrice - new execution price (scaled by Client.PRICE_SCALE)

newFilledQuantity - new execution quantity

quantityLeft - number of shares left open in order

transactTime - market or Lime-Brokerage timestamp when the correct occurred

symbol - order's specified symbol

options - optional additional information

onOrderEcho

void onOrderEcho(long eventId,
               long orderId,
               Side side,
               long price,
               int quantity,
               java.lang.String route,
               java.lang.String symbol)

Called when a new US-Equities order is placed via some alternative mechanism into the trading-server (for example, via Portal).

This callback provides a programatic way to inform about the placement of new orders via some alternative mechanism that this application may not be aware of. This behavior must be configured and is not enabled by default.

If an order is reported via this mechanism, it will be followed by an onOrderAck (or possibly onOrderReject) callback sometime after for the same order. This callback is triggered when the trading-server receives the order, where the onOrderAck callback is triggered when the market acknowledges the order.

The identifier of this order is generated according to the rules of the mechanism which placed it. In general it is not possible to predict the identifier of the order, but it won't conflict with identifiers of any other live orders.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

price - order's specified price

quantity - order's specified quantity

route - order's specified route

symbol - order's specified symbol

onUSOptionsOrderEcho

void onUSOptionsOrderEcho(long eventId,
                        long orderId,
                        Side side,
                        long price,
                        int quantity,
                        PositionEffect positionEffect,
                        java.lang.String route,
                        USOptionsSymbol symbol)

Called when a new US-Options order is placed via some alternative mechanism into the trading-server (for example, via Portal).

This callback provides a programatic way to inform about the placement of new orders via some alternative mechanism that this application may not be aware of. This behavior must be configured and is not enabled by default.

If an order is reported via this mechanism, it will be followed by an onOrderAck (or possibly onOrderReject) callback sometime after for the same order. This callback is triggered when the trading-server receives the order, where the onOrderAck callback is triggered when the market acknowledges the order.

The identifier of this order is generated according to the rules of the mechanism which placed it. In general it is not possible to predict the identifier of the order, but it won't conflict with identifiers of any other live orders.

Parameters:

eventId - event identifier

orderId - client order identifier

side - order's specified side

price - order's specified price

quantity - order's specified quantity

positionEffect - order's specified position-effect

route - order's specified route

symbol - order's specified symbol

onReplaceEcho

void onReplaceEcho(long eventId,
                 long origOrderId,
                 long orderId,
                 long price,
                 int quantity)

Called when a cancel-replace is attempted via some alternative mechanism (for example, via Portal).

This callback provides a programatic way to inform about cancel-replace attempts via some alternative mechanism that this application may not be aware of. This behavior must be configured and is not enabled by default.

If a cancel-replace is reported via this mechanism, it will be followed by an onReplaceAck (or possibly onReplaceReject) callback sometime after for the same order. This callback is triggered when the trading-server receives the cancel-replace, where the onReplaceAck callback is triggered when the market acknowledges the cancel-replace.

The identifier of this replacement order is generated according to the rules of the mechanism which placed it. In general it is not possible to predict the identifier of the order, but it won't conflict with identifiers of any other live orders.

Parameters:

eventId - event identifier

origOrderId - client identifier of replaced order

orderId - client identifier of replacement order

price - order's specified price

quantity - order's specified quantity