Skip to content

Formats

The exact schema of every file you upload and every file you receive, as enforced by helyx validate and by the service. A complete valid example set is at intraday-docs.helyx-energy.com/examples/ (pm_targets.jsonl, da_cleared.csv, delivered.csv, config.yaml, request.json) and is written locally by helyx examples.

Conventions that apply to every file

  • Timestamps are UTC: YYYY-MM-DD HH:MM:SS (2026-03-02 12:00:00) or ISO 8601 with Z or an offset. A timestamp without a zone is taken as UTC.
  • Delivery periods are 15 minutes and start on a quarter hour (:00, :15, :30, :45).
  • A delivery day is 00:00–23:45 UTC.
  • Names (request_id, dataset names, config names): lower-case letters, digits, ., _, -; a request_id is 3–64 characters, a dataset or config name 1–64.

Uploads

pm_targets.jsonl — Position Manager targets

JSON Lines: one JSON object per line, one line per target revision. No other format is accepted (a JSON array, CSV or Parquet is refused, not converted).

Field Type Required Rule
portfolio_id string yes the same value on every record of the file
delivery_from_utc timestamp yes start of the 15-minute delivery period; quarter-hour aligned
delivery_to_utc timestamp yes end of the period
created_utc timestamp yes when this revision was issued; must be before delivery_from_utc
target array of levels yes at least one level; see below
da_position_delta array of objects yes the components of the position, see below
any other field — no additional fields in Position Manager records are permitted and ignored by the backtest (for example strategy)

Each element of target is a price–volume level:

Field Type Rule
quantity_mw number signed: negative = sell, positive = buy; all levels of one record carry the same sign
min_price_eur_per_mwh number sell floor; for a sell level |min_price| ≤ 5000 (no "infinite" floors)
max_price_eur_per_mwh number buy ceiling; for a buy level |max_price| ≤ 5000

The levels of one record add up to the net target for the period. Level 0 is worked above its floor (below its ceiling); each further level is worked only at its own, worse, limit.

Each element of da_position_delta carries reference_time and the components forecast, schedule, availability (numbers, MW; a missing component counts as zero). The element with reference_time: "da" is used; if none has it, the first element is used. The position's tag is derived from it, once per delivery period, from the last revision of that period, and applies to every revision of it: the component with the largest absolute value decides — forecast → forecast_update, schedule → schedule, availability → availability_update; a tie is resolved in that order. Per-tag configuration parameters apply according to this tag.

Revisions: records with the same delivery_from_utc are one position; they are ordered by created_utc and replayed in that order. The last revision is the converged target. A period whose converged |Σ quantity_mw| is below 0.1 MW (the exchange minimum) is dropped as untradeable.

{"portfolio_id": "example_portfolio_nl", "delivery_from_utc": "2026-03-02 06:00:00", "delivery_to_utc": "2026-03-02 06:15:00", "created_utc": "2026-03-02 00:00:00", "target": [{"quantity_mw": -0.3, "min_price_eur_per_mwh": 20.0, "max_price_eur_per_mwh": 4000.0}], "da_position_delta": [{"reference_time": "da", "forecast": -0.3, "schedule": 0.0, "availability": 0.0}]}
{"portfolio_id": "example_portfolio_nl", "delivery_from_utc": "2026-03-02 06:00:00", "delivery_to_utc": "2026-03-02 06:15:00", "created_utc": "2026-03-02 04:00:00", "target": [{"quantity_mw": -0.6, "min_price_eur_per_mwh": 20.0, "max_price_eur_per_mwh": 4000.0}], "da_position_delta": [{"reference_time": "da", "forecast": -0.6, "schedule": 0.0, "availability": 0.0}]}

Two revisions of the 06:00 period: at 00:00 sell 0.3 MW, revised at 04:00 to sell 0.6 MW, floor €20/MWh, tagged forecast_update.

da_cleared.csv or .parquet — cleared day-ahead position

Column Type Rule
delivery_from_utc timestamp one row per 15-minute period; complete grid from first to last row, no gaps, no duplicates
cleared_mwh number MWh cleared in the day-ahead auction for the period; negative = sold, positive = bought; no missing values
delivery_from_utc,cleared_mwh
2026-03-02 06:00:00,-0.55
2026-03-02 06:15:00,-0.70

delivered.csv or .parquet — realised production

Column Type Rule
delivery_from_utc timestamp same grid rules as above
delivered_mwh number metered MWh delivered in the period; positive = produced; no missing values

Both volume files must cover every period the Position Manager file trades inside the requested run period. CSV: header row, comma-separated, . decimal separator, no thousands separators. Parquet: the same two columns.

config.yaml — run configuration

Only the parameters below may appear; any other key is refused. Every parameter is optional; an omitted one takes the policy version's default. Bounds are enforced on upload.

schema_version: "1"          # required, exactly "1"
deadband_mw: 1.0             # number, 0–2
flush_minutes: 0             # number, 0–120; 0 = the deadband is never lifted
fee_eur_mwh: 0.10            # number, 0–1
tags:                        # per tag; tag names: forecast_update, schedule, availability_update, uncommitted_volume
  schedule:
    default_window_minutes: 1440          # number, 5–2880
    urgency_schedule: [[360, 0.0], [120, 0.3], [30, 0.6], [5, 0.9]]   # [[minutes_to_gate, urgency 0–1], …], minutes decreasing
    pacing_curve: [[0.0, 0.0], [0.25, 0.5], [0.5, 0.75], [1.0, 1.0]]  # [[elapsed 0–1, done 0–1], …] or null
    hold_back_mw: 1.0                     # number, 0–20   (policy v1.3.0 and later)
    da_price_gate:                        # (policy v1.3.0 and later)
      sell_only_below: -5                 # number or null, −500–4000, EUR/MWh
      buy_only_above: null                # number or null, −500–4000, EUR/MWh

