@vasokai/fxbg-sdk

Forex Bulgaria Academy — student SDK. Write trading strategies locally with Claude Code, backtest them against cached historical candles with an identical-to-production viewer, then deploy certified runs to the platform.

npx @vasokai/fxbg-sdk login
npx @vasokai/fxbg-sdk backtest src/strategies/my-strategy.ts \
  --from 2024-01-01 --to 2024-12-31

A browser tab opens with the same viewer you see on forexbulgaria.bg/backtest: PositionBox overlays per trade, engine primitives (FVG, CISD, Order Blocks, engulfing, etc.) on every timeframe pane, HTF + LTF context, full metrics dashboard.

What this package gives you

• 85+ curated detectors — candlestick patterns, FVGs, CISD, liquidity sweeps, killzones, swings, imbalances, market-structure — available under a single import surface (@vasokai/fxbg-sdk).
• fxbg backtest — local engine run on the same runBacktest() the platform uses in production. First run fetches candles from the platform with your API key, caches them at ~/.fxbg/candles/ (SQLite), subsequent runs are sub-second (zero network).
• Identical viewer — the Vite-bundled @vasokai/backtest-viewer ships inside the SDK and is served over a local 127.0.0.1 HTTP server. Same React viewer as the platform, with /api/chart/* proxied through to the platform (Bearer token injected) for neighbor-TF fetches.
• fxbg deploy — uploads the bundled strategy + source tree to forexbulgaria.bg/api/strategies/deploy for a certified, shareable, signed production run.
• fxbg candles — manage the local SQLite cache: status, sync --pair X --tf Y --years N, clear.

Commands

| Command | What it does | |---|---| | fxbg login | Authenticate once — saves API key to ~/.fxbg-auth.json. | | fxbg backtest [file] | Bundle → cache-fetch → run engine → open browser viewer. | | fxbg deploy [file] | Bundle → upload to the platform for certified production run. | | fxbg candles status | Inspect the local candle cache. | | fxbg candles sync --pair EURUSD --tf H1,M15 --years 2 | Pre-warm a range. | | fxbg candles clear [--pair X --tf Y] | Drop all or a subset. | | fxbg dev | Live engine visualizer for src/engines/. | | fxbg update | Refresh CLAUDE.md + .mcp.json in a student's project. |

fxbg backtest flags

--from YYYY-MM-DD       inclusive start (default: 1 year ago)
--to   YYYY-MM-DD       inclusive end (default: today)
--capital 10000         initial capital in account currency
--risk 0.5              risk per trade, percent
--broker blueberry-markets
--no-open               print URL but don't auto-open browser

Symbol + timeframe are read from the strategy's meta.symbols[0] and meta.timeframes[0] — no flags needed.

Declare meta.engines to paint the viewer

The strategy's meta block accepts a engines: string[] field — the list of visual primitives the viewer overlays on every pane, so you see exactly what the strategy "saw" at each candle:

export default {
  meta: {
    id: 'engulfing-london',
    name: 'Engulfing London KZ',
    version: '1.0.0',
    symbols: ['EURUSD'],
    timeframes: ['H1'],
    direction: 'both',
    markets: ['forex'],
    engines: ['bullishEngulfing', 'bearishEngulfing'],
  },
  // ...
};

Recognized ids: bullishEngulfing, bearishEngulfing, engulfing, doji, hammer, pinBar, insideBar, fvg, cisd, swings, ema20, ema50, ema200. Missing / empty = plain candles.

Storage layout

~/.fxbg-auth.json                              # login credentials
~/.fxbg/candles/<broker>/candles.db           # SQLite cache, same schema as server
~/.fxbg/candles/<broker>/<SYMBOL>__<TF>.meta.json
~/.fxbg/runs/<timestamp>-<slug>/result.json   # every local run

Safe to delete ~/.fxbg/runs/ any time. fxbg candles clear is the friendly way to reclaim the cache.

Requirements

• Node 20 or newer
• An active Forex Bulgaria Academy account

License

UNLICENSED — internal tool for Forex Bulgaria Academy students.