117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# SoftTrader Backend
|
||
|
||
A .NET 10 Web API backend for a lite Bloomberg-style terminal. Provides live and historical equity data via Interactive Brokers, AI-driven news sentiment analysis using FinBERT, configurable price alerts, and supporting services like weather and chart annotations.
|
||
|
||
## Prerequisites
|
||
|
||
- [.NET 10 SDK](https://dotnet.microsoft.com/download)
|
||
- [PostgreSQL](https://www.postgresql.org/)
|
||
- [Interactive Brokers Gateway](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) running on `127.0.0.1:4002`
|
||
- FinBERT ONNX model files in `AIModels/finbert/` (`model.onnx`, `vocab.txt`, tokenizer configs)
|
||
|
||
## Getting Started
|
||
|
||
1. **Configure the database** — update the connection string in `appsettings.json`:
|
||
```json
|
||
"ConnectionStrings": {
|
||
"MarketDataDb": "Host=127.0.0.1;Port=5432;Database=softtraderbackend_pricedata;Username=postgres;Password=<your-password>"
|
||
}
|
||
```
|
||
|
||
2. **Start IB Gateway** — the application connects on startup and will exit if the connection fails.
|
||
|
||
3. **Run the application:**
|
||
```bash
|
||
dotnet run
|
||
```
|
||
The API starts on `http://localhost:5000` by default.
|
||
|
||
4. **Swagger UI** is available at `/swagger` for interactive API exploration (no API key required).
|
||
|
||
## Authentication
|
||
|
||
All API endpoints (except Swagger) require an API key via the `X-Api-Key` header. Keys are validated against PostgreSQL.
|
||
|
||
## API Endpoints
|
||
|
||
### Market Data — `/api/market`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| GET | `/live/{symbol}` | Live quote from IB Gateway |
|
||
| GET | `/historical` | Historical OHLCV bars (configurable duration, bar size, data type) |
|
||
| GET | `/historical-line` | Historical line data |
|
||
| GET | `/symbol-check/{symbol}` | Validate a ticker symbol |
|
||
| GET | `/last-trading-day` | Last trading day for a symbol |
|
||
|
||
### News Sentiment — `/api/news-sentiment`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| GET | `/` | Analyze sentiment for a keyword (fetches Google News RSS, scores with FinBERT) |
|
||
| GET | `/feed` | Personalized news feed based on user interests |
|
||
| GET | `/refresh` | Refresh sentiment data for all of a user's tracked symbols/topics |
|
||
|
||
### Alerts — `/api/alerts`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| POST | `/create` | Create a price alert |
|
||
| GET | `/list` | List all alerts for a user |
|
||
| GET | `/triggered` | List triggered alerts for a user |
|
||
| DELETE | `/delete` | Delete an alert |
|
||
|
||
**Alert types:** `price_threshold`, `percent_change`, `price_spike`, `trailing_price`
|
||
|
||
Alerts are evaluated by a background service every minute during market hours (Mon–Fri, 6 AM – 2 PM Pacific).
|
||
|
||
### User Interests — `/api/user-interest`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| GET | `/fetch` | Get a user's tracked symbols or topics |
|
||
| POST | `/add` | Add a symbol or topic |
|
||
| DELETE | `/remove` | Remove a symbol or topic |
|
||
|
||
### Annotations — `/api/annotations`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| GET | `/fetch` | Get saved chart annotations for a user/symbol |
|
||
| POST | `/save` | Save chart annotations |
|
||
| DELETE | `/delete` | Delete chart annotations |
|
||
|
||
### Weather — `/api/weather`
|
||
|
||
| Method | Route | Description |
|
||
|--------|-------|-------------|
|
||
| PUT | `/set-location` | Set a user's city (geocoded) |
|
||
| GET | `/current` | Get current weather for a user's saved location |
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Backend/
|
||
├── Controller/ # REST API controllers
|
||
├── ServiceHandler/ # Business logic (market data, news, alerts, weather)
|
||
├── DatabaseHandler/ # PostgreSQL data access via Npgsql (no ORM)
|
||
├── Interface/ # Store and service abstractions
|
||
├── Middleware/ # API key auth, global exception filter
|
||
├── MarketDataRequest/ # IB Gateway integration and request/response models
|
||
└── AIModels/finbert/ # FinBERT ONNX model and tokenizer files
|
||
```
|
||
|
||
## Background Services
|
||
|
||
- **AlertEvaluationService** — polls active alerts every minute during market hours and evaluates them against live prices
|
||
- **NewsSentimentRefreshService** — periodically refreshes news sentiment data for tracked interests
|
||
|
||
## Dependencies
|
||
|
||
| Package | Purpose |
|
||
|---------|---------|
|
||
| `Microsoft.ML.OnnxRuntime` | FinBERT model inference |
|
||
| `Npgsql` | PostgreSQL driver |
|
||
| `Swashbuckle.AspNetCore` | Swagger / OpenAPI |
|
||
| `twsapi` (project ref) | Interactive Brokers TWS API client |
|