Class HiddenLiquidityDetector

java.lang.Object
com.quantfinlib.microstructure.HiddenLiquidityDetector
public final class HiddenLiquidityDetector extends Object
Hidden-liquidity / iceberg detection from the lit tape. Displayed size is only part of what rests at a price — icebergs show a small tip and reload, and hidden/midpoint orders don't show at all. You can't see them, but you can infer them from a tell: a level that trades more than it ever displayed, and keeps quoting.

The sound per-print signature: a single execution larger than the size displayed at that moment. Displayed liquidity cannot fill more than it shows, so the excess in that one print necessarily executed against hidden size at the level. (A cumulative executed-vs-displayed comparison is NOT sound at L2: a busy level legitimately trades many times its instantaneous display through ordinary adds — that formulation false-flags normal flow.) Per level, the detector keeps an EWMA of the print/displayed ratio at those hidden events; hiddenMultiplier(int) ≈ 1 means "what you see is what's there," 3 means "≈3× the tip is likely lurking."

Complements execution.VenueScorecard, which learns dark-venue liquidity by probing; this one infers lit-venue hidden size without sending an order, so an execution algo can size a child against the true depth rather than the tip. Cross-asset: the trades-more-than-displayed-and-keeps-quoting tell is the same on an equity exchange level and an FX ECN level (icebergs are standard on both); sizes are longs, levels are dense tick indices, same convention as the books. Zero allocation, single writer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HiddenLiquidityDetector(int levels)
     
    HiddenLiquidityDetector(int levels, double alpha)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    estimatedTrueDepth(int level)
    Estimated total resting size at a level = displayed × hidden multiplier — the depth an execution algo should size against, not the visible tip.
    double
    hiddenMultiplier(int level)
    Estimated ratio of true resting size to displayed size at a level: 1 = no hidden liquidity detected, >1 = likely iceberg.
    boolean
    isIceberg(int level)
    True once a level has shown iceberg behavior at least once.
    int
    levels()
     
    void
    onDisplayed(int level, long size)
    The displayed size now standing at level.
    void
    onExecution(int level, long qty)
    One trade print of qty at level, compared against the size displayed at that moment.
    void
    onLevelCleared(int level)
    The level fully cleared (best moved away / all pulled).
    long
    refillObservations(int level)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • HiddenLiquidityDetector

      public HiddenLiquidityDetector(int levels, double alpha)
      Parameters:
      levels - number of price levels tracked (dense tick indices)
      alpha - EWMA weight on each refill observation, e.g. 0.2

    • HiddenLiquidityDetector

      public HiddenLiquidityDetector(int levels)

  • Method Details

    • onDisplayed

      public void onDisplayed(int level, long size)
      The displayed size now standing at level.

    • onExecution

      public void onExecution(int level, long qty)
      One trade print of qty at level, compared against the size displayed at that moment. A print exceeding the display is the hidden-liquidity event: the overflow could only have filled against unseen size. The EWMA seeds from the first observation — a ratio's meaningful floor is 1.0, so ramping up from 0 would under-register a genuine single event.

    • onLevelCleared

      public void onLevelCleared(int level)
      The level fully cleared (best moved away / all pulled).

    • hiddenMultiplier

      public double hiddenMultiplier(int level)
      Estimated ratio of true resting size to displayed size at a level: 1 = no hidden liquidity detected, >1 = likely iceberg. Uses the EWMA refill ratio, falling back to 1 before any evidence.

    • estimatedTrueDepth

      public double estimatedTrueDepth(int level)
      Estimated total resting size at a level = displayed × hidden multiplier — the depth an execution algo should size against, not the visible tip.

    • isIceberg

      public boolean isIceberg(int level)
      True once a level has shown iceberg behavior at least once.

    • refillObservations

      public long refillObservations(int level)

    • levels

      public int levels()