NexusTrade Financial MCP

NexusTrade TypeScript SDK

Author trading strategies in typed TypeScript. Backtest them on the engine that runs them live.

Quickstart · Authoring · Polling · Agents · Lake SQL · Auth · Errors

npm install nexustrade

Zero runtime dependencies. ESM and CommonJS builds ship together, with types.

MCP server

NexusTrade also exposes the platform as a hosted, remote Model Context Protocol server. Modern MCP clients connect directly to the production Streamable HTTP endpoint and discover NexusTrade OAuth automatically:

claude mcp add --transport http nexustrade https://nexustrade.io/api/mcp

Cursor and other remote-capable clients use:

{
  "mcpServers": {
    "nexustrade": {
      "url": "https://nexustrade.io/api/mcp"
    }
  }
}

For Claude Desktop and other stdio-only clients, use the established mcp-remote bridge—no clone or local NexusTrade server is required:

{
  "mcpServers": {
    "nexustrade": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://nexustrade.io/api/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

The live server exposes more than 120 tools across market research, portfolio construction, backtesting, optimization, walk-forward validation, managed compute, Aurora agents, paper trading, and controlled brokerage operations. Its creator-marketplace tools cover the full strategy adoption path:

• search_creators discovers public creators and their marketplace portfolios.
• subscribe_portfolio validates a monetized listing and returns a safe checkout preview; the user completes payment in NexusTrade, never through the MCP tool.
• fork_shared_portfolio creates a one-time editable copy of a marketplace strategy in a new or existing portfolio.
• copy_trade_shared continuously mirrors an accessible strategy into a paper or live portfolio at an explicit allocation.

See the developer guide, the utility tool reference, and the Aurora tool reference.

Research and historical results are not investment advice and do not guarantee future performance. Keep paper and live modes explicit. Tools that can affect portfolios, schedules, or brokerage orders remain subject to the authenticated account's NexusTrade permissions and approval controls.

Quickstart

import {
  NexusTradeClient,
  always,
  backtest,
  buy,
  portfolio,
  stockAsset,
  strategy,
} from "nexustrade";

const client = new NexusTradeClient();

const book = portfolio("Example", [
  strategy("Buy SPY", always(), buy(stockAsset("SPY"), 100)),
]);

const operation = await client.createBacktest(
  backtest(book, { startDate: "2024-01-01", endDate: "2024-12-31" }),
  { idempotencyKey: "example-v1" }
);
const result = await client.waitForBacktest(operation.id as string);
console.log(result.result);

Backtest operations may include warnings: string[] immediately after submission and again in the terminal result. Treat them as material caveats; they do not change a successful operation into a failure.

Collateral at risk

A terminal operation's result.statistics answers how much capital the run had on the line, not only what it returned. Two fields carry it, typed as BacktestCollateralStatistics:

Both are optional and may be null, and that absence is a real answer: a backtest run before the engine reported collateral has no value, which is not the same as a book that locked nothing. Display "not recorded" rather than $0 — a zero here reads as "this strategy risks nothing", the opposite of what an unpopulated field means. Do not substitute the portfolio's value either: a book risking a few thousand dollars would be reported as risking all of it.

Never reconstruct either number from cash - buyingPower. Buying power is clamped at both ends and carries an open credit-spread premium term, so the inversion breaks precisely on the heavily collateralised books this measures.

Authoring strategies

Every builder is generated from the same indicator specification the NexusTrade engine runs, so a book is valid by construction rather than by convention.

TypeScript cannot overload comparison operators, so indicators compose through gt / gte / lt / lte / eq / neq and and / or:

import * as nt from "nexustrade";

const book = nt.portfolio(
  "Momentum",
  [
    nt.strategy(
      "Rotate into strength",
      nt.always(),
      nt.dynamicRebalance({
        universe: nt.universe("SP500"),
        pipeline: [
          nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200))),
          nt.selectTop(nt.RSI(nt.CANDIDATE, 14), 10),
        ],
        weightIndicator: nt.RSI(nt.CANDIDATE, 14),
        limit: 10,
        deploymentPercent: nt.Value(80),
      })
    ),
  ],
  { initialValue: 100_000 }
);

Congressional-disclosure signals are native indicators too. House and Senate are combined unless you explicitly choose a chamber; amount metrics default to the disclosed lower bound and confirmed option disclosures are excluded by default:

