# Cival Trapped Traders — Guide

Release 1.2.1-atas · archive SHA-256 `4087fb14a1257bfce4a3e6e93a6d1ce5e06d0b23b76e641e98e0316b238ba933` · 206,674 bytes

Contents: install guide · reading the indicator · trading playbook · settings reference · platform compatibility

## Cival Trapped Traders v1.2.1 - Install Guide

Indicator for ATAS Platform. One file: `Cival.TrappedTraders.dll`. Display name in ATAS: **Cival Trapped Traders** (category Cival). Support: support@civalsystems.com.

## 1. Requirements

| Need | Detail |
|---|---|
| Platform | ATAS Platform **8.0.15 or newer**, Windows. The DLL targets the .NET 10 runtime that ATAS ships; you install nothing extra. |
| Footprint / cluster data | The chart history must carry **bid and ask volume at each price** for every bar you want analysed. This is the one hard data requirement. Many feeds supply candles only; with those, the indicator reports Footprint unavailable and draws nothing. |
| History | At least **21 completed bars** are needed before the first reading can appear (a 20-bar reference window plus the source bar). Load several days. By default the indicator analyses the newest 5,000 bars of the chart (setting *Maximum chart slots at rebuild*). |
| Chart | Start on a regular time-based chart; the worked examples in these docs use 5-minute bars. The engine reads completed bars in order. |
| Tick size | ATAS must report the instrument's real tick size, and the footprint rows must sit on that price grid. Rows that do not are rejected as "off-grid". |

## 2. Install with the included script (recommended)

**Step 1.** **Close ATAS completely** (every ATAS window; check Task Manager for leftover ATAS processes).

**Step 2.** Extract the ZIP to an ordinary folder, for example `Downloads\Cival-Trapped-Traders-v1.2.1`.

**Step 3 (optional).** Integrity check, in PowerShell from the extracted folder:

```powershell
Get-FileHash .\ATAS\Cival.TrappedTraders.dll -Algorithm SHA256
Select-String -Path .\SHA256SUMS.txt -Pattern 'Cival.TrappedTraders.dll'
```

The two hashes must match (letter case does not matter).

**Step 4.** Run the installer from the extracted folder:

```powershell
.\ATAS\Install.ps1
```

It copies the DLL into `%APPDATA%\ATAS\Indicators`, backs up a DLL of the same name if one is already there, and verifies the SHA-256 of the copy. If Windows blocks the script because it came from the internet, run `Unblock-File .\ATAS\Install.ps1` once (or `powershell -ExecutionPolicy Bypass -File .\ATAS\Install.ps1`) and try again.

**Step 5.** Start ATAS.

## 3. Manual install

