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 same indicator specification the NexusTrade engine executes, so a book assembled from them is structurally valid before it ever leaves the process.

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));

Available: gt gte lt lte eq neq, combined with and / or.

3. Every mutation needs an idempotency key, and it must be deterministic.

Jobs cost money. A retry with the same key returns the original operation; a retry with a new key launches a second paid job.