Order-state alerts

Pre-trade covers the order a client is about to place. Order-state alerts cover orders and positions that already exist — a resting stop that's about to trigger, an open position with no stop-loss, a position drifting into auto-square-off, adding to a loser. You push these events from your OMS; we score them with the same engine and hand back warnings to render.

You push each order-state event from your OMS; we score it and return the verdict synchronously for you to render. TradLyt never polls your order book.

---

Push an event

POST /order-event

Authenticated by your subscription key, like every SDK call. The verdict comes back in the response — render it directly.

Request body

Field	Type	Required	Description
user_ref	string	✅	The client, by your own identifier.
type	enum	✅	The event — see below.
subject	object		The order the event is about (an OrderRef).
change	object		Before/after values, for type: "modified".
snapshot	object		Current positions + session + last prices. If omitted, we derive a minimal session from synced trades.

type is one of:

Value	Meaning
placed	A new resting order appeared.
imminent	A resting order is about to fill (LTP within a band of its trigger).
modified	A resting order's limit/trigger price or quantity changed.
cancelled	The client pulled a resting order.
filled	A resting order executed.
square_off_pending	An open MIS position is nearing auto-square-off with no exit queued.
snapshot	A periodic full order-state push (when you can't emit discrete events).

subject (OrderRef) — the order the event concerns:

Field	Type	Notes
instrument	string	Trading symbol (required).
side	enum	BUY / SELL.
quantity	number	Units.
variety	enum	LIMIT / SL / SL_M / MARKET / GTT / AMO.
trigger_price	number	SL / GTT trigger, if any.
limit_price	number	Limit price, if any.
product	string	MIS / CNC / NRML.
leg_type	enum	ENTRY / STOP / TARGET / UNKNOWN — a known bracket/cover leg role.
broker_order_id	string	Your order id (used for dedup).
security_id	string	Broker numeric id (e.g. Dhan) — we resolve it to a symbol.

snapshot — the current picture (all fields optional; send what you have):

Field	Type	Notes
positions[]	array	Open positions: instrument, net_qty (signed), avg_price, unrealised_pnl, product, is_holding.
pending_orders[]	array	Other resting orders (OrderRefs) — lets us see if a stop already covers a position.
ltp	object	{ "SYMBOL": last_price } — powers the distance-to-trigger checks.
session	object	trades_today, session_pnl, loss_streak, … (same fields as pre-trade's session_context).
available_margin	number	For over-exposure checks.

{
  "user_ref": "me",
  "type": "snapshot",
  "snapshot": {
    "positions": [
      { "instrument": "TCS", "net_qty": 150, "avg_price": 3900, "unrealised_pnl": -5200, "product": "MIS" }
    ],
    "pending_orders": [],
    "ltp": { "TCS": 3865 },
    "session": { "trades_today": 4, "session_pnl": -5200, "loss_streak": 2 }
  }
}

Response

An OrderScenarioVerdict — the same severity vocabulary as pre-trade.

{
  "user_ref": "me",
  "risk_level": "WARNING",
  "recommendation": "review",
  "friction": "nudge",
  "tilt_score": 0.42,
  "results": [
    {
      "scenario_id": "missing_sl",
      "severity": "warning",
      "message": "150 TCS open with no stop-loss and ₹5,200 unrealised loss.",
      "recommendation": "review",
      "instrument": "TCS"
    }
  ]
}

Field	Type	Description
risk_level	enum	OK / WARNING / CRITICAL.
recommendation	enum	proceed / review / cancel / exit / hold.
friction	string	UX hint: silent / nudge / hard_warning.
tilt_score	float	0–1 composite of how "tilted" the session looks — escalates severity.
results[]	array	The fired scenarios. Each has scenario_id, severity, a human-readable message, a recommendation, and instrument. Render these.

The scenario_id + message are self-describing (e.g. a position with no stop, a resting order about to trigger, averaging into a loser, an open position nearing square-off). An empty results[] with risk_level: OK means nothing fired.

---

Feeding the engine

You don't need to give us a broker session — you push the events, so we never poll your OMS. Send a snapshot on a cadence (e.g. per minute during market hours) plus discrete events (imminent, modified, square_off_pending) when you can detect them.

Fail open

Order-state alerts are decision-support. If TradLyt is unreachable, carry on — never block or delay a client's order flow on our availability.