1. Close ATAS.
2. Copy `ATAS\Cival.TrappedTraders.dll` into `%APPDATA%\ATAS\Indicators` (paste that path into Explorer's address bar).
3. If a file with that name is already there, move it **out of** the Indicators folder first (keep your backup elsewhere; do not leave two copies in the folder).
4. If Windows marked the file as downloaded, right-click it, choose Properties and tick Unblock, or run `Unblock-File` on it.
5. Start ATAS.

## 4. First load

1. Open a chart of an instrument whose history has footprint data. A quick check: temporarily switch the chart to a cluster/footprint view and confirm bid x ask numbers appear in each candle, then switch back if you prefer.
2. Open the chart's Indicators window (right-click the chart, then Indicators), search for **Cival Trapped Traders**, and add it.
3. Leave every setting at its default for now. If you want to set the baseline explicitly, set *Apply a starting preset* to **Balanced** (it equals the defaults).
4. Wait for history to load. A heads-up display (HUD) titled **CIVAL TRAPPED TRADERS** appears in the top-right corner of the price pane. It needs a pane of at least 190 x 110 pixels.

The first HUD line is a status. What the common ones mean:

| First HUD line | Meaning |
|---|---|
| Warmup / Warmup: prior ATR / volume baseline | Not enough earlier bars yet: 14 for the ATR baseline and, because *Require prior-relative volume* is on, 20 for the volume baseline. Normal for the first bars after loading. |
| Footprint unavailable: `<reason>` | The newest closed bar has no usable bid/ask rows. The reason names the check that failed (for example No reported price rows). Fix the data, not the settings. |
| Waiting for known structure reference | Footprint is fine but no reference level exists yet (for example the 20-bar window is not full, or no confirmed swing has formed). |
| Active: closed-bar failed-aggression hypotheses | The detector is running. Having no zones on screen is normal. |
| Waiting for valid native tick size | ATAS has not supplied a tick size for the instrument. |
| AS OF bar N; later candles excluded from study | Review mode is on (setting *Review as of bar*). |

The last HUD lines read `Closed classified coverage 100%` (how much of the newest closed bar's volume carries a bid/ask classification; at least 99% is required) and the reminder `Failed-aggression hypothesis / positions and exits unknown`. With no qualified zone the HUD says `NO QUALIFIED TRAP / inspect data and filters`.

## 5. Verify it works

Tick every line:

- [ ] **Cival Trapped Traders** appears in the indicator list and adds without an error message.
- [ ] The HUD titled CIVAL TRAPPED TRADERS is visible (or *Show dashboard* is on and the pane is large enough).
- [ ] After at least 21 completed bars, the first HUD line reads `Active: closed-bar failed-aggression hypotheses` (not `Footprint unavailable`).
- [ ] The HUD's coverage line reads `Closed classified coverage` with a value of 99% or more.
- [ ] A gold line reads `LIVE preview / forming bar N / may change` (or `Live preview waiting for ticks` until the first tick arrives). This is the provisional layer, not a confirmation.
- [ ] The settings window lists 85 settings in numbered groups (00 Chart clarity through 99 Export).
- [ ] Review test: set *Review as of bar* to a bar number inside your loaded history (the `CONFIRMED @ n` and `source n` numbers shown by the indicator are such numbers). The first HUD line changes to `AS OF bar N; later candles excluded from study`. If it says `Review bar is outside the bounded loaded history`, choose a more recent number. Set it back to **-1** when done.
- [ ] If you scroll back through history and find any zone, hovering a candle inside it switches the HUD to that zone.

Seeing no zones for a while does not mean the install failed. Zones need a qualifying source, a reclaim and a later confirmation (see `03-Reading-the-Indicator`).

## 6. Updating

1. Save your chart template first (your indicator settings live in your ATAS workspace and chart templates, not in the DLL).
2. Close ATAS and run the new version's `.\ATAS\Install.ps1`. It backs up the DLL it replaces.
3. Start ATAS and reopen your chart. If ATAS was left running, it may offer *Reload indicators* in the main window's status bar; reopening ATAS is the safe alternative.
4. If an older saved chart shows fewer layers than the docs describe, open the indicator settings and switch on **Apply upgraded visual defaults now** (group 89 Live visuals). It switches on live preview, trap cards, confluence checklist, edge-extended boxes, arrows, zones, labels, unconfirmed candidates, ended zones, markers and the dashboard, and sets fill opacity 26% and minimum box height 10 pixels.

## 7. Uninstalling

Close ATAS, then run `.\ATAS\Uninstall.ps1` from the extracted folder, **or** delete `Cival.TrappedTraders.dll` from `%APPDATA%\ATAS\Indicators` by hand. Charts that used the indicator will no longer show it. Exports, if you made any, stay in `%APPDATA%\ATAS\CivalTrappedTraders` (or your chosen folder) until you delete them.

## 8. Troubleshooting

| Symptom | Likely cause and fix |
|---|---|
| Not in the indicator list | ATAS was not restarted after copying; the DLL is not directly in %APPDATA%\ATAS\Indicators; Windows blocked the file (Properties, Unblock); ATAS is older than 8.0.15; or you searched a partial name. Search the exact name Cival Trapped Traders. |
| HUD says Footprint unavailable: No reported price rows (or "waiting for footprint") | Your data connection supplies candles without bid/ask volume per price, or the footprint history for those bars is not loaded. Load tick/cluster history or use a connection that provides it. No setting substitutes for missing data. |
| Footprint unavailable: Incomplete volume/classification reconciliation | The bar's bid + ask volume does not add up to its candle volume within 1% (or under 99% classified). A partial or filtered footprint. Reload history; do not lower *Minimum classified candle volume percent* to hide it. |
| Footprint unavailable: Invalid/duplicate/off-grid footprint row | Rows are not on the instrument's tick grid, or a price repeats. Check the tick size ATAS shows for the instrument. |
| HUD never appears / panel empty | The price pane is smaller than 190 x 110 px; *Show dashboard* is off; or the HUD sits behind another panel. Enlarge the pane, change *Dashboard corner* or *Dashboard width*. |
| Warmup does not end | Fewer than 21 completed bars are loaded, or the baselines keep resetting because bars are malformed. Load more history. |
| Nothing drawn, status Active | Normal when no candle met the source rules. Check that *Detect failed breakout aggression*, *Detect extreme aggression rejection* and *Detect stranded diagonal stacks* are on. Do not loosen settings to force output. |
| Gold zones appear but never confirm | By design confirmation is delayed. Read the HUD checklist and check the reclaim deadline (8 bars), the confirmation window (4 bars after reclaim), the displacement test (0.25 frozen ATR from the reclaim close) and the close-location test (0.60). A near miss does not confirm. See 03-Reading-the-Indicator section 17. |
| Too many zones on the chart | Lower *Maximum recent visible zones*, switch *Show ended confirmed zones* off, or use the compact layout (*Full analysis detail* off, *Compact display* on). |
| Copy fails: file in use / DLL locked | ATAS is still running. Close every ATAS window and process, then run Install.ps1 again. |
| Settings reset after an update | ATAS stores settings by name in the chart template. Restore your saved template, or re-enter the settings. Keep a template copy before each update. |
| A setting change seems ignored | A combination was rejected as invalid and the earlier values stay in force (the status line shows Invalid trapped-trader settings). Common cases: *Minimum later bars after reclaim* greater than *Maximum bars after reclaim*; manual upper reference not above the manual lower reference while *Structural reference* is ManualLevels. |
| No alerts | *Enable new live local alerts* is off by default; alerts also stay silent during history loading, recalculation, review mode and delivered history corrections. |
| Export did nothing | The status line says why: No completed report to export, or Export failed: `<error type>`. |



## 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:

| Name | Meaning | Response direction | Colour |
|---|---|---|---|
| **BUYERS** (trapped buyers) | Aggressive buying beyond or at a reference failed to hold | Bearish (price moved down) | Rose #FB7185 |
| **SELLERS** (trapped sellers) | Aggressive selling beyond or at a reference failed to hold | Bullish (price moved up) | Teal #2DD4BF |

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

| State | What triggers it (defaults) | Event name | What you see |
|---|---|---|---|
| **At risk** | A closed candle passes the source rules (section 3). The zone is a hypothesis only. | at-risk | Gold dashed box from the source bar, label BUYERS AT RISK / `<kind>` |
| **Reclaimed** | A completed close back through the reference by more than the buffer (1 tick minimum). It can happen on the source candle itself or on a later bar, up to 8 bars after the source (*Maximum bars to reclaim reference*). | reclaimed | Still gold; card says BUYERS RECLAIMED |
| **Confirmed** | A later closed candle satisfies the confirmation rules (section 5). Never the source candle. | confirmed | Solid rose/teal box starting at the confirmation bar, a circle and arrow at the confirmation close, label CONFIRMED @ `<bar>` \| BUYERS TRAPPED |
| **Retested** (still active) | The first later candle whose range touches the zone (plus 1 tick, *Retest price tolerance ticks*) and that closes beyond the zone on the response side: below the zone low for BUYERS, above the zone high for SELLERS. Only the first retest is recorded. | retest-rejected | Small marker RETEST-REJECTED |
| **Invalidated** | A close (or, with *Confirmed invalidation price source* = Wick, a high/low) strictly beyond the invalidation price. Invalidation wins over a guide touch on the same candle. | invalidated | Zone turns grey, marker INVALIDATED (gold), card TRAP ENDED |
| **Accepted** | Before confirmation, a close strictly beyond the invalidation price: price accepted beyond the source extreme, so the hypothesis failed. | accepted | The gold zone disappears; **no marker** |
| **Expired** | No reclaim within 8 bars; or reclaimed but not confirmed within 4 bars of the reclaim (*Maximum bars after reclaim*); or a confirmed zone older than 200 bars (*Maximum confirmed-zone tracking bars*). Capacity limits can also expire the oldest candidate (capacity-expired). | expired | An unconfirmed zone disappears with **no marker**; a confirmed one turns grey |
| **Filtered** | Confirmation geometry was met but evidence points were below *Minimum evidence points*. Cannot happen at the default of 0. | filtered | Zone disappears |
| **Interrupted** | A malformed-OHLC bar (or an ordinal gap in the bar sequence) ends every pending and active zone and resets the ATR, volume and reference baselines, so warm-up restarts. | interrupted | Zones end; for a malformed bar the status says Invalid bar; warmup reset |

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.

| Source kind | Condition (defaults) | Eligible rows |
|---|---|---|
| **Failed breakout** (*Detect failed breakout aggression*) | The candle's high is more than 1 tick (*Break clearance ticks*) above the reference high (low below the reference low for sellers). | Rows priced strictly beyond the reference |
| **Edge rejection** (*Detect extreme aggression rejection*) | The candle's extreme is within 2 ticks of the reference or beyond it, **and** the candle closes back away from the source rows by more than the buffer. | Rows in the outer 30% of the candle's range (*Extreme region fraction of candle range*) |
| **Stack failure** (*Detect stranded diagonal stacks*) | At least 3 consecutive diagonal imbalance rows in that outer region, the same close-back-away rule, and (by default) a known reference within 2 ticks (*Stack failures require known structure*). | The strongest qualifying stack |

**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):

| Gate | Default | How it is computed |
|---|---|---|
| Eligible rows | at least 2 (*Minimum reported aggressive price rows*) | Rows with positive volume in the eligible region |
| Aggressive share | 10% (*Minimum aggressive edge volume / candle percent*) | 100 x aggressive-side volume in eligible rows / whole candle volume |
| Edge delta | 20% (*Minimum directional edge delta percent*) | 100 x (aggressive - opposite) / (aggressive + opposite), eligible rows only. Aggressive = ask volume for buyers, bid volume for sellers |
| Absolute volume | 0 (*Minimum observed aggressive volume (feed units)*) | Feed units (contracts, coins), not dollars. Set a floor that suits your instrument |
| Relative volume | 1.2 (*Minimum prior-baseline RVOL*) | Source candle volume / mean volume of the previous 20 bars (*Prior volume baseline bars*), source excluded |
| Diagonal imbalance | ratio 3, stack of 3 (*Minimum diagonal imbalance ratio*, *Minimum consecutive diagonal stack rows*) | A buy row counts when its ask volume is at least 3 times the bid volume one tick **below**; a sell row, its bid volume against the ask one tick **above**. Zero opposite volume never counts. Rows must be tick-adjacent |
| Stack for every source | off (*Require stack for every source*) | When on, breakouts and edge rejections must also contain a qualifying stack |

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

| Price | Computation (defaults) | Notes |
|---|---|---|
| **Invalidation** | Source extreme +/- the largest of 1 tick, *Invalidation offset ticks* and 0.10 x frozen source ATR (*Invalidation offset / frozen ATR*), rounded outward to a whole tick | Frozen at the source. It is a reference for where this hypothesis is considered wrong. It is not a stop order and says nothing about where anyone's stops are |
| **1R reference** | Confirmation close, moved in the response direction (down for BUYERS, up for SELLERS) by the distance from the confirmation close to the invalidation price | Off by default (*Show analytical 1R / 2R guides*) |
| **2R reference** | Twice that distance | Observed events guide-1-observed / guide-2-observed only record that price traded there |

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)

| Item | Points | Met when |
|---|---|---|
| Directional classified edge aggression | 25 | Always, for a zone that was created (the source gates were passed) |
| Known structural reference | 15 | The zone has a reference (always, unless a stack failure with *Stack failures require known structure* off) |
| Consecutive diagonal imbalance | 15 | The source contains at least 3 stacked rows |
| Prior-relative volume | 10 | RVOL at least the minimum (1.2) |
| Completed close back through reference | 10 | The reclaim has happened |
| Later adverse price displacement | 15 | Confirmed (not scored before) |
| Directional confirmation close location | 10 | Confirmed (not scored before) |

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

