Nexara

Nexara is a private research and signal platform for systematic crypto trading.

The project started as a BTC/USDT 5m signal prototype. It now includes a local research lab, PostgreSQL-backed strategy records, Telegram alert plumbing, worker heartbeat tracking, and BTC/ETH spread backtesting from public historical candles.

The goal is not to make a beautiful trading dashboard first. The goal is to prove whether a signal has enough edge after execution costs, then only promote it toward paper trading when the evidence is strong enough.

Current Status

Working locally:

• monorepo foundation with apps/web, apps/api, apps/worker, and shared packages
• PostgreSQL through Docker Compose
• Prisma schema for signals, alerts, candles, worker heartbeats, and backtest runs
• Fastify API for dashboard data and research actions
• Next.js dashboard with Dashboard and Strategy Lab pages
• Telegram notification test flow
• BTC/USDT 5m live/research baseline
• Binance public monthly candle importer
• BTC/ETH spread candle derivation
• BTC/ETH spread 4h div006 backtest records
• Strategy Lab detail pages for individual research runs
• date-bounded spread refreshes so yearly/YTD evidence does not mix windows

Current research conclusion:

• BTC/USDT 5m remains useful as the baseline strategy and live-signal learning path.
• BTC/ETH spread 4h div006 showed strong 2025 evidence, but 2026 YTD currently has too few signals to trust.
• The next research-system improvement is venue-aware cost scoring. 31 bps is a conservative stress/default level, not the only realistic execution assumption.

Product Priority

1. data quality
2. strategy quality
3. execution-cost realism
4. alert quality
5. reliability
6. dashboard polish

MVP Scope

Included in the first production version:

• spot market monitoring
• BTC/USDT 5m baseline workflow
• BTC/ETH spread 4h research workflow
• research mode for backtesting and parameter testing
• fee, spread, and slippage awareness
• PostgreSQL persistence
• Telegram signal alerts
• worker heartbeat and basic monitoring
• private dashboard and Strategy Lab
• Docker-based deployment path
• GitHub Actions CI/CD path

Not included in the first version:

• automated trading
• futures trading
• billing
• mobile app
• public SaaS access
• multi-user account management
• live order execution
• paper trading before venue-aware gates exist

Architecture

GitHub
  -> GitHub Actions
  -> VPS later
  -> Docker Compose
      - web
      - api
      - worker
      - postgres

Market data
  -> exchange/archive adapter
  -> worker or research importer
  -> PostgreSQL
      - API
      - Strategy Lab
      - Telegram alerts

Tech Stack

• Frontend: Next.js, TypeScript
• API: Node.js, Fastify, TypeScript, Zod
• Worker: Node.js, TypeScript, CCXT
• Research: TypeScript, shared strategy contracts, historical candles
• Database: PostgreSQL, Prisma ORM
• Infrastructure: Docker Compose, Nginx, Cloudflare, Hetzner VPS
• Notifications: Telegram Bot API
• CI/CD: GitHub Actions

Research Rules

• Worker code must use generic exchange interfaces, not exchange-specific calls directly.
• Backtests must record the date window, data source, candle count, strategy parameters, and cost assumptions.
• Failed strategies stay recorded. A rejected strategy with a known reason is useful evidence.
• Gross edge and net edge are different. Gross edge proves signal quality; net edge proves whether execution can capture it.
• 31 bps should be treated as a conservative stress/default cost level. It should not be treated as the only valid fee model.
• Strategy classification should move toward per-venue scoring: a strategy can be rejected on Kraken taker economics and still be interesting under low-cost maker execution.
• Paper trading comes before any live execution.

Repository Layout

nexara/
├── apps/
│   ├── web/
│   ├── api/
│   └── worker/
├── packages/
│   ├── shared/
│   ├── db/
│   ├── exchanges/
│   ├── indicators/
│   ├── strategies/
│   └── research/
├── research-log/
│   ├── README.md
│   ├── methodology.md
│   ├── strategies/
│   └── experiments/
├── infrastructure/
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
└── roadmap.md

Local Development

Expected local tools:

• Node.js
• pnpm through Corepack
• Docker Desktop

Common commands:

corepack pnpm install
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build

Start local PostgreSQL:

corepack pnpm db:up
corepack pnpm db:generate
corepack pnpm db:migrate
corepack pnpm db:seed

Run the local API:

corepack pnpm api:dev

Run the local dashboard:

corepack pnpm web:dev

Run one worker cycle:

corepack pnpm worker:once

Research Commands

Run a live Kraken BTC/USDT 5m evaluation:

corepack pnpm research:live:btc-usdt-5m

Run a BTC/USDT 5m backtest:

corepack pnpm research:backtest:btc-usdt-5m

Run database-backed BTC/USDT research:

corepack pnpm research:backtest-db:btc-usdt-5m
corepack pnpm research:sweep-db:btc-usdt-5m

Import Binance public monthly candles:

$env:NEXARA_BINANCE_KLINE_TIMEFRAME="5m"
$env:NEXARA_BINANCE_KLINE_START_MONTH="2025-01"
$env:NEXARA_BINANCE_KLINE_END_MONTH="2025-12"
corepack pnpm research:import-binance-monthly-klines

Run the BTC/ETH spread research pipeline:

$env:NEXARA_BINANCE_KLINE_START_MONTH="2025-01"
$env:NEXARA_BINANCE_KLINE_END_MONTH="2025-12"
$env:NEXARA_BACKTEST_LIMIT="2190"
corepack pnpm research:refresh-spread:btc-eth

Run 2026 YTD BTC/ETH spread evidence:

$env:NEXARA_BINANCE_KLINE_START_MONTH="2026-01"
$env:NEXARA_BINANCE_KLINE_END_MONTH="2026-05"
$env:NEXARA_BACKTEST_LIMIT="720"
corepack pnpm research:refresh-spread:btc-eth

The refresh command imports BTC/USDT and ETH/USDT 4h candles, derives BTC/ETH-SPREAD candles, and persists a btc-eth-spread-4h-div006 backtest record. The backtest is bounded to the requested month window.

Telegram

Telegram alerts are sent only for newly created BUY or SELL signals. Set these environment variables locally or in production secrets:

TELEGRAM_BOT_TOKEN="your-bot-token"
TELEGRAM_CHAT_ID="your-chat-id"

For local development, put them in .env.local. The file is ignored by Git.

Test Telegram delivery:

corepack pnpm notifications:test:telegram

Research Log

See research-log/README.md for the permanent v1 research archive. The log records methodology, strategy notes, experiment results, and the reason each strategy is kept, watched, or rejected.

Roadmap

See roadmap.md for the product and engineering roadmap.

Security

Never commit secrets, API keys, exchange credentials, SSH keys, Telegram bot tokens, database passwords, or production environment files. Use environment variables and GitHub secrets for sensitive configuration.