Trading API — Flowchart & Freelancer Brief > Purpose: A single-page brief + flowchart to hand to a freelancer to build a real-time Indian equities trading API + algo BOT targeting 2%–10% intraday moves with high-confidence selective signals. --- 1. One-line summary Build a millisecond-capable system that ingests market tick & depth, scores high-confidence momentum signals (confidence ≥ 0.85), executes fixed-amount trades automatically with SL/target/OCO logic, logs everything for audit, and exposes REST + WebSocket APIs for control, monitoring, and backtesting. --- 2. High-level flowchart (text + diagram) [DATA PROVIDERS] --> [INGESTION LAYER] --> [FEATURE ENGINE] --> [DECISION ENGINE] --> [EXECUTION ENGINE] --> [BROKER] | | | | v v v v [STORAGE] [MODEL SERVING] [ORDER DB] [EXTERNAL MONITORING] | | | | v v v v [BACKTEST / REPLAY] [WEBSOCKET OUT] [AUDIT LOGS] [DASHBOARD / ALERTS] Flow description: 1. Data Providers: TrueData / vendor tick feed, broker websocket (Kite/Upstox), news feed, options/derivatives feed. 2. Ingestion Layer: Normalize feeds, validate, sequence ticks; publish events to internal stream (Kafka/Redis). 3. Feature Engine: Rolling aggregates (VWAP, ATR, depth sums, order-flow metrics) per-symbol in-memory. 4. Decision Engine: Rule + ML scoring; requires at least 2 confirming triggers and confidence >= 0.85 to emit signal. 5. Execution Engine: Places entry order, on-fill places SL and target (OCO), monitors fills, adjusts if needed. 6. Broker: Live/paper execution via Zerodha/Upstox adapter. 7. Storage & Backtest: ClickHouse / Timescale storage for ticks; tick replay for backtesting. 8. Monitoring & Dashboard: P&L, latency, model metrics, alerts, manual kill-switch. --- 3. Component responsibilities (brief) Ingestion Layer: websockets, sequencing, heartbeat, reconnects, de-dup. Stream Bus: Kafka/Redis Streams for events and durability. Feature Engine: 100–500ms rolling windows, precomputed features for Decision Engine. Decision Engine: Lightweight service (Python/Go). Outputs Signal objects. Model Server: LightGBM/XGBoost model serving (low-latency), calibration. Execution Engine: Broker adapters, OCO logic, retry/fill logic, slippage model in sim. Storage: Time-series DB + OLAP store for archives. API Layer: REST (config/backtest/admin) + WS (realtime ticks/signals/orders). Dashboard: Grafana/React showing health, P&L, signals, trades. --- 4. Sequence of a trade (step-by-step) 1. Tick arrives → Ingestion normalizes and publishes. 2. Feature Engine updates rolling stats for symbol. 3. Decision Engine computes features and model score. 4. If score >= 0.85 AND >=2 triggers: create Signal and publish to WS. 5. Strategy checks auto-execute policy → Execution Engine places entry (limit/IOC). 6. On entry fill: place SL and target (OCO) and register trade in DB. 7. Monitor orderbook & trades; if adverse flow detected, close or tighten SL. 8. When target or SL hit or timeout reached, close trade and log result. 9. Post-trade: log features, raw ticks, outcome for model retraining. --- 5. API & WebSocket topics (concise) REST highlights POST /strategy (create strategy) GET /signals (recent signals) POST /orders (place manual order) POST /backtest (start backtest) GET /audit/logs WebSocket topics tick:<SYM> — trade events depth:<SYM> — depth updates signals — emitted signals orders — order state changes alerts — system alerts --- 6. Signal JSON (fields freelancer must include) signal_id, symbol, timestamp strategy_id, type (buy/sell), confidence (0..1) entry_hint (price, order_type), qty, target_pct, stop_loss_pct features (order_flow_score, depth_imbalance, volume_spike, vwap_distance, atr) reason (short human-readable explanation) --- 7. Trigger logic (must implement) At least two confirmatory triggers within trigger_window_seconds (default 120s): Buy Sweep: repeated market buys consuming asks (count >= N within window). Depth Imbalance: top-5 bids sum / top-5 asks sum > threshold (e.g., 1.6). Volume Spike: 1-min volume > 3× 5-min avg. VWAP Breakout: price crosses above intraday VWAP with positive order_flow. News Spike: high positive sentiment + volume change. --- 8. Execution & Order life-cycle rules Entry: limit preferred; small market component allowed for urgent sweeps. On-fill: place OCO (SL + target). SL mode: market SL when liquidity low; limit SL when stable. Partial take: 50% at 50% of target, remaining trailed. Timeout: if position open > trade_timeout_seconds (default 3600s) without target/SL hit, re-evaluate and possibly close. --- 9. Backtest & acceptance tests for freelancer (copy-paste) Paid test task (small) Implement buy_signal_detector that emits signal when: last 30s market buy volume > 3× last 5min avg AND (sum_top5_bids / sum_top5_asks) >= 1.6 Provide a tick-replay script to run detector on 1 week sample and output detected signals + simulated trade results (simulate 2% target, 0.8% SL). Acceptance for M2 Backtest on provided 3-month tick set and deliver: total trades, win-rate, avg pnl, max drawdown, P&L curve. Provide code + unit tests for detector. --- 10. Deliverables & milestones (precise) Milestone 1 (Prototype): Ingestion + WS streaming for ticks of 10 symbols; REST /universe; simple dashboard. Milestone 2 (Signals & Backtest): Feature engine + 2 triggers + backtest results and detector unit tests. Milestone 3 (Execution): Execution adapter (paper) + full trade lifecycle + audit logs. Milestone 4 (Hardening): Dockerized apps, monitoring, README, OpenAPI docs, 1 month paper run support. --- 11. Non-functional requirements & constraints Latency: decision latency target <= 300ms from tick ingestion to signal (initial). Scalability: support 200+ symbols streaming concurrently. Reliability: auto reconnects, at-least-once event processing, idempotent order placement. Security: TLS, HMAC signed order API, role-based access for admin endpoints. --- 12. Testing dataset & tools (use these tactics) Use historical tick + L2 depth if available. If not, synthesize depth by interpolating snapshots. Use realistic slippage: base 0.03% + impact factor (order_size / ADV). Tools: Python (asyncio), Docker, ClickHouse, LightGBM for model prototypes. --- 13. Handover checklist to include Docker images + Helm/K8s manifest OpenAPI spec + WS topic docs Sample env file with mock credentials Unit tests and a small data sample for verification Operation runbook (start/stop/restart, kill-switch) --- 14. Communication & reporting template for freelancer Every 3 days provide: Progress update (what's done, blockers) Demo link (screenshots/video or live staging) Next 3-day plan Any data/vendor procurement needed (list exact feeds & contracts) --- 15. Final note to freelancer (paste into job) "Implement the ingestion → feature → decision → execution pipeline as described. Start with a small, well-tested prototype and move iteratively: ingestion → two-trigger signal → backtest → execution. Provide reproducible tests and a 1-week paper-run before live. Pay attention to auditability: every decision and raw tick must be logged for post-trade analysis."