| Element | Setting that controls it | Meaning |
|---|---|---|
| Zone box | *Show trap zone bands* | Source rows, half a tick wider each end. Solid thick outline once confirmed (begins at the **confirmation bar**); dashed gold while unconfirmed (begins at the source bar). Fill strength *Zone fill opacity percent* (26%). Boxes of current pending/active zones extend to the right edge on the latest view (*Extend current trap boxes to chart edge*) |
| Faint source span | *Show faint historical source span* | A very faint band between the source bar and the confirmation bar, for context. The reading is known only at confirmation |
| Aggression VWAP line | *Show observed aggression VWAP* | 2-pixel line at the aggression VWAP; dashed while unconfirmed |
| Source profile bars | *Show top observed source rows* | Up to 32 short bars beside the zone: the largest source rows by aggressive volume. Executed volume, **not resting liquidity**. Rows sharing a pixel show the biggest, not a sum |
| Labels | *Show numeric labels* | BUYERS FAILED / failed breakout (or AT RISK) above or below the zone; low - high / `<volume>` observed units at the VWAP |
| Confirmation marker | *Show later confirmation markers* | Circle at the confirmation close with CONFIRMED @ `<bar>` \| BUYERS TRAPPED |
| Direction arrow | *Show large trapped-side arrows* | Large arrow at the confirmation close in the response direction (down for BUYERS, up for SELLERS) |
| Event markers | *Show retest and invalidation markers* | Last 24 RETEST-REJECTED, INVALIDATED and AMBIGUOUS markers in view; INVALIDATED is gold |
| Invalidation guide | *Show selected invalidation* | Dashed gold line from the confirmation bar to the right edge for the selected confirmed zone. In the default full-detail mode it is labelled Count invalid below/above `<price>` (wording shared with other Cival tools); with *Full analysis detail* off it reads INVALIDATION `<price>`. Same price either way |
| 1R / 2R guides | *Show analytical 1R / 2R guides* (off) | Dashed lines 1R reference `<price>` and 2R reference `<price>` |
| Trap cards | *Show trap cards with volume and price* | Up to three 310 x 112 px cards at the chart edge: stage title, low - high \| timing, `<volume>` observed units \| evidence N/100, the live pressure line, and an evidence bar. Needs room; they are skipped when the pane is small or space is taken |
| HUD | *Show dashboard* | Section 8 |

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`.

| Line | Example | Meaning |
|---|---|---|
| Status | Active: closed-bar failed-aggression hypotheses | Section 10 lists every status |
| Counts | CONFIRMED buyers 1 \| sellers 2 \| at risk 0 | Retained **active** confirmed zones by trapped side, and retained pending candidates (at risk + reclaimed) |
| Live line | LIVE preview / forming bar 1380 / may change | Gold. Only when *Show live forming trap preview* is on and not in review mode |
| Selected zone | BUYERS TRAP ENDED \| Invalidated \| 100/100 | Stage, state (or FORMING for a live projection), evidence points |
| Zone and VWAP | Zone 81606.5 - 81612.5 \| VWAP 81610.7469... | Exact zone bounds and aggression VWAP |
| Volume and delta | Observed 2.05851 units \| source delta 78.04% | Aggressive-side executed volume in the source rows (feed units) and the edge delta from section 3 |
| Baselines | Relative volume 1.76 \| stack 3 \| source 62 | RVOL, stacked rows, source bar number |
| Ordinals | Reclaim 62 \| confirmed 64 \| invalid 81616 | Bar numbers of reclaim and confirmation (- if not yet, PENDING for a live projection) and the invalidation price |
| Pressure | Adverse `<n>`t \| live delta `<n>`% | Section 9. Ended / Invalidated once over |
| Checklist (3 lines) | AGGRESSION YES \| STRUCTURE YES \| STACK YES / Relative volume YES \| RECLAIM YES \| MOVE YES / CLOSE YES | The evidence items. YES met, WAIT not met, N/A unavailable. MOVE is the displacement item. Shown with *Show orderflow confluence checklist* |
| Coverage | Closed classified coverage 100% | Share of the newest closed candle's volume carrying bid/ask; or the reason the footprint failed |
| Footer | Failed-aggression hypothesis / positions and exits unknown | A permanent reminder |

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

| Message | Meaning |
|---|---|
| Warmup | Initial state; no closed bars processed |
| Warmup: prior ATR / volume baseline | Fewer than 14 prior bars for ATR, or fewer than 20 for volume with relative volume required |
| Footprint unavailable: `<reason>` | Reasons: No reported price rows; Price-row budget exceeded (more rows than *Maximum footprint rows per candle*); No positive reported candle volume; Invalid/duplicate/off-grid footprint row; Reported rows exceed candle volume; Incomplete volume/classification reconciliation |
| Waiting for known structure reference | No reference level yet for the chosen mode |
| Active: closed-bar failed-aggression hypotheses | Running normally |
| Invalid bar; warmup reset | A malformed candle interrupted the study |
| Waiting for valid native tick size | ATAS has not supplied a tick size |
| AS OF bar N; later candles excluded from study | Review mode |
| Review bar is outside the bounded loaded history | The review bar is older than the analysed window |
| Delivered history correction rebuilt; historical alerts suppressed | ATAS revised an already-closed candle |
| Invalid trapped-trader settings | A setting combination was rejected; previous values remain |
| Study unavailable: `<error>` | An unexpected error; the study is cleared until the next recalculation |
| Local alert unavailable: `<error>`; study retained | The sound/notification host failed; the study is unaffected |
| Exported JSON and causal event CSV to `<folder>` / No completed report to export / Export failed: `<error>` | Export results |
| Move crosshair to a completed bar first | *Set review at completed crosshair now* had no completed bar under the cursor |

## 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.

| Setting | Balanced | Selective | Responsive |
|---|---|---|---|
| Prior range lookback bars | 20 | 20 | 12 |
| Minimum directional edge delta percent | 20 | 30 | 15 |
| Minimum aggressive edge volume / candle percent | 10 | 10 | 8 |
| Minimum reported aggressive price rows | 2 | 3 | 2 |
| Require prior-relative volume / minimum RVOL | on / 1.2 | on / 1.5 | **off** / 1.2 |
| Require stack for every source | off | **on** | off |
| Confirmation evidence policy / opposite delta % | CompleteFootprint / 5 | OpposingDelta / 8 | CompleteFootprint / 5 |
| Confirmation displacement / frozen ATR | 0.25 | 0.40 | 0.15 |

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**

| Setting | Default | Effect |
|---|---|---|
| Compact display (full detail must be off) | on | Reduced layout, only when *Full analysis detail* is off |
| Full analysis detail | on | Full layout; expands abbreviations such as RVOL in text |
| Apply a starting preset | Custom | Action; section 11 |

**01 Structure**

| Setting | Default | Effect |
|---|---|---|
| Structural reference | PriorRange | PriorRange / ConfirmedSwings / ManualLevels |
| Prior range lookback bars | 20 | 3 to 500; width of the PriorRange window |
| Confirmed pivot bars each side | 3 | 1 to 30; pivot strictness for ConfirmedSwings |
| Manual upper reference | 0 | Used only in ManualLevels; must exceed the lower |
| Manual lower reference | 0 | Used only in ManualLevels |
| Detect failed breakout aggression | on | Enables failed-breakout sources |
| Detect extreme aggression rejection | on | Enables edge-rejection sources |
| Detect stranded diagonal stacks | on | Enables stack-failure sources |
| Stack failures require known structure | on | Stack failures must be within 2 ticks of a reference |

**02 Source aggression**

| Setting | Default | Effect |
|---|---|---|
| Break clearance ticks (at least one) | 1 | 0 to 1000; at least 1 is always enforced |
| Minimum reported aggressive price rows | 2 | 1 to 100 |
| Extreme region fraction of candle range | 0.30 | 0.05 to 1; outer part of the candle used for rejections and stacks |
| Minimum aggressive edge volume / candle percent | 10 | 0 to 100 |
| Minimum directional edge delta percent | 20 | 0 to 100 |
| Minimum observed aggressive volume (feed units) | 0 | Absolute floor in native units |
| Minimum diagonal imbalance ratio | 3 | 1 to 100 |
| Minimum consecutive diagonal stack rows | 3 | 2 to 100 |
| Require stack for every source | off | Applies the stack gate to all source kinds |

**03 Prior baselines**

| Setting | Default | Effect |
|---|---|---|
| Prior simple ATR bars | 14 | 2 to 200; frozen into each zone |
| Prior volume baseline bars | 20 | 2 to 500 |
| Require prior-relative volume | on | Gate on RVOL for every source |
| Minimum prior-baseline RVOL | 1.2 | 0.1 to 100 |

**04 Later confirmation**

| Setting | Default | Effect |
|---|---|---|
| Reclaim clearance ticks (at least one) | 1 | 0 to 1000; buffer for the reclaim and the confirmation threshold |
| Maximum bars to reclaim reference | 8 | 1 to 200 |
| Maximum bars after reclaim | 4 | 1 to 200; confirmation window |
| Minimum later bars after reclaim | 1 | 1 to 20; must not exceed the confirmation window |
| Confirmation displacement / frozen ATR | 0.25 | 0 to 10 |
| Directional confirmation close location fraction | 0.60 | 0.5 to 1 |
| Confirmation evidence policy | CompleteFootprint | CompleteFootprint / OpposingDelta / PriceOnly |
| Minimum opposite delta percent (opposing mode) | 5 | 0 to 100; used only with OpposingDelta |
| Minimum evidence points (not probability) | 0 | 0 to 100; extra gate on the checklist score |

**05 Zone lifecycle**

| Setting | Default | Effect |
|---|---|---|
| Invalidation offset ticks (at least one) | 1 | 0 to 1000 |
| Retest price tolerance ticks | 1 | 0 to 1000 |
| Maximum confirmed-zone tracking bars | 200 | 2 to 10000 |
| Nearby same-side source cooldown bars | 8 | 0 to 1000 |
| Invalidation offset / frozen ATR | 0.10 | 0 to 10 |
| Confirmed invalidation price source | Close | Close uses completed closes; Wick uses highs/lows |

**70 Review**

| Setting | Default | Effect |
|---|---|---|
| Review as of bar (-1 latest) | -1 | Section 12 |
| Set review at completed crosshair now | off | Action |
| Return to latest study now | off | Action |

**80 Data and limits**

| Setting | Default | Effect |
|---|---|---|
| Maximum retained zone records | 128 | 16 to 512 |
| Maximum simultaneous candidates | 16 | 1 to 64 |
| Maximum retained event records | 2048 | 64 to 8192 |
| Maximum footprint rows per candle | 20000 | 100 to 100000; over-budget candles are unavailable, never partly classified |
| Row/candle volume tolerance percent | 1 | 0 to 5 |
| Minimum classified candle volume percent | 99 | 90 to 100; lowering it does not restore missing history |
| Maximum chart slots at rebuild | 5000 | 200 to 20000; earlier bars are not analysed |

**89 Live visuals**

| Setting | Default | Effect |
|---|---|---|
| Show live forming trap preview | on | Section 9 |
| Live preview refresh milliseconds | 250 | 100 to 2000 |
| Show trap cards with volume and price | on | Cards, full layout only |
| Show orderflow confluence checklist | on | Checklist lines in the HUD |
| Extend current trap boxes to chart edge | on | Pending/active boxes reach the right edge |
| Show large trapped-side arrows | on | Arrow at the confirmation close |
| Minimum visible box height pixels | 10 | 6 to 40 |
| Apply upgraded visual defaults now | off | Action; switches the key layers back on in an older saved template. It overwrites deliberate layout choices, so note them first |

**90 Display**

| Setting | Default | Effect |
|---|---|---|
| Show trap zone bands | on | Zone boxes |
| Show unconfirmed at-risk candidates | on | Gold pending zones |
| Show ended confirmed zones | on | Grey zones that had been confirmed |
| Show faint historical source span | on | Faint band, source to confirmation |
| Show observed aggression VWAP | on | VWAP line |
| Show top observed source rows | on | Source profile bars |
| Show numeric labels | on | Labels and cards |
| Show later confirmation markers | on | Circle and label at confirmation |
| Show retest and invalidation markers | on | Event markers |
| Show selected invalidation | on | Invalidation guide |
| Show analytical 1R / 2R guides | off | Reference lines |
| Show dashboard | on | HUD |
| Inspect crosshair cycle | on | HUD follows the candle under the cursor |
| Dashboard corner | TopRight | TopRight / TopLeft / BottomRight / BottomLeft |
| Dashboard width | 430 | 260 to 500 pixels |
| Maximum recent visible zones | 6 | 1 to 24 |
| Zone fill opacity percent | 26 | 0 to 60 |

**91 Colors**

| Setting | Default | Effect |
|---|---|---|
| Trapped buyers color (bearish response) | #FB7185 | Rose |
| Trapped sellers color (bullish response) | #2DD4BF | Teal |
| Unconfirmed candidate color | #FBBF24 | Gold |

**95 Alerts and 99 Export**

| Setting | Default | Effect |
|---|---|---|
| Enable new live local alerts | off | Master switch |
| Alert on new confirmation | on | Used when the master is on |
| Alert on later rejected retest | off | |
| Alert on invalidation | off | |
| Alert sound | alert1 | ATAS sound identifier |
| Export folder (blank uses ATAS profile) | blank | %APPDATA%\ATAS\CivalTrappedTraders when blank |
| Export current JSON and event CSV now | off | Action; section 14 |

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

| Observation | Check |
|---|---|
| Gold zones never confirm | Read the HUD checklist for the zone: structure, footprint coverage, relative volume, the 8-bar reclaim and 4-bar confirmation deadlines, and the displacement (0.25 frozen ATR) and close-location (0.60) tests. A bar that misses displacement by a tick still does not confirm (section 16, bar 63) |
| Almost no sources | Check where the prior-range reference sits, the feed's volume units against *Minimum observed aggressive volume (feed units)*, tick size, the number of source rows, RVOL and whether *Require stack for every source* is on. Use Responsive to inspect more candidates, not as a proven better model |
| Too many zones on screen | Lower *Maximum recent visible zones*, switch *Show ended confirmed zones* off, or use the compact layout |
| A past zone is gone | Check *Show ended confirmed zones*, the retention limits, a delivered history correction, the current symbol and the *Maximum chart slots at rebuild* floor. Unconfirmed endings are never charted |
| A zone is thin or hard to see | Zoom the price scale, raise *Zone fill opacity percent* or *Minimum visible box height pixels*, show numeric labels, or move the HUD corner |
| Footprint coverage shows a reason instead of a percentage | Unavailable data is not a measured zero. Fix the data; do not lower the classification checks to hide it |

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.




## Trading Playbook - Cival Trapped Traders

**What this page is.** A way to think about the indicator's output when you trade discretionary order flow. It describes where the indicator's own reference prices sit and what must be true on the chart before a reading deserves attention. It does not tell you to take any trade, and the indicator does not issue orders, targets or forecasts. Read `03-Reading-the-Indicator` first; this page assumes you know the lifecycle (at risk, reclaimed, confirmed, retested, invalidated) and the difference between a closed-bar reading and the gold LIVE preview.

**What the indicator can offer.** A consistent, closed-bar description of one specific event: executed aggression at a known reference that did not hold. Whether that event matters to your trading is for you to establish by reviewing it (section 7). No profit, win rate or accuracy is claimed anywhere in this product.

## 1. Context first

Check these before you look at a single zone:

- **Is the data trustworthy?** The HUD status should read `Active: closed-bar failed-aggression hypotheses` and the coverage line should read `Closed classified coverage` at 99% or more. After a reconnect or a history reload, the study rebuilds; wait for it to settle before reading anything.
- **Where is the reference?** The default reference is the high/low of the previous 20 bars on *this* chart. Ask whether that level means anything on a larger timeframe: a prior session high/low, a weekly level, a value-area edge, a round number. The indicator does not know. A break of a meaningless 20-bar high is still reported.
- **What is the volatility?** Compare the distance from the confirmation close to the invalidation price with the move you actually want to risk. The invalidation sits beyond the source extreme by at least 1 tick, and by 0.10 x the 14-bar ATR if that is larger, so a wide source candle produces a wide invalidation.
- **What is the session doing?** The engine does not know about sessions. Early in a session its 20-bar window and ATR may include bars from another session. Thin hours and scheduled news change how much weight a "failed" move deserves.
- **Volume units.** Observed volume is in the feed's units (contracts or coins). A source that qualifies on a quiet instrument can be trivial on a busy one. Use *Minimum observed aggressive volume (feed units)* to express "large enough for this instrument".

## 2. Reading the reference prices

| Price on the chart | What it is | What it is not |
|---|---|---|
| **Zone** (solid box once confirmed) | The price rows where the source candle's aggressive volume executed, half a tick wider each end | Resting liquidity; where positions are held |
| **Aggression VWAP** (line in the zone) | Volume-weighted mean price of the aggressive side across those rows | An entry price for anyone |
| **Reference** (not drawn; sits just inside the zone's near edge for a failed breakout) | The prior-range, swing or manual level that was broken or tested | A support/resistance claim |
| **Invalidation** (gold dashed line) | A frozen price beyond the source extreme where this hypothesis is considered wrong | A stop order, or the location of anyone's stops |
| **1R / 2R reference** (off by default) | Distances equal to confirmation-close-to-invalidation, projected in the response direction | Profit targets or expected outcomes |

## 3. Playbook A - A confirmed failed breakout at a prior-range extreme

**Idea.** Price pushes beyond a prior extreme on directional aggression, then closes back inside, and a later closed candle moves away with displacement. The failed-aggression hypothesis is now confirmed by the study's rules.

**What must be true on the chart.**

1. A gold at-risk zone beyond a prior extreme, labelled `failed breakout`, whose source candle shows the numbers you care about in the HUD (observed units, source delta, relative volume, stack).
2. A separate closed candle later produced `CONFIRMED @ <bar> | BUYERS TRAPPED` (or SELLERS). A gold LIVE preview is **not** this; wait for the candle to close and the solid box to start.
3. The checklist lines show `RECLAIM YES` and `MOVE YES` and `CLOSE YES`; note whether `STACK` and relative volume are `YES`. With the defaults an 85 means the diagonal stack was missing; it does not mean "less likely".
4. The invalidation line is visible and the distance from the confirmation close to it fits your risk.

**Where the indicator's prices sit.** The zone and aggression VWAP are *behind* price after confirmation (above it for BUYERS, below it for SELLERS). The invalidation is beyond the zone's far edge. The optional 1R and 2R references continue away from the zone in the response direction at multiples of the confirmation-to-invalidation distance.

**How a trader might define the plan (one example, not a rule).**

- *Entry.* Some traders act after the confirmation candle has closed; others wait for a pullback toward the zone and look for the `RETEST-REJECTED` marker (Playbook B). Each changes the distance to the invalidation. Entering later usually shrinks the distance, and also means you may never get the opportunity.
- *Stop.* If you choose to use the invalidation price as the level where the idea is wrong, your stop would sit beyond it, so your real risk is the distance from your entry to there plus your own allowance for slippage. The indicator places nothing. If that distance is too large for your risk limit, the answer is a smaller size or no trade, not a tighter stop that the idea does not support.
- *Management.* The 1R and 2R lines are distances, not promises. A trader might use them as places to reassess, to reduce, or to ignore. Decide in advance. Confirmed zones are tracked for up to 200 bars; you may prefer a much shorter time-based exit.
- *Position size.* Fix it from the stop distance and what a stop-out costs you, before entry.

**When to stand aside.**

- The footprint coverage is incomplete, the status is not `Active`, or the data feed has just reconnected.
- The distance to invalidation is wider than you are willing to risk.
- The confirmation arrived against a clear higher-timeframe push, at a level that matters to other participants, and you do not have a plan for that situation. (The indicator does not say which setting is better; record both cases in your journal.)
- A scheduled news release is minutes away.
- You are tempted because the evidence score is 100. The score is a checklist of the study's own conditions.

**What cancels it.** A close beyond the invalidation price (marker `INVALIDATED`, zone turns grey). The study also ends the zone as expired after 200 bars. Before confirmation, a close beyond the invalidation price (accepted) or a missed deadline makes the gold zone vanish with no marker. If any of these happen, the hypothesis is off; do not stretch the level.

## 4. Playbook B - A rejected retest of a confirmed zone

**Idea.** After confirmation, price returns to the source zone and closes back on the response side. The study logs this once per zone as `RETEST-REJECTED`. Some traders prefer to assess a zone on its second visit rather than on the first confirmation.

**What must be true on the chart.**

1. A confirmed zone that is still active (rose or teal, not grey).
2. A `RETEST-REJECTED` marker on a **closed** candle: the candle's range touched the zone (within 1 tick) and it closed below the zone low (BUYERS) or above the zone high (SELLERS).
3. The invalidation is still unbroken. Note how far price has already moved since confirmation; the 1R and 2R references are still measured from the *original* confirmation close.

**Where the prices sit.** The zone edges are the retest area and the invalidation is unchanged. Measured from a close just beyond the zone's edge, the distance to the invalidation is set mostly by the zone's height and the invalidation offset, so it can be smaller than the distance from the original confirmation close (check the actual numbers). A smaller distance also leaves less room for noise.

**How a trader might define the plan.** Entry after the retest candle has closed; stop beyond the invalidation (or beyond the retest candle's extreme, if that is farther in your plan); size from that distance. Management and time limits as in Playbook A. Only the *first* retest of a zone is recorded, so a second return to the zone will not produce a new marker.

**When to stand aside.** The candle touches the zone but closes inside it or on the wrong side of it (no marker is drawn, and nothing has been rejected). Spread or slippage is a large fraction of the distance to the invalidation. Many bars have passed since confirmation and your own time limit has expired.

**What cancels it.** A close beyond the invalidation price; expiry at 200 bars after confirmation; a data interruption that ends the zone.

## 5. Playbook C - Use gold (unconfirmed) zones as a watch list, and learn when to drop them

**Idea.** A gold zone is a hypothesis, not a reading. Some traders mark it as a place to pay attention and do nothing until the study confirms. This is a discipline playbook about not acting early.

**What must be true on the chart.** A gold zone exists near a reference you care about; the HUD's `at risk` count is above zero; you have a written note of what would turn it into a confirmed zone (a closed candle through the reference and the zone, with displacement and the close location) and what would end it.

**Where the prices sit.** The zone and its aggression VWAP are the only prices drawn. The invalidation price is shown in the HUD (`invalid <price>`), not as a chart line, until the zone confirms.

**What the plan can look like.** Nothing to execute until a candle closes and the study confirms. When it does, move to Playbook A. If the zone ends first (price closes beyond the invalidation, or the reclaim/confirmation deadline passes), the study removes it **without a marker**; note that in your journal as a non-event and move on.

**When to stand aside.** Always, until confirmation. The LIVE preview in particular can show `LIVE BUYERS TRAPPED?` and then retract on the next tick.

**What cancels it.** The zone vanishes from the chart or the `at risk` count falls; a close beyond the invalidation; 8 bars pass without a reclaim, or 4 bars pass after a reclaim without confirmation.

## 6. Combining with other context

Use what the indicator cannot see: higher-timeframe structure, session highs and lows, volume-profile edges, VWAP, scheduled events, and your own notion of trend. Agreement between a confirmed zone and another tool is context for your discretion. It is not independent statistical proof, and two tools that look at the same candles are partly telling you the same thing.

If you also run Cival Manipulation (in the Manipulation & Pressure Toolkit), remember the two indicators calculate independently from their own settings; neither reads the other's output.

## 7. Journaling and review

The only way to know whether these readings help *your* trading is to keep records. Suggested routine:

1. **Log every at-risk source, not just confirmed ones.** The export (JSON and event CSV) keeps accepted, expired and filtered endings that the chart does not show.
2. **Replay with *Review as of bar*.** Set it to the confirmation bar of an old zone and see what was known then. Step it forward one candle at a time. Record how each zone ended (retest, invalidation, expiry) and how far price travelled in each direction, in your own units and with your own costs.
3. **Screenshot the decision candle,** with the HUD visible, so you can see later whether the data was complete.
4. **Separate the signal from the trade.** Record the study's outcome (confirmed, invalidated) and, separately, what you did and why.
5. **Review in batches.** In the demo run, 42 of 100 at-risk sources confirmed, 34 of those 42 were later invalidated (20 before the 1R reference was ever observed), and every confirmed zone scored 85 or 100. That is one 4.8-day BTC sample with no entries, costs or profit/loss modelled; it shows that confirmation is a stage, not an outcome. Build your own sample on your own instrument.
6. **Change one thing at a time.** Presets are starting points. None has been optimised or validated for any market. If you change a threshold, note the date and the reason, and review again.

## 8. Mistakes to avoid

- Treating the zone as a limit-order opportunity or as "where stops were". It is executed volume.
- Acting on the gold LIVE overlay. It is provisional and can retract on any tick.
- Reading evidence points as odds. With the defaults, a confirmed zone scores 85 or 100 and nothing else.
- Ignoring the invalidation because the zone "looks right". When price closes beyond it, the study's hypothesis has ended.
- Lowering *Minimum classified candle volume percent* or other data checks to make output appear. Missing data is missing; fix the feed.
- Loosening the source gates until the chart is full of zones, then judging the indicator by the noise.
- Forgetting that unconfirmed zones disappear without a marker, and then believing the chart "missed" nothing.
- Trusting a reading across a reconnect, a history reload, or a delivered data correction without checking that the study has rebuilt.
- Sizing from the evidence score rather than from the stop distance and your risk limit.
- Assuming a reading that worked once on one instrument will transfer to another, or to a different timeframe, without review.

## 9. Risk

Trading futures and cryptocurrency involves substantial risk of loss, including, on some leveraged products, losses beyond your initial deposit. Indicators describe what has already happened in executed order flow and price. They do not describe what will happen. Nothing in this product is trading advice, a recommendation to buy or sell, or a forecast, and no result is claimed or implied.

- **Test on replay or a simulated account first,** using the exact settings you intend to use.
- **Size positions so that a stop-out is affordable.** Decide the loss you can accept before entry, and size from the stop distance, not from the indicator's evidence score.
- **Past observations do not predict future results,** including the demonstration run quoted in these documents.
- Slippage, fees, funding, spread and outages are not modelled by the indicator and can change an outcome materially.
- You are responsible for every order you place. Cival Systems does not place trades, manage accounts or certify this indicator for automated execution.



## Cival Trapped Traders — Settings Reference

Version 1.2.1. Generated from the compiled ATAS plugin: every value below is the default a fresh instance loads with.

## Cival Trapped Traders

Closed-bar failed aggression: at-risk source, reclaim, later confirmation and observed lifecycle. Footprint required; positions remain unknown.

### 00 Chart clarity

| Setting | Default | Allowed |
|---|---|---|
| Compact display (full detail must be off) | on | on / off |
| Full analysis detail | on | on / off |

### 00 Quick setup

| Setting | Default | Allowed |
|---|---|---|
| Apply a starting preset | Custom | Custom, Balanced, Selective, Responsive |

### 01 Structure

| Setting | Default | Allowed |
|---|---|---|
| Structural reference | PriorRange | PriorRange, ConfirmedSwings, ManualLevels |
| Prior range lookback bars | 20 | Int32 |
| Confirmed pivot bars each side | 3 | Int32 |
| Manual upper reference | 0 | Decimal |
| Manual lower reference | 0 | Decimal |
| Detect failed breakout aggression | on | on / off |
| Detect extreme aggression rejection | on | on / off |
| Detect stranded diagonal stacks | on | on / off |
| Stack failures require known structure | on | on / off |

### 02 Source aggression

| Setting | Default | Allowed |
|---|---|---|
| Break clearance ticks (at least one) | 1 | Int32 |
| Minimum reported aggressive price rows | 2 | Int32 |
| Extreme region fraction of candle range | 0.3 | Decimal |
| Minimum aggressive edge volume / candle percent | 10 | Decimal |
| Minimum directional edge delta percent | 20 | Decimal |
| Minimum observed aggressive volume (feed units) | 0 | Decimal |
| Minimum diagonal imbalance ratio | 3 | Decimal |
| Minimum consecutive diagonal stack rows | 3 | Int32 |
| Require stack for every source | off | on / off |

### 03 Prior baselines

| Setting | Default | Allowed |
|---|---|---|
| Prior simple ATR bars | 14 | Int32 |
| Prior volume baseline bars | 20 | Int32 |
| Require prior-relative volume | on | on / off |
| Minimum prior-baseline RVOL | 1.2 | Decimal |

### 04 Later confirmation

| Setting | Default | Allowed |
|---|---|---|
| Reclaim clearance ticks (at least one) | 1 | Int32 |
| Maximum bars to reclaim reference | 8 | Int32 |
| Maximum bars after reclaim | 4 | Int32 |
| Minimum later bars after reclaim | 1 | Int32 |
| Confirmation displacement / frozen ATR | 0.25 | Decimal |
| Directional confirmation close location fraction | 0.6 | Decimal |
| Confirmation evidence policy | CompleteFootprint | CompleteFootprint, OpposingDelta, PriceOnly |
| Minimum opposite delta percent (opposing mode) | 5 | Decimal |
| Minimum evidence points (not probability) | 0 | Int32 |

### 05 Zone lifecycle

| Setting | Default | Allowed |
|---|---|---|
| Invalidation offset ticks (at least one) | 1 | Int32 |
| Retest price tolerance ticks | 1 | Int32 |
| Maximum confirmed-zone tracking bars | 200 | Int32 |
| Nearby same-side source cooldown bars | 8 | Int32 |
| Invalidation offset / frozen ATR | 0.1 | Decimal |
| Confirmed invalidation price source | Close | Close, Wick |

### 70 Review

| Setting | Default | Allowed |
|---|---|---|
| Review as of bar (-1 latest) | -1 | Int32 |
| Set review at completed crosshair now | off | on / off |
| Return to latest study now | off | on / off |

### 80 Data and limits

| Setting | Default | Allowed |
|---|---|---|
| Maximum retained zone records | 128 | Int32 |
| Maximum simultaneous candidates | 16 | Int32 |
| Maximum retained event records | 2048 | Int32 |
| Maximum footprint rows per candle | 20000 | Int32 |
| Row/candle volume tolerance percent | 1 | Decimal |
| Minimum classified candle volume percent | 99 | Decimal |
| Maximum chart slots at rebuild | 5000 | 200 – 20000 |

### 89 Live visuals

| Setting | Default | Allowed |
|---|---|---|
| Show live forming trap preview | on | on / off |
| Live preview refresh milliseconds | 250 | 100 – 2000 |
| Show trap cards with volume and price | on | on / off |
| Show orderflow confluence checklist | on | on / off |
| Extend current trap boxes to chart edge | on | on / off |
| Show large trapped-side arrows | on | on / off |
| Minimum visible box height pixels | 10 | 6 – 40 |
| Apply upgraded visual defaults now | off | on / off |

### 90 Display

| Setting | Default | Allowed |
|---|---|---|
| Show trap zone bands | on | on / off |
| Show unconfirmed at-risk candidates | on | on / off |
| Show ended confirmed zones | on | on / off |
| Show faint historical source span | on | on / off |
| Show observed aggression VWAP | on | on / off |
| Show top observed source rows | on | on / off |
| Show numeric labels | on | on / off |
| Show later confirmation markers | on | on / off |
| Show retest and invalidation markers | on | on / off |
| Show selected invalidation | on | on / off |
| Show analytical 1R / 2R guides | off | on / off |
| Show dashboard | on | on / off |
| Inspect crosshair cycle | on | on / off |
| Dashboard corner | TopRight | TopRight, TopLeft, BottomRight, BottomLeft |
| Dashboard width | 430 | 260 – 500 |
| Maximum recent visible zones | 6 | 1 – 24 |
| Zone fill opacity percent | 26 | 0 – 60 |

### 91 Colors

| Setting | Default | Allowed |
|---|---|---|
| Trapped buyers color (bearish response) | #FB7185 | Color |
| Trapped sellers color (bullish response) | #2DD4BF | Color |
| Unconfirmed candidate color | #FBBF24 | Color |

### 95 Alerts

| Setting | Default | Allowed |
|---|---|---|
| Enable new live local alerts | off | on / off |
| Alert on new confirmation | on | on / off |
| Alert on later rejected retest | off | on / off |
| Alert on invalidation | off | on / off |
| Alert sound | alert1 | String |

### 99 Export

| Setting | Default | Allowed |
|---|---|---|
| Export folder (blank uses ATAS profile) | (blank) | String |
| Export current JSON and event CSV now | off | on / off |



## Cival Trapped Traders — Platform Compatibility

The ATAS plugin is the reference implementation. Each port computes what its platform's data allows and labels
anything approximate or unavailable inside the indicator itself. The sections below are the READMEs that ship next
to each port's source file (`ports/<platform>/README.md`).

## TradingView (Pine Script v6)

## Cival Trapped Traders for TradingView (Pine Script v6)

Port of the ATAS original **Cival Trapped Traders v1.2.1**. It maps closed-bar *failed-aggression hypotheses*: directional executed volume outside a known structural reference (source, "at risk"), a later close back through that reference ("reclaimed"), a still-later qualifying displacement ("confirmed"), and the observed aftermath (rejected retest, invalidation, expiry). It never infers positions, identities, stops or exits, and the 0-100 evidence points are a checklist, not a probability. Nothing here trades or sends orders.

**Requirements**

- TradingView **Premium or Ultimate** plan. The detector is built on `request.footprint()`, which returns `na` on lower plans. This mirrors ATAS, where the source rule makes footprint mandatory: **without footprint data the source detector is OFF** and the dashboard says so. There is no price-only or lower-timeframe substitute for the source rule, because per-price-row aggression, diagonal imbalances and candle-extreme rows cannot be reconstructed from bars.
- A symbol and timeframe for which TradingView can build a volume footprint (history depth varies by plan and timeframe). Use standard candles/bars.
- File: `CivalTrappedTraders.pine`, overlay indicator, Pine v6.

**Install**

1. Open the Pine Editor on TradingView, choose *Open > New blank indicator*, paste the contents of `CivalTrappedTraders.pine`, click *Save*, then *Add to chart*.
2. Leave **Apply a starting preset** on `Custom` (identical to Balanced at default values) or pick Balanced / Selective / Responsive.
3. Alerts are off by default. To use them: turn on *Enable new live local alerts*, then create a TradingView alert on this indicator with condition **Any alert() function call**. Alerts fire only on live bar closes, never for history.
4. If TradingView reports a runtime/time-limit error on instruments with thousands of ticks per bar, raise **Footprint ticks per row** (group `98 TradingView data`) or lower **Maximum chart slots at rebuild**.

### Feature matrix

Values: Full / Approximate / Not available / Not ported.

| Feature | ATAS original | This port | Notes |
|---|---|---|---|
| Failed-breakout source (aggression beyond a known boundary after a strict breakout) | Yes | Approximate | Same rules and thresholds; data comes from TradingView footprint rows (aggregated by *ticks per row*, default 1) instead of ATAS per-price bid/ask levels. |
| Extreme-aggression rejection source | Yes | Approximate | Same as above; extreme region = outer fraction of the candle range. |
| Stranded diagonal-stack source | Yes | Approximate | Diagonal ratio computed by the script from adjacent rows (not TradingView's `has_buy_imbalance`), so the ratio setting means exactly "aggressor volume >= ratio x opposite volume one row away". |
| Structural reference: prior range / confirmed swings / manual levels | Yes | Full | Source candle is excluded from its reference; pivots usable only after right-hand confirmation. |
| Prior ATR, prior-volume baseline and RVOL gate | Yes | Full | Frozen at the source; uses the chart's volume. |
| Ambiguous-path guard (both boundaries crossed in one candle) | Yes | Full | Emits an "ambiguous" marker, creates no source. |
| Footprint mandatory; unavailable-data status | Yes | Full | Dashboard row `DATA:` states footprint on/off and the reason when a bar is rejected. |
| Footprint reconciliation checks | Yes | Approximate | Candle-level only: positive volume, row budget, footprint total vs chart volume within tolerance, buy+sell coverage. Per-row duplicate/off-grid checks are not needed (TradingView supplies aggregated rows). A symbol whose chart volume differs from its footprint total by more than the tolerance is reported "Incomplete volume/classification reconciliation" rather than guessed. |
| Lifecycle: at risk, reclaimed, confirmed, retested | Yes | Full | No same-bar confirmation; minimum later bars; displacement, close-location and flow gates. |
| Terminal outcomes: accepted, expired, filtered, invalidated, interrupted | Yes | Full | Invalidation takes precedence over guide touches. |
| Confirmation evidence policy (CompleteFootprint / OpposingDelta / PriceOnly) | Yes | Full | Delta comes from the reconciled footprint only. |
| Evidence points /100 (7 items) and minimum-evidence gate | Yes | Full | Unavailable evidence is not scored. Not a probability. |
| Frozen invalidation (tick/ATR offset, rounded outward; Close or Wick) | Yes | Full | |
| Rejected retest and 1R/2R reference observations | Yes | Full | Reference prices only; no fills or P&L. |
| Cooldown, overlap suppression, bounded retention (zones, candidates, events, rows) | Yes | Full | Same limits and eviction order. |
| Interruption on bad data or gaps | Yes | Approximate | Malformed OHLC/volume interrupts and resets baselines. Pine bars cannot skip ordinals and has no explicit source-gap flag, so those two ATAS triggers do not exist here. |
| Zone bands (solid confirmed, dashed candidate, fill opacity, extend to edge) | Yes | Approximate | Time-anchored boxes. Zone edges are +/- half a row around row prices (a half-tick offset from TradingView's own row edges). No minimum pixel height. |
| Faint historical source span | Yes | Full | |
| Observed aggression VWAP line | Yes | Approximate | Weighted by each row's representative price (see Known differences). |
| Top-32 observed source rows profile | Yes | Approximate | Drawn as horizontal boxes up to 6 bars wide beside the zone; capped by the 500-box budget. |
| Numeric labels (cycle, range, volume) | Yes | Approximate | Pine labels; no collision avoidance. |
| Confirmation marker and large trapped-side arrow | Yes | Full | Marker carries the Pine bar_index of confirmation. |
| Retest / invalidated / ambiguous event markers (newest 24) | Yes | Full | Hidden in compact mode, as in ATAS. |
| Selected-cycle invalidation line and optional 1R/2R guides | Yes | Approximate | Selected cycle = newest eligible one; ATAS can also pick by mouse position. |
| Dashboard with confluence checklist | Yes | Approximate | Pine table, four corners; no width control. Adds a TradingView `DATA:` row. |
| Trap cards (stacked per-trap cards) | Yes | Not ported | The labels and dashboard carry the same figures. |
| Live forming-bar preview (provisional gold overlay) | Yes | Not ported | Only closed-bar state is drawn. The dashboard's live line (adverse ticks from the current price, live delta) is marked "live, may change" and never feeds confirmed state. |
| Review "as of" bar | Yes | Approximate | Type a Pine `bar_index`; processing stops there. Does not hide later candles (same as ATAS). |
| Crosshair inspection, "set review at crosshair", "return to latest" buttons | Yes | Not available | Pine cannot read the crosshair or run action buttons. Use the bar-index input (-1 = latest). |
| Presets Balanced / Selective / Responsive | Yes | Approximate | While a preset is selected it overrides **every** computation input (ATAS applies it once as an action and leaves settings editable). Select Custom to edit. |
| Compact display / full analysis detail | Yes | Approximate | Compact hides ended zones and event markers and shows only pending/active cycles. The ATAS read-out badge and plain-language relabelling are not ported. |
| Opt-in alerts: confirmation, retest, invalidation | Yes | Full | Via `alert()`; live bar closes only; alert sound is chosen in TradingView's alert dialog. |
| Hidden numeric outputs for integrations | 16 series | Approximate | 2 of 16 ported (Buyers confirmed, Sellers confirmed), data-window only. |
| JSON and event-CSV export | Yes | Not available | Pine cannot write files. |

### Settings mapping

Input names, groups and defaults are the ATAS ones (see the shared settings reference). Present in this port: `00 Quick setup`, `00 Chart clarity`, `01 Structure`, `02 Source aggression`, `03 Prior baselines`, `04 Later confirmation`, `05 Zone lifecycle`, `70 Review` (Review as of bar), `80 Data and limits`, `89 Live visuals` (extend boxes, arrows, confluence), `90 Display` (all but the items below), `91 Colors`, `95 Alerts` (not the sound).

TradingView-only input: `98 TradingView data` > **Footprint ticks per row** (default 1).

**Not ported**

| ATAS setting | Reason |
|---|---|
| Dashboard width | Pine tables size to their text. |
| Inspect crosshair cycle | No crosshair access. |
| Minimum visible box height pixels | Pine boxes have no pixel minimum. |
| Show live forming trap preview, Live preview refresh milliseconds | Live preview layer not ported. |
| Show trap cards with volume and price | Cards not ported. |
| Apply upgraded visual defaults now | Action button. |
| Set review at completed crosshair now, Return to latest study now | Action buttons; use the Review input. |
| Alert sound | Chosen in TradingView's alert dialog. |
| Export folder, Export current JSON and event CSV now | No file I/O in Pine. |

### Known differences from ATAS results

1. **Row prices.** ATAS reads one bid/ask row per traded price. TradingView returns rows of *ticks per row* ticks with an upper and lower edge. The script uses each row's lowest tradable tick as its price (`down_price + max(0, up_price - down_price - mintick) / 2`), which equals the ATAS price at 1 tick per row. This convention is an assumption and has not been checked against live TradingView data. At more than 1 tick per row, stacks and imbalances compare rows of that size, so results diverge from ATAS.
2. **Footprint availability.** TradingView footprint history depth, symbols covered and chart-volume agreement differ from an ATAS feed. Bars without reconcilable footprint count as "unavailable"; sources cannot form on them.
3. **Visible zones.** ATAS limits to cycles in the scrolled viewport; Pine cannot read the viewport, so "Maximum recent visible zones" keeps the newest N overall.
4. **Review mode** uses TradingView `bar_index`, not ATAS ordinals, so the same number points at a different bar.
5. **Drawing caps.** Boxes (460 budget), lines and labels are capped by TradingView at 500 each; very busy charts drop the oldest profile bars first.
6. **Runtime.** Row scanning runs only on bars where a detector can possibly fire, but wide-range bars at 1 tick per row can be slow on TradingView. Raise ticks per row if needed.

### Verification status

Compiled with TradingView's Pine compiler (`pine_check`) on 2026-10-26: `compiled: true`, 0 errors, 0 warnings. **Not run on a live chart or in replay.** Footprint row conventions, history depth, the runtime on real symbols, alert delivery and drawing appearance are unverified. No claim of profitability, accuracy or vendor parity is made.

## NinjaTrader 8 (NinjaScript)

## Cival Trapped Traders - NinjaTrader 8

Port of the ATAS original v1.2.1 (`Cival.TrappedTraders`). Closed-bar failed-aggression study: directional aggression at a known structural reference, a later reclaim and a later qualifying confirmation, followed through to retest, invalidation, expiry or interruption. "Confirmed" means this study's failed-aggression criteria were met on a closed bar. It does not say anything about traders' actual positions, size, entry price or exits, which the study never sees. Evidence points are a checklist out of 100, not a probability. No orders, no account access, no network access.

### Requirements

| Item | Requirement |
|---|---|
| Platform | NinjaTrader 8 (NinjaScript, .NET Framework 4.8). |
| Bar type | Order Flow+ **Volumetric** bars. Footprint detections need real per-price bid/ask volume, so the chart must use Volumetric bars with **Ticks per level = 1** (the original works per tick) and delta type **Bid/Ask**. |
| License | An Order Flow+ entitlement (Volumetric bars) and a data feed that supplies tick-level bid/ask history and real-time data. |
| Calculation | `Calculate` must stay **On bar close**. Any other setting is refused and the HUD says so. |
| Not volumetric | On any other bar type the study loads, runs its price-only baselines, and shows "Footprint source OFF". It does not invent footprint rows and it produces no trap candidates. |
| **Compile status** | **Not compiled.** NinjaTrader is not installed on the machine where this port was written, so the source has never been through the NinjaScript compiler. Compile on import: **NinjaScript Editor -> F5**. Please report any compiler message verbatim. |

### Install

1. Close any open NinjaScript Editor windows.
2. Copy `CivalTrappedTraders.cs` to `Documents\NinjaTrader 8\bin\Custom\Indicators\`.
3. In NinjaTrader choose **New -> NinjaScript Editor**, open the file, and press **F5** to compile. If the compiler reports an error, keep the exact message.
4. Open a chart with an Order Flow+ Volumetric series (Ticks per level 1), then right-click -> **Indicators** -> add **Cival Trapped Traders**.
5. Start with the defaults (they match the ATAS "Balanced" preset). Allow at least 21 completed bars of footprint history.

Colours: rose = buyers failed (bearish response), teal = sellers failed (bullish response), gold = at risk / unconfirmed.

### What is detected

Same rule set as the ATAS original (see its README for the full text):

- **Failed breakout** - aggressive volume outside a prior range, confirmed swing, or manual reference after a strict price breakout.
- **Edge rejection** - directional extreme-row aggression at a known boundary that the source candle already rejects.
- **Stack failure** - consecutive diagonal imbalances (aggressor volume >= ratio x opposite volume one tick away) that fail to hold their source region.
- **Lifecycle** - at risk -> reclaimed -> confirmed -> rejected retest, with accepted, filtered, expired, invalidated and interrupted as explicit outcomes. A confirmation can never happen on the source bar.
- **Data checks** - every source needs reconciled rows (row volume within tolerance of candle volume, classified bid+ask >= the configured coverage). Missing or inconsistent rows make the footprint "unavailable" for that bar; nothing is filled in.

### Feature matrix

Values: **Full** = same rule set and thresholds; **Approximate** = same idea, platform-specific difference described; **Not available** = the platform cannot supply it; **Not ported** = not implemented.

| Feature | ATAS original | This port | Notes |
|---|---|---|---|
| Failed breakout source | Yes | Full | Rows come from Volumetric bars. |
| Edge rejection source | Yes | Full | |
| Stack failure source (diagonal stacks) | Yes | Full | Needs tick-adjacent rows (Ticks per level 1). If rows are not tick-adjacent the bar is marked "footprint off" rather than approximated. |
| Reference modes (prior range / confirmed swings / manual) | Yes | Full | |
| ATR and RVOL baselines (prior bars only, frozen per source) | Yes | Full | |
| Footprint reconciliation (volume tolerance, classification coverage, row budget) | Yes | Full | The row budget counts the bar's price span in ticks (including empty ticks), not only traded rows. |
| Lifecycle states (at risk, reclaimed, confirmed, retested, invalidated, accepted, expired, filtered, interrupted) | Yes | Full | |
| Closed-bar confirmation, no repainting | Yes | Full | `Calculate.OnBarClose`; the forming bar is never read. |
| Evidence points /100 (7 checks) | Yes | Full | Not a probability. |
| Cooldown, overlap suppression, capacity limits | Yes | Full | |
| Invalidation (close or wick), ATR + tick buffer, outward tick rounding | Yes | Full | |
| Analytical 1R / 2R guide observations | Yes | Full | Reference prices only. No order, fill or P&L. |
| Ambiguous-candle handling (both boundaries crossed) | Yes | Full | Emits an "ambiguous" event; no source is created. |
| Malformed bar quarantine / baseline reset | Yes | Full | |
| Ordinal-gap interruption | Yes | Approximate | NinjaTrader delivers every bar index in order, so the ATAS ordinal-gap case cannot occur; malformed bars still interrupt. |
| Presets (Balanced / Selective / Responsive) | One-shot action | Approximate | An enum, not an action: a non-Custom value replaces **all** computation settings with that preset when the indicator loads. Leave on Custom to use your own values. |
| Trap zone boxes | Pixel-space boxes, dashed when unconfirmed | Approximate | Drawn with `Draw.Rectangle` in bar/price units. No dashed style, no minimum pixel height, and active zones extend to the last closed bar rather than the chart edge. |
| Aggression VWAP line | Yes | Full | |
| Top 32 observed source rows | Right of the zone, pixel scaled | Approximate | Short `Draw.Line` bars to the left of the source candle, length scaled to at most 5 bars. |
| Numeric labels, confirmation markers, directional arrows | Yes | Approximate | `Draw.Text` / `Draw.ArrowUp` / `Draw.ArrowDown` / `Draw.Dot`. No label collision handling. |
| Retest / invalidation / ambiguous markers | Yes | Approximate | Last 24, as in the original. |
| Selected-cycle invalidation and optional 1R / 2R lines | Mouse-selected cycle | Approximate | The newest selected cycle is used; there is no crosshair selection. |
| Dashboard HUD | Floating panel, width setting | Approximate | One `Draw.TextFixed` block. Corner is supported; width is not. |
| Trap cards | Floating cards | Approximate | A text block under the HUD for up to three cycles. |
| Confluence checklist (YES / WAIT / N/A) | Yes | Full | Text lines in the HUD. |
| Live forming-bar preview (gold LIVE overlay, live adverse ticks, live delta) | Yes | Not ported | The port is strictly closed-bar. The HUD shows the adverse distance from the aggression VWAP as of the **last closed bar** instead. |
| Inspect crosshair cycle | Yes | Not ported | No crosshair-to-bar access in a closed-bar study. |
| Review as of bar | Yes | Approximate | `Review as of bar` works (later bars are ignored). The crosshair and "return to latest" actions are not ported: set the value to -1 instead. |
| Alerts (confirmation, retest, invalidation) | Local, off by default, history suppressed | Full | `Alert()` in real-time only; off by default. `Alert sound` is a file name under `<NinjaTrader install>\sounds` (default `alert1` -> `alert1.wav`). If the file is missing the alert is silent. |
| JSON + event CSV export | Action button, atomic files | Approximate | Same schema id (`cival.trappedtraders.v1`) and a hand-written JSON writer. NinjaTrader has no action buttons, so `Export current JSON and event CSV now` is a switch: when on, a snapshot is written once after history loads and again whenever the event list changes in real time. Default folder `Documents\NinjaTrader 8\CivalTrappedTraders`. |
| 16 hidden integration outputs | Hidden series | Full | Public non-plotted `Series<double>` properties (`NetConfirmed`, `BuyersConfirmed`, ... `InvalidationCount`), same values and order. |
| Chart clarity compact display | Yes | Approximate | Only the compact/full switch is ported (hides ended zones, trap cards and event markers). The clarity banner is not ported. |
| Bounded history window | Yes | Full | Starts `Maximum chart slots at rebuild` bars before the last loaded bar. |

### Settings mapping

All 77 ported inputs keep the ATAS display names, group names and defaults (taken from the compiled settings dump). Groups: `00 Chart clarity`, `00 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`, `99 Export`. Decimal settings are `double`, colours are NinjaTrader brushes.

Not ported (not present as inputs):

| ATAS setting | Reason |
|---|---|
| Show live forming trap preview | Needs forming-bar footprint; the port is closed-bar only. |
| Live preview refresh milliseconds | Same. |
| Inspect crosshair cycle | No crosshair access. |
| Set review at completed crosshair now | Action button / crosshair access. Use `Review as of bar`. |
| Return to latest study now | Action button. Set `Review as of bar` to -1. |
| Dashboard width | `Draw.TextFixed` has no width control. |
| Minimum visible box height pixels | Boxes are drawn in bar/price units. |
| Apply upgraded visual defaults now | Action button; the defaults already enable those layers. |

### Known differences from ATAS

- **Different data.** The rules are the same, but the rows come from NinjaTrader Volumetric bars instead of ATAS price levels. Feed, tick history and bid/ask classification differ between platforms, so the same market can produce different rows and therefore different candidates. Bar timestamps are NinjaTrader's (bar close time for time-based bars); ATAS used bar open time. Exports record the NinjaTrader timestamp and make no time-zone conversion.
- **Arithmetic.** The ATAS engine used `decimal`; this port uses `double` with a one-thousandth-of-a-tick tolerance on price comparisons so grid-exact ties behave the same.
- **Volumetric delta type.** With delta type "Up/Down tick" instead of "Bid/Ask", NinjaTrader classifies volume differently and results will differ from a Bid/Ask chart.
- **Ticks per level above 1** is refused rather than approximated (see the stack failure row).
- **Real-time only alerts.** NinjaTrader raises `Alert()` only in real-time, which matches the original's rule that history never alerts.
- **Reloading.** Changing any input reloads the indicator and recomputes from the bounded history window, as the ATAS settings changes did.

### Verification status

Done offline against stand-ins for the NinjaTrader API, because NinjaTrader is not installed here:

- The engine was run side by side with the ATAS `TrapEngine` on 96 seeded synthetic footprint scenarios (1,713 zones, 7,131 events, all three source kinds and all lifecycle states). Zones, events, evidence and the 16 output values matched within 1e-7.
- The indicator was driven through load, history and real-time bars against API stand-ins, including exports (JSON parsed successfully).
- The source was syntax- and type-checked as C# 7.3 against .NET Framework reference assemblies.

Not verified: compilation against the real NinjaTrader assemblies, behaviour on a live chart, Volumetric API behaviour on real data, and appearance of the drawings. The scenarios are synthetic; they say nothing about market behaviour and this study makes no claim of profitability or accuracy.