Parameters marked v1.3.0 are refused by earlier policy versions. helyx policies prints, per version, the exposed parameters and their defaults.

request.json — run request

Written by helyx request; shown here so that a request can also be produced by other tooling.

{
  "schema_version": "0.2",
  "request_id": "esg-2026-09-24-floor20",
  "pm_targets": "improved_floor20",
  "da_cleared": "actual_da",
  "delivered": "realised",
  "config": "gate5-holdback1",
  "policy": "v1.3.0",
  "start": "2026-03-01",
  "end": "2026-05-31",
  "notes": "optional, up to 2000 characters"
}
Field Rule
schema_version exactly "0.2"
request_id 3–64 characters, ^[a-z0-9][a-z0-9._-]{2,63}$; names the run and its results folder
pm_targets, da_cleared, delivered names of uploaded datasets; all three required
config name of an uploaded configuration; omit for the policy defaults
policy a published version, vMAJOR.MINOR.PATCH
start, end YYYY-MM-DD, inclusive UTC delivery days; start ≤ end, at most 366 days, inside the published coverage and avoiding its gaps
notes optional; not part of the run identity

Results

economics_<YYYY-MM-DD>.csv — one file per delivery day

96 rows (one per 15-minute period of the UTC day), in the order of the columns below. Volumes in MW for the period unless the name says MWh; cash in EUR, received positive.

Column Unit Meaning
cet hh:mm local clock label of the period start (display only)
delivery_start_utc timestamp period start, UTC
dah_forecast_mw MW cleared day-ahead sold volume, as a positive quantity
actual_mwh MWh realised production
actual_mw MW realised production
delta_mw MW realised minus day-ahead sold, before intraday: positive = long, negative = short
dah_price EUR/MWh day-ahead price
imb_long_eur_mwh EUR/MWh imbalance price, long leg
imb_short_eur_mwh EUR/MWh imbalance price, short leg
imb_price_applied EUR/MWh the leg applied to the final residual position
id_sell_mw MW intraday volume sold
id_sell_vwap EUR/MWh volume-weighted average sell price (0 when nothing sold)
id_buy_mw MW intraday volume bought
id_buy_vwap EUR/MWh volume-weighted average buy price (0 when nothing bought)
net_id_mw MW signed intraday volume: buy positive, sell negative
A_total_eur EUR day-ahead cash flow
B_total_eur EUR A + imbalance settlement without intraday trading
C_total_eur EUR A + intraday cash flows + imbalance settlement of the residual
id_value_add_eur EUR C − B
delivery_date date the UTC day of the file

economics_monthly.csv — the run in daily rows

One row per delivery day, then one YYYY-MM TOTAL row per month, then one N-DAY TOTAL row for the run. Totals are sums of the daily rows; the VWAP columns are empty on total rows.

Column Unit Meaning
delivery_date date or TOTAL label
dah_mwh MWh day-ahead sold volume
actual_mwh MWh realised production
id_sell_mwh, id_buy_mwh MWh intraday sold and bought
id_sell_vwap, id_buy_vwap EUR/MWh daily volume-weighted average prices
A_total_eur, B_total_eur, C_total_eur, id_value_add_eur EUR as above, summed over the day
month YYYY-MM

run_parameters.json — what ran

{
  "request_id": "esg-2026-09-24-floor20",
  "identity_sha256": "cedaf60ac38d00a1e31cd268a7e6e9c2f63378d49f80812939b23faf8ad8a96a",
  "inputs": {
    "pm_targets": {"sha256": "…", "name": "improved_floor20", "generation": 1790108301159686},
    "da_cleared": {"sha256": "…", "name": "actual_da", "generation": 1790108303050979},
    "delivered":  {"sha256": "…", "name": "realised", "generation": 1790108305021316},
    "config":     {"sha256": "…", "name": "gate5-holdback1", "generation": 1790108306000000}
  },
  "parameters": {"deadband_mw": 1.0, "flush_minutes": 0, "fee_eur_mwh": 0.1,
                 "tags": {"schedule": {"default_window_minutes": 1440, "hold_back_mw": 1.0, "da_price_gate": {"sell_only_below": -5}}}},
  "policy": "v1.3.0",
  "market_corpus_revision": "mc-33406daa0d193927",
  "period": {"start": "2026-03-01", "end": "2026-05-31"},
  "frozen_at": "2026-09-24T20:07:37+00:00"
}

identity_sha256 identifies the experiment: two runs with the same value have byte-identical results. parameters is the fully resolved configuration, defaults included. generation is the stored version of each uploaded dataset that this run used.

status.json

Field Meaning
state queued, deferred, rejected, running, done, failed
reason for rejected and failed, why; for done, a one-line summary
identity_sha256 as above, once accepted
results_from set when an identical earlier run's results were reused
submitted_at, accepted_at, started_at, finished_at, updated_at timestamps, UTC

validation.json

The checks applied at acceptance: for each dataset and for the request, a list of {name, ok, detail} and a status of valid or rejected.