← Strategy index

Strategy file: hawkesMM.js Market: spot

Description

Hawkes (1971) self-exciting process · Ogata (1981) recursive MLE — adaptive spot MM that widens quotes under detected order-flow clustering.

How it works

Hawkes processes (Hawkes 1971) are self-exciting point processes where each event increases the conditional intensity λ(t) of future events for a decaying period: λ(t) = μ + Σ α·e^(-β(t-t_i)) summed over past events t_i. Bacry, Mastromatteo & Muzy (2015) and Bauwens & Hautsch (2009) showed that order-flow arrivals on exchanges exhibit strong self-excitation — a buy cluster is more likely to be followed by another buy than a Poisson model would predict. A Hawkes market maker estimates this excitation, widens its ask when buy-intensity spikes (because the next trade is more likely to be a buy, which means the maker would be the seller into rising pressure), and widens its bid when sell-intensity spikes. The strategy captures short-horizon flow clustering without requiring a fundamental view.

Capital & Period

Order sizing and candle timeframe

Key Type Default Description
PERIOD select 5 Candle timeframe. Hawkes events are derived from mid-price moves > 1bp, so finer candles produce more events and a faster MLE convergence.
TRADING_LIMIT range (range 100..5000) 900 Gunbot-level cap on a single buy order. Keep equal to Per-order size below.
HW_TL range (range 100..5000) 900 Quote-currency notional per resting quote order. Each side (bid/ask) is sized to this.
HW_CAPITAL_ALLOC range (range 500..50000) 9090 Per-pair capital cap in quote currency. The strategy treats min(baseBalance, this) as working capital.

Allocation

How much of THIS pair’s wallet the strategy may use, what it must start with, and the hard config gate. Trading is BLOCKED until Wallet allocation % is set AND Allocation confirmed is ON. Optional grid splits an order into laddered post-only rungs for better fills.

Key Type Default Description
ALLOC_PCT range (range 1..100) 25 Percentage of THIS pair’s wallet balance the strategy may deploy. Effective cap = min(wallet × this %, the absolute Capital allocation). Every order is clamped to it and can never exceed it. REQUIRED — trading is blocked until this is set (>0) and Allocation confirmed is ON.
ALLOC_CONFIRMED boolean False Explicit acknowledgement that the allocation above is correct for this pair. The strategy will NOT place any entry order until this is ON. A clear "ALLOCATION CONFIGURED" line is logged once it is; otherwise an "ALLOCATION NOT CONFIGURED — refusing to trade" line is logged each cycle.
ALLOC_SPLIT_TOL range (range 0..100) 15 How far the starting base/quote split may deviate from what this strategy needs before it refuses to start. Long-only strategies want mostly quote/cash; two-sided market-makers want ~50/50 base/quote; futures want free margin. Mismatch beyond this % blocks trading (unless Enforce start inventory is OFF).
ALLOC_ENFORCE_SPLIT boolean True When ON, the strategy refuses to trade until the starting base/quote split is within tolerance of what it needs (archetype-aware). When OFF, a mismatch is logged as a warning but trading proceeds.
ALLOC_AUTO_REBALANCE boolean True Two-sided market-makers only. ON by default: if the pair starts off the target base/quote split, the strategy places a single bounded market order on start to reach it (e.g. buys ~half the allocation into base for a 50/50 maker), then begins normal trading. Set to OFF to instead stay blocked and log the exact amount to buy/sell manually. Long-only and futures strategies ignore this.
ALLOC_RESERVE_PCT range (range 0..50) 0 A buffer, as % of wallet, kept BELOW the allocation cap and never deployed. Use to leave headroom for fees/slippage. Effective cap = min(wallet × allocation %, absolute cap) − wallet × this %.
HW_GRID boolean False When ON, an entry order is split into several laddered post-only rungs across a price band instead of one order — often gets better average fills. Cumulative size is still clamped to the allocation. OFF = single order.
HW_GRID_LEVELS range (range 2..10) 3 Number of laddered rungs to split an entry into when "Split entries into a grid" is ON. More rungs = finer fills but more orders.
HW_GRID_SPAN_PCT range (range 0.1..5) 0.5 Price band width, as % from the reference price, across which the grid rungs are spread. e.g. 0.5 places rungs from the reference price down to 0.5% below it (for buys).

Spread

Quote spread response to intensity

Key Type Default Description
HW_BASE_SPREAD range (range 2..30) 6 Half-spread (each side) when event intensity is at baseline λ₀. Total spread between your bid and ask is roughly 2× this value in calm regimes. Raise to widen baseline quotes (less aggressive); lower to tighten.
HW_MAX_MULT range (range 1.5..6) 3 Upper bound on the λ/λ₀ ratio used when clustering pushes intensity high. Effective max half-spread = HW_BASE_SPREAD × this. Default 3.0 = up to 18 bps at peak intensity. Lower this to limit how wide quotes can pull back during bursts; raise to allow more defensive widening.