const pelosiPurchases = nt.PoliticalTrades(
  nt.CANDIDATE,
  "Nancy Pelosi",
  "BuyAmount",
  90,
  "LowerBound",
  "Equity",
);

Use "" as the filer to include all members. BuyCount counts canonical purchase events, while BuyAmount measures disclosed magnitude. Select "Option" only when you want option-disclosure activity associated with the underlying ticker.

Order execution belongs to the strategy. Omit it for the backward-compatible Market default, use a fixed unit price for Buy/Sell, or set an option strategy's maximum net debit / minimum net credit:

nt.strategy("Buy SPY at my price", nt.always(), nt.buy(nt.stockAsset("SPY"), 10), {
  orderExecution: nt.limitOrder({
    price: nt.unitPriceLimit(500),
    workingTime: nt.goodForDay(),
  }),
});

nt.strategy("Sell the spread for $1.50 or better", nt.always(), optionAction, {
  orderExecution: nt.limitOrder({
    price: nt.minimumNetCredit(1.5),
    workingTime: nt.goodForMinutes(30),
  }),
});

An option net limit can also follow a position the strategy holds. Pass an indicator instead of a number and the engine evaluates it when the strategy fires. If it has no positive value at that moment, no order is placed:

nt.strategy("Sell the credit spread for the debit fill plus $0.50", whenDebitSpreadHeld, creditSpreadAction, {
  orderExecution: nt.limitOrder({
    price: nt.minimumNetCredit(
      nt.Plus(nt.OptionSpreadEntryPrice("SPX", "call", "long", "vertical"), nt.Value(0.5)),
    ),
    workingTime: nt.goodForDay(),
  }),
});

currentLimit() creates a quote-relative Limit for dynamic rebalance strategies. It keeps the no-worse-than-current-quote protection, but it is not a resting price target. Live option strategies must choose an explicit Limit policy.

Option selection and execution limits

strategy(..., { pendingOrderPolicy: "CancelConflictingBuys" }) enables backtest-only exit priority over conflicting pending buys. Omission preserves waiting. Paper and live deployment reject this opt-in because broker cancellation acknowledgements are not implemented. The setting also accepts explicit "Wait".

Builders describe drafts. Typechecking does not prove that the engine can execute every requested rule; the API validates complete portfolios and their conditions.

• Expiration selectors support a DTE window and nearest, middle, or furthest. middle selects the middle eligible expiration by index, not the expiration nearest a target such as 180 days. There is no monthly-only or quarterly-only expiration filter.
• rebalanceOption accepts renewBeforeDays (integer 1–90) and revisitDisclosedTargets. These maintain modeled political-disclosure option targets. The strategy must contain a NewPoliticalDisclosure condition for instrument Option with exactly one member ID. These fields do not implement a general close-and-replace roll for a trend strategy.
• For backtests, the job's feeConfig.OptionSlippageFraction sets quote-side fills: 0 uses the midpoint, 1 uses ask for buys and bid for sells, and the default is 0.5. This job setting does not add a last-trade fallback or define live order execution.
• Evaluation timing and order execution are separate. OpenClose schedules evaluations at session open and close; it does not itself carry a signal observed at close into an order at the next open. Explicit zero timing offsets and a gt(MinutesAfterOpen(), Value(0)) condition can restrict evaluations to the calendar session close. MinutesUntilClose counts down to 16:00 Eastern, so it cannot identify an early session close.

When authoring an approximation, describe the actual expiration policy, signal timing, fills, and replacement behavior. Backtest results describe that implementation, not the exact method it approximates.

Every builder is fully typed — your editor completes the whole surface.

Jobs run on the engine — you poll

create* enqueues work and returns immediately. It does not resolve when results exist. There are no webhooks today.

sequenceDiagram
    participant You
    participant SDK
    participant Engine

    You->>SDK: createBacktest(book)
    SDK->>Engine: POST (enqueue)
    Engine-->>SDK: id, status=queued
    SDK-->>You: operation (returns immediately)

    loop waitForBacktest — backoff 2s→15s
        SDK->>Engine: GET /operations/{id}
        Engine-->>SDK: status update
    end

    SDK-->>You: result (when completed)

    Note over You,Engine: Poll timeout throws operation_timeout.<br/>The job keeps running — call wait again with the same id.

Every job kind reports the same envelope, so one poller serves all of them:

