MarketPulse Intelligence documentation

Overview

MarketPulse monitors 9 instruments across crypto, stablecoins, forex and metals. The scheduler fetches quotes every five minutes, persists them, runs multi-timeframe technical analysis, generates conservative signals, evaluates alerts and queues Telegram notifications. A daily job sends market reports, stores forecast snapshots and applies retention cleanup.

• Market data: Kraken public ticker/OHLC (crypto), Binance fallback, Frankfurter/ECB (forex), Gold-API (XAU spot), DefiLlama (liquidity pools).
• Analysis: EMA/SMA, MACD, ADX, RSI, Stochastic RSI, CCI, ROC, ATR, Bollinger, historical volatility, volume trend, swings, BOS/CHoCH, fair value gaps and liquidity zones.
• Delivery: Telegram Bot API via webhook, Cloudflare Queue, dedupe keys, retries and per-chat rate limits.

Architecture

src/
├── app.ts                 Hono app, middleware, routes
├── index.ts               Worker entry: fetch, scheduled, queue
├── routes/                auth · market · signal · forecast · liquidity · alert · telegram · user · admin
├── services/              market data · analysis · signals · forecast · liquidity · alerts · telegram
├── providers/             kraken · binance · frankfurter · goldapi + registry
├── durable/realtime.ts    MarketRoom Durable Object (WebSocket quotes)
├── scheduled/monitor.ts   market monitor, daily jobs, retention
├── queue/consumer.ts      Telegram delivery consumer
├── middleware/            auth · csrf · security headers
├── repositories/          (reserved; D1 access currently in services)
└── types.ts               Bindings and domain types

Quotes are cached in KV for 60 seconds (KV's minimum TTL) and labelled cached. Provider health is recorded in D1 on failure/transition. MarketRoom pushes a fresh quote to chart subscribers every 15 seconds over WebSocket; the REST API remains the source of truth for history.

Deployment

1. Install dependencies: npm install.
2. Create D1: wrangler d1 create marketpulse-db and copy the database id into wrangler.jsonc.
3. Create KV: wrangler kv namespace create CACHE and copy the id.
4. Create the queue: wrangler queues create marketpulse-notifications (and the DLQ if needed).
5. Apply migrations: npm run db:migrate:remote.
6. Set secrets (see below), then npm run deploy.
7. Register the Telegram webhook from Admin → Configuration or with the Bot API.

npm install
npm run build:css
npm run typecheck
npm run db:migrate:remote
wrangler secret put TELEGRAM_BOT_TOKEN
wrangler secret put TELEGRAM_WEBHOOK_SECRET
wrangler secret put SESSION_SECRET
npm run deploy

Local development: npm run db:migrate then npm run dev. Local D1/KV/Queues state lives under .wrangler/state. The first registered account becomes the super admin.

To test cron handlers locally, run wrangler dev --test-scheduled and call /__scheduled?cron=*/5+*+*+*+*. Queues can be exercised with wrangler dev and a real Telegram token.

Secrets & environment

Telegram setup

1. Create a bot with @BotFather and copy the token.
2. wrangler secret put TELEGRAM_BOT_TOKEN.
3. Generate a random secret and set TELEGRAM_WEBHOOK_SECRET.
4. Deploy, then register the webhook: POST https://<worker>/api/admin/telegram/webhook with {"url":"https://<worker>/api/telegram/webhook"} as a super admin. Or call setWebhook directly with the same secret token.
5. In the dashboard, open Telegram Center → Link Telegram and send the generated /start CODE command to the bot.

Commands: /start, /help, /status, /market, /watchlist, /price, /signal, /trend, /analyze, /forecast, /alerts, /portfolio (explicitly reports that portfolio tracking is unavailable), /lp, /summary, /settings.

API reference

All endpoints return { success, data, meta } or { success: false, error: { code, message, details } }. Session cookie auth plus X-CSRF-Token is required for mutations.

GET  /api/market/overview
GET  /api/market/instruments
GET  /api/market/instruments/:symbol      (encode "/" as %2F)
GET  /api/market/price/:symbol
GET  /api/market/candles/:symbol?timeframe=1h&limit=200
GET  /api/market/analyze/:symbol[?timeframe=4h]
GET  /api/market/trend/:symbol
GET  /api/market/intelligence
GET  /api/market/providers
GET  /api/market/realtime?symbol=BTC%2FUSDT   (WebSocket upgrade)

GET  /api/signals?status=&symbol=&limit=
GET  /api/signals/performance
GET  /api/signals/:id
POST /api/signals/generate/:symbol        (admin)

GET  /api/forecast/:symbol
GET  /api/forecast/:symbol/history

GET  /api/liquidity/pools?search=&sort=&stablecoin=
GET  /api/liquidity/pool/:poolRef
GET  /api/liquidity/risk-check/:poolRef

GET/POST/PUT/DELETE /api/alerts[/:id]
GET  /api/alerts/logs

GET  /api/telegram/status
POST /api/telegram/link
DELETE /api/telegram/link
POST /api/telegram/test
GET  /api/telegram/notifications
POST /api/telegram/webhook                (Telegram secret header)

GET  /api/admin/overview
GET/PATCH /api/admin/users[/:id]
GET/POST /api/admin/providers[/check]
GET  /api/admin/logs
GET/PUT /api/admin/settings
POST /api/admin/telegram/webhook
POST /api/admin/cleanup
POST /api/admin/broadcast
POST /api/admin/notifications/:id/retry

Known limitations

• Forex: ECB reference rates are daily. Intraday forex analysis and signals are not available; forecasts scale daily ATR and label the approximation.
• XAU/USD: the gold spot feed has no historical candles, so technical analysis, signals and forecasts are explicitly unavailable for gold.
• Stablecoins: USDC/USDT and USDT/USD are monitored for peg deviation; directional signals are intentionally not generated.
• Email features: email verification, password reset and email notifications are not implemented because no email provider is configured. The settings UI states this explicitly.
• Weekly report: stored as a preference but not scheduled; only the daily report cron exists.
• Billing: no payment provider is integrated. All workspaces are free during early access.
• KV caching: the eviction/consistency model is eventual; cache is a cost guard, not a hard real-time guarantee. Quotes are labelled cached when served from KV.
• Provider geography: Binance may be unavailable from some Cloudflare locations; the configurable chain falls back to Kraken.

Operations

The Admin console exposes provider health, users, audit logs, notification failures, scheduler health, retention cleanup, Telegram webhook registration and broadcast tools. Permission model:

• member — personal watchlist, alerts, signals, Telegram settings.
• admin — member tools plus provider checks, logs, user suspension, signal generation.
• super_admin — role changes, system configuration, cleanup, webhook registration, broadcasts.

Retention: quotes 14 days, analysis 30 days, signals 90 days, notifications/logs 30 days, expired sessions removed on schedule. These are configurable in Admin → Configuration.

Create a workspace Back to home