Kiploks Integration for OctoBot

Send your OctoBot backtest results to Kiploks for strategy robustness and risk analysis.

Use the Kiploks OctoBot integration to send OctoBot backtest exports to Kiploks and get a robustness score, risk metrics, and walk-forward analysis (WFA) for your crypto trading strategies. No plugins or OctoBot code changes: the script reads your existing backtest data and uploads it for analysis.

• Read-only: No OctoBot dependency; the script only reads exported files from your OctoBot profile.
• One or multiple runs: Point to a single backtesting_N folder or to the backtesting/ parent (uses metadata.json, sends latest or multiple runs).
• Round-trip trades: OctoBot all_trades are order fills; the script aggregates them into round-trips (FIFO by symbol) and builds oos_trades for risk analysis and strategy validation.

---

Key Features

• No plugins: Just run backtests in OctoBot, then run the script from your OctoBot root to get Kiploks strategy analysis.
• Walk-Forward Analysis (WFA): Single run or multiple runs; when pointing to the parent folder, the script builds Walk-Forward periods from metadata.json for out-of-sample validation.
• Robustness and risk report: Get a robustness score, deployment gate verdict, benchmark comparison, and risk metrics (Sharpe, profit factor, drawdown) on Kiploks.
• Instant analyze links: Direct kiploks.com/analyze/... links in your terminal after upload; view results on the Data page when logged in.
• Run via bash: Run ./kiploks-octobot/run.sh from your OctoBot backtesting project root.

---

Quick Start

1. Setup

Place the kiploks-octobot folder in your OctoBot project root (or ensure it is on the path when you run from OctoBot root). You need Python 3.9+ (stdlib only; no extra packages for run).

# From your OctoBot root (directory that contains your bot profile and backtesting exports)
chmod +x kiploks-octobot/run.sh

2. Configuration

Create your config from the template and add your API credentials:

cp kiploks-octobot/kiploks.json.example kiploks-octobot/kiploks.json

Edit kiploks-octobot/kiploks.json and fill in:

• backtesting_path: Path relative to OctoBot root, e.g. bot1/user/data/GridTradingMode/Buy the dip/backtesting or a single backtesting_1 folder. Absolute paths and ~ are supported.
• api_token: Your key from Kiploks -> API Keys.

3. Usage

Run from your OctoBot root:

OS / method	Command
Linux / macOS	./kiploks-octobot/run.sh
Windows (cmd / PowerShell)	python kiploks-octobot/run.py
Windows (Git Bash or WSL)	./kiploks-octobot/run.sh

With a valid api_token, the script uploads to Kiploks and prints the analyze URL(s). Without a token it still builds the payload and writes export_octobot_result.json in the script directory. If skip_already_uploaded is true and this run set was already uploaded, the script skips upload and uses uploaded.json.

---

Configuration Details (kiploks.json)

Option	Default	Description
api_url	"https://kiploks.com"	Kiploks API base URL. Required for upload.
api_token	""	Your API key from Kiploks -> API Keys. Required for upload.
backtesting_path	(required)	Path to a single backtesting_N folder or to the backtesting/ parent. Relative to OctoBot root. Absolute paths and ~ supported.
top_n	3	When path is the parent folder, number of runs to use, by date (latest N).
wfaPeriods	(optional)	Max WFA windows (each = 2 runs: IS + OOS). If set, only the last wfaPeriods * 2 runs are used.
primary_run_id	(optional)	Run id (e.g. "6" for backtesting_6) to use as the main analysis. Verdict, benchmark metrics and equity come from this run; all runs still feed WFA periods and parameter sensitivity. If unset, the last run is used.
wfaISSize	90	WFA in-sample size in days (informational; display/config parity with Freqtrade).
wfaOOSSize	30	WFA out-of-sample size in days (informational).
skip_already_uploaded	true	Skip POST when this run set is already in uploaded.json. Set to false or remove uploaded.json to re-upload.

