docs(trading-strategies): document strategy contract, runtimes, and data access#1185
Open
bennycode wants to merge 5 commits into
Open
docs(trading-strategies): document strategy contract, runtimes, and data access#1185bennycode wants to merge 5 commits into
bennycode wants to merge 5 commits into
Conversation
…ata access - Add 'The Strategy Contract' section: processCandle candle-in/advice-out model, TradingSessionState input, OrderAdvice output, lifecycle hooks - Add 'Running a Strategy' section: BacktestExecutor vs TradingSession, both routing advice through the shared AdviceExecutor - Add 'Strategies Are Just Async Code' section: strategies may await any data source (DB, news, reports, MCP), not only trading-signals indicators - Rewrite 'Strategy Signals' to the real OrderAdvice shapes (the previous BUY_MARKET/NONE enum did not exist) - Fix Usage imports: OrderAdvice/AllAvailableAmount from trading-strategies, OrderSide/OrderType from @typedtrader/exchange
Add an 'Extending a base strategy' note to the Strategy Contract section: subclasses can layer shared behaviour onto the base contract (ProtectedStrategy adds stop-loss/take-profit guards), or extend Strategy directly when none is needed.
Reader feedback: the added sections were too technical. Replace the type signatures, interface/union dumps, lifecycle-hooks table, and executor/event internals with concept-first prose: - 'How a Strategy Works' — buy / sell / wait, one candle at a time - 'Same Strategy, Backtest or Live' — one short backtest example - 'What a Strategy Can Use' — indicators or any other data Drop the now-orphaned bare-import 'Usage' block.
…es-contract-and-runtimes
bennycode
commented
Jul 12, 2026
| ## Usage | ||
| ## How a Strategy Works | ||
|
|
||
| A strategy watches the market one candle at a time and decides what to do next: **buy, sell, or wait.** You write that decision; the library handles the rest — turning it into a correctly sized order and keeping track of balances, fees, and each exchange's trading rules for you. |
bennycode
commented
Jul 12, 2026
|
|
||
| A strategy watches the market one candle at a time and decides what to do next: **buy, sell, or wait.** You write that decision; the library handles the rest — turning it into a correctly sized order and keeping track of balances, fees, and each exchange's trading rules for you. | ||
|
|
||
| On every new candle your strategy sees the latest price data and a snapshot of your account, then returns one of: |
Owner
Author
There was a problem hiding this comment.
For this showcase an example code that returns an advice.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The
trading-strategiesREADME explained trading domain knowledge well but was thin on the actual programming contract. This adds the missing architectural docs and fixes some stale/incorrect examples.Changes
processCandle(candle, state)as the one method you implement, theTradingSessionStateinput, the realOrderAdviceoutput union, and the full lifecycle-hook table (init/onFill/onOrderFilled/onMessage). Also clarifiesonCandleis a template method — you overrideprocessCandle.BacktestExecutorhistorical vsTradingSessionlive) and the key fact that both route advice through the sameAdviceExecutor, so a backtest is a faithful dry run of the live path. Includes runnable examples for each.processCandle/initare async by design and mayawaitany data source (DB, news, analyst/stock reports, an MCP such as TipRanks), not onlytrading-signalsindicators. CitesMeanReversionStrategy'sfetchCandlesandinit(market)as existing proof, with a perf caveat to keep the per-candle path cheap.BUY_MARKET/SELL_LIMIT/NONEenum did not exist in the code; replaced with the realOrderAdviceshapes.OrderAdvice/AllAvailableAmountcome fromtrading-strategies(were imported from@typedtrader/exchange);OrderSide/OrderTypeare the real names (were the non-existentExchangeOrderSide/ExchangeOrderType).Notes
Docs-only change. All type names and imports were verified against the current source (
Strategy.ts,TradingSessionTypes.ts,BacktestExecutor.ts,MeanReversionStrategy.ts).