Hawkes / MLE

Self-exciting process estimation

Key Type Default Description
HW_USE_TAPE boolean False When ON, Hawkes events are taken from the live exchange tape (real trade arrivals via the shared tape module). When OFF, events come from the candle-mid proxy (|Δmid|>1bp per cycle). Tape gives Ogata MLE the true intensity instead of an approximation; recommended for live trading on supported exchanges (Bybit, Binance, Kraken, OKX). Auto-falls-back to the proxy if the exchange is unsupported or the tape feed errors.
HW_MLE_ENABLED boolean True When ON, λ₀, α and β are re-estimated online from observed events. When OFF, the strategy uses the configured constants below and never updates them. Leave ON unless the configured values are deliberately calibrated and should not move.
HW_BASELINE range (range 0.05..2) 0.3 Initial baseline event rate before MLE converges. Influences only the warmup window — once HW_MLE_MIN_EV events are observed, MLE derives λ₀ from the data. Set to a sensible guess for the pair (0.1-1.0 typical for liquid pairs on 1-5m candles).
HW_ALPHA range (range 0.05..1) 0.3 Initial self-excitation strength. Each event raises intensity by α; large α means strong clustering. Like λ₀, only matters during warmup — MLE adapts this.
HW_BETA range (range 0.005..0.2) 0.02 Initial decay rate of the excitation kernel. Half-life of clustering is ln(2)/β ≈ 35s at β=0.02. Only matters during warmup; MLE adapts it.
HW_MLE_INTERVAL range (range 10..120) 30 How often MLE re-fits α, β, λ₀ to recent event history. Lower = more responsive to regime changes but higher CPU. Default 30 is a balanced choice for 5-min candles.
HW_MLE_MIN_EV range (range 5..80) 20 MLE is skipped until at least this many events are in the lookback window. Prevents fitting on too little data. Lower = MLE kicks in earlier on quiet pairs; higher = waits for more evidence.
HW_MLE_GRID_A range (range 4..16) 8 Resolution of the α-axis grid search. Higher = finer fit but more CPU per refit. 8 is adequate for most cases; raise to 12-16 only if MLE estimates look unstable.
HW_MLE_GRID_B range (range 4..16) 8 Resolution of the β-axis grid search. Same trade-off as α grid.
HW_MLE_BLEND range (range 0..1) 0.5 How aggressively each refit replaces the previous estimate. 0 = MLE result ignored (keep configured constants). 1 = use fresh fit only (most responsive, also most jittery). 0.5 is a stable mid-point.
HW_INV_SKEW_K range (range 0..2) 0.5 Reservation-price inventory-skew strength; shifts both quotes to lean against inventory (A-S style). 0 = no price skew.
HW_INV_NEUTRAL_FRAC range (range 0..1) 0.5 Target inventory fraction treated as neutral (0.5 = 50/50 base/quote).

Risk & Safety

Exposure caps and circuit breakers

Key Type Default Description
HW_MAX_EXP range (range 30..95) 60 Hard cap on quote-asset weight; further buys blocked above this exposure.
HW_MAX_DD range (range 2..30) 5 Peak-to-trough equity drop that triggers a pause. Tighter than the spot strategies because Hawkes MM has higher trade frequency.
HW_STALE_CYCLES range (range 2..20) 5 Resting orders older than N cycles are cancelled. Prevents stale quotes from sitting through regime changes.

Fees

Fee tier (informational)

Key Type Default Description
HW_FEE range (range 0..0.2) 0.1 Taker fee for your exchange tier, as a percentage. Used in P&L bookkeeping inside the strategy and to size break-even targets. Get the exact number from your exchange fee schedule for your VIP/maker tier; defaults assume retail tier on Bybit/Binance.
HW_MAKER_FEE range (range -0.05..0.1) 0.02 Maker fee for your tier, as a percentage. Set to your actual fee; if you get a rebate, use the Maker rebate variant instead.
HW_SP range (range 2..8) 6 Number of decimal places used to format prices in logs and the sidebar. Purely display — does not affect order rounding (Gunbot handles tick size automatically). Set higher for low-priced pairs (SHIB, etc.) and lower for high-priced pairs (BTC, ETH).

Runtime & Exchange

Logging, warmup, exchange safety toggles

