Reading Cival Trapped Traders v1.2.1

This page explains every element the indicator draws, every state a zone can be in, every HUD line, and how each number is computed. Defaults quoted here are the values a fresh instance loads with; the full list is in 02-Settings-Reference. Where a number depends on a setting, the setting's exact ATAS name is in italics.

The vocabulary is deliberate. The indicator tracks a hypothesis of failed aggression. A "trapped" side is shorthand for "this side's executed aggression did not hold"; it is not a statement about anyone's account. Evidence points are a checklist, not a probability. Guide prices are reference prices, not orders or targets.

1. What is being measured

For every closed candle the indicator reads the executed volume at each price: bid volume (trades that hit the bid, aggressive selling) and ask volume (trades that lifted the ask, aggressive buying). Delta is ask minus bid. It then follows one hypothesis from start to finish:

1. A candle shows directional aggression at or beyond a known structural reference (the source).
2. Price closes back through that reference (the reclaim).
3. A later closed candle moves away from the source zone with enough displacement (the confirmation).
4. The zone is then tracked until a retest, an invalidation, or expiry.

Two side names are used everywhere:

Gold #FBBF24 means unconfirmed (at risk, or a LIVE preview). Grey means an ended zone.

Closed-bar rule. The newest candle loaded in ATAS is always treated as still forming, even on a static history chart. A candle counts as closed once the next one exists. Everything the indicator calls confirmed, every marker, alert, export and hidden output is computed from closed candles only. The separate gold LIVE layer (section 9) is the one exception, and it is marked as provisional wherever it appears. If ATAS later delivers a corrected historical candle or footprint, or you change a setting, the indicator rebuilds from its loaded history, so past zones can change; historical alerts are suppressed during a rebuild. A different amount of loaded history, a different timeframe or bar type, and any settings change can likewise legitimately change results. Merely moving the cursor changes only which zone the HUD shows, never the underlying closed-bar sequence.

2. Lifecycle: every state

Other events: guide-1-observed and guide-2-observed (price reached the 1R / 2R reference price after confirmation), ambiguous (one candle crossed both known boundaries, so the path is unknown and no source is created; marker AMBIGUOUS), and capacity-evicted (bounded memory dropped an old zone; bookkeeping, not a market outcome).

What is charted. Pending zones are drawn when Show unconfirmed at-risk candidates is on. A zone that was confirmed is drawn while active, and after it ends if Show ended confirmed zones is on. A candidate that ends without ever confirming (accepted, expired, filtered) is not charted, so a gold zone can vanish without a marker. The HUD's at risk count and the exports are where to see those endings.

3. Where a source comes from

All three source types need a valid footprint for the candle and, by default, relative volume of at least 1.2 times the prior 20-bar average (Require prior-relative volume, Minimum prior-baseline RVOL). The candle is checked against each side (buyers, then sellers). Order of precedence on one candle and side: failed breakout, then edge rejection, then stack failure. The first that qualifies wins.

Reference (Structural reference):

• PriorRange (default): highest high and lowest low of the preceding 20 completed bars (Prior range lookback bars). The source candle is excluded.
• ConfirmedSwings: the latest strict pivot with 3 lower highs / higher lows on each side (Confirmed pivot bars each side). A pivot becomes usable only after its right-hand bars close.
• ManualLevels: your own Manual upper reference and Manual lower reference (upper must be above lower). Enter them in the instrument's own prices on its tick grid, for the symbol on the chart. A combination that is rejected leaves the previous values in force, so set both levels while another mode is selected, then switch the mode.

The reference itself is not drawn. For a failed breakout the zone's near edge sits half a tick or more beyond it, so the reference is just inside the zone's lower edge (buyers) or upper edge (sellers). Each zone's Reference is in the JSON export.

Source gates (a candle must pass all of them):

Further source rules:

