AccumulateDistribute

Accumulate/Distribute allows you to break up a large order into smaller randomized chunks, submitted at regular or irregular intervals to minimise detection by other players in the market.

By enabling the 'Await Fill' option, the algorithm will ensure each component fills before submitting subsequent orders. Enabling the 'Catch Up' flag will cause the algorithm to ignore the slice interval for the next order if previous orders have taken longer than expected to fill, thereby ensuring the time-to-fill for the entire order is not adversely affected.

The price must be manually specified as limitPrice for LIMIT order types, or as a combination of a price offset & cap for RELATIVE order types. MARKET A/D orders execute using MARKET atomic orders, and offer no price control.

For RELATIVE A/D orders, the price offset & cap can both be set to one of the following:

  • Top ask
  • Top bid
  • Orderbook mid price
  • Last trade price
  • Moving Average (configurable period, time frame, candle price)
  • Exponential Moving Average (configurable period, time frame, candle price)

The period limit for moving average targets/caps is 240, being the number of candles returned by the Bitfinex API when subscribing to a candle data channel.

Source:
Example
await host.startAO('bfx-accumulate_distribute', {
  symbol: 'tBTCUSD',
  amount: -0.2,
  sliceAmount: -0.1,
  sliceInterval: 10000,
  intervalDistortion: 0.20, // %
  amountDistortion: 0.20, // %
  orderType: 'RELATIVE', // MARKET, LIMIT, RELATIVE
  offsetType: 'ask',
  offsetDelta: -10,
  capType: 'bid',
  capDelta: 10,
  submitDelay: 150,
  cancelDelay: 150,
  catchUp: true, // if true & behind, ignore slice interval (after prev fill)
  awaitFill: true, // await current slice fill before continuing to next slice
  _margin: false,
})
Parameters:
Name Type Attributes Description
symbol string

symbol to trade on

amount number

total order amount

sliceAmount number

individual slice order amount

sliceInterval number

delay in ms between slice orders

intervalDistortion number <optional>

slice interval distortion in %, default 0

amountDistortion number <optional>

slice amount distortion in %, default 0

orderType string

LIMIT, MARKET, RELATIVE

limitPrice number <optional>

price for LIMIT orders

catchUp boolean

if true, interval will be ignored if behind with filling slices

awaitFill boolean

if true, slice orders will be kept open until filled

relativeOffset object <optional>

price reference for RELATIVE orders

Properties
Name Type Attributes Description
type string <optional>

ask, bid, mid, last, ma, or ema

delta number <optional>

offset distance from price reference

args Array.<number> <optional>

MA or EMA indicator arguments [period]

candlePrice string <optional>

'open', 'high', 'low', 'close' for MA or EMA indicators

candleTimeFrame string <optional>

'1m', '5m', '1D', etc, for MA or EMA indicators

relativeCap object <optional>

maximum price reference for RELATIVE orders

Properties
Name Type Attributes Description
type string <optional>

ask, bid, mid, last, ma, or ema

delta number <optional>

cap distance from price reference

args Array.<number> <optional>

MA or EMA indicator arguments [period]

candlePrice string <optional>

'open', 'high', 'low', 'close' for MA or EMA indicators

candleTimeFrame string <optional>

'1m', '5m', '1D', etc, for MA or EMA indicators

_margin boolean

if false, order type is prefixed with EXCHANGE

Members

(inner) generateOrder

Source:

Generates an atomic order to fill one slice of an AccumulateDistribute instance.

Methods

(async, static) declareChannels(instance, host) → {Promise}

Source:
See:

Declares necessary data channels for price offset & cap calculations. The instance may require a trades channel, book channel, or multiple candle channels depending on the execution parameters.

Part of the meta handler section.

Parameters:
Name Type Description
instance AOInstance

AO instance state

host AOHost

algo host instance for declaring channel requirements

Returns:

p

Type
Promise

(static) declareEvents(instance, host)

Source:

Declares internal self:submit_order and self:interval_tick event handlers to the host for event routing.

Part of the meta handler section.

Parameters:
Name Type Description
instance AOInstance

AO instance state

host AOHost

algo host instance for event mapping

(static) generateOrderAmounts(args) → {Array.<number>}

Source:

Generates an array of order slices which add up to the total configured amount. Randomizes them if amountDistortion is finite and non-zero.

Parameters:
Name Type Description
args object

order parameters

Properties
Name Type Description
amount number

total order amount

sliceAmount number

individual slice amount

amountDistortion number

desired distortion in %

Returns:

orderAmounts

Type
Array.<number>

(static) genOrderLabel(state) → {string}

