Sammy — Multi-Exchange Trading Bot Platform
A production-grade, self-hosted spot trading bot platform built as a Turborepo monorepo: a web dashboard to configure and run automated post-only limit-order bots across multiple exchanges, a rule-based "Brain" service that recalculates buy/sell price bands, and a per-exchange API/bot architecture designed so a new exchange integration is a drop-in scaffold.
What it does
- Multi-platform bot dashboard — a tab per enabled exchange (Hyperliquid, Binance, Alpaca, Gate, Polymarket), each listing saved asset presets. Users create/edit a preset (buy price, sell price, % of balance to trade), Play to launch the Python bot, and Stop to cancel resting orders — no code changes needed to add a new tradable asset.
- Live market data & account view — real-time price, price change, order book, open orders, fills, balance and performance pulled straight from each exchange's public/authenticated API, rendered with a candlestick chart.
- Automated order execution — a Python bot per exchange polls the market and places post-only limit orders (maker-only, no slippage), buying below and selling above the configured band, sized as a percentage of available balance.
- Brain — automated strategy assistant — a cross-cutting background service that analyzes an asset's recent price history (OLS trend slope + Bollinger band width) to detect range-bound ("sideways") markets and propose a new buy/sell band. Recalculation is fully automatic (on a configurable weekly schedule or on demand) but applying a suggestion is always an explicit human "Accept" click — the system never trades on a suggestion unsupervised.
- Zero-database design — no database at all. All state is plain JSON on
disk per platform (
bot-config.json, saved presets), keeping the deployment footprint tiny and the source of truth trivially inspectable.
Architecture
Turborepo + pnpm workspaces, apps grouped per exchange so new venues can be added side by side without touching existing ones, sharing one web frontend and one typed contract:
| Package | Role |
|---|---|
apps/web |
Next.js 16 / React 19 dashboard, shared across every platform |
apps/<exchange>/api |
NestJS 11 API per exchange (Hyperliquid, Binance, Alpaca, Gate, Polymarket) — reads market data, manages bot presets, launches the bot |
apps/<exchange>/bot |
Python execution engine per exchange — polls the market, places post-only limit orders |
apps/brain/api |
NestJS orchestration service — schedules and runs price-band recalculation across all enabled platforms |
apps/brain/model |
Python — deterministic technical-analysis engine (trend + volatility) spawned per recalculation |
packages/contracts |
Shared TypeScript contract (Market, BotConfig, Performance, …) consumed by web and every exchange's API, so adding an exchange means implementing one adapter surface |
Tech stack
- Monorepo — Turborepo, pnpm workspaces
- Frontend — Next.js 16, React 19, CSS Modules
- Backend — NestJS 11, class-validator DTOs, Swagger docs
- Execution engine — Python (frozen dataclasses, type hints), exchange SDK/HTTP integrations, systemd-managed long-running processes
- Deployment — native systemd services (no Docker) via a single deploy script, self-healing on reboot, running on a Raspberry/Orange Pi on the LAN
Highlights
- Exchange-agnostic contract: adding a new exchange is a scaffolded
api/botpair implementing one adapter interface — the web dashboard and Brain strategy engine need zero changes. - Safety-first execution: maker-only order placement, single-active-bot-per- platform invariant, and an automated advisory layer (Brain) that is architecturally incapable of placing a trade without human confirmation.
- Config-as-state: the entire runtime state of every bot is a human-readable JSON file, self-seeding on first run and resumable across reboots with no manual intervention.
- Deployment automation that provisions per-platform Python virtualenvs, builds each Next.js/NestJS app, and installs/updates systemd units end-to-end from a single script.