🛠 Developer Docs

Deployment guide and API reference for NXTN Bot.

Architecture

Telegram ──▶ grammY Bot (src/bot/)
                ├── Middleware: session, auth, rate-limit, conversations
                ├── Command handlers (src/bot/handlers/command.ts)
                ├── AI Agent (src/agent/) ◀── Claude (Anthropic API)
                │     └── Tool executors (src/agent/executors/*.ts)
                └── Webhook HTTP server (src/bot/webhook.ts)
                      ├── GET /api/console/* — admin dashboard
                      └── GET/POST/PUT/DELETE /api/miniapp/* — mini app

Background workers (BullMQ + Redis):
  ├── tx-confirm.worker  — polls chain for transaction confirmations
  ├── portfolio.worker   — refreshes position values
  ├── arb.worker         — executes arbitrage opportunities
  └── auto-order.worker  — runs DCA / limit / stop-loss orders

Databases:
  ├── PostgreSQL (Prisma) — users, wallets, positions, transactions, orders
  └── Redis — sessions, BullMQ queues, confirmation gates

Quick Deploy (Railway)

# 1. Clone and install git clone https://github.com/minikwave/nxtn && cd nxtn npm install # 2. Set required env vars (see table below) cp .env.example .env && vim .env # 3. Run DB migrations npx prisma migrate deploy # 4. Build and start npm run build && npm start

Environment Variables

TELEGRAM_BOT_TOKENRequiredBot token from @BotFather.
ANTHROPIC_API_KEYRequiredClaude API key for the AI agent.
MASTER_ENCRYPTION_KEYRequired≥64 hex chars. Used for AES-256-GCM wallet key encryption.
DATABASE_URLRequiredPostgreSQL connection string (or SQLite file:./data/nxtn.db for dev).
REDIS_URLOptionalRedis for BullMQ workers and sessions. Default: redis://localhost:6379
BOT_ADMIN_IDSOptionalComma-separated Telegram user IDs with admin access.
TON_RPC_ENDPOINTOptionalTON RPC node. Default: https://toncenter.com/api/v2/jsonRPC
TON_RPC_API_KEYOptionalAPI key for TON Center.
ETH_RPC_URLOptionalEthereum RPC. Default: https://eth.llamarpc.com
BASE_RPC_URLOptionalBase RPC. Default: https://mainnet.base.org
BSC_RPC_URLOptionalBNB Chain RPC. Default: https://bsc-dataseed.binance.org
POLYGON_RPC_URLOptionalPolygon RPC. Default: https://polygon-rpc.com
ARBITRUM_RPC_URLOptionalArbitrum RPC. Default: https://arb1.arbitrum.io/rpc
SOLANA_RPCOptionalSolana RPC. Default: https://api.mainnet-beta.solana.com
COINGECKO_API_KEYOptionalCoinGecko API key for live price feeds.
ONEINCH_API_KEYOptional1inch API key for EVM swap aggregation.
TONCONNECT_MANIFEST_URLOptionalPublicly accessible URL to your tonconnect-manifest.json.
BOT_WEBHOOK_URLOptionalHTTPS URL for Telegram webhook. Leave blank to use long-polling (dev).
BOT_WEBHOOK_SECRETOptionalRandom secret sent in X-Telegram-Bot-Api-Secret-Token header.
CONSOLE_SECRETOptionalProtects /api/console/* endpoints in production.
PAPER_MODEOptionalSet true to simulate all transactions without real funds.
ARB_ENABLEDOptionalEnable arbitrage monitor and vault keeper.
ARB_MIN_SPREAD_BPSOptionalMinimum spread in basis points to flag an opportunity. Default: 30
ARB_MIN_PROFIT_USDOptionalMinimum net profit in USD. Default: 1.0
NEXTON_API_BASE_URLOptionalNexton (third-party ≠ Exton) REST API base. Default: https://d248w8qz2kq46b.cloudfront.net
PORTOptionalHTTP server port. Default: 3000
LOG_LEVELOptionalPino log level (trace/debug/info/warn/error/fatal). Default: info

API Reference

PublicNo auth
TG SecretX-Telegram-Bot-Api-Secret-Token
Adminx-console-secret header (prod)
initDatax-telegram-init-data header
GET/healthPublicLiveness probe. Returns {status, uptime, ts}.
GET/statusPublicFull system status: db, redis, arbMonitor, mode, version.
POST/bot-webhookTG SecretTelegram update delivery (BOT_WEBHOOK_SECRET header).
GET/api/console/statsPublic24h stats: users, positions, txs, failed, PnL, recent txs.
GET/api/console/apysAdminLive protocol APYs (Evaa + static fallbacks).
GET/api/console/streamAdminSSE stream — pushes stats every 5s, heartbeat every 25s.
POST/api/console/chatAdminAI agent chat for console (userId=0). Body: {message}.
GET/api/console/pnl-historyPublic7-day daily PnL buckets.
GET/api/console/announcementsAdminList all announcements (admin).
POST/api/console/announcementsAdminCreate announcement. Body: {title, body, type, expiresAt?}.
DELETE/api/console/announcements/:idAdminDeactivate an announcement.
GET/api/miniapp/portfolioinitDataActive positions for userId.
GET/api/miniapp/walletsinitDataConnected wallets (no secrets).
GET/api/miniapp/balancesinitDataLive on-chain balances (best-effort).
GET/api/miniapp/historyinitDataLast 30 transactions.
GET/api/miniapp/pnl-historyinitDataPortfolio value series + trade notional (not profit).
GET/api/miniapp/alertsinitDataActive price alerts.
POST/api/miniapp/alertsinitDataCreate price alert. Body: {tokenSymbol, targetPrice, direction}.
DELETE/api/miniapp/alerts/:idinitDataCancel a price alert.
GET/api/miniapp/ordersinitDataActive auto-orders (DCA/LIMIT/STOP_LOSS).
DELETE/api/miniapp/orders/:idinitDataCancel an auto-order.
GET/api/miniapp/settingsinitDataUser preferences (slippage, notifications, language).
PUT/api/miniapp/settingsinitDataUpdate user preferences.
GET/api/miniapp/nextoninitDataNexton (3P ≠ Exton) NAV, token rate, and user staking summary.
GET/api/miniapp/announcementsinitDataActive announcements for popup display.
GET/api/partner/v1/statusPublicPartner catalog: Exton+NXTN paper status, Starton onramp, Fragment rail (botAutomatedStarsToTon:false), Star Points.
GET/api/partner/v1/onramp/startonPublicStars→credits→tokens→NXTN guide (Starton credit rail preferred).
GET/api/partner/v1/rail/fragmentPublicFragment self-serve deeplink honesty — not bot FX.
GET/api/partner/v1/surface/combinedPublicExton combined Starton+Fragment+NXTN surface (deduped roles).
GET/api/partner/v1/surface/usablePublicUsable matrix: possible/paper/Human/wont + handoff paths.
GET/api/partner/v1/surface/exton-standalonePublicExton-only honesty — Starton/Fragment not required; NXTN engine required.
GET/api/partner/v1/railsPublicMulti-rail labels: ton | evm-paper (paper stubs).
GET/api/partner/v1/custody/modesPublicDual custody modes (non-custodial default · custodial gated).
GET/api/partner/v1/star-points/protocolPublicStar Points paper protocol (≠ Telegram Stars).

Database Schema

User
telegramId, username, language, isAdmin, isActive
Wallet
userId, chain, address, walletType, encryptedKey, isDefault
Position
userId, protocol, positionType, valueUsd, apy, entryPriceUsd, chain
Transaction
userId, type, status, fromToken, toToken, fromAmount, toAmount, txHash, isPaper
ConversationSession
userId, role (user|assistant), content
PriceAlert
userId, tokenSymbol, coingeckoId, targetPrice, direction (ABOVE|BELOW)
UserSettings
userId, defaultSlippageBps, notifyOnTxConfirm, notifyOnArbExec, language
AutoOrder
userId, type (DCA|LIMIT|STOP_LOSS), status, fromToken, toToken, amountPerRun, intervalHours, triggerPrice
Announcement
title, body, type (INFO|WARNING|UPDATE), isActive, expiresAt