Source:

Generates a label for an AccumulateDistribute instance for rendering in an UI.

Part of the meta handler section.

Parameters:
Name Type Description
state object

source instance state

Properties
Name Type Description
args object

source instance execution parameters

Returns:

label

Type
string

(static) genPreview(args) → {Array.<object>}

Source:

Generates an array of preview orders which show what could be expected if an instance of AccumulateDistribute was executed with the specified parameters.

Part of the meta handler section.

Parameters:
Name Type Description
args object

instance parameters

Returns:

previewOrders

Type
Array.<object>

(static) getUIDef() → {AOUIDefinition}

Source:

Returns the UI layout definition for AccumulateDistribute, with a field for each parameter.

Part of the meta handler section.

Returns:

uiDef

Type
AOUIDefinition

(static) hasIndicatorCap(args) → {boolean}

Source:

Utility function that checks if a set of execution parameters require an indicator for price cap calculation.

Parameters:
Name Type Description
args object

instance execution parameters

Returns:

hasIndicatorCap

Type
boolean

(static) hasIndicatorOffset(args) → {boolean}

Source:

Utility function that checks if a set of execution parameters require an indicator for price offset calculation.

Parameters:
Name Type Description
args object

instance execution parameters

Returns:

hasIndicatorOffset

Type
boolean

(static) hasOBRequirement(args) → {boolean}

Source:

Utility function that checks if a set of execution parameters require order book data for price cap or offset calculation.

Parameters:
Name Type Description
args object

instance execution parameters

Returns:

hasOBRequirement

Type
boolean

(static) hasTradeRequirement(args) → {boolean}

Source:

Utility function that checks if a set of execution parameters require trade data for price cap or offset calculation.

Parameters:
Name Type Description
args object

instance execution parameters

Returns:

hasTradeRequirement

Type
boolean

(static) initState(args) → {object}

Source:

Creates an initial state object for an AccumulateDistribute instance to begin executing with. Generates randomized order amounts depending on the execution parameters and resets the order timeline (orders behind, etc).

Part of the meta handler section.

Parameters:
Name Type Description
args object

instance execution parameters

Returns:

initialState

Type
object

(async, static) onDataManagedBook(instance, book, meta) → {Promise}

Source:
See:

Saves the book on the instance state if it is needed for order generation, and it is for the configured symbol.

Parameters:
Name Type Description
instance AOInstance

AO instance state

book object

order book model

meta EventMetaInformation

source channel information

Listens to Events:
Returns:

p - resolves on completion

Type
Promise

(async, static) onDataManagedCandles(instance, candles, meta) → {Promise}

Source:
See:

If the instance has internal indicators, they are either seeded with the initial candle dataset or updated with new candles as they arrive. The candle dataset is saved on the instance state for order generation.

Parameters:
Name Type Description
instance AOInstance

AO instance state

candles Array.<object>

array of incoming candles

meta EventMetaInformation

source channel information

Listens to Events:
Returns:

p

Type
Promise

(async, static) onDataTrades(instance, trades, meta) → {Promise}

Source:
See:

Saves the received trade on the instance state if it is needed for order generation.

Parameters:
Name Type Description
instance AOInstance

AO instance state

trades Array.<object>

array of incoming trades, only the most recent is used.

meta EventMetaInformation

source channel information

Listens to Events:
Returns:

p

Type
Promise

(async, static) onLifeStart(instance) → {Promise}

Source:
See:

If needed, creates necessary indicators for price offset & cap calculation and saves them on the instance state.

Schedules the first tick of self:interval_tick.

Parameters:
Name Type Description
instance AOInstance

AO instance state

Listens to Events:
Returns:

p

Type
Promise

(async, static) onLifeStop(instance) → {Promise}

Source:

Clears the tick timeout in preperation for teardown

Parameters:
Name Type Description
instance AOInstance

AO instance state

Listens to Events:
Returns:

p

Type
Promise

(async, static) onOrdersOrderCancel(instance, order) → {Promise}

Source:

Triggered on atomic order cancellation; clears the tick timeout and cancels any remaining orders, before triggering the exec:stop event & teardown

Parameters:
Name Type Description
instance AOInstance

AO instance state

order object

the order that was cancelled externally

Listens to Events:
Returns:

p

Type
Promise

(async, static) onOrdersOrderFill(instance, order) → {Promise}

Source:
See:

Called when an order fills. Updates the remaining amount & order timeline position (if behind, etc) on the instance state. If the instance is fully filled, the exec:stop event is triggered.

Otherwise, if catchUp is enabled and the instance is behind with order fills the next tick is re-scheduled to occur earlier in order to compensate.