• Cooldown. A nearby same-side source within 8 bars of the previous one is suppressed (Nearby same-side source cooldown bars) if its reference is within the larger of 2 ticks and 0.25 ATR. A new source that overlaps an existing pending or active zone on the same side is also suppressed.
• Capacity. At most 16 pending candidates (Maximum simultaneous candidates); the oldest is expired when exceeded.
• Source ATR. Mean true range of the previous 14 bars (Prior simple ATR bars), frozen for that zone's whole life.

Zone geometry. The box covers the eligible rows, widened half a tick at each end. Its numeric bounds are exact; Minimum visible box height pixels only makes thin zones easier to see.

Aggression VWAP. The volume-weighted mean price of the aggressive-side volume across the source rows.

4. Invalidation and reference prices

The 1R and 2R lines are analytical distances. They are not targets, fills or profit/loss. Wick mode tests highs and lows, which cannot show the order of events inside one candle; when a candle touches more than one level, invalidation is given priority and no intrabar sequence is assumed.

5. What confirmation requires (defaults)

A pending zone is checked on each later closed candle. The candle must come at least 1 bar after the reclaim bar (Minimum later bars after reclaim), can never be the source candle, and must fall within 4 bars of the reclaim (Maximum bars after reclaim). It must satisfy all of:

1. Crossed. Its close is strictly beyond both the buffered reference and the buffered source zone (below min(reference - buffer, zone low - buffer) for buyers).
2. Displacement. Its close is at least 0.25 frozen source ATR beyond the reclaim close (Confirmation displacement / frozen ATR). This is measured from the reclaim close, not from the aggression VWAP.
3. Close location. For a bearish response, (high - close) / (high - low) is at least 0.60, so the close is at least 60% of the way from the candle's high to its low; for a bullish response, (close - low) / (high - low) is at least 0.60 (Directional confirmation close location fraction, 0.5 to 1).
4. Flow policy (Confirmation evidence policy): CompleteFootprint (default) needs a reconciled footprint on the confirmation candle; OpposingDelta additionally needs whole-candle delta against the source side of at least 5% of volume (Minimum opposite delta percent); PriceOnly allows missing confirmation flow. The source candle always needs a footprint in every mode.

Reclaim buffer: a completed close back through the reference by more than 1 tick (Reclaim clearance ticks; a setting of 0 still enforces 1 tick).

6. Evidence points (a checklist, not a probability)

Unavailable items are not scored. With the default settings the only item that can be missing on a confirmed zone is the diagonal stack, so confirmed zones score 85 or 100. The score therefore tells you which optional boxes were ticked, not how likely anything is. Minimum evidence points (default 0) can add a gate; it does not turn the score into a probability.

7. What is drawn

When the chart is crowded, current (pending or active) zones take precedence, then the newest ended ones, up to Maximum recent visible zones (default 6, up to 24). Labels may be nudged up or down a little to avoid overlapping each other, and are dropped if there is no room, so read the numbers inside a label rather than its exact vertical position.

Compact layout. With Full analysis detail off and Compact display on, the indicator shows only pending and active zones, no trap cards or event markers, at most three short labels, and replaces the HUD with a small shared panel CIVAL / CURRENT CHART READ that lists one line per Cival indicator on the chart. The defaults (both on) use the full layout described here.

8. The HUD, line by line

Hover a candle to select the zone spanning it (Inspect crosshair cycle); otherwise the newest pending or active zone is shown. Dashboard corner and Dashboard width (260 to 500) place it. In the default mode the abbreviation RVOL appears spelled out as Relative volume.

Bar numbers are ordinals of the loaded chart. They can change when history reloads.

9. The live preview layer

Show live forming trap preview (on) draws a separate, provisional overlay computed from the still-forming candle as if it closed now, on an isolated copy of the closed-bar state. It refreshes at most every 250 ms (Live preview refresh milliseconds, 100 to 2000) when ATAS delivers a tick; it uses no timer and no extra data subscription, so it does not update during a feed outage.

What it shows: gold dashed boxes; card and HUD titles LIVE <SIDE> AT RISK, LIVE <SIDE> RECLAIMED or LIVE <SIDE> TRAPPED? (with UNCONFIRMED / forming bar as the timing); a marker LIVE TRAP / UNCONFIRMED; and, in the pressure line, LIVE INVALIDATION WATCH or LIVE CONTINUATION WATCH when the forming candle would end a zone as it stands. It can change or vanish on any tick.

