Bot Sandbox

The Bot Sandbox widget is a built-in JavaScript strategy editor powered by Monaco Editor. Write, test, and run automated trading strategies that react to real-time market data and news events directly within the terminal.

⚠️

Bot strategies execute live orders on your connected exchange. Uncomment trade calls only when you are ready to risk real funds.

Features

Monaco Editor - Full-featured code editor with syntax highlighting, autocomplete, and line numbers
Web Worker Execution - Strategies run in an isolated Web Worker for safety
Real-Time Data - Market trades, orderbook updates, and news events are piped into your strategy
Live Trading - Place market and limit orders via the exchange API
Pre-Built Templates - Load example strategies to get started quickly
Console Output - Timestamped log panel for debugging and monitoring

Requirements

A connected exchange with trading credentials
An active symbol selected in the terminal header

Strategy API

Strategies are plain JavaScript. The sandbox injects the following functions into the execution environment.

Event Handlers

Subscribe to real-time data streams:

on('trade', (trade) => { ... })     // Latest trade on the active symbol
on('news', (news) => { ... })       // News feed items (deduplicated)
on('orderbook', (book) => { ... })  // Registered, not currently streamed
on('tick', (data) => { ... })       // Registered, not currently streamed

Currently only trade and news events are piped into the worker; orderbook and tick are part of the API surface but do not receive data yet.

The trade object contains price, qty, time, and isBuyerMaker. The news object contains id, content, and (when present) author, source, symbols, and timestamp.

Trading Functions

buy(qty)                // Market buy on active symbol (base quantity)
buy(qty, price)         // Limit buy on active symbol
buy(symbol, usdSize)    // Market buy by USD notional (auto-resolves symbol)
buy(symbol, usdSize, price) // Limit buy by USD notional
 
sell(qty)               // Market sell on active symbol
sell(qty, price)        // Limit sell on active symbol
sell(symbol, usdSize)   // Market sell by USD notional
sell(symbol, usdSize, price) // Limit sell by USD notional
 
closePosition()         // Close the entire position on the active symbol

When using the buy(symbol, usdSize) form, the bot automatically resolves the symbol across exchanges, fetches the mark price, and converts the USD amount to the correct base quantity with proper precision.

Utility Functions

getPosition()           // Current position size (synced from exchange)
getBalance()            // Available balance (synced from exchange)
log(message)            // Print to the console panel
matchesRegex(text, pattern) // Test a regex match (returns boolean)
extractCoin(text)       // Extract a coin ticker (e.g. "BTC") from text

Pre-Built Templates

Load a template from the dropdown in the toolbar:

Template	Description
SMA Crossover	Simple moving average crossover strategy with configurable period
News Trigger	Keyword-based news trading with blacklist filtering and cooldowns
Regex Bot	Advanced regex pattern matching for news events (listings, partnerships, exploits)
Simple Scalper	Profit target and stop loss scalping on each trade tick
Grid Bot	Configurable grid of buy/sell orders around a base price

All templates ship with trade calls commented out. Uncomment buy() / sell() / closePosition() lines when you are ready to go live.

Running a Strategy

Write or load a strategy in the editor
Click Start in the toolbar
The editor becomes read-only while running
Monitor output in the console panel
Click Stop to terminate the Web Worker

While running, the toolbar shows a pulsing green indicator and the active symbol.

Console

The console panel at the bottom displays:

Info messages (grey) - Strategy logs via log()
Warnings (yellow) - Executed order confirmations
Errors (red) - Runtime errors and failed orders

Click Clear to reset the console. The log retains the last 200 entries.

Order Execution

When a strategy calls buy(), sell(), or closePosition():

The bot validates exchange credentials
Fetches current mark price if needed for USD conversion
Determines quantity precision from the exchange symbol info
Submits the order via the exchange API
Logs the result and creates a notification

Failed orders are logged as errors with the failure reason.

Tips and Best Practices

Start with logging only - Test your strategy logic with log() before enabling live orders
Use small sizes - Start with minimal quantities (e.g. buy(0.001)) to validate behavior
Handle edge cases - Check for null from getPosition() and getBalance() before trading
News deduplication - The sandbox automatically deduplicates news events, so your on('news') handler fires once per item
Keep arrays bounded - If you accumulate data (e.g. trade history), slice to a fixed length to avoid memory issues
Monitor the console - Check for errors regularly; a failing strategy continues running silently

⚠️

The sandbox does not enforce risk limits. Your strategy can place orders as fast as the exchange allows. Always include size checks and rate limiting in your code.

Troubleshooting

Strategy Won't Start

Check the browser console for JavaScript syntax errors
Ensure exchange credentials are configured

No Trade Data

Verify a symbol is selected and the exchange connection is active
The strategy only receives trades for the currently active symbol

Orders Failing

Confirm API credentials have trading permissions
Check the console for specific error messages (insufficient balance, invalid quantity, etc.)
Ensure the order size meets the exchange minimum

Trenches Command Line