Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theonetrade/uzse-backtest-app/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the complete end-to-end workflow — from cloning the repository to opening an interactive Pine Script chart — using the Uzbekistan Stock Exchange symbol HMKB (Hamkorbank) as a concrete example. Each step is a discrete script you can re-run independently, making it easy to add new symbols or date ranges later without repeating the full setup.
1

Clone the repository and install dependencies

Start by cloning the project and installing all Node.js packages. The project uses npx tsx to run TypeScript scripts directly without a separate compile step, so no build phase is required after npm install.
git clone https://github.com/theonetrade/uzse-backtest-app.git
cd uzse-backtest-app
npm install
After installation, your node_modules will contain all required packages including the backtest-kit suite, Playwright, and Mongoose. You can verify the key packages are present:
ls node_modules | grep backtest-kit
# @backtest-kit/cli
# @backtest-kit/graph
# @backtest-kit/pinets
# @backtest-kit/ui
# backtest-kit
Playwright downloads browser binaries separately from npm install. After the packages are installed, run the following command to install the Chromium browser used by the scraper:
npx playwright install chromium
2

Start MongoDB

UZSE Backtest App stores all trade records and candles in MongoDB. You must have a running MongoDB instance before executing any of the pipeline scripts.The app connects to mongodb://localhost:27017/backtest by default. You can override this by setting the MONGO_URI environment variable before running any script:
export MONGO_URI="mongodb://localhost:27017/backtest"

docker run -d \
  --name uzse-mongo \
  -p 27017:27017 \
  mongo:7
For a full Docker Compose setup that also includes Redis and MinIO, see the MongoDB infrastructure guide.
MongoDB must be running before you proceed to any of the following steps. The import-trades.ts and build-candles.ts scripts will fail immediately with a connection error if the database is not reachable.
3

Download trade data from uzse.uz

The download script launches a headless Chromium browser via Playwright, navigates to the paginated trade results on uzse.uz, and saves each page as an HTML file in the local tmp/ directory.The arguments are: <ISIN> <begin_date> <end_date> and an optional [mktId] market identifier (defaults to STK) where dates use the DD.MM.YYYY format.
npx tsx scripts/download-trades.ts UZ7011340005 01.01.2024 31.01.2024
You should see output similar to:
Total pages: 14
Downloaded page 2/14
Downloaded page 3/14
...
Downloaded page 14/14
Done. HTML saved to tmp/
The ISIN UZ7011340005 corresponds to HMKB (Hamkorbank). Each HTML file covers one page of trade results for the specified date range. Files are written to tmp/trades_page_1.html, tmp/trades_page_2.html, and so on.
To download the full trade history from 2018 to the present, use the bulk fetch script generator described in the Bulk Fetch guide. It generates a shell script that loops through every month and calls download-trades.ts and import-trades.ts sequentially — ideal for an overnight run.
4

Import trades into MongoDB

Once the HTML files are saved in tmp/, the import script parses each file, extracts trade rows (timestamp, symbol, price, quantity, volume), computes a SHA-1 deduplication hash per row, and upserts the records into the trade-results MongoDB collection.
npx tsx scripts/import-trades.ts
Expected output:
Found 14 file(s)
MongoDB connected
trades_page_1.html: 14 rows
...
Done. Inserted: 186, skipped (duplicates): 0
Tmp cleaned.
The deduplication hash ensures that re-running this script against the same HTML files is safe — existing records are silently skipped, so you will never end up with duplicate trades in your database.
5

Build OHLCV candles for HMKB

With raw trades in MongoDB, run the candle builder. Provide the ticker symbol and its ISIN as arguments. The script aggregates trades into 1-minute buckets, fills intraday and holiday gaps, and then rolls the 1m series up to all supported higher timeframes.
npx tsx scripts/build-candles.ts HMKB UZ7011340005
Expected output:
MongoDB connected
Range: 2024-01-01 — 2024-01-31 (31 days)
[31/31] 2024-01-31  trades:12  real_min:9  candles:363  inserted:11253  skipped:0
Done. Inserted: 11253, skipped (duplicates): 0
After this step, the candle-items collection holds candles for all eleven timeframes. The unique index { symbol, interval, timestamp } guarantees idempotency — re-running the script will not create duplicates.To verify the data landed correctly, you can query MongoDB directly:
mongosh backtest --eval \
  "db['candle-items'].countDocuments({ symbol: 'HMKB', interval: '1d' })"
6

Launch the visual editor

Start the backtest-kit editor with the standard npm script. This launches the @backtest-kit/cli server, which serves the visual editor UI and connects to your local MongoDB instance through the custom mongo-exchange adapter defined in modules/editor.module.ts.
npm start

> backtest-kit-project@1.0.0 start
> node ./node_modules/@backtest-kit/cli/build/index.mjs --editor

Editor running at http://localhost:8080
Open http://localhost:8080 in your browser. In the editor, set the exchange to mongo-exchange, the symbol to HMKB, choose a timeframe (e.g. 1d), and the chart will render the candles you built in the previous step. From here you can apply any Pine Script indicator from the @backtest-kit/pinets library.For a full walkthrough of the editor interface, see the Visual Editor guide. To learn how to write and attach custom Pine Script strategies, see the Pine Script guide.

​
What’s Next

Now that your first symbol is live in the editor, explore the rest of the documentation to go deeper:

Check Gaps

Use check-gaps.ts to identify which days the exchange was closed or had no trades, so you can audit your data completeness.

Bulk Fetch

Generate a shell script that downloads and imports every month of trade history in a single overnight batch run.

Pine Script

Apply built-in and custom Pine Script indicators and strategies to your UZSE candle data in the editor.

Timeframes Reference

Review all eleven supported timeframes and how the candle aggregation algorithm handles each one.

Build docs developers (and LLMs) love

Get started for freeTalk to us