{
  id: "op_...",
  kind: "backtest",          // backtest | optimization | walk_forward
  status: "queued",          // queued | running | completed | failed | cancelled
  result: {...},             // present only once terminal
  error: { code, message, retryable },
}

const finished = await client.waitForBacktest(operation.id as string);

A timeout throws operation_timeout and does not cancel the job — call the waiter again with the same id rather than resubmitting.

Transient network and HTTP 408/429/5xx polling failures retry the same operation at most twice consecutively, within the wait deadline. Persistent failures keep their original error code and operation ID; no new job is submitted.

Durable lake exports use a 900-second server budget by default (registered API keys may request up to 1800 seconds). waitForLakeQuery defaults to 1200 seconds to include queue time. Compute token budgets remain 90 seconds by default and 180 seconds maximum. A client wait timeout does not extend the server budget.

Batches. createBacktests submits many in one request and returns one operation each; waitForBacktests(operations) waits on all of them. Prefer it over a loop: one request, one idempotency key, one rate-limit slot.

Optimization and walk-forward follow the identical shape:

const study = await client.createWalkForward(
  nt.walkForward(book, {
    globalStartDate: "2022-01-01",
    globalEndDate: "2024-12-31",
    foldCount: 4,
  }),
  { idempotencyKey: "wf-v1" }
);
await client.waitForWalkForward(study.id as string);

Deploying a portfolio

Authoring and backtesting a book does not persist it. save writes it to your account; deploy starts running it.

const book = nt.portfolio("Momentum", [
  /* … */
]);

await book.save({ idempotencyKey: "momentum-v1" }); // persists; sets book.id
const deployment = await book.deploy(); // starts paper trading
await book.undeploy(); // stops it

save and deploy produce different ids, and the distinction matters. save persists a draft and sets book.id to it. deploy mints the real paper portfolio and returns its own portfolioId — deploying creates a portfolio rather than converting the draft into one, so the two ids coexist. Hold on to deployment.portfolioId for anything that reads live state; book.id addresses the draft.

deployment.portfolioId; // the running portfolio
deployment.deploymentType; // paper, unless you deployed an existing live one
deployment.outcome; // created | reactivated

Handle methods accept an optional transport; omitted, they resolve one from the environment. The same operations exist on the client — client.deploy(id), client.undeploy(id) — when you have an id rather than a handle.

await client.listPortfolios({ includePaper: true, includePositions: true });
await client.getPortfolio(portfolioId);

Editing a saved portfolio

updatePortfolio applies deterministic edits with no LLM in the path. The operations array is a typed union, so the compiler knows which fields each edit needs.

import type { PortfolioEditOperation } from "nexustrade";

const operations: PortfolioEditOperation[] = [
  { type: "rename", name: "AAPL Income" },
  {
    type: "replaceStrategy",
    targetStrategyId: strategyId, // or targetStrategyName
    strategyObject: nt.strategy(
      "Buy AAPL",
      nt.always(),
      nt.buy(nt.stockAsset("AAPL"), 25, "percent of portfolio"),
      {
        orderExecution: nt.limitOrder({
          price: nt.unitPriceLimit(150),
          workingTime: nt.goodForDay(),
        }),
      },
    ),
  },
];

await client.updatePortfolio(portfolioId, operations, {
  idempotencyKey: "aapl-limit-v1",
});

Prefer one updatePortfolio operation with a finished portfolio patch. It can combine strategies, deployment (frequency and timing), name, policy.stockEligibility, dividendPolicy, and alerts. Omitted fields retain their saved values. Draft starting capital and capabilities can change only before deployment. The existing strategy and rename operations remain supported. Every authored operation for the target in one call commits together; validation failure saves none of them. Reusing the same idempotency key replays the saved result. Deploy, undeploy, delete and automated approval remain separate account operations.

replaceStrategies replaces the whole set, so a strategy left out of the array is deleted. Carry unchanged strategies through verbatim, including the orderExecution each already has, or a working Limit silently reverts to Market. removeStrategies takes strategy ids from a fetched portfolio; removal by name is rejected.

Stock eligibility is part of what you author. Pass policy: { stockEligibility } to portfolio(...), or call setStockEligibility(...) on a handle, to set market-cap bounds, an industry filter, missingMarketCapBehavior, or shareClassBehavior. Omitted fields take the defaults. A GOOG/GOOGL pairs book needs ALL_CLASSES, because the default keeps one share class per company:

