JuiceGram

JuiceGram is a Telegram-native BNB Chain trading bot with an encrypted, Trojan-style Bot Wallet and isolated on-chain Credit. Wallet creation, deposits, withdrawals, private-key export, token scanning, Spot Buy/Sell, Credit orders, position management, confirmations, signing, and transaction submission all happen inside the Telegram chat.

The optional Mini App is a separate read-only market radar. It can search public BNB DEX markets, render free OHLCV charts, and display the on-chain Credit allowlist. It contains no browser wallet SDK, wallet connection, signature request, quote execution, or transaction endpoint.

Product boundary

• TELEGRAM_WATCH_APP_ENABLED=false is the default and produces a strict pure bot with Telegram's normal command menu.
• Setting it to true exposes the read-only chart Mini App as an optional menu button. Trading still remains Bot-only.
• Telegram's published exemption applies explicitly to regular bots without a Mini App. A read-only non-TON market page should not be assumed compliant without written Telegram guidance; keep the flag off for the strictest mode.
• Permissionless Spot accepts arbitrary BEP-20 contracts with an executable PancakeSwap route. Credit remains restricted to governance-enabled markets with a fresh independent oracle.

Implemented flows

• Telegram webhook secret verification, update idempotency, private-chat enforcement, commands, inline keyboards, expiring conversations, and one-time atomic action confirmation.
• Per-user BNB Testnet Bot Wallet creation with AES-256-GCM authenticated encryption, address/key integrity checks, and serialized nonce execution.
• Native Bot menu for Buy, Sell, Credit Boost, Positions, Wallet, Token Scanner, and Risk Shield.
• Buy amount presets, Sell percentage presets, custom amounts, server-side routing, re-quotation, contract simulation, confirmation waiting, and transaction links.
• Permissionless Spot routing through the best quoted PancakeSwap V2/V3 direct/WBNB route using only the user's Bot Wallet balance.
• Isolated Credit positions backed by CreditVault, with governed leverage, market caps, origination fees, oracle freshness, slippage limits, automatic debt accrual, close, and liquidation.
• Free cached market search via DEX Screener and GeckoTerminal OHLCV candles. No paid market-data key or browser RPC is required.
• A watch-only API that returns public protocol liquidity and Credit allowlist data without creating or loading a user wallet.
• Separate keeper and group-executor processes with durable cursors, adaptive log ranges, Multicall reads, simulations, and signer isolation.
• Mainnet launch gates for audit evidence, bug bounty, legal review, governance, testnet rehearsal, and redundant keepers.

Trust and production warning

This repository contains real contracts, signing, routing, oracle, keeper, and database logic. It is not a declaration that unrestricted mainnet custody is safe. The current local-aes signer is deliberately restricted to chain 97. Chain 56 requires an independently reviewed, non-exportable KMS/HSM signer, external audits, operational controls, market stress testing, and legal review.

Lender principal is not guaranteed. Price gaps, malicious token behavior, vanishing liquidity, oracle failure, chain congestion, compromised governance, and contract defects can create bad debt.

Repository map

contracts/
  CreditVault.sol
  IsolatedMarginManager.sol
  SocialGroupBuy.sol
  oracle/
src/
  client/                 read-only market and chart terminal
  server/                 Telegram bot, Bot Wallet, API, database, market data
  keeper/                 liquidation event indexer and executor
  group-executor/         aggregate private-RPC swap worker
scripts/
  deploy-contracts.ts
  configure-market.ts
  set-telegram-webhook.ts
docs/
  ARCHITECTURE.md
  SECURITY.md
  OPERATIONS.md
  RAILWAY_TELEGRAM.md

Local development

Requirements:

• Node.js 22.13 or newer
• PostgreSQL 15 or newer
• a BNB Chain RPC endpoint
• a 32-byte BOT_WALLET_MASTER_KEY for chain-97 Bot Wallet testing

cp .env.example .env
npm install
npm run dev

Set ALLOW_DEVELOPMENT_AUTH=true only for local browser testing. Production ignores that bypass.

Quality gates:

npm run check
npm test
npm run build

BNB Testnet deployment

npm run contracts:deploy:testnet
npm run oracle:configure:testnet
npm run contracts:market:testnet
npm run group:market:testnet
npm run deployment:verify:testnet

After the API has a public HTTPS domain:

npm run bot:set-webhook
npm run keeper
npm run group-executor

Run the API, PostgreSQL, keepers, and group executor as isolated services. Never place deployer, keeper, or group-executor keys in the API service.

For Railway variables, strict pure-bot setup, and optional watch-only setup, see Railway and Telegram Testnet Deployment.