What you will accomplish
- Build and verify the official CLI
- Configure paper mode without committing secrets
- Understand how local L2 triggers use bid and ask depth
- Check positions and risk before real mode
Before you begin
- Node.js and npm
- Git
- A secure terminal environment
- Read-only credentials for private-state testing; live trading credentials only after review
The current CLI and Telegram repositories may default DEFAULT_PAYMENT_CURRENCY to USD, while the authenticated order reference treats paymentCurrency as a separate field and illustrates stablecoins such as USDT. Before enabling real mode, use the value accepted by the current account and order schema. Do not infer the funding asset from quoteAsset=USD.
The public CLI has worked before: commit e66154b4 builds cleanly. The May 31, 2026 upload at 4ebdf05d removed the Candle export from src/types.ts while candle-aggregator.ts still imports it. This is a current source regression, not a conclusion about the CLI's history. Use the tested repair in Troubleshooting until the repository is corrected.
Clone, build, and verify the repository
Use the official quoteTrade organization repository and record the commit you tested. Install dependencies, compile, and print the CLI help. The current package's npm test script names test files that are not present in the public repository, so do not claim that suite passed unless those files are restored.
git clone https://github.com/quoteTrade/quote-trade-CLI-trading-bot.git
cd quote-trade-CLI-trading-bot
npm install
npm run build
npm run helpThe project builds and the help command runs without placing an order.
Configure paper mode first
Copy sample.env and preserve MODE=paper. The official sample points to Quote.Trade REST, liquidity, and private listen-key URLs. Keep credentials empty for public tests or inject them securely for read-only private tests.
cp sample.env .envThen edit .env and keep paper mode enabled:
API_BASE_URL=https://app.quote.trade/api
LIQUIDITY_WS_URL=wss://app.quote.trade/ws/liquidity
LISTEN_KEY_WS_URL=wss://app.quote.trade/ws/listenKey
MODE=paper
TRADE_API_KEY=
TRADE_API_SECRET=
SIGNING_ALGORITHM=sha256
QUOTE_TRADE_STATE_DIR=.quote-trade
POSITIONS_ENDPOINT=/positionsThe CLI starts in paper mode and does not submit live orders.
Inspect positions and risk
The repository caches positions in .quote-trade/positions.json and can refresh from current account interfaces. Review the state directory’s permissions and do not publish it.
npm run cli -- positions:refresh
npm run cli -- positions:list
npm run cli -- riskThe CLI displays current or paper account state and risk without placing an order.
Create a paper L2 trigger
The CLI’s local trigger engine is side- and quantity-aware: BUY triggers evaluate ask-side depth; SELL triggers evaluate bid-side depth. It fires only when cumulative executable depth covers the resolved order quantity.
npm run cli -- trigger:limit \
--symbol BTC \
--side BUY \
--price 60000 \
--quantity 0.01
npm run cli -- trigger:list
npm run cli -- trigger:watchThe trigger is stored locally and a paper action is logged only when its price and depth conditions are met.
Know that local triggers stop when the CLI stops
The API does not receive native trigger instructions in advance. The watcher must remain running for local triggers, OCO, bracket, trailing-stop, time, and risk-guard actions to fire. Monitor process health and restart behavior.
Local triggers work only while the CLI process is running.
Enable real mode only after testing the full workflow
Before MODE=real, use a dedicated limited key, verify symbol and notional controls, test the kill switch, confirm current positions, and use the smallest practical order. The optional LLM planner creates a draft; it does not replace confirmation.
Real mode is enabled only after credentials, limits, and the full workflow have been tested.
Common problems and fixes
Build fails because Candle is not exported from ../types
On current main commit 4ebdf05d, restore a compatible type in src/types.ts, then rerun npm run build. This minimal repair was compiled successfully:
export interface Candle { start: number; end: number; open: number; high: number; low: number; close: number; orderBook?: unknown; }npm test cannot find tests/trigger-engine.test.js
The current public package references four test files that are not included in the repository. This is a separate packaging issue. Use the compile and help smoke tests above, plus paper-mode checks, until the repository ships the referenced tests or updates its test script.
A local stop did not fire
Confirm trigger:watch was running, fresh L2 data was available, and cumulative side-specific depth covered the required quantity.
Position-sized close has no quantity
Refresh and inspect the local position cache before arming the trigger.
An LLM proposed an unsafe command
Do not confirm it. Treat the planner output as a draft and require hard-coded validation rules plus user review.