const pair = portfolio("GOOG/GOOGL pair", strategies, {
  policy: { stockEligibility: { shareClassBehavior: "ALL_CLASSES" } },
});

Automated trading is never authored. Only the owner enables it, in Portfolio Settings, and a policy that names automatedApproval is refused before it is sent. Fetched handles include a typed, read-only policy snapshot; saving or deploying a copy of one carries its stock eligibility and nothing else.

listPortfolios filters with includePaper, includeLive, includeInactive, includeChatPortfolios, search, limit, and page. includePositions defaults off when search is set.

A portfolio you create here is always paper, and minting a live one still happens in the web app. Orders and brokerage status are reachable from here; see Live trading.

But deploy can start live trading. Given the id of a portfolio that is already deployed, it reactivates that portfolio as whatever it already is — so client.deploy(id) on a paused live portfolio resumes live trading against the connected brokerage, and includeLive: true above will hand you such an id. Check deployment.deploymentType before treating a deploy as simulated.

Live trading

Live trading needs a brokerage linked to your account. Linking is an OAuth redirect, so an API key cannot complete it — a human opens the URL.

await client.listBrokerages();
// [{ brokerage: "Alpaca", connected: false,
//    connectUrl: "https://nexustrade.io/live-trading" }, ...]

await client.connectBrokerage("Alpaca"); // logs the URL, waits until connected

connectBrokerage waits by default only when stdout is a TTY. In CI, cron, or run_compute it rejects with brokerage_not_connected immediately, with the URL in the message, rather than stalling for five minutes in front of nobody. Pass { wait: true } or { wait: false } to force either.

A live-only listing that comes back empty rejects with the same error rather than an empty array, since an empty array says nothing about why:

await client.listPortfolios({ includeLive: true, includePaper: false });
// NexusTradeApiError: brokerage_not_connected: No live portfolios, and no
// brokerage is connected. Connect one at https://nexustrade.io/live-trading

Orders

const result = await client.createOrders(
  portfolioId,
  [
    {
      asset: { name: "SPY", type: "STOCK", symbol: "SPY" },
      side: "BUY",
      quantity: 10,
      orderType: "MARKET",
    },
  ],
  { idempotencyKey: "rebalance-2024-04-01" }
);

// Dollar notional (stock/crypto only — options require contract quantity):
await client.createOrders(
  portfolioId,
  [
    {
      asset: { name: "AAPL", type: "STOCK", symbol: "AAPL" },
      side: "BUY",
      amount: 500,
      orderType: "MARKET",
    },
  ],
  { idempotencyKey: "buy-aapl-500" }
);

Paper orders are accepted immediately. Live orders are staged for approval and are never sent to a broker by this call.

if (result.requiresApproval) {
  console.log("nothing has traded yet — approve at", result.approvalUrl);
}

There is no argument, scope, or flag that submits a live order without approval. The brokerage boundary refuses an unapproved live order regardless of what any caller asks for, so this is a property of the system rather than a promise made by this method. At most 50 orders per request.

Listing requires a read key; cancellation requires a trade key. Both require a registered account and are unavailable inside compute sandboxes.

const page = await client.listOrders({
  portfolioId,
  statuses: ["Accepted", "Pending User Approval"],
  page: 1,
  limit: 50,
});
console.log(page.orders, page.totalPages);

// Cancel only explicit IDs you selected from the listing.
const cancellation = await client.cancelOrders(["ORDER_ID"], {
  portfolioId,
  idempotencyKey: "cancel-order-v1",
});
console.log(cancellation.canceled, cancellation.rejected);

Listing defaults to Accepted and Pending User Approval. Request Pending, Partially Filled, Filled, or Canceled explicitly to inspect other states. Pages are 1-based, with a default limit of 50 and a maximum of 100. The response includes orders, total, returned, page, limit, totalPages, truncated, and ignoredStatuses; unknown statuses are reported there when valid statuses remain, and a wholly invalid filter raises an error. Set includeRebalanceOrders: true for an additional page of pending rebalance actions. Their IDs are separate from order IDs and cannot be passed to cancellation.