What it never does: feed confirmed zones, the hidden outputs, alerts, exports or review mode. Only a completed candle can promote anything to a confirmed reading.

Pressure line. Adverse <n>t = trapped-side sign x (aggression VWAP - current price) / tick size. Positive means price is on the adverse side of the source aggression's VWAP. It is a distance, not a measured loss for anyone. live delta <n>% is the forming candle's ask minus bid as a percentage of its reported volume; live flow unavailable appears if the forming candle has no usable footprint.

10. Status messages

11. Presets

Apply a starting preset is an action: choosing a value resets all computation settings (structure, source, baseline, confirmation and lifecycle groups, including the reference mode, detection toggles and manual levels) to that preset's values. Display, review, alerts and export settings are untouched. The box returns to Custom afterwards, because it is an action rather than a stored choice. Apply a preset before you tune anything.

All other computation settings keep their defaults. None of the presets has been optimised or validated for any market; use Responsive to inspect more candidates, not as a better model.

12. Review mode

Setting Review as of bar to a completed bar number recomputes the study using only data up to that bar, so you can see what was known then. Later candles stay visible because ATAS draws them, but nothing after the cutoff is analysed, the hidden outputs after it are cleared, live preview is off and no alerts are sent. Set review at completed crosshair now (an action) takes the bar under the crosshair when it is applied; if the cursor is not over a completed bar the status says Move crosshair to a completed bar first, so typing the bar number is the more reliable route. Return to latest study now (an action) sets the value back to -1.

13. Alerts

All alerts are local ATAS notifications and are off by default (Enable new live local alerts). With the master on, a new live confirmation notifies (Alert on new confirmation, on by default); Alert on later rejected retest and Alert on invalidation are separate switches (off). The text is Cival Trapped Traders: <event> BUYERS|SELLERS at <price> where the side is the trapped side. An alert is raised when the next candle begins, for events known on the candle that just closed. Nothing is sent while history loads, during recalculation, after a delivered history correction, on first attachment, or in review mode. Alert sound defaults to alert1.

14. Export

Export current JSON and event CSV now (an action) writes two files into Export folder (blank uses %APPDATA%\ATAS\CivalTrappedTraders):

• traps-<UTC stamp>-<instance>-<id>.json: schema cival.trappedtraders.v1, with the instrument, data provider, chart-clock note, review cutoff, the settings used, every retained zone (bounds, VWAP, volumes, evidence items, bar numbers, reference, invalidation, guides) and the retained events. It states explicitly that positions are not inferred, observed volume is not open inventory and guides are not orders.
• traps-<same stamp>-events.csv: columns id,zone_id,known_bar,chart_time,kind,trapped_side,price,detail. trapped_side is +1 for source buyers (bearish response) and -1 for source sellers; known_bar is when the event became known.

Files are written atomically and uniquely named. The export is a snapshot of bounded retained state (up to 128 zones and 2,048 events by default), not a permanent recorder, and a later history correction can revise earlier rows. Chart times are the chart's own clock; no timezone is assumed.

15. Where every setting acts (all 85)

Ranges are what the indicator accepts; out-of-range combinations are rejected and the earlier values stay.

00 Chart clarity and quick setup

01 Structure

02 Source aggression

03 Prior baselines

04 Later confirmation

05 Zone lifecycle

70 Review

80 Data and limits

89 Live visuals

90 Display

91 Colors

95 Alerts and 99 Export

The indicator also keeps 16 hidden data series (counts, nearest zone bounds, invalidation prices, footprint-available flag). They are not plotted, have no settings, and are not needed to read the chart.

16. Worked example from the demo data

The same sequence mirrored (SELLERS). Aggressive sellers execute below a known low; price closes back above it; a later closed candle moves above the source zone with the required displacement and, by default, a reconciled footprint. That supports SELLERS TRAPPED (a bullish response). The source candle alone does not confirm it.

