Documentation

Helion is two processes:

• The agent (agent/) — a Node.js engine that ticks every 20 seconds. Each tick it refreshes prices from DexScreener's price API, runs every enabled strategy over every tradable token, filters the signals through the risk manager (and optionally Claude), and executes what survives.
• The console (web/) — this Next.js app. It talks to the agent over a local HTTP API and renders the portfolio, equity curve, markets, and a live feed of every decision.

The console has five views on the same engine: Console (state right now), Performance (is it any good), Activity (what it did, hour by hour), Trades (every execution), and Proof (independent verification straight from the chain).

Execution goes through the KyberSwap aggregator, which routes each swap across BNB Chain DEXes for the best price. In live mode the agent builds the swap transaction, signs it with your local keypair, submits it to mainnet, and waits for confirmation. The transaction signature is stored with the trade and linked to BscScan.

The agent chooses its own universe. Every 30 minutes a market scanner pulls GeckoTerminal's market-wide feeds (top organic score and top traded over 24h), applies hard quality gates — quoted against WBNB or a major stable, ≥ $1M on-chain liquidity, ≥ $500k daily volume — and rebuilds the tradable set on top of a curated core. Tokens it currently holds are never dropped mid-position.

xStocks are BEP-20 tokens issued by Backed Finance against real shares held in regulated custody — they track the underlying equity and trade 24/7 on-chain. You hold price exposure, not shareholder rights, and they are geo-restricted in some jurisdictions. Turn them off with INCLUDE_STOCKS=false.

To pin a token the scanner would not pick, add it manually — no code change: EXTRA_TOKENS=SYMBOL:MINT:DECIMALS.

# 1. install everything (repo root)
npm install

# 2. start the agent (paper mode by default)
npm run agent

# 3. in another terminal, start this console
npm run web

# or both at once
npm run dev

The agent starts in paper mode with $10,000 of virtual BNB. It uses real market prices and the full decision pipeline — only the fills are simulated.

1. Generate a dedicated trading wallet:

   npm run create-wallet

   Never reuse your main wallet. Fund it only with what you can afford to lose.
2. Put the secret key in agent/.env:

   WALLET_SECRET_KEY=your_base58_secret_key
   TRADING_MODE=live

3. Fund the wallet with BNB — it is the trading capital and the gas reserve in one (0.005 BNB is held back for gas).
4. Strongly recommended: a dedicated RPC endpoint (Helius, Triton, QuickNode) — the public one is rate-limited:

   BSC_RPC_URL=https://your-endpoint.example.com

5. Restart the agent. It will refuse to start in live mode without a valid key.

Every signal — strategy-generated or manual — passes through the same gate. It can shrink or veto a trade, never enlarge it:

• No position may exceed 20% of total portfolio value — 10% for memecoins and scanner-discovered tokens
• Per-trade notional capped at $250 — $125 for those same higher-volatility classes
• At most 60 trades per UTC day across the universe, and 4 per token so one name can't eat the budget
• 5-minute cooldown per token between trades
• Automatic stop-loss at −5% and take-profit at +12%, checked every tick and never subject to AI veto
• On-chain slippage capped at 75 bps
• At most 2 strategy executions per tick, highest-confidence first

All limits are tunable via environment variables — see agent/.env.example.

Two independent AI features, each behind its own key in agent/.env:

• Desk analyst chat — set OPENROUTER_API_KEYand the floating "Ask the analyst" button on every page comes alive. Each conversation is grounded in a live snapshot of the agent's full state: prices with 24h and short-term drift, your portfolio and positions, the last dozen trades, the decision log, and the risk configuration. Pick any model with OPENROUTER_MODEL (default: Claude Sonnet 4.5 via OpenRouter). Responses stream in token by token.
• Pre-trade signal review — set ANTHROPIC_API_KEY and every strategy signal gets a second opinion from Claude before execution: a structured approve/veto verdict with a rationale. High-confidence vetoes block the trade; everything lands in the activity feed. Protective exits (stop-loss/take-profit) never wait for the analyst. This key also serves as the chat fallback when no OpenRouter key is set.

The agent exposes everything on http://localhost:8899:

GET  /api/status                    engine, mode, universe, strategies, risk config
GET  /api/prices                    latest prices for the whole universe
GET  /api/prices/:symbol/history    tick history
GET  /api/tokens                    universe with asset class + discovery source
GET  /api/portfolio                 positions + valuations
GET  /api/trades?limit=100          trade log
GET  /api/equity                    portfolio value over time
GET  /api/events                    recent signals, vetoes, fills, scans
GET  /api/activity?hours=24         activity stats + hourly histogram + timeline
GET  /api/performance?days=30       win rate, PnL by strategy/token, drawdown
GET  /api/onchain                   live mainnet balances + tx history (RPC)
POST /api/engine/start | stop       pause / resume trading
POST /api/strategies/:name          { "enabled": true | false }
POST /api/trade                     { "action": "BUY", "symbol": "BTCB", "size": 50 }
POST /api/chat                      { "messages": [...] } -> streamed analyst reply

• The secret key lives only in agent/.env, which is git-ignored. The agent signs locally; the key is never transmitted.
• Run paper mode for at least a few days before going live. Strategies that look smart in a trend can bleed in chop.
• Live crypto trading can lose money quickly. The risk engine limits damage per trade and per day — it cannot eliminate market risk.
• This software is provided as-is, without warranty. It is not financial advice.

Ready? Open the console →