Cancellation accepts at most 50 IDs and returns canceled and rejected arrays. Each success includes orderId, mode (db, broker, or already_canceled), and canceledOrderIds, including sibling legs canceled together. Each rejection includes orderId and reason. Inspect both arrays: HTTP success does not mean every order was canceled. The optional portfolio ID guards against canceling an order from another portfolio. Reuse the same idempotency key and identical payload when retrying; an already canceled order returns already_canceled.

The same cancellation rules as MCP/REST apply: Accepted and Pending User Approval orders can be canceled; Pending, Partially Filled, and Filled orders are rejected. Rebalance children must be managed through their parent action. Live orders with a broker ID invoke broker cancellation. Creation still stages live orders for human approval.

Your own data

A custom data source is a time series you own — sentiment counts, a proprietary factor, anything the platform does not already carry. Create one, then reference it from a strategy with CustomIndicator.

const series = await client.createCustomIndicator(
  {
    name: "WSB NVDA Mentions",
    scope: "asset",
    description: "Daily r/wallstreetbets mentions",
    pointKind: "observation",
    points: [
      { timestamp: "2024-04-01", value: 152, ticker: "NVDA" },
      { timestamp: "2024-04-02", value: 90, ticker: "NVDA" },
    ],
  },
  { idempotencyKey: "wsb-mentions-v1" }
);

const busy = nt.gt(
  nt.CustomIndicator(nt.stockAsset("NVDA"), String(series.customIndicatorId)),
  100
);
const book = nt.portfolio("Attention", [
  nt.strategy("Buy the buzz", busy, nt.buy(nt.stockAsset("NVDA"), 25)),
]);

scope is "global" (one series) or "asset" (one series per ticker, so every point needs a ticker). It cannot be changed after creation.

Declare pointKind whenever the time semantics are known: observation for point-in-time samples, period_aggregate plus aggregatePeriod (1d, 1w, 1mo, or 1q) for closed-period values, and disclosed for values with an explicit publication time on every row. The SDK applies this contract before both inline and large-upload writes. A same-day date-only observation becomes an explicit same-day UTC instant instead of shifting to the next calendar day.

Size is not a constraint. points is unlimited. A batch that fits the request goes with it; a larger one is uploaded to storage and validated before the call resolves. Either way the returned indicator reflects what actually landed, and an upload that fails validation rejects rather than reporting success.

Growing a series. Append to the same id every run:

await client.appendCustomIndicatorPoints(
  String(series.customIndicatorId),
  [{ timestamp: "2024-04-03", value: 118, ticker: "NVDA" }],
  { idempotencyKey: "wsb-mentions-2024-04-03" }
);

Creating a fresh series per run splits the history into fragments no strategy can read. Re-sending an identical batch is safe — the duplicate is not written twice.

Points accept timestamp, value, ticker, assetType, and availableAt — camelCase or snake_case, with Date objects allowed. Set availableAt when a value became knowable later than it is dated: an earnings figure stamped to quarter-end but published weeks after. An unrecognized field throws rather than being silently dropped.

To hand over a file you already have on disk, createCustomIndicatorUpload / completeCustomIndicatorUpload / waitForCustomIndicatorUpload expose the three steps directly. CSV, JSON, and JSONL up to 100 MB.

Agent runs

Every other job is fire-and-poll. Agents are not — three states (pending_plan_approval, pending_action_approval, awaiting_user_input) cannot advance without you. Iterate the run and answer when it blocks:

sequenceDiagram
    participant You
    participant Run as AgentRun
    participant Engine

    You->>Run: createAgent(prompt)
    Run->>Engine: POST /agents
    Engine-->>Run: run id

    loop for await (const event of run)
        Run->>Engine: GET events (cursor)
        Engine-->>Run: new events

        alt event.needsApproval
            Run-->>You: plan or action awaiting approval
            You->>Run: approve() or reject()
            Run->>Engine: POST approval
        else event.needsInput
            Run-->>You: awaiting user input
            You->>Run: say("...")
            Run->>Engine: POST message
        else
            Run-->>You: event.text
        end
    end

    Run-->>You: terminal

    Note over You,Engine: Without approve/say, the run stalls and bills.<br/>Reattach later with attachAgent(run.id).

const run = await client.createAgent("Find momentum names in the S&P 500", {
  idempotencyKey: "momentum-scan-v1",
  costCeilingUsd: 20,
});
for await (const event of run) {
  console.log(event.text);
  if (event.needsApproval) await run.approve();
  if (event.needsInput) await run.say("Focus on tech");
}

