@@ -172,6 +172,88 @@ library's `strategy_set_syminfo_*` setters.
172172` docker/run_json.py ` is vendored: pineforge-release copies it from the engine tag
173173at every release, so the lot-grid handling (` mincontract ` ) lives in this file.
174174
175+ ### Other symbols' bars (` PINEFORGE_SYMBOL_FEEDS ` )
176+
177+ A script that calls ` request.security ` on another symbol reads that symbol's
178+ own bars, never the chart's. Without them, or when the index below lacks the
179+ requested symbol string or timeframe, the run stops where the request's value
180+ is read (`request.security(...) at line N: no data is pinned for this request,
181+ and its value was read` , exit 4). ` PINEFORGE_SYMBOL_FEEDS` (the
182+ harness's ` --symbol-feeds ` ) names a JSON index of those bars, installed through
183+ the library's ` strategy_set_symbol_facts ` and ` strategy_set_symbol_feed ` (engine
184+ 1.0.0 and later):
185+
186+ ``` json
187+ {"symbols" : {
188+ "BINANCE:ETHUSDT" : {
189+ "syminfo" : {"tickerid" : " BINANCE:ETHUSDT" , "type" : " crypto" , "currency" : " USDT" ,
190+ "mintick" : 0.01 , "session" : " 24x7" , "timezone" : " UTC" },
191+ "feeds" : {"240" : " ethusdt-240.csv" , "1D" : " ethusdt-1D.csv" }}}}
192+ ```
193+
194+ ``` bash
195+ docker run --rm \
196+ -v $( pwd) /strategy.pine:/in/strategy.pine:ro \
197+ -v $( pwd) /btcusdt-240.csv:/in/ohlcv.csv:ro \
198+ -v $( pwd) /symbols:/in/symbols:ro \
199+ -e PINEFORGE_SYMBOL_FEEDS=/in/symbols/symbols.json \
200+ pineforge > report.json
201+ ```
202+
203+ - A symbol key is the exact string the script passes at run time, exchange
204+ prefix and suffix included: ` BINANCE:ETHUSDT ` , ` ETHUSDT ` and
205+ ` BINANCE:ETHUSDT.P ` are three symbols. For ` input.symbol ` it is the input's
206+ value (its default, or the ` PINEFORGE_INPUTS ` override). A string naming the
207+ chart's own market is another symbol too: the harness does not set the chart's
208+ ` syminfo.tickerid ` .
209+ - One feed per timeframe the script requests, keyed in the engine's spelling:
210+ whole minutes as a bare integer (` "240" ` , never ` "4h" ` ), else ` <n>D|W|M|S ` ;
211+ a bare ` D ` /` W ` /` M ` /` S ` is folded to ` 1D ` /` 1W ` /` 1M ` /` 1S ` . A request at
212+ ` timeframe.period ` (or ` "" ` ) reads the feed at the chart's timeframe.
213+ - A feed is a CSV like ` ohlcv.csv ` (` timestamp,open,high,low,close,volume ` ; an
214+ empty volume is a symbol that publishes none), paths relative to the index.
215+ Each bar's close is its open plus the timeframe (calendar months for ` M ` ),
216+ right for a 24x7 symbol; give a session-bound symbol a ` time_close ` column
217+ (unix ms; an empty cell falls back to open plus timeframe). Bars before the
218+ chart's first bar are delivered as history on it; bars after its last are
219+ never read. A header-only feed installs the symbol without bars: its requests
220+ read na on every bar (a symbol with no bars in the window).
221+ - ` syminfo ` is the symbol's catalog object, flat or ` {"syminfo": {...}} ` . Its
222+ ` type ` , ` timezone ` , ` session ` , ` currency ` and ` mintick ` are set as the
223+ symbol's facts, which ` syminfo.* ` reads inside the request; ` tickerid ` is set
224+ as its ` canonical ` fact, which no ` syminfo.* ` reads; other keys are ignored.
225+ Inside the request ` syminfo.tickerid ` is always the key and ` syminfo.ticker `
226+ the key after its last ` : ` . Without ` syminfo ` , ` syminfo.mintick ` reads NaN
227+ and those four strings read empty.
228+ - Merge rule (TradingView's): with ` lookahead ` off a chart bar reads the latest
229+ requested bar whose close is at or before the chart bar's close; with it on,
230+ the latest that opened at or before the chart bar's open. A missing requested
231+ bar carries the last value forward (` gaps ` off) or reads na (` gaps ` on).
232+ - Limits: at most 256 symbols and 256 feeds in one index. The chart must be its
233+ own input (` PINEFORGE_SCRIPT_TF ` unset or equal to the input timeframe), else
234+ the run fails with `request.security of another symbol needs the chart's own
235+ bars as input; input '<i >' aggregated to chart '<s >' is not supported`. The run
236+ is historical only. Each feed is a full pass of its request's expression over
237+ its bars. ` request.security_lower_tf ` on another symbol reads no feed.
238+ - A feed must be at the timeframe it serves. Nothing aggregates another
239+ symbol's bars: the engine looks a feed up by the exact symbol string and
240+ timeframe, and ` strategy_set_symbol_feed ` installs the bars as given. A ` 240 `
241+ feed does not serve a ` D ` request, and a ` 1 ` feed serves only a request at
242+ ` 1 ` , so give each requested timeframe its own bars.
243+ - An index or feed the harness cannot install (for example: not JSON, a bad
244+ timeframe spelling, two feeds at one timeframe, a CSV without ` close ` ,
245+ timestamps that do not strictly increase, a close after the next bar's open,
246+ a non-positive ` mintick ` , more than 256 feeds, a library without the setters,
247+ a feed the engine refuses)
248+ fails the run before it starts: one line
249+ ` {"engine":"pineforge","error":"--symbol-feeds: ..."} ` on stdout, harness exit
250+ 1, entrypoint exit 4.
251+ - What was installed is recorded as ` applied_runtime.symbol_feeds ` (each
252+ symbol's facts, and per feed its bar count, first and last open and a hash of
253+ its values), so the fingerprint digest differs from a run without it. Unset,
254+ or an index naming no symbol: the key is absent and the report is what it was
255+ before this variable existed, apart from ` elapsed_seconds ` .
256+
175257The engine catches every error (TF mismatch, unsupported emulation
176258flags, unknown-input-TF, etc.) into ` strategy_get_last_error() ` ; the
177259container surfaces these as ` {"engine":"pineforge","error":"..."} ` on
0 commit comments