SmartCell

Personal AI trader. SmartCell is the control plane for autonomous crypto trading — it connects to exchanges, ingests signals from pluggable providers, and executes multi-entry positions with take-profit ladders, stop-loss automation, and full audit history.

The long-term goal: a self-contained trading node that runs on a Raspberry Pi. No cloud dependency, no subscription, no black box. Plug it into any supported exchange, load a signal provider or use the built-in AI strategy, pick your pairs and concurrent-trade limit, and let it run while you check the portfolio from time to time.

┌──────────────────────────────────────────────────────┐
│                     SmartCell                        │
│                                                      │
│   ┌────────────┐   ┌─────────────────────────────┐   │
│   │  Web UI    │   │  REST API  (Node.js/Express) │   │
│   │ React/Vite │──▶│  Risk engine · Position mgr  │   │
│   └────────────┘   │  TP/SL monitor · Audit log   │   │
│                    └──────────────┬──────────────┘   │
└───────────────────────────────────┼──────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
              ▼                     ▼                     ▼
   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
   │ Signal Providers │  │    Exchanges     │  │    Database      │
   │                  │  │                  │  │                  │
   │ • Freqtrade (AI) │  │ • Bitvavo ✓      │  │ MongoDB Atlas    │
   │ • Custom webhook │  │ • More later     │  │ (or local)       │
   │ • Telegram       │  │                  │  │                  │
   │ • AI engine (→)  │  │                  │  │                  │
   └──────────────────┘  └──────────────────┘  └──────────────────┘

Signal providers are loosely coupled — any service that POSTs to /api/providers/{name}/webhook can drive positions. Freqtrade is the built-in AI strategy provider; the interface is open to any other source.

The goal is a single-board device you can configure and forget:

• Hardware: Raspberry Pi + LCD screen + battery pack
• Software: SmartCell (this repo) + optional signal provider, deployed via Docker Compose
• User flow: connect exchange API keys → pick pairs → set concurrent-trade limit → choose signal source (built-in AI or custom strategy) → monitor portfolio on the LCD panel
• Safety: dry-run by default, hard kill-switch for live execution, per-position risk checks that no signal source can bypass

This is a personal trading node, not a SaaS product. One owner, one device, full control.

Bitvavo spot trading with Freqtrade as the signal provider, running as a paper-trade dry run. All features below are working in dry-run; live execution requires explicit opt-in.

Plan a position before touching the exchange. SmartCell stores your full trade plan — entries, take-profit targets, stop-loss — and executes it automatically once you start it.

• Multi-entry ladders — up to N limit or market entry orders per position, each with its own price and size.
• Take-profit ladder — define up to N TP targets with a price and a size percentage. Each TP is submitted as a limit sell automatically when entries fill.
• Stop-loss automation — set a stop price; the monitor fires a market sell of your entire filled position when price reaches it, cancels all pending TPs, and marks the position stopped.
• Partial fill accounting — average entry price and filled base amount update per fill. Unrealized P&L is live on every open position.
• Position lifecycle — planned → entering → open → reducing → closed / stopped.

• Start — submit all planned entry orders to the exchange.
• Edit — update take-profit targets, stop-loss price, or notes on a live position.
• Cancel a pending entry — remove a single unfilled limit order while keeping the rest running.
• Reprice an entry — change the limit price of an unfilled order in-flight.
• Close (partial or full) — sell any percentage (1–100 %) of your filled position as a market order.
• Reconcile — link real exchange fill amounts back to SmartCell entries after a crash or desync.

• Freqtrade — built-in AI strategy (providers/freqtrade/SmartSellBridge.py). Multi-timeframe consensus (5m + 15m + 1h filter), configurable vote threshold. Sends planned_position and close_position webhooks to SmartCell.
• Generic webhook — any service can POST a trade_intent or planned_position payload to the provider endpoint.
• Telegram — ingest raw Telegram signals for manual review before conversion.

• Allowed markets list — editable from Settings, syncs to Freqtrade whitelist automatically.
• Max concurrent Freqtrade positions — configurable cap with live count in Settings.
• Max quote exposure per position (EUR) — hard risk limit.
• Require-dry-run flag — forces simulation until explicitly disabled.
• Global execution mode toggle (dry-run ↔ live) with confirmation gate.

All routes are under http://localhost:4100/api.

corepack pnpm install

cp .env.example apps/api/.env

Edit apps/api/.env and set MONGO_URI to your MongoDB Atlas connection string. Or start a local replica-set via Docker:

docker compose up -d mongodb

Freqtrade paper-trade QA: follow docs/freqtrade-paper-trade-bootstrap.md then docs/freqtrade-paper-trade-runbook.md. The Freqtrade strategy lives at providers/freqtrade/SmartSellBridge.py.

corepack pnpm dev

Web app: http://localhost:5173 · API: http://localhost:4100

corepack pnpm dev                    # API + web in watch mode
corepack pnpm paper-trade:preflight  # API Vitest suite (before smoke / CI)
corepack pnpm paper-trade:smoke      # webhook smoke test
corepack pnpm build                  # production build
corepack pnpm typecheck              # TypeScript across all packages
corepack pnpm test                   # Vitest (shared + api + web)
corepack pnpm lint                   # ESLint
corepack pnpm staging-preflight      # typecheck + lint + format:check
corepack pnpm storybook              # UI kit at http://localhost:6006

• Default execution mode is dry-run. No exchange credentials needed to explore the app.
• The browser never calls the exchange directly. All exchange interaction goes through the SmartCell API.
• Every order request passes deterministic risk checks before any execution adapter sees it. Signal providers cannot bypass them.
• Live execution requires explicit opt-in via the Settings execution mode switch.
• ALLOW_PROVIDER_LIVE=false hard-blocks provider-originated live orders even if execution mode is live.