Lake SQL

Read-only SQL over the NexusTrade market-data lake, against the server-resolved lake.* catalog. Results are durable Parquet parts rather than an implicitly materialized in-memory array.

flowchart LR
    A[createLakeQuery] --> B[waitForLakeQuery]
    B --> C[getLakeQueryManifest]
    C --> D[downloadLakeQueryPart]
    D --> E[Stream Parquet within your memory budget]

const query = await client.createLakeQuery(
  {
    query:
      "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
    params: ["AAPL"],
    limits: { maxRows: 10_000 },
  },
  { idempotencyKey: "aapl-daily-v1" }
);
const finished = await client.waitForLakeQuery(query.id as string);
const manifest = await client.getLakeQueryManifest(finished.id as string);

Natural language

Describe the screen instead of writing the SQL. The server generates it, validates it against the same lake.* catalog the engine reads, executes it, and hands back both the rows and the statement.

const screen = await client.createNlScreen(
  "technology stocks with a market cap over 100 billion and a PE under 30"
);
const done = await client.waitForNlScreen(screen.id as string);

const result = done.result as Record<string, unknown>;
console.log(result.rows);
console.log(result.sql); // always check the SQL — it is model-generated

returnQuery defaults to true because the SQL is the audit trail: without it the rows are a number you cannot re-derive. It is returned on failure whatever you pass, since a rejected query is the most useful thing to read.

Branch on result.outcome, not on status alone:

This method spends LLM credits. The structured lake API below does not.

Use the manifest plus downloadLakeQueryPart to stream results within your own memory budget. NexusTrade picks a compatible backing engine for the referenced tables; your SQL does not change when it does.

The Python SDK additionally ships nt.lake.sql(...), a DuckDB/pandas convenience layer over these same endpoints.

Managed watchlist universes

nt.updateWatchlist({watchlistKey, memberId, instrument, amountBasis, chamber, output}) maintains a visible managed list from PoliticalRemainingPurchases. Its strategy has no condition and places no orders. nt.watchlistUniverse(watchlistKey) selects that producer's committed membership for a separate DynamicRebalance in the same portfolio. Each key has one producer and may have several consumers. Other action types cannot consume this universe.

const producer = nt.updateWatchlist({
  watchlistKey: "pelosi-holdings", memberId: "P000197", instrument: "Equity",
  amountBasis: "Midpoint", chamber: "All",
  output: {name: "Pelosi disclosed holdings", purpose: "Follow public holdings",
    alertSettings: {onChange: true, inApp: true, email: true, briefCadence: "weekly"}},
});
const consumerUniverse = nt.watchlistUniverse("pelosi-holdings");

output supplies initial name, purpose and alerts. Subsequent user renames and settings remain authoritative. Live and paper consumers wait for durable list publication; backtests keep membership local to the run and never edit the user's visible list. Discovery and data loads remain full, so this does not establish a performance saving. Omitted amount basis uses LowerBound.

updateInstitutionalWatchlist follows an exact manager's latest publicly available complete equity book. updateInsiderWatchlist selects qualifying positive purchases by first public availability, with optional owner, issuer, and role scope. Both use the same publication and consumer contract:

const manager = nt.updateInstitutionalWatchlist({
  watchlistKey: "berkshire-equities", managerCik: "1067983",
});
const insider = nt.updateInsiderWatchlist({
  watchlistKey: "insider-purchases", windowDays: 90, role: "OfficerOrDirector",
});
const screen = nt.updateScreenerWatchlist({
  watchlistKey: "berkshire-top-20", refreshMinutes: 1440,
  columns: [nt.screenColumn("price", nt.screenPrice()),
    nt.screenColumn("holding", nt.screenDisclosure(manager.source))],
  filter: nt.screenAll(nt.screenCompare("price", "Gte", 5),
    nt.screenCompare("holding", "Gt", 0)),
  selection: nt.screenTop("holding", 20),
});
const screenUniverse = nt.watchlistUniverse("berkshire-top-20");

The screen evaluates on its scheduled cadence and reuses accepted membership between refreshes. Missing facts remain unknown. screenAny composes OR rules; screenPercentile ranks the filtered candidates with known rank values. screenBarVolume and screenBarDollarVolume require a completed historical bar; live quotes do not supply those metrics in this release. Price and disclosure metrics support live screens. Failed coverage or publication blocks new allocation while consumers retain their exit behavior. Screen execution uses in-memory DuckDB; no local database volume or LLM call is required for refreshes.

