nexustrade 1.52.0 → 1.58.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md
CHANGED
|
@@ -7,9 +7,11 @@ friendlier read.
|
|
|
7
7
|
## What this package is
|
|
8
8
|
|
|
9
9
|
A typed client plus ~170 **generated** builders for authoring trading
|
|
10
|
-
strategies. The builders are generated from the
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
strategies. The builders are generated from the engine's indicator specification.
|
|
11
|
+
They describe draft payloads; the API still validates complete portfolios and
|
|
12
|
+
their conditions. A builder's existence does not guarantee support for every
|
|
13
|
+
trading method. Read the [option selection and execution limits](README.md#option-selection-and-execution-limits)
|
|
14
|
+
before claiming exact option timing, expiration selection, or rolling behavior.
|
|
13
15
|
|
|
14
16
|
```
|
|
15
17
|
author a portfolio → submit a job → poll until terminal → read result
|
package/README.md
CHANGED
|
@@ -234,6 +234,36 @@ nt.strategy("Sell the credit spread for the debit fill plus $0.50", whenDebitSpr
|
|
|
234
234
|
It keeps the no-worse-than-current-quote protection, but it is not a resting
|
|
235
235
|
price target. Live option strategies must choose an explicit Limit policy.
|
|
236
236
|
|
|
237
|
+
### Option selection and execution limits
|
|
238
|
+
|
|
239
|
+
Builders describe drafts. Typechecking does not prove that the engine can
|
|
240
|
+
execute every requested rule; the API validates complete portfolios and their
|
|
241
|
+
conditions.
|
|
242
|
+
|
|
243
|
+
- Expiration selectors support a DTE window and `nearest`, `middle`, or
|
|
244
|
+
`furthest`. `middle` selects the middle eligible expiration by index, not the
|
|
245
|
+
expiration nearest a target such as 180 days. There is no monthly-only or
|
|
246
|
+
quarterly-only expiration filter.
|
|
247
|
+
- `rebalanceOption` accepts `renewBeforeDays` (integer 1–90) and
|
|
248
|
+
`revisitDisclosedTargets`. These maintain modeled political-disclosure option
|
|
249
|
+
targets. The strategy must contain a `NewPoliticalDisclosure` condition for
|
|
250
|
+
instrument `Option` with exactly one member ID. These fields do not implement
|
|
251
|
+
a general close-and-replace roll for a trend strategy.
|
|
252
|
+
- For backtests, the job's `feeConfig.OptionSlippageFraction` sets quote-side
|
|
253
|
+
fills: `0` uses the midpoint, `1` uses ask for buys and bid for sells, and the
|
|
254
|
+
default is `0.5`. This job setting does not add a last-trade fallback or define
|
|
255
|
+
live order execution.
|
|
256
|
+
- Evaluation timing and order execution are separate. `OpenClose` schedules
|
|
257
|
+
evaluations at session open and close; it does not itself carry a signal
|
|
258
|
+
observed at close into an order at the next open. Explicit zero timing offsets
|
|
259
|
+
and a `gt(MinutesAfterOpen(), Value(0))` condition can restrict evaluations
|
|
260
|
+
to the calendar session close. `MinutesUntilClose` counts down to 16:00 Eastern,
|
|
261
|
+
so it cannot identify an early session close.
|
|
262
|
+
|
|
263
|
+
When authoring an approximation, describe the actual expiration policy, signal
|
|
264
|
+
timing, fills, and replacement behavior. Backtest results describe that
|
|
265
|
+
implementation, not the exact method it approximates.
|
|
266
|
+
|
|
237
267
|
<details>
|
|
238
268
|
<summary><b>What you can build</b> — 170+ generated builders</summary>
|
|
239
269
|
|
|
@@ -98,6 +98,7 @@ exports.Negative = Negative;
|
|
|
98
98
|
exports.NewInsiderDisclosure = NewInsiderDisclosure;
|
|
99
99
|
exports.NewInstitutionalFiling = NewInstitutionalFiling;
|
|
100
100
|
exports.NewPoliticalDisclosure = NewPoliticalDisclosure;
|
|
101
|
+
exports.NewsSentiment = NewsSentiment;
|
|
101
102
|
exports.NewTradingWeek = NewTradingWeek;
|
|
102
103
|
exports.OnBalanceVolume = OnBalanceVolume;
|
|
103
104
|
exports.OpeningPrice = OpeningPrice;
|
|
@@ -680,14 +681,16 @@ function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
|
|
|
680
681
|
* @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
|
|
681
682
|
* @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
|
|
682
683
|
* @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
|
|
684
|
+
* @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
|
|
683
685
|
*/
|
|
684
|
-
function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
|
|
686
|
+
function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
|
|
685
687
|
const d = { type: "ChartBar" };
|
|
686
688
|
setAsset(d, "targetAsset", asset);
|
|
687
689
|
d["barMinutes"] = barMinutes;
|
|
688
690
|
d["line"] = line;
|
|
689
691
|
d["bars"] = bars;
|
|
690
692
|
d["offsetBars"] = offsetBars;
|
|
693
|
+
d["minutePolicy"] = minutePolicy;
|
|
691
694
|
return d;
|
|
692
695
|
}
|
|
693
696
|
/**
|
|
@@ -1606,6 +1609,19 @@ function NewPoliticalDisclosure(memberId, instrument, disclosureAction) {
|
|
|
1606
1609
|
d["disclosureAction"] = disclosureAction;
|
|
1607
1610
|
return d;
|
|
1608
1611
|
}
|
|
1612
|
+
/**
|
|
1613
|
+
* Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
|
|
1614
|
+
* @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
|
|
1615
|
+
* @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
|
|
1616
|
+
* @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
|
|
1617
|
+
*/
|
|
1618
|
+
function NewsSentiment(asset, measure = "Mean", lookbackDays = 1) {
|
|
1619
|
+
const d = { type: "NewsSentiment" };
|
|
1620
|
+
setAsset(d, "targetAsset", asset);
|
|
1621
|
+
d["measure"] = measure;
|
|
1622
|
+
d["lookbackDays"] = lookbackDays;
|
|
1623
|
+
return d;
|
|
1624
|
+
}
|
|
1609
1625
|
/**
|
|
1610
1626
|
* NewTradingWeek indicator.
|
|
1611
1627
|
*/
|
|
@@ -2206,6 +2222,7 @@ const backtest = (portfolio, config) => ({
|
|
|
2206
2222
|
"start_date": config.startDate,
|
|
2207
2223
|
"end_date": config.endDate,
|
|
2208
2224
|
"baseline_symbol": config.baselineSymbol,
|
|
2225
|
+
"baseline_asset": config.baselineAsset,
|
|
2209
2226
|
"interval": config.interval,
|
|
2210
2227
|
"initial_value": config.initialValue,
|
|
2211
2228
|
"generate_events": config.generateEvents,
|
|
@@ -430,9 +430,9 @@ export interface RebalanceOptionAction {
|
|
|
430
430
|
sleeves?: RebalanceOptionSleeve[];
|
|
431
431
|
allocationPolicy?: AllocationPolicy;
|
|
432
432
|
exposurePolicy?: ExposurePolicy;
|
|
433
|
-
/**
|
|
433
|
+
/** Disclosure maintenance only: requires a NewPoliticalDisclosure Option condition with exactly one memberId; integer 1..90. Not a generic DTE roll. */
|
|
434
434
|
renewBeforeDays?: number;
|
|
435
|
-
/**
|
|
435
|
+
/** Disclosure maintenance only: revisit continuing public option targets when another option filing arrives. Same condition restriction as renewBeforeDays. */
|
|
436
436
|
revisitDisclosedTargets?: boolean;
|
|
437
437
|
}
|
|
438
438
|
export type OptionParentSelectionSort = "oldest" | "highestPnl" | "nearestExpiry";
|
|
@@ -775,20 +775,7 @@ export declare const sleeve: (config: {
|
|
|
775
775
|
* Rank a universe and rotate an option book. Keep take-profit / stop-loss / DTE
|
|
776
776
|
* exits in separate closeOption strategies, not here.
|
|
777
777
|
*/
|
|
778
|
-
export declare const rebalanceOption: (config:
|
|
779
|
-
universe: Universe;
|
|
780
|
-
pipeline: PipelineStage[];
|
|
781
|
-
weightIndicator: Indicator | CandidateIndicator;
|
|
782
|
-
structureTemplates: OptionStructureTemplate[];
|
|
783
|
-
limit?: number;
|
|
784
|
-
totalBudget?: DeploymentBudget;
|
|
785
|
-
perNameAllocation?: OptionAllocation;
|
|
786
|
-
sizingMode?: "fixedPerName" | "proportionalToWeight" | "proportionalToWeightWholeContracts";
|
|
787
|
-
positionScope?: RebalanceOptionPositionScope;
|
|
788
|
-
sleeves?: RebalanceOptionSleeve[];
|
|
789
|
-
allocationPolicy?: AllocationPolicy;
|
|
790
|
-
exposurePolicy?: ExposurePolicy;
|
|
791
|
-
}) => RebalanceOptionAction;
|
|
778
|
+
export declare const rebalanceOption: (config: Omit<RebalanceOptionAction, "type">) => RebalanceOptionAction;
|
|
792
779
|
export declare const pnlTrigger: (bounds: {
|
|
793
780
|
minPnlPercent?: number;
|
|
794
781
|
maxPnlPercent?: number;
|
|
@@ -919,8 +906,9 @@ export declare function ChaikinMoneyFlow(asset: AssetArg, length?: number, inter
|
|
|
919
906
|
* @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
|
|
920
907
|
* @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
|
|
921
908
|
* @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
|
|
909
|
+
* @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
|
|
922
910
|
*/
|
|
923
|
-
export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number): Indicator;
|
|
911
|
+
export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number, minutePolicy?: "strict" | "observed"): Indicator;
|
|
924
912
|
/**
|
|
925
913
|
* CommodityChannelIndex indicator.
|
|
926
914
|
* @param asset Ticker name (ex. SPY, BTC)
|
|
@@ -1418,6 +1406,13 @@ export declare function NewInstitutionalFiling(manager: string): Indicator;
|
|
|
1418
1406
|
* @param disclosureAction Which newly public trade sides trigger a decision.
|
|
1419
1407
|
*/
|
|
1420
1408
|
export declare function NewPoliticalDisclosure(memberId: string, instrument: Instrument2, disclosureAction: "Any" | "Purchase" | "Sale"): Indicator;
|
|
1409
|
+
/**
|
|
1410
|
+
* Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
|
|
1411
|
+
* @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
|
|
1412
|
+
* @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
|
|
1413
|
+
* @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
|
|
1414
|
+
*/
|
|
1415
|
+
export declare function NewsSentiment(asset: AssetArg, measure?: "Mean" | "NetCount" | "ArticleCount", lookbackDays?: number): Indicator;
|
|
1421
1416
|
/**
|
|
1422
1417
|
* NewTradingWeek indicator.
|
|
1423
1418
|
*/
|
|
@@ -1753,7 +1748,7 @@ export interface FeeConfig {
|
|
|
1753
1748
|
Stock?: FeeAmount;
|
|
1754
1749
|
Cryptocurrency?: FeeAmount;
|
|
1755
1750
|
Option?: FeeAmount;
|
|
1756
|
-
/**
|
|
1751
|
+
/** Option fill slippage: 0=quote mid, 1=ask for buys/bid for sells; absent means 0.5. Requires a current executable quote. */
|
|
1757
1752
|
OptionSlippageFraction?: number;
|
|
1758
1753
|
}
|
|
1759
1754
|
export interface MetricConstraint {
|
|
@@ -1792,15 +1787,17 @@ export interface BacktestConfig {
|
|
|
1792
1787
|
startDate: string;
|
|
1793
1788
|
/** Backtest end date (ISO format, e.g. 2024-12-31). Minute allows up to 730 days of minute data from start_date, counting minute-indicator warmup; never split a longer span into yearly Minute jobs. */
|
|
1794
1789
|
endDate: string;
|
|
1795
|
-
/**
|
|
1790
|
+
/** Legacy Stock benchmark shorthand for comparisonValue. Use baseline_asset with explicit Cryptocurrency type for crypto pairs; never provide both fields. When both fields are omitted, the single traded stock/option underlying is inferred, otherwise SPY. For single-name options use that underlying; compare multi-name books against a deliberately chosen benchmark. */
|
|
1796
1791
|
baselineSymbol?: string;
|
|
1792
|
+
/** Typed buy-and-hold benchmark for comparisonValue. Use {type:'Cryptocurrency',symbol:'BTC-USD',name:'BTC-USD'} for BTC or {type:'Stock',symbol:'SPY',name:'SPY'} for a stock/ETF. Symbol text never determines asset type. Omit baseline_symbol when using this field. */
|
|
1793
|
+
baselineAsset?: Record<string, unknown>;
|
|
1797
1794
|
/** Time interval: Day or Minute (default Day). Minute is a daytrade tape. 730 days of minute data (selected range plus warmup) is the HARD CAP; 90 days is only the DEFAULT when you name no dates. Name the dates you actually want — certifying a candidate on a full year or two is a normal second backtest, not an escalation. */
|
|
1798
1795
|
interval?: "Day" | "Minute";
|
|
1799
1796
|
/** Starting portfolio value (default 10000) Range 1..inf. */
|
|
1800
1797
|
initialValue?: number;
|
|
1801
1798
|
/** Generate detailed event data (signals, orders, audits) during backtest. Costs 5x research tokens. Events are Mongo hot-store traces retained for 3 days. Use query_backtest_events to explore them while retained. */
|
|
1802
1799
|
generateEvents?: boolean;
|
|
1803
|
-
/** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig.
|
|
1800
|
+
/** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig. OptionSlippageFraction is supported: 0 fills at quote mid, 1 at ask for buys/bid for sells; omitted uses the engine default 0.5. Fills require a current executable quote; this does not enable last-trade fallback pricing. */
|
|
1804
1801
|
feeConfig?: FeeConfig;
|
|
1805
1802
|
/** Overrides the portfolio's dividend policy for this run only. Omit to use the portfolio's own setting (cash unless it was set to reinvest). "reinvest" buys more of the paying stock on each pay date, which is what a buy-and-hold comparison against the SPY total-return baseline needs. */
|
|
1806
1803
|
dividendPolicy?: "cash" | "reinvest";
|
|
@@ -460,14 +460,16 @@ export function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
|
|
|
460
460
|
* @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
|
|
461
461
|
* @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
|
|
462
462
|
* @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
|
|
463
|
+
* @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
|
|
463
464
|
*/
|
|
464
|
-
export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
|
|
465
|
+
export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
|
|
465
466
|
const d = { type: "ChartBar" };
|
|
466
467
|
setAsset(d, "targetAsset", asset);
|
|
467
468
|
d["barMinutes"] = barMinutes;
|
|
468
469
|
d["line"] = line;
|
|
469
470
|
d["bars"] = bars;
|
|
470
471
|
d["offsetBars"] = offsetBars;
|
|
472
|
+
d["minutePolicy"] = minutePolicy;
|
|
471
473
|
return d;
|
|
472
474
|
}
|
|
473
475
|
/**
|
|
@@ -1386,6 +1388,19 @@ export function NewPoliticalDisclosure(memberId, instrument, disclosureAction) {
|
|
|
1386
1388
|
d["disclosureAction"] = disclosureAction;
|
|
1387
1389
|
return d;
|
|
1388
1390
|
}
|
|
1391
|
+
/**
|
|
1392
|
+
* Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
|
|
1393
|
+
* @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
|
|
1394
|
+
* @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
|
|
1395
|
+
* @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
|
|
1396
|
+
*/
|
|
1397
|
+
export function NewsSentiment(asset, measure = "Mean", lookbackDays = 1) {
|
|
1398
|
+
const d = { type: "NewsSentiment" };
|
|
1399
|
+
setAsset(d, "targetAsset", asset);
|
|
1400
|
+
d["measure"] = measure;
|
|
1401
|
+
d["lookbackDays"] = lookbackDays;
|
|
1402
|
+
return d;
|
|
1403
|
+
}
|
|
1389
1404
|
/**
|
|
1390
1405
|
* NewTradingWeek indicator.
|
|
1391
1406
|
*/
|
|
@@ -1986,6 +2001,7 @@ export const backtest = (portfolio, config) => ({
|
|
|
1986
2001
|
"start_date": config.startDate,
|
|
1987
2002
|
"end_date": config.endDate,
|
|
1988
2003
|
"baseline_symbol": config.baselineSymbol,
|
|
2004
|
+
"baseline_asset": config.baselineAsset,
|
|
1989
2005
|
"interval": config.interval,
|
|
1990
2006
|
"initial_value": config.initialValue,
|
|
1991
2007
|
"generate_events": config.generateEvents,
|