This project provides a robust signal engine for the Tehran Stock Exchange (TSE), offering real-time market data analysis, technical and fundamental scoring, order flow analysis, smart money detection, and manipulation detection. It is designed to assist traders and analysts in making informed decisions by providing comprehensive insights into stock behavior.
tehran-stock-exchange-buysell-engine/
├── main.py # Entry point for the FastAPI application (uvicorn)
├── api.py # Defines FastAPI endpoints and handles CORS
├── requirements.txt # Python dependencies
├── cache.py # In-memory cache with TTL for data optimization
├── fetcher.py # Data fetching module from TSETMC
├── scorer.py # Core scoring engine for technical, fundamental, and other metrics
├── tse-live-dashboard.jsx # React dashboard component (Artifact for Claude Artifact)
├── .gitignore # Specifies intentionally untracked files to ignore
└── LICENSE # MIT License for the project
- Real-time Data Fetching: Integrates with TSETMC to retrieve up-to-date stock and market data.
- Comprehensive Scoring: Provides a 5000-point scoring system covering:
- Technical Analysis: RSI, MACD, Moving Averages, Support/Resistance, Breakout detection.
- Fundamental Analysis: EPS, P/E ratios.
- Order Flow Analysis: Buyer/seller power, real/legal inflow/outflow.
- Smart Money Detection: Identifies accumulation/distribution phases and smart money movements.
- Manipulation Detection: Flags suspicious activities like pump-and-dump, fake volume, and spoofing.
- Growth Probability: Calculates short-term and mid-term growth probabilities.
- Actionable Signals: Generates clear buy, hold, or sell signals based on aggregated scores.
- FastAPI Backend: Provides a high-performance, asynchronous API for data access.
- React Dashboard Component: A JSX artifact for visualizing live data and signals.
Ensure you have Python 3.10+ installed.
cd tse-signal-engine
pip install -r requirements.txtuvicorn main:app --reload --port 8000The server will be accessible at http://localhost:8000. Automated API documentation is available at http://localhost:8000/docs.
Use curl to test the API endpoints:
# Health check
curl http://localhost:8000/
# Data for a single symbol (e.g., فولاد)
curl http://localhost:8000/api/stock/فولاد
# Data for multiple symbols concurrently
curl "http://localhost:8000/api/stocks?symbols=فولاد,فملی,شبندر"
# Market index
curl http://localhost:8000/api/market
# Search for a symbol
curl "http://localhost:8000/api/search?q=فولاد"
# Top screener filter
curl "http://localhost:8000/api/screener?mode=top"
# Manipulation detection screener
curl "http://localhost:8000/api/screener?mode=manipulation"The tse-live-dashboard.jsx file located in the tse-signal-engine directory is a React component designed to be used with Claude Artifact or similar environments. Ensure the Python server is running on port 8000 for the dashboard to fetch data.
The following table summarizes the available API endpoints:
| Method | Path | Description (توضیح) |
|---|---|---|
| GET | / |
Health check |
| GET | /api/stock/{symbol} |
Full data for a single stock symbol (داده کامل یک نماد) |
| GET | /api/stocks?symbols=... |
Data for multiple stock symbols in parallel (داده چند نماد موازی) |
| GET | /api/market |
Overall market index + macro data (شاخص کل + ماکرو) |
| GET | /api/search?q=... |
Search for stock symbols (جستجوی نماد) |
| GET | /api/history/{symbol}?days=90 |
OHLCV history for a symbol (تاریخچه OHLCV) |
| GET | /api/screener?mode=top |
Top performers screener (فیلتر برترین) |
| GET | /api/screener?mode=smart_money |
Smart money inflow screener (ورود پول هوشمند) |
| GET | /api/screener?mode=accumulation |
Accumulation phase screener (فاز انباشت) |
| GET | /api/screener?mode=manipulation |
Suspicious manipulation screener (دستکاری مشکوک) |
| POST | /api/cache/clear |
Clear in-memory cache (پاکسازی کش) |
| GET | /api/cache/stats |
Cache statistics (وضعیت کش) |
{
"symbol": "فولاد",
"name": "فولاد مبارکه اصفهان",
"sector": "فلزات",
"price": 7840,
"yesterday": 7591,
"change": 3.28,
"volume": 1820000000,
"eps": 930,
"pe": 8.4,
"technical": {
"rsi": 62.4,
"macd": 180.2,
"ma50": 7200,
"ma100": 6800,
"support": 7100,
"resist": 8200,
"breakout": false,
"trend": "UP",
"score": 1120
},
"orderflow": {
"buyer_power": 72.0,
"buy_per_share": 18200000,
"sell_per_share": 12100000,
"buy_ratio": 1.51,
"real_inflow": 42000000000,
"legal_inflow": -8000000000,
"real_buy_count": 420,
"real_sell_count": 280,
"abnormal_vol": false,
"score": 750
},
"smart_money": {
"phase": "ACCUMULATION",
"smart_money": true,
"break_valid": false,
"distribution": false,
"smart_score": 640,
"phase_score": 330
},
"manipulation": {
"pump_dump": false,
"fake_vol": false,
"spoofing": false,
"price_manip": false,
"manip_score": 0,
"danger_level": "پایین"
},
"growth": {
"short_term": 68,
"mid_term": 54,
"break_prob": 42
},
"scores": {
"technical": 1120,
"fundamental": 650,
"orderflow": 750,
"smart_money": 640,
"phase": 330,
"manip_penalty": 0,
"total": 3490
},
"signal": {
"label": "نگهداری",
"en": "HOLD",
"color": "#F5A623",
"icon": "◆"
}
}| Source (منبع) | Data (داده) |
|---|---|
tsetmc.com/api/Instrument/GetInstrumentStaticData |
Real-time price, EPS, P/E (قیمت لحظهای، EPS، P/E) |
tsetmc.com/api/Trading/TradeByOrderType |
Retail/Institutional trades (حقیقی/حقوقی) |
tsetmc.com/api/ClosingPrice/GetClosingPriceHistory |
OHLCV history (تاریخچه OHLCV) |
tsetmc.com/api/Index/GetIndexB2Lastday |
Overall market index (شاخص کل) |
tsetmc.com/tsev2/data/search.aspx |
Symbol search (جستجوی نماد) |
- Cache: Real-time data is cached for 20 seconds, and historical data for 5 minutes.
- CORS: Fully open for development; restrict in production environments.
- Rate Limit: Automatic delays are implemented between requests to TSETMC.
- Fallback: An older endpoint is attempted if the primary API fails.
This project is closely related to the tse-alpha-agent skill, which is a comprehensive AI agent for the Tehran Stock Exchange. The tse-alpha-agent leverages models like Alpha Predictor and Liquidity Cycle, providing deep financial analysis, including real-time market data from TSETMC, financial reports from Codal, macro-economic indicators (M2, CPI, USD/IRR), and commodity prices. It features tools for alpha prediction, technical and fundamental analysis, risk assessment, and portfolio optimization, specifically tailored for the Iranian market context.
This tse-signal-engine can serve as a foundational component or a data provider for more advanced agents like tse-alpha-agent.
This project is licensed under the MIT License - see the LICENSE file for details.