Key Type Default Description
LOG_LEVEL select NORMAL Controls how much the strategy writes to Gunbot logs. SILENT keeps only errors and circuit-breaker messages. NORMAL writes one summary line per cycle plus order events — recommended for live trading. DEBUG adds the internal model state and every decision; use only when investigating a problem.
WARMUP_CYCLES range (range 0..30) 5 How many cycles the strategy collects data before placing any orders. Indicators (ATR, vol, etc.) need a few cycles to stabilise; trading too early gives noisy values. Raise this on slower timeframes (15m candles or longer) or after restarting an empty pair. 0 disables the warmup.
MIN_ORDER_QUOTE range (range 1..25) 5 Floor for order notional in quote currency (typically USDT). The runtime always uses max(this, exchange-minimum), so setting this lower than the exchange minimum has no effect. Raise it if dust orders are getting rejected or you want to enforce a larger per-trade size.
BE_GUARD boolean True When ON, blocks any sell or position-close priced below the position break-even while holding a long. Prevents stop-loss, scratch, max-drawdown and cap-reduce paths from realising a loss — the pair will hold the position until price recovers above break-even. Off = sells below break-even are permitted (standard stop-loss behaviour). Recommended ON for spot accumulation; consider OFF on highly leveraged futures where forced closes are needed.
NO_POST_ONLY boolean False When ON, the strategy uses regular limit orders instead of post-only. Turn this on only if your exchange does not support post-only flags or rejects them, or if you do not benefit from a maker rebate. The strategy auto-applies this on PancakeSwap and Aster regardless of this toggle. OFF (default) is correct for every standard CEX.
HW_TRACE boolean False When ON, writes a structured JSONL audit trail to gunbot_logs/quantroduction/-.jsonl AND echoes every gate, compute, quote, order and fill decision to the main console log. Useful for verifying literature fidelity, debugging mis-fills and post-hoc analysis of strategy behaviour. Default OFF (zero overhead).
VERBOSE_LOGS boolean False When ON, the full Quantroduction × Gunbot dashboard (every config value + state snapshot) re-emits every VERBOSE_INTERVAL_MIN minutes for forensic audit. When OFF (default), the dashboard only fires once per Gunbot restart per pair.
VERBOSE_INTERVAL_MIN range (range 5..240) 30 How often the dashboard re-emits when VERBOSE_LOGS is ON. Lower = more frequent / noisier; higher = quieter. Has no effect when VERBOSE_LOGS is OFF.
BE_GUARD_BLOCK_MARKET_SELLS boolean True Default ON (legacy). Set OFF to enable SOFT BE_GUARD: market sells and closeMarket pass through (treated as urgent / stop-loss). Only limit sells below break-even remain blocked. Prevents BE_GUARD from silently swallowing stop-loss exits.
SCRATCH_LIVENESS_MIN range (range 0..120) 0 When >0: if the pair holds inventory and hasn't filled in N minutes AND the bid is at break-even+1bp, force a market exit to rotate capital. 0 = disabled. Typical: 30.
CONSEC_RESET_CYCLES range (range 60..2880) 480 After this many cycles without any order activity, auto-reset consecutiveLosses to 0. Default 480 cycles ≈ 2h at 15s/cycle. Prevents a 3-loss streak from killing the pair for the entire session.
DRIFT_ATR_FRAC range (range 0..0.5) 0 When >0: scale drift-requote threshold to this fraction of the recent 10-candle high-low range (clamped 2-100 bps). 0 = use fixed *_STALE_DRIFT_BPS. Typical: 0.05 = 5% of recent range. Adapts drift detection to per-pair volatility.
SKEW_QTY_MAX range (range 1..5) 2.5 Maximum ask:bid qty ratio when inventory is heavily skewed. 2.5 means a heavily-bagged pair quotes up to 2.5x ask qty vs bid qty to drain inventory faster. Set 1.0 to disable (symmetric quoting).
SKEW_QTY_TARGET range (range 0.1..0.9) 0.5 Target inventory fraction of pair equity. 0.5 = 50/50 balanced base/quote. Skew kicks in proportionally as actual exposure deviates from target.
PORTFOLIO_INCLUDE boolean True When ON (default), this pair participates in the shared PORTFOLIO_EXP_BUDGET — its exposure counts toward portfolio total and bids pause when budget is exceeded. When OFF, the pair stands alone (use PAIR_EXP_BUDGET for own cap).
PORTFOLIO_EXP_BUDGET range (range 0..1) 0 Cap on total portfolio inventory as fraction of total allocated equity (sum across PORTFOLIO_INCLUDE pairs). 0 = disabled. Typical: 0.6 = 60% inventory cap across the included portfolio. When exceeded, bids pause but exits remain active.
PAIR_EXP_BUDGET range (range 0..1) 0 This pair's own exposure cap as fraction of pair equity (inventory / pair allocated capital). Applies independently of portfolio budget. 0 = disabled. Typical: 0.2 = 20% per-pair cap.
DISABLE_BREAKER_WINDDOWN boolean False When OFF (default), an active breaker (3 consecutive losses or daily loss limit) actively frees capital: cancels open orders and scratch-sells inventory IF profitable (bid >= BE+1bp). When ON, legacy halt-and-hold behaviour.
TRACE_ALL boolean False Master switch for the Quantroduction tracer. When ON, writes detailed per-cycle JSONL to gunbot_logs/quantroduction/ AND emits a verbose console summary. Equivalent to setting every _TRACE to true. Useful for diagnosing silent gates and breakers. Disk overhead ~1MB/day/pair.