Each run can write kiploks-octobot/export_octobot_result.json (full payload) and uploaded.json (tracker) in the script directory.

---

Project Structure

Your OctoBot root should look like this so that backtesting_path in config resolves correctly:

octobot_root/
├── bot1/
│   └── user/
│       └── data/
│           └── .../backtesting/          <-- point backtesting_path here or to backtesting_N
│               ├── metadata.json
│               ├── backtesting_1/
│               │   ├── run_data.json
│               │   └── binance/
│               └── backtesting_2/
└── kiploks-octobot/                      <-- script folder
    ├── run.sh
    ├── run.py
    ├── kiploks.json
    └── ...

---

Single run vs multiple runs

• Single run: Set backtesting_path to one folder that contains run_data.json and binance/ (or your exchange) with trades and portfolio_value. The script sends one period in Walk-Forward (optimizationReturn = validationReturn = total return). WFA metrics (retention, decay, WFE) are degenerate with one period.
• Multiple runs: Set backtesting_path to the parent folder that contains metadata.json and backtesting_1/, … and set top_n or wfaPeriods. The script builds WFA periods from all selected runs. Use primary_run_id to base the main analysis (verdict, metrics, equity) on one specific run while still using all runs for parameter sensitivity and WFA. For real WFA you need different date ranges per run. Parameter Sensitivity requires runs with different strategy parameters (see Limitations).

---

Known limitations

• Parameter Sensitivity: Not available. OctoBot does not export hyperopt/optimizer results; we only have one (or the same) parameter set per run. The Parameter Sensitivity block in Kiploks will be empty unless you run multiple backtests with different strategy parameters and a way to send them (not implemented in this script).
• Walk-Forward: With one run we send a single period (opt = val = total return). Full WFA requires several runs (different windows) and is supported when pointing to the parent folder with metadata.json.
• Benchmark: Kiploks uses BTCUSDT for benchmark. If your backtest is BTC/USDC we send symbol BTCUSDC; a small symbol mismatch is possible.
• Fee: Derived as the average over all fills in all_trades (fee_cost/cost). Shown in the report when source is OctoBot.
• GridTradingMode / round-trips: Round-trips are built with FIFO aggregation by symbol. With partial fills or grid-style orders, net_return and trade-level PnL may be approximate; the backend is the single source for Sharpe, profit factor, and validation max drawdown.

---

Troubleshooting & API Errors

Code	Cause	What to do
401	Missing Authorization header (Bearer API key required).	Set api_token in kiploks.json.
401	Invalid or expired API token.	Generate a new key in Kiploks -> API Keys and update api_token.
403	results must be a non-empty array.	Fix payload: ensure backtesting_path points to valid run data.
403	Maximum number of stored tests reached.	Delete some tests on the Data page in Kiploks, then retry.
400	Result at index N is missing required data for analysis.	Ensure payload has valid backtestResult, symbol, walkForwardAnalysis.periods; check run_data.json and exchange folder.
400	Benchmark is required; payload must have date range and timeframe.	Backtest must have start/end and timeframe in run_data.
429	Only one analyze request per minute is allowed.	Wait and retry.
502	Failed to submit results (proxy to backend failed).	Retry later; check Kiploks status.

Script / environment errors

• Config not found or empty – Copy kiploks.json.example to kiploks.json in the same folder as run.py and set backtesting_path and api_token.
• backtesting_path not found – Run the script from the OctoBot root so that relative paths in config resolve. Use ./kiploks-octobot/run.sh from that root.
• No run_data.json in folder – Point backtesting_path to a folder that contains run_data.json and the exchange subfolder (e.g. binance/) with trades and portfolio_value.
• Export structure differs – If your OctoBot version uses different paths or field names, see docs/OCTOBOT_INTEGRATION_PLAN.md in the main repo for the expected layout.

---

Part of the Kiploks ecosystem for crypto trading strategy analysis and backtest validation. Full setup guide and OctoBot integration docs: kiploks.com/integrations/octobot-integration.

---