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
|
||||||||||||||||||||||||
relativeCap |
object |
<optional> |
maximum price reference for RELATIVE orders Properties
|
||||||||||||||||||||||||
_margin |
boolean | if false, order type is prefixed with EXCHANGE |
Members
(inner) generateOrder
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)
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>}
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
|
Returns:
orderAmounts
- Type
- Array.<number>
(static) genOrderLabel(state) → {string}
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
|
Returns:
label
- Type
- string
(static) genPreview(args) → {Array.<object>}
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}
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}
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}
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}
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}
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}
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}
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}
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}
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}
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}
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}
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
|
Returns:
error - null if parameters are valid, otherwise a description of which parameter is invalid.
- Type
- string
Events
selfIntervalTick
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