Some of the most expensive mistakes in trading happen when a move looks strong right before it fails.
A breakout prints on the chart, traders chase it, and then the move loses conviction and reverses. In derivatives, that reversal is often visible not just in price, but in the structure sitting behind the move: weak participation, thin order flow, or options positioning that does not actually support the breakout.
That is where nubra-trap-detector becomes useful.
Available on PyPI, the library is built on top of the Nubra SDK and is designed to detect bull traps, bear traps, short squeezes, and long squeezes in Indian index derivatives. Instead of looking only at candles or only at the option chain, it combines both and turns them into a structured probability-style output you can monitor from the terminal or plug into a larger workflow.
If you already work with NIFTY or BANKNIFTY and want a cleaner way to judge whether a move has real conviction behind it, this library gives you a strong starting point.
Why Trap Detection Matters#
Most traders know what a trap looks like after the reversal has already happened.
The difficult part is identifying the conditions that make a trap more likely while the move is still developing. A bull trap is not just a candle breaking resistance. It is usually a breakout that happens without meaningful participation. A bear trap is the same idea on the downside. Short squeezes and long squeezes add another layer, because positioning in the options market can create forced exits that distort price behavior very quickly.
That is why trap detection works best when it is treated as a multi-signal problem instead of a single-chart pattern.
nubra-trap-detector takes that approach directly.
What the Library Does#
At a high level, the engine watches a symbol, collects both market structure and options structure, and then evaluates whether the current setup looks like a genuine move or a likely trap.
On the price side, it checks whether the latest bar is breaking a recent range and then asks a more important question: is that breakout actually backed by volume, chain-wide OI expansion, and enough nearby orderbook liquidity?
On the squeeze side, it looks at the options market through metrics like Put-Call Ratio, delta-weighted OI imbalance, and rapid unwinding in dominant strikes. That helps the engine identify when one side of the market is getting too crowded and vulnerable to a squeeze.
Those two readings are then combined into a final trap probability, along with a dominant trap type and direction.
So instead of manually interpreting several moving parts, you get a single structured output that still shows the underlying reasoning.
The Visual Overview#
The visual below uses a terminal-style raw response example built from the actual payload shape returned by the library. Instead of a generic concept diagram, it shows what the detector result really looks like in practice: top-level metadata, the price-trap block, the squeeze-trap block, and the final total section that carries the main trap probability.
That makes the asset much more useful for anyone trying to understand how the detector can plug into their own monitoring, logging, or downstream strategy workflow.
How the Engine Works#
One of the stronger parts of the package is that it is not just a detector function. It is a small monitoring system.
The main engine first discovers the active expiry, resolves the required instrument references, starts the live feed, preloads recent OHLCV history, refreshes option-chain snapshots, and then begins evaluating signals on the chosen interval. In the default live workflow, it uses the Nubra ecosystem for both streaming and reference data, and the result is a much more production-friendly pipeline than a one-off notebook script.
Internally, the engine keeps a thread-safe state store for candles, chain snapshots, and orderbook data. From there it runs two separate detectors: a PriceTrapDetector, which focuses on breakout quality, and a SqueezeDetector, which focuses on options crowding and unwind pressure.
The final result is aggregated using the library's default detector weights of 0.55 for price traps and 0.45 for squeeze traps. That weighted view is what produces the final trap probability.
This matters because the library is not trying to pretend every trap looks the same. Some setups are primarily price-structure failures. Others are more about positioning imbalance. The split detector design makes that distinction much clearer.
The Best Part: Walkthrough Mode#
A lot of trading libraries can produce a signal.
Far fewer can explain how they got there.
That is what makes the built-in walkthrough utility especially valuable. It lets you feed the library raw candles, option-chain tuples, previous OI snapshots, and orderbook levels, then prints the formulas and intermediate calculations step by step.
That turns the package into more than just a live monitor. It becomes a debugging and learning tool.
If you want to understand why a breakout was classified as weak, or why a squeeze score fired, walkthrough mode makes the logic inspectable. That is useful for strategy research, threshold tuning, and sanity-checking your assumptions before you trust the detector in a live environment.
For anyone building systematic workflows, that kind of transparency is a real advantage.
Installation#
Install the package from PyPI.
Based on the current package metadata on PyPI, the library targets Python 3.10+ and depends on Nubra SDK 0.3.8 or newer. The current PyPI release is 0.1.0, and the package is positioned as a detector for Indian index derivatives, especially NIFTY and BANKNIFTY.
Authentication and Live Usage#
Like the other focused Nubra libraries, nubra-trap-detector keeps its job narrow.
It does not try to hide SDK authentication behind its own wrapper. Instead, you authenticate with the Nubra SDK and pass the live client into the engine. That keeps login concerns separate from signal logic, which is usually the cleaner design for anyone building real trading tools.
A minimal live flow is to authenticate with Nubra, create the monitoring engine for symbols like NIFTY and BANKNIFTY on a five-minute interval, choose the terminal format you prefer, and then start the live loop.
In this flow, the engine discovers expiries, starts the feed, loads recent candles for context, refreshes the chain snapshot periodically, and emits results at aligned candle boundaries.
That gives you a live monitoring loop without having to write the market-data plumbing yourself.
What the Output Gives You#
The output is one of the more practical parts of the package.
Every evaluation produces a structured result containing the symbol, timestamp, interval, spot price, candle range, price-trap metrics, squeeze-trap metrics, and the final combined trap probability. That means you are not just getting a bull-trap or squeeze label; you are also getting the context that explains it.
For terminal-first workflows, the built-in formatters make this easier to consume. The compact formatter is useful for live monitoring, the table formatter is better for debugging, and the JSON-lines formatter is convenient if you want to pipe the results into logs, dashboards, or your own downstream system.
A callback-driven model also means you can build on top of the detector instead of treating it as an isolated script. You can alert when trap probability crosses a threshold, block entries in a strategy engine, or log the results alongside your own signals.
That flexibility makes the package much more usable in real infrastructure.
Why This Library Is Useful#
What makes nubra-trap-detector interesting is not that it claims to predict reversals perfectly.
Its value is that it gives you a more disciplined way to score whether a move looks fragile.
It combines price confirmation, volume context, chain-wide OI behavior, orderbook thinness, and options crowding into one repeatable framework. That is much stronger than trying to eyeball a breakout and then making a judgment call from a few scattered numbers.
It is also a good example of what focused trading libraries should do well: solve one specific problem, expose the logic cleanly, and remain easy to plug into larger systems.
For traders and developers working with the Nubra SDK, that is exactly the kind of tool that shortens the path from idea to usable workflow.
Final Thoughts#
nubra-trap-detector is best thought of as a market-structure filter, not a magic signal generator.
It helps answer a very practical question:
Is this move gaining real conviction, or is it starting to look like a trap?
By combining live market data with options-chain context, and by offering both real-time callbacks and an explainable walkthrough mode, the library gives you a cleaner framework for monitoring fragile moves in NIFTY and BANKNIFTY.
If you already build with the Nubra SDK and want to bring more structure to breakout quality and squeeze detection, this library is a very solid place to start.