Vexis Trading Agents

Multi-agent crypto trading desk in TypeScript using LangGraph + LLM reasoning, real data providers, and simulated execution.

Pipeline:

Market Data -> Analysts -> Bull/Bear Research -> Debate -> Trader (advisory) -> Risk (advisory) -> Portfolio (advisory) -> ExecutionController (advisory) -> FinalDecisionLLM (mandatory tool-call) -> Simulated Exchange

Features

• LangGraph orchestration with strict typed JSON contracts.
• LLM decision nodes (OpenRouter) with retry + fallback.
• LLM-first final authority node (FinalDecisionLLM) with mandatory tool-calling.
• Real crypto inputs (CCXT market, CoinGecko, Alternative.me, Cryptocurrency.cv + NewsAPI).
• Binance account snapshot integration (spot + USD-M + COIN-M).
• Binance Spot CCXT action pack (live actions, whitelist guarded).
• Binance Futures CCXT action pack (USD-M + COIN-M, leverage/margin/position pre-setup).
• SL/TP protection across Spot, USD-M, COIN-M (native-first + fallback trigger strategy).
• Manual protect-position flows for existing spot/futures positions.
• Observability stack (metrics/logs/alerts, SQLite persistence, health endpoints).
• Standalone metrics dashboard (/metricsz) with interactive start/stop from CLI.
• Continuous runner with interval + candle alignment + backoff.
• Unified CLI (vexis) with interactive mode.

Project Structure

src/
  agents/     # Analyst/research/trader/risk/portfolio agents
  core/       # Pipeline, providers, env, telemetry, runner, spot services
  sim/        # Simulated exchange
  types/      # Shared domain/contracts/json types
  utils/      # Reporting and helpers

Requirements

• Node.js 20+
• npm 10+
• Binance API key/secret for account + spot actions
• Binance API key/secret for account + spot + futures actions
• OpenRouter API key for LLM-driven nodes

Installation

npm install
cp .env.example .env

Global install:

npm i -g vexis-trading-agents
vexis env init --scope global

Build & Validate

npm run build
npm run validate

Quick Start

Single cycle:

npm start
# or
node dist/cli.js run --asset SOL/USDT --timeframe 1h --limit 50

Interactive console:

vexis interactive

CLI Overview

Core commands:

vexis run
vexis runner
vexis ops tail
vexis health
vexis account check
vexis doctor
vexis env init
vexis env check
vexis validate

Spot commands:

vexis spot buy --symbol BTC/USDT --type market --amount 0.001
vexis spot buy --symbol BTC/USDT --type market --amount 0.001 --stop-loss 93000 --take-profit 98000
vexis spot sell --symbol BTC/USDT --type limit --amount 0.001 --price 90000
vexis spot protect --symbol BTC/USDT --amount 0.001 --stop-loss 93000 --take-profit 98000
vexis spot order get --symbol BTC/USDT --order-id <id>
vexis spot order cancel --symbol BTC/USDT --order-id <id>
vexis spot order cancel-all [--symbol BTC/USDT]
vexis spot orders open [--symbol BTC/USDT --limit 50]
vexis spot orders closed [--symbol BTC/USDT --limit 50]
vexis spot balance
vexis spot trades --symbol BTC/USDT [--limit 50]
vexis spot quote --symbol BTC/USDT [--depth 5]

Futures commands:

vexis futures buy --scope usdm --symbol BTC/USDT:USDT --type market --amount 0.001
vexis futures buy --scope usdm --symbol BTC/USDT:USDT --type market --amount 0.001 --stop-loss 93000 --take-profit 98000
vexis futures sell --scope usdm --symbol BTC/USDT:USDT --type limit --amount 0.001 --price 90000
vexis futures protect --scope usdm --symbol BTC/USDT:USDT --side buy --amount 0.001 --stop-loss 93000 --take-profit 98000
vexis futures protect --scope coinm --symbol SOL/USD:SOL --side buy --amount 1 --take-profit 100
vexis futures order get --scope usdm --symbol BTC/USDT:USDT --order-id <id>
vexis futures order cancel --scope usdm --symbol BTC/USDT:USDT --order-id <id>
vexis futures order cancel-all --scope usdm [--symbol BTC/USDT:USDT]
vexis futures orders open --scope usdm [--symbol BTC/USDT:USDT --limit 50]
vexis futures orders closed --scope usdm [--symbol BTC/USDT:USDT --limit 50]
vexis futures balance --scope usdm
vexis futures positions --scope usdm [--symbol BTC/USDT:USDT]
vexis futures trades --scope usdm --symbol BTC/USDT:USDT [--limit 50]
vexis futures quote --scope usdm --symbol BTC/USDT:USDT [--depth 5]

Use --json on commands for machine-readable output.

Use custom env file per command:

vexis --env-file ./secrets/prod.env env check
vexis --env-file ./secrets/prod.env run

Interactive UX

vexis interactive provides menu-driven workflows:

• Trading Cycle: run cycle / start runner
• Spot Desk: buy, sell, order ops, balance, trades, quote
• Futures Desk: buy, sell, order ops, balance, positions, trades, quote
• Ops & Health: ops tail, health check, dashboard start/stop, account check
• Admin: doctor, env check, validate

UX behavior:

• loading indicator + elapsed time on each action
• symbol and numeric input validation
• back navigation on each submenu
• dashboard server in interactive mode is non-blocking and toggles menu option between Start/Stop

Configuration

Env precedence (highest to lowest):

1. CLI flag overrides (for example --env-file)
2. OS/session env (process.env)
3. File from --env-file
4. Global env file ~/.vexis/.env
5. Local env file ./.env
6. Internal defaults

Bootstrap env file:

vexis env init --scope global
vexis env init --scope local
vexis env init --path ./configs/dev.env

Runtime mode

PIPELINE_MODE=paper          # backtest | paper | live-sim
OUTPUT_FORMAT=pretty         # pretty | json
STRICT_REAL_MODE=true

LLM (OpenRouter)

OPENROUTER_API_KEY=your_key
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini
LLM_MAX_RETRIES=2

Notes:

• Final decision is produced by mandatory tool-call (final_decision_tool).
• If mandatory tool-calling fails until retry exhausted, run returns terminal llm_abort decision path.

Real data providers

NEWSAPI_KEY=your_key
COINGECKO_API_KEY=optional
CRYPTOCURRENCY_CV_BASE_URL=https://cryptocurrency.cv
NEWSAPI_BASE_URL=https://newsapi.org/v2
ALTERNATIVE_ME_BASE_URL=https://api.alternative.me
COINGECKO_BASE_URL=https://api.coingecko.com/api/v3
PROVIDER_CACHE_TTL_SECONDS=300

Risk controls (env-driven)

RISK_MAX_PER_TRADE_USD=1
RISK_USD_TOLERANCE=1.1
RR_MIN_THRESHOLD=1.5
FUTURES_MAX_LEVERAGE=5
TP_PARTIAL_SPLIT=50,30,20
TP_BREAKEVEN_AFTER_TP1=true
RISK_MAX_PER_TRADE_PCT=1.0
RISK_MAX_EXPOSURE_PCT=35
RISK_DRAWDOWN_CUTOFF_PCT=12
RISK_MAX_ATR_PCT=6
RISK_MIN_LIQUIDITY_USD=20

Notes:

• Execution is futures-first in run cycle (long/short valid). Spot/futures market data can still be used as analysis input.
• Main sizing driver is RISK_MAX_PER_TRADE_USD.
• Core sizing math:
  • stop_pct = abs(entry - stop_loss) / entry
  • notional_by_risk = RISK_MAX_PER_TRADE_USD / stop_pct
  • target_notional = max(notional_by_risk, exchange_min_notional)
  • effective_risk_usd = target_notional * stop_pct