Parameters:
Name Type Description
instance AOInstance

AO instance state

order object

the order that filled

Listens to Events:
Returns:

p

Type
Promise

(async, static) onSelfIntervalTick(instance) → {Promise}

Source:
See:

Mapped to the self:interval_tick event and triggered by the instance itself.

Schedules the next tick, and updates the orders-behind count on the instance state if an order is currently open (meaning it has not filled in its allocated window).

If awaitFill is false, the open order is cancelled and will be replaced by the new order on the next tick. Otherwise nothing is done in order to await a fill.

Parameters:
Name Type Description
instance AOInstance

AO instance state

Fires:
Listens to Events:
Returns:

p

Type
Promise

(async, static) onSelfSubmitOrder(instance) → {Promise}

Source:
See:

Mapped to the self:submit_order event and triggered by the instance itself.

Generates an order and submits it if the necessary data was received for price offset & cap calculation.

Parameters:
Name Type Description
instance AOInstance

AO instance state

Listens to Events:
Returns:

p

Type
Promise

(static) processParams(data) → {object}

Source:

Converts a raw parameters Object received from an UI into a parameters Object which can be used by an AccumulateDistribute instance for execution.

Part of the meta handler section.

Parameters:
Name Type Description
data object

raw parameters from an UI

Returns:

parameters - ready to be passed to a fresh instance

Type
object

(async, static) scheduleTick(instance) → {Promise}

Source:
See:
  • module:AccumulateDistribute~onSelfIntervalTick

Sets a timeout to emit the self:interval_tick event after the configured slice interval passes, taking into account the configured interval distortion for the AccumulateDistribute instance.

If catchUp was enabled and the instance is behind with order fills, the next tick is always scheduled in 200ms.

Parameters:
Name Type Description
instance AOInstance

AO instance

Fires:
  • module:AccumulateDistribute.event:selfIntervalTick
Returns:

p - resolves on completion

Type
Promise

(static) serialize(state) → {object}

Source:

Creates a POJO from an instance's state which can be stored as JSON in a database, and later loaded with the corresponding module:AccumulateDistribute~unserialize method.

Part of the meta handler section.

Parameters:
Name Type Description
state object

instance state to be serialized

Returns:

pojo - DB-ready plain JS object

Type
object

(static) unserialize(loadedState) → {object}

Source:

Converts a loaded POJO into a state object ready for live execution.

Part of the meta handler section.

Parameters:
Name Type Description
loadedState object

data from a DB

Returns:

instanceState - ready for execution

Type
object

(static) validateParams(args) → {string}

Source:

Verifies that a parameters Object is valid, and all parameters are within the configured boundaries for a valid AccumulateDistribute order.

Part of the meta handler section.

Parameters:
Name Type Description
args object

incoming parameters

Properties
Name Type Attributes Description
amount number

total order amount

sliceAmount number

individual slice order amount

sliceInterval number

delay in ms between slice orders

intervalDistortion number <optional>

slice interval distortion in %, default 0

amountDistortion number <optional>

slice amount distortion in %, default 0

orderType string

LIMIT, MARKET, RELATIVE

limitPrice number <optional>

price for LIMIT orders

catchUp boolean

if true, interval will be ignored if behind with filling slices

awaitFill boolean

if true, slice orders will be kept open until filled

relativeOffset Object <optional>

price reference for RELATIVE orders

Properties
Name Type Attributes Description
type string <optional>

ask, bid, mid, last, ma, or ema

delta number <optional>

offset distance from price reference

args Array.<number> <optional>

MA or EMA indicator arguments [period]

candlePrice string <optional>

'open', 'high', 'low', 'close' for MA or EMA indicators

candleTimeFrame string <optional>

'1m', '5m', '1D', etc, for MA or EMA indicators

relativeCap Object <optional>

maximum price reference for RELATIVE orders

Properties
Name Type Attributes Description
type string <optional>

ask, bid, mid, last, ma, or ema

delta number <optional>

cap distance from price reference

args Array.<number> <optional>

MA or EMA indicator arguments [period]

candlePrice string <optional>

'open', 'high', 'low', 'close' for MA or EMA indicators

candleTimeFrame string <optional>

'1m', '5m', '1D', etc, for MA or EMA indicators

Returns:

error - null if parameters are valid, otherwise a description of which parameter is invalid.

Type
string

Events

selfIntervalTick

Source:

Triggers verification of the price target, and a potential atomic order submit.

Listeners of This Event:

selfSubmitOrder

Source:
See:

Triggers generation of the configured atomic slice, and submits it

Listeners of This Event: