xAlmanac Upload API

Overview

The xAlmanac Upload API lets your own local script or agent send MetaTrader 5 Strategy Tester output to xTriel. The agent reads the files on your machine, then posts the contents to the ingest endpoint.

Authentication

Uploads use your per-user Ingest Token, the same xti_... token the Reporter EA uses. There is no separate API credential.

Authorization: Bearer xti_xxxxxxxxxxxxxxxxxxxxxxxx

Endpoint

POST https://xtriel.com/api/almanac/ingest
Authorization: Bearer xti_...
Content-Type: application/json

The request body is a batch with one or more preset results:

{
  "presets": [
    {
      "ea": "MyExpert",
      "version": "v1",
      "name": "EURUSD H1 example",
      "kind": "optimization",

      "setFile": {
        "name": "result.set",
        "content": "InpRiskPerSetupPercent=2.0\nInpTakeProfitMode=3\n..."
      },

      "reportFile": {
        "name": "ReportTester.html",
        "contentBase64": "PGh0bWw+...",
        "encoding": "utf-16le"
      },

      "tester": {
        "expert": "MyExpert.ex5",
        "symbol": "EURUSD",
        "timeframe": "H1",
        "model": 4,
        "fromDate": "2026.06.22",
        "toDate": "2026.06.28",
        "deposit": 10000,
        "currency": "USD",
        "leverage": "1:100"
      },

      "results": {
        "netProfit": 12450,
        "profitFactor": 1.84,
        "maxDDpct": 8.7
      },
      "sourceKey": "sha256-of-set-and-report"
    }
  ]
}

Field reference

Limits

• Report size: 2 MB or less after decoding.
• Request body: 25 MB or less.
• Batch size: up to 50 presets per request.
• results: up to 16 KB.
• equity: up to 5000 points.

Response

A successful request returns 200 OK with created, updated, and skipped arrays.

{
  "ok": true,
  "created": [
    { "artifactId": "...", "ea": "MyExpert", "version": "v1", "name": "..." }
  ],
  "updated": [],
  "skipped": []
}

• created: new results stored.
• updated: existing results updated because the dedupe key matched.
• skipped: rejected items, each with a reason such as MISSING_EA, MISSING_SET, BAD_REPORT, REPORT_TOO_LARGE, or ALMANAC_LIMIT.
• A bad item does not fail the entire batch.
• If any item hits the plan cap, the response also carries code: "ALMANAC_LIMIT".

What appears in xAlmanac

Open xAlmanac. Uploaded results are auto-imported on load, or by using the Agent uploads button, and render like a manual import.

• Full Detail view: net profit, profit factor, drawdown, Sharpe, and balance curve.
• Tester settings panel: Expert, Symbol, Period, Model, date range, Deposit, Currency, and Leverage.
• Blue Download .set button for the uploaded preset.
• Source filter and source column for Manual vs Agent API uploads.
• API badge on uploaded results.
• Download report action for retrieving the original .htm.

To reproduce a run in MT5, download the .set, open View -> Strategy Tester, load the EA, choose Inputs -> Load, then match Symbol, Period, Modelling, date range, and Deposit to the Tester settings panel.

Python upload agent

This example reads the preset as text, reads the report as raw bytes, base64-encodes the report, and posts one result to the ingest endpoint.

import base64
import os
import pathlib
import requests

GATEWAY = "https://xtriel.com/api/almanac/ingest"
TOKEN = os.environ["XTRIEL_INGEST_TOKEN"]

def upload_result(set_path, report_path, ea, version="v1", name="", tester=None):
    set_path = pathlib.Path(set_path)
    report_path = pathlib.Path(report_path)

    set_text = set_path.read_text(encoding="utf-8", errors="replace")
    report_raw = report_path.read_bytes()

    preset = {
        "ea": ea,
        "version": version,
        "name": name or report_path.stem,
        "setFile": {
            "name": set_path.name,
            "content": set_text,
        },
        "reportFile": {
            "name": report_path.name,
            "contentBase64": base64.b64encode(report_raw).decode("ascii"),
            "encoding": "utf-16le",
        },
    }

    if tester:
        preset["tester"] = tester

    response = requests.post(
        GATEWAY,
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"presets": [preset]},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

print(upload_result(
    set_path="myexpert.set",
    report_path="report.htm",
    ea="MyExpert",
    version="v1",
    name="EURUSD H1 example",
    tester={
        "expert": "MyExpert.ex5",
        "symbol": "EURUSD",
        "timeframe": "H1",
        "model": 4,
        "fromDate": "2026.06.22",
        "toDate": "2026.06.28",
        "deposit": 10000,
        "currency": "USD",
        "leverage": "1:100",
    },
))

curl upload

Use curl when you already have a prepared batch.json payload.

curl -sS -X POST https://xtriel.com/api/almanac/ingest \
  -H "Authorization: Bearer $XTRIEL_INGEST_TOKEN" \
  -H "Content-Type: application/json" \
  --data @batch.json

Deploy the upload agent

The upload agent can run on the same machine that can read your MT5 files, or on a VPS where you sync Strategy Tester exports. Keep the ingest token out of code and pass it as an environment variable.

python3 -m venv .venv
. .venv/bin/activate
pip install requests

export XTRIEL_INGEST_TOKEN="xti_xxxxxxxxxxxxxxxxxxxxxxxx"

python upload_xalmanac.py

To upload your 10 good results, send 10 objects in the presets array in one batch, or call the Python helper once per result. Re-running with the same .set and report updates the existing entry instead of duplicating it.

Troubleshooting

• 401: copy a fresh Ingest Token from Profile -> Connect your EA and update your environment variable.
• ALMANAC_LIMIT: upgrade to Pro or Max, or remove old results before uploading again.
• BAD_REPORT: re-export the report from MT5 Strategy Tester and preserve its original bytes before base64 encoding.
• REPORT_TOO_LARGE: keep the decoded report at 2 MB or less.
• Missing metrics: include the MT5 report. xAlmanac can fill many gaps from the report when you open the result.