nexustrade-ts: Instructions file for Codex

AGENTS.md — NexusTrade TypeScript SDK

Instructions for coding agents (Claude Code, Cursor, Codex, and friends) writing NexusTrade strategies with this package. Humans: README.md is the friendlier read.

What this package is

A typed client plus ~170 generated builders for authoring trading strategies. The builders are generated from the engine's indicator specification. They describe draft payloads; the API still validates complete portfolios and their conditions. A builder's existence does not guarantee support for every trading method. Read the option selection and execution limits before claiming exact option timing, expiration selection, or rolling behavior.

author a portfolio  →  submit a job  →  poll until terminal  →  read result

Setup

npm install nexustrade
export NEXUSTRADE_API_KEY=sk-...
export NEXUSTRADE_API_BASE_URL=https://nexustrade.io/api/v1

import { NexusTradeClient } from "nexustrade";
const client = new NexusTradeClient();   // reads the environment

Keys come from https://nexustrade.io/developers. Never hardcode one into a file you write; read it from the environment. Node 18+.

Rules that matter

1. Use the builders. Never hand-write the JSON.

// Right — validated shape, correct wire names
nt.buy(nt.stockAsset("SPY"), 100);

// Wrong — silently diverges from the engine's schema
{ type: "Buy", targetAsset: { symbol: "SPY" }, amount: 100 };

The client accepts both a builder result and a plain object, so a wrong literal will typecheck. Prefer the builder.

2. Comparisons are functions, not operators.

TypeScript cannot overload >, so indicator comparisons go through helpers. This is the single most common mistake in this SDK.

// Right
nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200)));

// Wrong — compares object references, always nonsense
nt.filter(nt.Price(nt.CANDIDATE) > nt.SMA(nt.CANDIDATE, 200));