JSON Export

JSON export is configured only through CLI flags.

You can get backtest results in JSON by adding --json to the command.

whale-e strategy.toml --json

In JSON mode, Whale‑E writes output to stdout and automatically disables console/file logs, SQLite result writes, and Pine Script export. It does not disable the market cache or the indicator cache.

JSON options#

All these options require --json. Using them without --json returns an argument error.

In --analyze --json mode, only --json-pretty is allowed. Preflight details are documented in Analyze (dry run).

In --search-symbol --json mode, only --json-pretty is allowed. Search-specific payload details are documented in Symbol Search.

Success envelope#

Backtest JSON mode uses _schema: "whale-e.backtests.v2".

• success: true
• mode: "backtest"
• backtest_count: integer
• objective_limit: integer
• include_trades: boolean
• include_block_usage: boolean
• include_all_grid_parameters: boolean
• include_all_hyperparameters: boolean
• include_strategy_toml: boolean
• whale_e_version: string
• trade_columns: [...] only when --json-include-trades is enabled
• backtests: [...]
• strategy_name: string
• strategy_toml only when --json-include-strategy is enabled

Each entry in backtests always contains rank, a 1-based integer that represents the backtest rank within its objective, together with blocks such as context, performance, trade_analysis, and risk. When trades are enabled, the shared trade schema is emitted once in trade_columns, and each backtest contains only trades.rows. The performance block notably includes total_pnl and total_pnl_percent. The risk block notably includes the margin_call, margin_call_long, and margin_call_short counters. All absolute timestamps in the payload use Unix UTC milliseconds, without an _ms suffix in field names.

Example (truncated):

{
  "success": true,
  "_schema": "whale-e.backtests.v2",
  "mode": "backtest",
  "strategy_name": "ema-crossover",
  "backtest_count": 1,
  "backtests": [
    {
      "rank": 1,
      "context": { "combination_code": "G3C123" },
      "performance": { "total_pnl": { "value": 123.45, "type": "quote_amount", "side": "all" } },
      "risk": { "margin_call": { "value": 0, "type": "count", "side": "all" } }
    }
  ],
  "strategy_toml": "[backtest]\n..."
}

Error envelopes#

Generic CLI errors:

• success: false
• _schema: "whale-e.error.v1"
• mode: "backtest" for CLI backtests, mode: "analyze" for --analyze --json, mode: "search_symbol" for --search-symbol --json
• error: { type: string, message: string }

Example:

{
  "success": false,
  "_schema": "whale-e.error.v1",
  "mode": "backtest",
  "error": { "type": "invalid_arguments", "message": "--json cannot be combined with --export-pinescript" }
}

TOML parse errors:

• returned on stdout as a JSON object
• success: false
• _schema: "whale-e.error.v1"
• mode: "backtest" or mode: "analyze" depending on context
• error: { type: "toml_parse_error", message: string, details: string[], strategy_file: string }

Example:

{
  "success": false,
  "_schema": "whale-e.error.v1",
  "mode": "backtest",
  "error": {
    "type": "toml_parse_error",
    "message": "Invalid key at line 12",
    "details": ["..."],
    "strategy_file": "strategy.toml"
  }
}

Examples#

Pretty JSON with trades and strategy TOML:

whale-e strategy.toml --json --json-pretty --json-include-trades --json-include-strategy

Compact JSON with 5 results per objective:

whale-e strategy.toml --json --json-objective-limit 5