Source of all numbers below: the store demo, which was produced by the shipped plugin (Cival.TrappedTraders 1.2.1.0, Balanced defaults) on Hyperliquid BTC-PERP five-minute bars with trades recorded by the Cival order-flow recorder, 17 to 21 October 2026 (1,380 closed bars), tick 1. It is an illustration of the mechanics on one sample, not a statement about results. Times are UTC bar open times.

Source (bar 62, 05:10). The 20 completed bars before it had a high of 81,606, the reference. Bar 62 traded up to 81,612 (more than 1 tick beyond), with aggressive buying of 2.05851 BTC across rows 81,607 to 81,612 against 0.25384 BTC of opposite executions: edge delta 78.04% (gate 20%), 12.8% of the candle's 16.14 BTC (gate 10%), RVOL 1.76 (gate 1.2), a 3-row diagonal stack, 6 rows (gate 2). Zone: 81,606.5 to 81,612.5, aggression VWAP 81,610.75, frozen ATR 35.64. Kind: failed breakout, BUYERS AT RISK.

Reclaim (same bar). Bar 62 closed at 81,603, 3 ticks back through 81,606 (buffer 1). State: Reclaimed. Still unconfirmed.

A bar that did not confirm (bar 63, 05:15). It closed at 81,595, below the buffered reference, but only 8 below the reclaim close; the rule needs 0.25 x 35.64 = 8.91. No confirmation.

Confirmation (bar 64, 05:20). Closed at 81,575: 28 below the reclaim close (needs 8.91), with a close location of 0.74 (needs 0.60: the close is 74% of the way from the candle's high to its low), whole-candle delta -64.3%, footprint reconciled. Evidence 100/100. Label: CONFIRMED @ 64 | BUYERS TRAPPED. Invalidation: 81,612 + max(1, 1, 0.10 x 35.64 = 3.56) = 81,615.56, rounded outward to 81,616. Distance from 81,575: 41, so the 1R reference is 81,534 and the 2R reference 81,493.

Afterwards. Bar 72 (06:00) traded down to 81,528, observing the 1R reference price. Bar 82 (06:50) traded up into the zone (high 81,616) and closed at 81,583, below the zone: a rejected retest. Bar 86 (07:10) closed at 81,620, above 81,616: invalidated, 22 bars after confirmation. The 2R reference price (81,493) was never observed on this zone.

What the same run shows in aggregate. 100 at-risk sources opened; 44 were later accepted and 14 expired without confirming; 42 confirmed. Of those 42, 34 were eventually invalidated (20 of them before the 1R reference was ever observed), 5 expired and 3 were still active at the end. All 42 scored 85 or 100 points. These are lifecycle counts on one short sample with no entries, exits, costs or profit/loss modelled. They illustrate that confirmation is a stage, not an outcome.

17. If a reading looks wrong or stays empty

Do not loosen thresholds merely to force a signal.

18. What the indicator cannot know

• Who traded, and whether trades opened or closed positions. Footprint rows are executions at prices. Observed aggressive volume is not trapped position size and not open inventory.
• Where anyone's stops are, or who was forced out. The invalidation is a price where the hypothesis is considered wrong. Expiry or invalidation does not prove anyone exited.
• Resting orders. The indicator uses executions only. Source profile bars are executed volume.
• Data completeness at the exchange. The coverage check only confirms that the bars you loaded are internally consistent. It is not an audit of the feed.
• Sessions. The engine reads consecutive loaded bars. It does not know about session breaks, so the 20-bar range, ATR and volume baselines run across overnight and weekend gaps.
• History before the analysis window. Earlier bars than Maximum chart slots at rebuild are not analysed, and each warm-up restart needs about 21 bars.
• Other Cival indicators. The confluence checklist is computed from this detector's own footprint and price data. It does not read the settings or outputs of any other Cival indicator on the chart.
• The future. A confirmed zone describes what happened up to that candle. It does not say what comes next, and no setting or preset has been validated for profit.