terminal

terminal is a multi-exchange crypto terminal that runs market-maker bots and automated buy/sell strategies to farm future activity points on supported exchanges. Initial exchange targets: Extended, Variational Omni Exchange, Ethereal and Hyperliquid.

What this repo includes

• FastAPI backend with JWT auth and a PostgreSQL database.
• React + TypeScript frontend (Vite).
• Docker Compose stack for local development.
• Mailcatcher for local email testing.
• Traefik proxy for local routing.
• Prometheus + Grafana + Loki observability stack.

Local development

Prerequisites

• Docker + Docker Compose

Start the stack

docker compose up -d

Stop the stack

docker compose down

Logs

docker compose logs -f --tail=200

Service endpoints

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• Backend docs: http://localhost:8000/docs
• Funding API (proxied through backend): http://localhost:8000/api/v1/funding
• Adminer: http://localhost:8080
• Mailcatcher UI: http://localhost:1080
• Traefik dashboard: http://localhost:8090
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3300
• Loki: http://localhost:3100

Configuration

Project-level settings live in .env.

Key fields:

• PROJECT_NAME (used for API title and emails)
• STACK_NAME (Docker Compose labels)
• SECRET_KEY (JWT signing)
• FIRST_SUPERUSER and FIRST_SUPERUSER_PASSWORD
• Postgres settings (POSTGRES_*)
• GRAFANA_ADMIN_USER and GRAFANA_ADMIN_PASSWORD

Observability

The stack includes Prometheus, Grafana, and Loki, preconfigured for backend and mm-bot metrics.

What is provisioned

• Prometheus scrape config for backend /metrics, mm-bot /metrics, and Prometheus self-scrape.
• Loki log storage and Promtail Docker log shipping for backend/mm-bot/funding services.
• Alert rules in observability/prometheus/alerts.yml:
  • BackendDown
  • Api5xxRateHigh
  • ApiP95LatencyHigh
  • ExchangeHealthDown
  • MarketDataSilent
  • MarketDataStale
  • OrderOperationErrorRateHigh
• Grafana datasource provisioning (Prometheus as default).
  • Loki datasource provisioning for log exploration in Grafana.
• Grafana dashboard provisioning:
  • terminal Observability (uid: terminal-observability)

Files

• observability/prometheus/prometheus.yml
• observability/prometheus/alerts.yml
• observability/loki/loki-config.yml
• observability/promtail/promtail-config.yml
• observability/grafana/provisioning/datasources/datasources.yml
• observability/grafana/provisioning/dashboards/dashboards.yml
• observability/grafana/dashboards/terminal-observability.json

Domain model (high level)

• Exchanges: Extended, Variational, Ethereal, Hyperliquid
• Strategies: per-exchange market maker settings (pairs, spreads, limits)
• Bots: execute strategies and emit order intents
• Orders: tracked asynchronously with exchange IDs
• Activity points: ledger of estimated points by exchange

Repo layout

• backend/ FastAPI app and database models
• frontend/ React app
• docker-compose.yml local stack
• development.md and deployment.md ops notes

License

MIT