Data

A series has a stable key such as file:help-example. Strategy reads refer to that saved key. An instrument-bound key can use file:name@Exchange/Market/SYMBOL. Use lowercase Latin letters, digits and the permitted _ . - characters in the name.

Studio first parses the complete file and presents a dry-run report. Import requires a separate confirmation. If the key already exists, the action replaces that stored series: check its destination carefully.

Save the text below as a UTF-8 file named example.csv. event_time is the event time, available_at is when the value became known, and value is a numeric field. The Z suffix specifies UTC.

This exact file passed EngineHost 1.0.0-preview.1 dry-run parsing on macOS: 3 rows, 3 points and no skipped rows, with a one-minute inferred interval. Its first event is at 00:00 but becomes available at 00:05. These are learning values, not a market dataset.

event_time,available_at,value
2020-01-01T00:00:00Z,2020-01-01T00:05:00Z,1
2020-01-01T00:01:00Z,2020-01-01T00:06:00Z,2
2020-01-01T00:02:00Z,2020-01-01T00:07:00Z,3

An event and its availability can have different timestamps. A value for 00:00 published at 00:05 must remain unknown to the strategy before 00:05. Reusing event time as availability without checking the source introduces look-ahead.

Without available_at, import asks for an explicit delay such as 5m, 6h or 1d. Zero is appropriate only when the value really is known immediately. Validation rejected the example without this column as missing_available_at; an explicit five-minute delay produced the expected shift.

Timestamps without Z or an offset require a separate UTC decision. Accept only when the source actually uses UTC. Correct local timestamps in the file first; declaring local time to be UTC shifts the series.

Review detected format and columns, accepted rows, event and availability ranges, interval and gaps. Skipped rows include reasons and examples. A valid file does not necessarily mean every original row was accepted.

Application screenshotXTester 1.0.0-preview.1

Enlarge screenshot

1. One-minute BTCUSDT series

Select a series in Data and choose Show Points… to print the first or last 50 or 500 points to XTester Engine output. The table contains event_time, available_at and value fields. Compare several points with the original file.

Check Series Gaps compares intervals with the available step. Fewer than two points cannot establish a step. No detected gaps does not establish data quality or correct publication timing.

Delete Series… removes the selected series from disk after confirmation. It leaves instrument candle history in place. Recovery requires the original file or another available source.

A strategy refers to the stable key through context.Series("file:help-example"). Discover exact reading methods and fields from the installed engine API. The series key is distinct from a CSV column name.

Reading data and plotting it are separate. Import does not automatically add a chart line: a strategy must explicitly register a plotted series. Also check the period, instrument and availability timestamps when relating it to a historical calculation.

Besides file: series, the exchange: source provides Binance USDT-M perpetual metrics: open_interest, long_short_ratio, top_trader_long_short_ratio and taker_ratio for supported instruments. These are additional time series, separately from candles or strategy trades.

A key includes source, name and scope, for example exchange:open_interest@Binance/FuturesUSDT/BTCUSDT. Exchange, market and instrument matter; a Spot or other-exchange key is not equivalent.

Read numeric fields, units and availability rules through describe_series. Event and publication times differ; a five-minute point must not be exposed earlier than its declared available-at time.

One loader request for an instrument fills the four supported series. Check actual coverage afterwards: missing or rejected days are not replaced with zero values.

This workflow applies to a finished build offering the Studio MCP download_series tool. Check your connection’s catalog and schema first. An older version or different MCP profile without it does not support an invented replacement call.

After agreeing source, instrument and period, supply exactly one of symbol or key. from is inclusive and to exclusive, in UTC. The example below requests one day; it is not evidence of a completed download.

This operation writes shared stored data and requires confirm=true. waitSeconds ranges from 0 to 600, default 120. A nonterminal call returns jobId/state; waiting does not by itself establish completion.

Read progress using job_status and cancel your own job with job_cancel. On completion inspect requested/stored/downloaded/missing days, missingRanges, rejectedDays and each series’ coverage. downloadedDays does not establish complete stored-window coverage.

This loader targets the stated Binance USDT-M metrics; funding has a separate operation. Use get_tool_schema for current fields and get_series_coverage for the stored window.

{
  "symbol": "BTCUSDT",
  "from": "2024-01-01",
  "to": "2024-01-02",
  "waitSeconds": 0,
  "confirm": true
}

missing_available_at: add actual publication time or supply a justified delay. naive_time: specify a time zone in the file or explicitly accept UTC when appropriate. Both outcomes were reproduced with example files; they are data-validation results rather than connection failures.

Duplicate event times, availability moving backwards, invalid headers or no numeric points require correcting the file. Changing its key does not fix its contents. If the key exists, deliberately choose between a separate series and replacement.

For an outdated-engine message, check Studio and EngineHost versions. Give support the exact error, column names and a small anonymized sample; a complete private dataset is usually unnecessary.