• Trade is rejected if effective_risk_usd > RISK_MAX_PER_TRADE_USD * RISK_USD_TOLERANCE.
• RR_MIN_THRESHOLD enforces minimum weighted RR before proposal can continue.
• TP model is multi-target by default (1R/2R/3R) with partial close split from TP_PARTIAL_SPLIT and optional SL to breakeven after TP1.
• FUTURES_MAX_LEVERAGE is used for margin-feasibility checks (required_margin = notional / leverage), not to increase allowed USD loss.
• RISK_MAX_PER_TRADE_PCT is legacy compatibility fallback.

Binance account snapshot

BINANCE_API_KEY=your_key
BINANCE_API_SECRET=your_secret
BINANCE_ACCOUNT_ENABLED=true
BINANCE_ACCOUNT_SCOPE=spot+usdm+coinm
BINANCE_DEFAULT_EXPOSURE_PCT=8
BINANCE_DEFAULT_DRAWDOWN_PCT=3

Binance Spot actions

BINANCE_SPOT_ENABLED=true
BINANCE_SPOT_SYMBOL_WHITELIST=BTC/USDT,ETH/USDT,SOL/USDT
BINANCE_SPOT_DEFAULT_TIF=GTC
BINANCE_SPOT_RECV_WINDOW=10000

Notes:

• Spot actions are live by default when enabled.
• Execution is restricted to symbols in BINANCE_SPOT_SYMBOL_WHITELIST.
• Withdraw/transfer are intentionally not included in this version.

Binance Futures actions

BINANCE_FUTURES_ENABLED=true
BINANCE_FUTURES_SCOPE_DEFAULT=usdm                # usdm | coinm
BINANCE_FUTURES_SYMBOL_WHITELIST=BTC/USDT:USDT,ETH/USDT:USDT,BTC/USD:BTC
BINANCE_FUTURES_DEFAULT_TIF=GTC                   # GTC | IOC | FOK
BINANCE_FUTURES_RECV_WINDOW=10000
BINANCE_FUTURES_DEFAULT_LEVERAGE=3
BINANCE_FUTURES_MARGIN_MODE=isolated              # isolated | cross
BINANCE_FUTURES_POSITION_MODE=hedge               # hedge | oneway

Notes:

• Futures actions are live by default when enabled.
• Scope uses explicit CCXT classes: binanceusdm and binancecoinm.
• Guard layer enforces whitelist, exchange min limits, and precision before placing orders.

Observability, health, runner

OBS_PERSIST_ENABLED=true
OBS_SQLITE_PATH=./data/observability.db
OBS_RETENTION_DAYS=30
OBS_CLEANUP_ENABLED=true
SHOW_TELEMETRY=true

HEALTH_SERVER_ENABLED=true
HEALTH_SERVER_PORT=8787

RUNNER_ENABLED=true
RUNNER_INTERVAL_SECONDS=60
RUNNER_CANDLE_ALIGN=true
RUNNER_MAX_BACKOFF_SECONDS=900

Health & Ops

Health endpoints:

• GET /healthz liveness
• GET /readyz readiness snapshot (providers/LLM/runner)
• GET /metricsz HTML metrics dashboard
• GET /metricsz/data JSON feed for dashboard data

Ops tail:

npm run ops:tail -- --run-id run-123 --severity critical --limit 50
npm run ops:tail -- --trace-id <trace-id> --since 2026-03-05T00:00:00.000Z --json

Run standalone dashboard server (without runner):

node dist/cli.js health --serve --port 8787

Safety Notes

• Trading pipeline execution is still simulated (no live order placement from AI pipeline).
• Binance Spot commands are live exchange actions when enabled.
• Binance Futures commands are live exchange actions when enabled.
• Use restricted API keys and symbol whitelist in production.

Troubleshooting

Troubleshooting is managed via GitHub Issues:

• Report bugs: Open a Bug Report
• Ask questions / ops incidents: Issues

Please include:

• command used
• mode/symbol/timeframe
• expected vs actual result
• relevant logs (--json output if possible)
• sanitized environment details

Contributing

See CONTRIBUTING.md for development workflow, coding standards, and PR checklist.