Complete method reference

Every public method on NexusTradeClient. A test in this package fails if one is missing here, so this list cannot drift from the code.

Live trading and orders

Portfolios

Backtests

Optimization and walk-forward

Custom data sources

Agent runs

Lake SQL

Natural language

Client construction

PortfolioHandle — returned by the portfolio(...) builder and by getPortfolio / listPortfolios.

Authentication

An API key is optional. With no key, the first API operation lazily creates a real unregistered NexusTrade workspace and applies stricter request, backtest, and AI limits. Anonymous workspaces can create, edit, and fork portfolios, launch backtests, and use the programmatic agent/chat surface. Every optimization operation—including genetic and systematic sweep launches, result reads, reruns, promotion, and out-of-sample workflows—requires a registered API key. Export the workspace's opaque token if the work must survive a new process:

const guest = new NexusTradeClient();
await guest.listPortfolios();
const token = guest.exportWorkspaceSession();

const resumed = new NexusTradeClient({ workspaceSession: token });

An expired explicit workspace token raises NexusTradeWorkspaceSessionExpiredError; the SDK never creates a replacement workspace that would make saved work appear deleted.

Registered users can create a key at nexustrade.io/developers (Profile → API Keys). Keys start with sk- and are shown once. When both credentials are provided, registered Authorization takes precedence and the workspace header is not sent.

const client = new NexusTradeClient({
  apiKey: "sk-...",
  baseUrl: "https://nexustrade.io/api/v1",
});
// or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL and:
const fromEnv = new NexusTradeClient();

Both variables are also read from a .env file at or above the current directory, so a local project works with no exports, no dotenv dependency, and no --env-file flag:

# .env
NEXUSTRADE_API_KEY=sk-...
NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1

The real environment always wins — a .env value is used only when the variable is absent, so a stale file can never override what you exported. Nothing is written back to process.env. Opt out with NEXUSTRADE_DISABLE_DOTENV=1.

A key missing the scope gets 403 insufficient_scope.

OAuth is not accepted here. NexusTrade's OAuth flow serves the MCP server. These endpoints take sk- API keys only; a bearer JWT is rejected with 401 invalid_token.

Transport hardening. HTTPS is required (except loopback). The client refuses cross-origin redirects, so the credential cannot be replayed to another host, and refuses to follow a redirect on any non-GET request, so a redirect can never re-submit a paid job. The key is held in a #private field and never appears in a stringified client.

Idempotency

Every mutation takes a key. Reusing the same key with the same request returns the original resource instead of launching a second paid job — so a retry after a network failure is free.

await client.createBacktest(handle, { idempotencyKey: "momentum-2024-v1" });

Errors

import { NexusTradeApiError } from "nexustrade";

try {
  await client.createBacktest(handle, { idempotencyKey: "run-1" });
} catch (error) {
  if (
    error instanceof NexusTradeApiError &&
    error.code === "rate_limit_exceeded"
  ) {
    // back off
  }
  throw error;
}

status is 0 when no HTTP status describes the failure: transport_error (never reached the API), unsafe_redirect, or an invalid_response envelope check on an otherwise-successful reply.

Timeouts

new HttpTransport({ timeoutSeconds }) (default 30) is a total wall-clock deadline for one request. Neither it nor the poll timeout bounds how long a job takes.

Scope

Portfolio drafting, backtesting, optimization, walk-forward studies, and read-only SQL over the market-data lake, versioned under /api/v1/nexustrade. The full surface requires a registered API key; anonymous workspaces are limited to portfolio authoring/forking, backtests, and programmatic agent/chat calls. The screener and creating a live deployment remain outside this surface. Orders are reachable, but a live order is only ever staged for human approval — never submitted. deploy and undeploy act on whatever an existing id already is, live included.

Requirements

Node 18+ (uses the global fetch). Contributing: the test suite runs TypeScript directly via node --test, which needs Node 22.6+ for type stripping. The published dist/ is plain JavaScript and has no such requirement.

Using this SDK with a coding agent

See AGENTS.md — the conventions, invariants, and recipes an agent needs to write correct NexusTrade strategies on the first pass.

License

MIT