Safety & Tuning (v1.0-beta)

Universal safety + tuning knobs added in v1.0-beta. These were previously hidden from the chart page even though the strategy reads them. Setting any of these here will be applied per-pair.

Key Type Default Description
HW_ASK_CLAMP_BUFFER_BPS range (range 0..50) 2 When BE_GUARD is on and the strategy computes a sub-BE ask, the clamp snaps the ask up to break-even + this many bps. Default 2 = ask sits 2 bps above BE. Larger = more profitable but slower fills.
HW_CROSS_PROT_BPS range (range 0..20) 1 Minimum distance from market touch for the Hawkes quote. Default 1bp. Prevents quoting inside the visible book during volatile bursts.
HW_DISABLE_ASK_CLAMP boolean False Default OFF (clamp active). Set ON to bypass the break-even-aware ask snap; ask remains at the strategy's raw computed value. Use only if you want the ask to occasionally sit below BE.
HW_DISABLE_CROSS_PROT boolean False Default OFF (floor active). Set ON for raw mid-anchored quotes.
HW_PERIOD string 1 Candle period in minutes used for this strategy's indicators. Common values: '1', '5', '15'. Some strategies need a long history to warm up indicators.
HW_STALE_DRIFT_BPS range (range 1..50) 8 Cancel and requote when an on-book order has drifted more than N bps from the current computed quote. Default 8. Lower = more cancels (higher fee burn); higher = more stale quotes. ATR-scaled override available via DRIFT_ATR_FRAC.
STRICT_LITERATURE boolean False Master switch. When ON, the strategy disables every operator-grade safety override (BE_GUARD, cross-protection floors, BE ask clamps, drift-ATR scaling, asymmetric sizing, scratch liveness, breaker wind-down) so it runs as faithful as we can make it to the cited academic paper. Use this for paper-comparison backtests or academic research. WARNING: in strict mode the strategy can take real losses (papers prove optimality only in expectation, not per-trade).
NO_CLOSE_MARKET toggle False When true, the strategy NEVER falls back to a market sell to close a held inventory — only post-only limits. Use to prevent any taker fee on exits. Default false (allow market close when necessary).
QUANTRODUCTION_TRACE toggle False When true, this single pair writes detailed cycle events to gunbot_logs/quantroduction/-.jsonl. Use TRACE_ALL to enable across all pairs at once; this knob overrides per-pair. Default false.
RESET_BREAKER_ONCE toggle False One-shot: set true and Gunbot will clear all tripped risk breakers (consec_losses, daily_loss, max_dd) on this pair on the next cycle, then re-arm them. The setting auto-clears itself after firing. Use when a breaker tripped on a now-stale condition.
RESET_STATS_ONCE toggle False One-shot: set true and Gunbot will clear customStratStore counters (wins, losses, totalPnL, peakEquity, maxDD, dailyPnL, dailyLossLimit) on this pair on the next cycle. The setting auto-clears itself after firing. Useful after a recovery / regime change.

Fill-detector Tuning

Knobs that shape how the strategy's fill detector attributes balance changes to its own orders versus external activity.

Key Type Default Description
HW_COUNT_WINDOW_CY range (range 1..20) 5 How many cycles the stop-loss attribution carry-over stays alive. Market exits sometimes settle across several ticks on illiquid pairs; this window keeps the carry-over from being dropped early.

Portfolio & Runtime (per-pair overrides)

Per-pair runtime knobs. Override any of these on a single pair without changing the strategy defaults.

Key Type Default Description
SPREAD_PNL_JUMP_GUARD range (range 0.1..1) 0.5 Realized-PnL deltas larger than this fraction of pair equity are treated as deposits/withdrawals/data-glitches and skipped. Default 0.5 means a single delta over 50% of equity is ignored. Lower for tighter glitch detection on small accounts.

References & further reading

Configuration playbook