nexustrade 0.1.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 ADDED
@@ -0,0 +1,256 @@
1
+ # AGENTS.md — NexusTrade TypeScript SDK
2
+
3
+ Instructions for coding agents (Claude Code, Cursor, Codex, and friends) writing
4
+ NexusTrade strategies with this package. Humans: [README.md](README.md) is the
5
+ friendlier read.
6
+
7
+ ## What this package is
8
+
9
+ A typed client plus ~170 **generated** builders for authoring trading
10
+ strategies. The builders are generated from the same indicator specification the
11
+ NexusTrade engine executes, so a book assembled from them is structurally valid
12
+ before it ever leaves the process.
13
+
14
+ ```
15
+ author a portfolio → submit a job → poll until terminal → read result
16
+ ```
17
+
18
+ ## Setup
19
+
20
+ ```bash
21
+ npm install nexustrade
22
+ export NEXUSTRADE_API_KEY=sk-...
23
+ export NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1
24
+ ```
25
+
26
+ ```ts
27
+ import { NexusTradeClient } from "nexustrade";
28
+ const nt = new NexusTradeClient(); // reads the environment
29
+ ```
30
+
31
+ Keys come from https://nexustrade.io/developers. Never hardcode one into a file
32
+ you write; read it from the environment. Node 18+.
33
+
34
+ ## Rules that matter
35
+
36
+ **1. Use the builders. Never hand-write the JSON.**
37
+
38
+ ```ts
39
+ // Right — validated shape, correct wire names
40
+ nt.buy(nt.stockAsset("SPY"), 100);
41
+
42
+ // Wrong — silently diverges from the engine's schema
43
+ { type: "Buy", targetAsset: { symbol: "SPY" }, amount: 100 };
44
+ ```
45
+
46
+ The client accepts both a builder result and a plain object, so a wrong literal
47
+ will typecheck. Prefer the builder.
48
+
49
+ **2. Comparisons are functions, not operators.**
50
+
51
+ TypeScript cannot overload `>`, so indicator comparisons go through helpers.
52
+ This is the single most common mistake in this SDK.
53
+
54
+ ```ts
55
+ // Right
56
+ nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200)));
57
+
58
+ // Wrong — compares object references, always nonsense
59
+ nt.filter(nt.Price(nt.CANDIDATE) > nt.SMA(nt.CANDIDATE, 200));
60
+ ```
61
+
62
+ Available: `gt` `gte` `lt` `lte` `eq` `neq`, combined with `and` / `or`.
63
+
64
+ **3. Every mutation needs an idempotency key, and it must be deterministic.**
65
+
66
+ Jobs cost money. A retry with the *same* key returns the original operation; a
67
+ retry with a new key launches a second paid job.
68
+
69
+ ```ts
70
+ // Right — same logical run reuses the key across retries
71
+ await nt.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
72
+
73
+ // Wrong — every retry is a new billable job
74
+ await nt.createBacktest(handle, { idempotencyKey: `run-${Date.now()}` });
75
+ ```
76
+
77
+ Reusing a key with a *different* payload is a `409 idempotency_conflict`. Version
78
+ the key when the request changes: `momentum-2024-v2`.
79
+
80
+ **4. `create*` does not wait. Poll.**
81
+
82
+ ```ts
83
+ const operation = await nt.createBacktest(handle, { idempotencyKey: "k" });
84
+ // operation.result is ABSENT here — the job has not run yet.
85
+ const finished = await nt.waitForBacktest(operation.id as string);
86
+ console.log(finished.result);
87
+ ```
88
+
89
+ A timeout does not cancel the job. Call the waiter again with the same id;
90
+ do not resubmit.
91
+
92
+ **5. Batch when you have several.**
93
+
94
+ ```ts
95
+ const operations = await nt.createBacktests([h1, h2, h3], {
96
+ idempotencyKey: "sweep-v1",
97
+ });
98
+ const results = await nt.waitForBacktests(operations);
99
+ ```
100
+
101
+ One request, one key, one rate-limit slot — instead of three of each.
102
+
103
+ **6. Percent semantics.** `buy(asset, 100)` is **100% of portfolio**, not 100
104
+ shares. Deployment and allocation parameters are percentages unless a builder
105
+ says otherwise.
106
+
107
+ **7. Credentials come from the environment, or a `.env` file.** Both
108
+ `NEXUSTRADE_API_KEY` and `NEXUSTRADE_API_BASE_URL` are read from `process.env`
109
+ first, then from a `.env` at or above the working directory — no `dotenv`
110
+ dependency and no `--env-file` needed. Never hardcode a key into a file you
111
+ write, and never log one. Exported values win over the file.
112
+
113
+ **8. Responses are `JsonObject`.** Fields come back typed as `JsonValue`, so
114
+ narrow before use (`operation.id as string`). This is deliberate: the envelope is
115
+ whatever the API returned, not a promise the SDK can statically make.
116
+
117
+ ## Recipes
118
+
119
+ <details open>
120
+ <summary><b>Buy and hold</b></summary>
121
+
122
+ ```ts
123
+ import * as nt from "nexustrade";
124
+
125
+ const book = nt.portfolio("Buy and hold SPY", [
126
+ nt.strategy("Buy", nt.always(), nt.buy(nt.stockAsset("SPY"), 100)),
127
+ ]);
128
+ ```
129
+ </details>
130
+
131
+ <details>
132
+ <summary><b>Condition on an indicator</b></summary>
133
+
134
+ ```ts
135
+ const aapl = nt.stockAsset("AAPL");
136
+ const oversold = nt.lt(nt.RSI(aapl, 14), 30);
137
+
138
+ const book = nt.portfolio("Dip buyer", [
139
+ nt.strategy("Buy the dip", oversold, nt.buy(aapl, 25)),
140
+ nt.strategy(
141
+ "Take profit",
142
+ nt.gt(nt.PositionPercentChange(aapl), 10),
143
+ nt.sell(aapl, 100),
144
+ ),
145
+ ]);
146
+ ```
147
+
148
+ Combine with `nt.and`, `nt.or`, `nt.atLeast`, `nt.atMost`, `nt.exactly`.
149
+ </details>
150
+
151
+ <details>
152
+ <summary><b>Rank and rotate a universe</b></summary>
153
+
154
+ `CANDIDATE` is the placeholder for "each name being evaluated". Use it inside a
155
+ pipeline; use a concrete asset outside one.
156
+
157
+ ```ts
158
+ const book = nt.portfolio("Momentum", [
159
+ nt.strategy("Rotate", nt.always(), nt.dynamicRebalance({
160
+ universe: nt.universe("SP500"),
161
+ pipeline: [
162
+ nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200))),
163
+ nt.selectTop(nt.RSI(nt.CANDIDATE, 14), 10),
164
+ ],
165
+ weightIndicator: nt.RSI(nt.CANDIDATE, 14),
166
+ limit: 10,
167
+ deploymentPercent: 80,
168
+ })),
169
+ ], { initialValue: 100_000 });
170
+ ```
171
+
172
+ Note the key is `universe`, not `universeConfig` (the Python SDK spells it
173
+ `universe_config`). `deploymentPercent: 80` invests 80% of the portfolio across
174
+ the selection and leaves the rest in cash — a **total** cap, not per-name.
175
+ </details>
176
+
177
+ <details>
178
+ <summary><b>Backtest, optimize, walk forward</b></summary>
179
+
180
+ ```ts
181
+ const bt = nt.backtest(book, { startDate: "2024-01-01", endDate: "2024-12-31" });
182
+
183
+ const opt = nt.optimization(book, {
184
+ startDate: "2022-01-01",
185
+ endDate: "2024-12-31",
186
+ });
187
+
188
+ const wf = nt.walkForward(book, {
189
+ globalStartDate: "2022-01-01",
190
+ globalEndDate: "2024-12-31",
191
+ foldCount: 4,
192
+ });
193
+ ```
194
+
195
+ Walk-forward uses `globalStartDate` / `globalEndDate` / `foldCount`, not
196
+ `startDate` / `endDate`. Each handle goes to its matching `create*` + `waitFor*`
197
+ pair.
198
+ </details>
199
+
200
+ <details>
201
+ <summary><b>Query the data lake</b></summary>
202
+
203
+ ```ts
204
+ const query = await nt.createLakeQuery(
205
+ {
206
+ query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
207
+ params: ["AAPL"],
208
+ limits: { maxRows: 10_000 },
209
+ },
210
+ { idempotencyKey: "aapl-daily-v1" },
211
+ );
212
+ const finished = await nt.waitForLakeQuery(query.id as string);
213
+ const manifest = await nt.getLakeQueryManifest(finished.id as string);
214
+ ```
215
+
216
+ Always parameterize with `?` rather than interpolating into the SQL string.
217
+ Stream parts with `downloadLakeQueryPart` instead of materializing large results.
218
+ </details>
219
+
220
+ ## Errors
221
+
222
+ All failures throw `NexusTradeApiError` with a stable `.status`, `.code`, and
223
+ `.message`. Branch on `.code`, never on message text.
224
+
225
+ | Code | What to do |
226
+ | --- | --- |
227
+ | `invalid_token` | Key missing/expired, or an OAuth JWT was used. Only `sk-` keys work here. |
228
+ | `insufficient_scope` | The key lacks `read` / `write` / `lake`. Do not retry. |
229
+ | `invalid_portfolio` | The book is malformed — fix the builders, do not retry as-is. |
230
+ | `idempotency_conflict` | Same key, different payload. Version the key. |
231
+ | `rate_limit_exceeded` | Back off and retry. |
232
+ | `operation_timeout` | Job still running. Re-poll the same id; never resubmit. |
233
+
234
+ `status === 0` means no HTTP status applies: the request never reached the API
235
+ (`transport_error`), or the reply failed an envelope check.
236
+
237
+ ## Out of scope
238
+
239
+ Not in this SDK. Do not attempt to reach them through it:
240
+
241
+ - **Screener** — MCP only.
242
+ - **Live trading and order placement** — deliberately excluded.
243
+ - **Agent runs** — the NexusTrade agent API is not exposed here yet.
244
+
245
+ ## Verifying your work
246
+
247
+ ```ts
248
+ // Assemble the book and inspect the JSON before spending money on a backtest.
249
+ console.log(JSON.stringify(book, null, 2));
250
+ ```
251
+
252
+ If you are editing this repository rather than consuming it:
253
+
254
+ ```bash
255
+ npm run typecheck && npm test
256
+ ```
package/CLAUDE.md ADDED
@@ -0,0 +1,7 @@
1
+ # CLAUDE.md
2
+
3
+ Claude Code reads this file automatically. The guidance for working in this
4
+ repository lives in **[AGENTS.md](AGENTS.md)** — a single source shared by every
5
+ agent tool, so the two can never drift.
6
+
7
+ Read AGENTS.md before writing NexusTrade strategy code.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Starks Technology, LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,283 @@
1
+ <div align="center">
2
+
3
+ <img src="https://nexustrade.io/logo192.jpeg" alt="NexusTrade" width="88" height="88">
4
+
5
+ # NexusTrade TypeScript SDK
6
+
7
+ **Author trading strategies in typed TypeScript. Backtest them on the engine that runs them live.**
8
+
9
+ [![npm](https://img.shields.io/npm/v/nexustrade.svg)](https://www.npmjs.com/package/nexustrade)
10
+ [![Node](https://img.shields.io/node/v/nexustrade.svg)](https://www.npmjs.com/package/nexustrade)
11
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
12
+ [![Deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
13
+
14
+ [Quickstart](#quickstart) · [Authoring](#authoring-strategies) · [Polling](#jobs-run-on-the-engine--you-poll) · [Lake SQL](#lake-sql) · [Auth](#authentication) · [Errors](#errors)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ```bash
21
+ npm install nexustrade
22
+ ```
23
+
24
+ **Zero runtime dependencies.** ESM and CommonJS builds ship together, with types.
25
+
26
+ ## Quickstart
27
+
28
+ ```ts
29
+ import {
30
+ NexusTradeClient, always, backtest, buy, portfolio, stockAsset, strategy,
31
+ } from "nexustrade";
32
+
33
+ const nt = new NexusTradeClient({
34
+ apiKey: "sk-...",
35
+ baseUrl: "https://nexustrade.io/api/v1",
36
+ });
37
+
38
+ const book = portfolio("Example", [
39
+ strategy("Buy SPY", always(), buy(stockAsset("SPY"), 100)),
40
+ ]);
41
+
42
+ const operation = await nt.createBacktest(
43
+ backtest(book, { startDate: "2024-01-01", endDate: "2024-12-31" }),
44
+ { idempotencyKey: "example-v1" },
45
+ );
46
+ const result = await nt.waitForBacktest(operation.id as string);
47
+ console.log(result.result);
48
+ ```
49
+
50
+ ## Authoring strategies
51
+
52
+ Every builder is generated from the same indicator specification the NexusTrade
53
+ engine runs, so a book is **valid by construction** rather than by convention.
54
+
55
+ TypeScript cannot overload comparison operators, so indicators compose through
56
+ `gt` / `gte` / `lt` / `lte` / `eq` / `neq` and `and` / `or`:
57
+
58
+ ```ts
59
+ import * as nt from "nexustrade";
60
+
61
+ const book = nt.portfolio("Momentum", [
62
+ nt.strategy(
63
+ "Rotate into strength",
64
+ nt.always(),
65
+ nt.dynamicRebalance({
66
+ universe: nt.universe("SP500"),
67
+ pipeline: [
68
+ nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200))),
69
+ nt.selectTop(nt.RSI(nt.CANDIDATE, 14), 10),
70
+ ],
71
+ weightIndicator: nt.RSI(nt.CANDIDATE, 14),
72
+ limit: 10,
73
+ deploymentPercent: 80,
74
+ }),
75
+ ),
76
+ ], { initialValue: 100_000 });
77
+ ```
78
+
79
+ <details>
80
+ <summary><b>What you can build</b> — 170+ generated builders</summary>
81
+
82
+ | Group | Examples |
83
+ | --- | --- |
84
+ | **Price & volume** | `Price` `OpeningPrice` `HighOfDay` `VWAP` `Volume` `GapPercentage` |
85
+ | **Technicals** | `SMA` `EMA` `RSI` `BollingerBand` `AverageTrueRange` `CrossAbove` |
86
+ | **Position state** | `PositionValue` `PositionPercentChange` `PositionMaxDrawdown` |
87
+ | **Portfolio state** | `PortfolioValue` `BuyingPower` `MaxDrawdown` `InitialValue` |
88
+ | **Fundamentals** | `Fundamental` `Economic` `DaysUntilEarnings` `IsIndexMember` `IsIndustry` |
89
+ | **Options** | `OptionDaysToExpiration` `OptionCollateral` `OptionUnrealizedPnL` `openOption` `closeOption` |
90
+ | **Actions** | `buy` `sell` `deposit` `withdraw` `alert` `dynamicRebalance` `rebalanceOption` |
91
+ | **Selection** | `filter` `selectTop` `selectPercentile` `universe` |
92
+ | **Logic** | `always` `atLeast` `atMost` `exactly` `fewerThan` `multi` `and` `or` |
93
+
94
+ Every builder is fully typed — your editor completes the whole surface.
95
+
96
+ </details>
97
+
98
+ ## Jobs run on the engine — you poll
99
+
100
+ `create*` enqueues work and returns immediately. It does **not** resolve when
101
+ results exist. There are no webhooks today.
102
+
103
+ Every job kind reports the same envelope, so one poller serves all of them:
104
+
105
+ ```ts
106
+ {
107
+ id: "op_...",
108
+ kind: "backtest", // backtest | optimization | walk_forward
109
+ status: "queued", // queued | running | completed | failed | cancelled
110
+ result: {...}, // present only once terminal
111
+ error: { code, message, retryable },
112
+ }
113
+ ```
114
+
115
+ ```ts
116
+ const finished = await nt.waitForBacktest(operation.id as string);
117
+ ```
118
+
119
+ | Option | Default | Meaning |
120
+ | --- | --- | --- |
121
+ | `timeoutSeconds` | `900` | Give up waiting (the job keeps running) |
122
+ | `pollIntervalSeconds` | `2` | First interval; backs off 1.5× |
123
+ | `maxPollIntervalSeconds` | `15` | Interval ceiling |
124
+ | `throwOnFailure` | `true` | Throw on `failed`/`cancelled` instead of returning |
125
+
126
+ A timeout throws `operation_timeout` and does **not** cancel the job — call the
127
+ waiter again with the same id rather than resubmitting.
128
+
129
+ **Batches.** `createBacktests` submits many in one request and returns one
130
+ operation each; `waitForBacktests(operations)` waits on all of them. Prefer it
131
+ over a loop: one request, one idempotency key, one rate-limit slot.
132
+
133
+ **Optimization and walk-forward** follow the identical shape:
134
+
135
+ ```ts
136
+ const study = await nt.createWalkForward(
137
+ nt.walkForward(book, {
138
+ globalStartDate: "2022-01-01",
139
+ globalEndDate: "2024-12-31",
140
+ foldCount: 4,
141
+ }),
142
+ { idempotencyKey: "wf-v1" },
143
+ );
144
+ await nt.waitForWalkForward(study.id as string);
145
+ ```
146
+
147
+ ## Lake SQL
148
+
149
+ Read-only SQL over the NexusTrade market-data lake, against the server-resolved
150
+ `lake.*` catalog. Results are durable Parquet parts rather than an implicitly
151
+ materialized in-memory array.
152
+
153
+ ```ts
154
+ const query = await nt.createLakeQuery(
155
+ {
156
+ query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
157
+ params: ["AAPL"],
158
+ limits: { maxRows: 10_000 },
159
+ },
160
+ { idempotencyKey: "aapl-daily-v1" },
161
+ );
162
+ const finished = await nt.waitForLakeQuery(query.id as string);
163
+ const manifest = await nt.getLakeQueryManifest(finished.id as string);
164
+ ```
165
+
166
+ Use the manifest plus `downloadLakeQueryPart` to stream results within your own
167
+ memory budget. NexusTrade picks a compatible backing engine for the referenced
168
+ tables; your SQL does not change when it does.
169
+
170
+ > The Python SDK additionally ships `nt.lake.sql(...)`, a DuckDB/pandas
171
+ > convenience layer over these same endpoints.
172
+
173
+ ## Authentication
174
+
175
+ Create a key at **[nexustrade.io/developers](https://nexustrade.io/developers)**
176
+ (Profile → API Keys). Keys start with `sk-` and are shown once.
177
+
178
+ ```ts
179
+ const nt = new NexusTradeClient({
180
+ apiKey: "sk-...",
181
+ baseUrl: "https://nexustrade.io/api/v1",
182
+ });
183
+ // or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL and:
184
+ const fromEnv = new NexusTradeClient();
185
+ ```
186
+
187
+ Both variables are also read from a **`.env` file** at or above the current
188
+ directory, so a local project works with no exports, no `dotenv` dependency, and
189
+ no `--env-file` flag:
190
+
191
+ ```bash
192
+ # .env
193
+ NEXUSTRADE_API_KEY=sk-...
194
+ NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1
195
+ ```
196
+
197
+ The real environment always wins — a `.env` value is used only when the variable
198
+ is absent, so a stale file can never override what you exported. Nothing is
199
+ written back to `process.env`. Opt out with `NEXUSTRADE_DISABLE_DOTENV=1`.
200
+
201
+ | Scope | Grants |
202
+ | --- | --- |
203
+ | `read` | `getBacktest`, `getOptimization`, `getWalkForward` |
204
+ | `write` | `createPortfolio`, `createBacktest(s)`, `createOptimization`, `createWalkForward` |
205
+ | `lake` | Lake catalog, query lifecycle, manifests, result parts |
206
+
207
+ A key missing the scope gets `403 insufficient_scope`.
208
+
209
+ > **OAuth is not accepted here.** NexusTrade's OAuth flow serves the MCP server.
210
+ > These endpoints take `sk-` API keys only; a bearer JWT is rejected with
211
+ > `401 invalid_token`.
212
+
213
+ **Transport hardening.** HTTPS is required (except loopback). The client refuses
214
+ cross-origin redirects, so the credential cannot be replayed to another host, and
215
+ refuses to follow a redirect on any non-GET request, so a redirect can never
216
+ re-submit a paid job. The key is held in a `#private` field and never appears in
217
+ a stringified client.
218
+
219
+ ## Idempotency
220
+
221
+ Every mutation takes a key. Reusing the same key with the same request returns
222
+ the original resource instead of launching a second paid job — so a retry after
223
+ a network failure is free.
224
+
225
+ ```ts
226
+ await nt.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });
227
+ ```
228
+
229
+ ## Errors
230
+
231
+ ```ts
232
+ import { NexusTradeApiError } from "nexustrade";
233
+
234
+ try {
235
+ await nt.createBacktest(handle, { idempotencyKey: "run-1" });
236
+ } catch (error) {
237
+ if (error instanceof NexusTradeApiError && error.code === "rate_limit_exceeded") {
238
+ // back off
239
+ }
240
+ throw error;
241
+ }
242
+ ```
243
+
244
+ | Status | Code | Meaning |
245
+ | --- | --- | --- |
246
+ | 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
247
+ | 403 | `insufficient_scope` | Key lacks `read`, `write`, or `lake` |
248
+ | 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
249
+ | 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
250
+ | 409 | `idempotency_conflict` | Key reused with a different payload |
251
+ | 404 | `not_found`, `operation_not_found` | Unknown or not yours |
252
+ | 429 | `rate_limit_exceeded` | Back off and retry |
253
+
254
+ `status` is `0` when no HTTP status describes the failure: `transport_error`
255
+ (never reached the API), `unsafe_redirect`, or an `invalid_response` envelope
256
+ check on an otherwise-successful reply.
257
+
258
+ ## Timeouts
259
+
260
+ `new HttpTransport({ timeoutSeconds })` (default 30) is a total wall-clock
261
+ deadline for one request. Neither it nor the poll timeout bounds how long a
262
+ *job* takes.
263
+
264
+ ## Scope
265
+
266
+ Portfolio drafting, backtesting, optimization, walk-forward studies, and
267
+ read-only SQL over the market-data lake, versioned under `/api/v1/nexustrade`.
268
+ The screener and live trading remain outside this surface.
269
+
270
+ ## Requirements
271
+
272
+ Node 18+ (uses the global `fetch`). Contributing: the test suite runs TypeScript
273
+ directly via `node --test`, which needs Node 22.6+ for type stripping. The
274
+ published `dist/` is plain JavaScript and has no such requirement.
275
+
276
+ ## Using this SDK with a coding agent
277
+
278
+ See **[AGENTS.md](AGENTS.md)** — the conventions, invariants, and recipes an
279
+ agent needs to write correct NexusTrade strategies on the first pass.
280
+
281
+ ## License
282
+
283
+ MIT