nexustrade 5.2.0 → 5.3.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/README.md +134 -1
- package/dist/cjs/client.js +97 -0
- package/dist/cjs/congress.js +29 -0
- package/dist/cjs/generated/ntSdk.generated.js +133 -133
- package/dist/esm/client.d.ts +60 -1
- package/dist/esm/client.js +97 -0
- package/dist/esm/congress.d.ts +390 -0
- package/dist/esm/congress.js +26 -0
- package/dist/esm/generated/ntSdk.generated.d.ts +133 -133
- package/dist/esm/generated/ntSdk.generated.js +133 -133
- package/dist/esm/index.d.ts +2 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -771,6 +771,120 @@ Branch on `result.outcome`, not on status alone:
|
|
|
771
771
|
|
|
772
772
|
This method spends LLM credits.
|
|
773
773
|
|
|
774
|
+
## Congressional trades
|
|
775
|
+
|
|
776
|
+
House and Senate stock disclosures (STOCK Act periodic transaction reports) are
|
|
777
|
+
readable as data, separately from the `PoliticalTrades` strategy indicators.
|
|
778
|
+
The client calls NexusTrade's REST API at `/api/political-disclosures`, on the
|
|
779
|
+
same host as the SDK routes.
|
|
780
|
+
|
|
781
|
+
Seven reads work with no API key and no workspace, so a bare client is enough:
|
|
782
|
+
|
|
783
|
+
```ts
|
|
784
|
+
import { NexusTradeClient } from "nexustrade";
|
|
785
|
+
|
|
786
|
+
const client = new NexusTradeClient(); // no API key needed for these reads
|
|
787
|
+
|
|
788
|
+
const page = await client.listCongressionalTrades({
|
|
789
|
+
ticker: "NVDA",
|
|
790
|
+
fromDate: "2026-01-01",
|
|
791
|
+
limit: 5,
|
|
792
|
+
});
|
|
793
|
+
for (const trade of page.data.trades) {
|
|
794
|
+
console.log(
|
|
795
|
+
trade.availableAt, // public from here: the date to trade from
|
|
796
|
+
trade.filerName,
|
|
797
|
+
trade.action,
|
|
798
|
+
trade.ticker,
|
|
799
|
+
trade.amountBracket
|
|
800
|
+
);
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
// Next page: the same filters plus the cursor.
|
|
804
|
+
if (page.data.nextCursor) {
|
|
805
|
+
await client.listCongressionalTrades({
|
|
806
|
+
ticker: "NVDA",
|
|
807
|
+
fromDate: "2026-01-01",
|
|
808
|
+
limit: 5,
|
|
809
|
+
cursor: page.data.nextCursor,
|
|
810
|
+
});
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
const pelosi = await client.getPolitician("nancy-pelosi");
|
|
814
|
+
console.log(pelosi.data.politician.displayName, pelosi.data.profile.summary);
|
|
815
|
+
|
|
816
|
+
const board = await client.getCongressionalLeaderboard({ limit: 5 });
|
|
817
|
+
console.log(board.best.map((row) => [row.displayName, row.excessReturn]));
|
|
818
|
+
|
|
819
|
+
const slowest = await client.listCongressionalFilingLatency({ limit: 5 });
|
|
820
|
+
console.log(slowest.data.map((row) => [row.displayName, row.medianDaysToPublic]));
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
**Trade from `availableAt`.** Each trade carries `transactionDate` (when the
|
|
824
|
+
member traded) and `availableAt` (when the disclosure became public). The gap is
|
|
825
|
+
usually weeks. A backtest or signal that acts on `transactionDate` uses
|
|
826
|
+
information nobody outside Congress had, so every date filter here
|
|
827
|
+
(`fromDate`, `toDate`, `asOf`) is compared against a public date, never the trade
|
|
828
|
+
date. `fromDate`, `toDate` and `sort` use `firstAvailableAt`, the day the first
|
|
829
|
+
version of a disclosure became public. It equals `availableAt` unless the
|
|
830
|
+
disclosure was later amended.
|
|
831
|
+
|
|
832
|
+
Filters, all optional: `q` (free text; a phrase naming exactly one member
|
|
833
|
+
resolves to that member), `filerKey` (Bioguide ID such as `P000197`), `ticker`,
|
|
834
|
+
`chamber` (`house`, `senate`, `all`), `action` (`purchase`, `sale`, `exchange`,
|
|
835
|
+
`unmarked`, `all`), `instrument` (`equity`, `option`, `fund`, `bond`, `other`,
|
|
836
|
+
`all`), `sort` (`newest`, `oldest`), `fromDate` / `toDate` (`YYYY-MM-DD`), `asOf` (ISO
|
|
837
|
+
timestamp; reads the record as it was publicly known then), `cursor` and
|
|
838
|
+
`limit` (1 to 100, default 25). `toDate` defaults to the day of `asOf`, which
|
|
839
|
+
defaults to the dataset's last update (`dataUpdatedAt`), and `fromDate` defaults
|
|
840
|
+
to 29 days before `toDate`, so with no dates the feed covers the 30 days ending
|
|
841
|
+
on the last update day. `instrument` defaults to `equity`. Amounts are the disclosed brackets (`amountLow`,
|
|
842
|
+
`amountHigh`), never exact figures.
|
|
843
|
+
|
|
844
|
+
Each method takes the filters its route reads. The summary takes no `sort`,
|
|
845
|
+
`cursor` or `limit`. The filer, filing latency and volume lists take `limit`
|
|
846
|
+
but no `sort` or `cursor`. The member records (`getPolitician`,
|
|
847
|
+
`getCongressionalFiler`) take `ticker`, `action`, `instrument`, `sort`, the
|
|
848
|
+
dates, `cursor` and `limit`; with neither date they cover the whole record,
|
|
849
|
+
2012-01-01 to today, and `instrument` defaults to `all`.
|
|
850
|
+
|
|
851
|
+
Every read except the leaderboard and the copy bot returns an envelope:
|
|
852
|
+
`data`, plus `snapshotId`, `asOf`, `dataUpdatedAt`, `stale`, `cache`,
|
|
853
|
+
`coverage` and the applied `filters`.
|
|
854
|
+
|
|
855
|
+
The detail and coverage reads need an API key with the `read` scope. Without
|
|
856
|
+
one they raise `NexusTradeApiError` with status 401. The client sends its key
|
|
857
|
+
on every read when it holds one, so a key that is supplied must be valid and
|
|
858
|
+
have the `read` scope even on the calls that need no key.
|
|
859
|
+
|
|
860
|
+
```ts
|
|
861
|
+
const authed = new NexusTradeClient({ apiKey: process.env.NEXUSTRADE_API_KEY });
|
|
862
|
+
|
|
863
|
+
const detail = await authed.getCongressionalTrade("house:20035831:0");
|
|
864
|
+
console.log(detail.data.current, detail.data.history.length);
|
|
865
|
+
|
|
866
|
+
const coverage = await authed.getCongressionalCoverage();
|
|
867
|
+
console.log(coverage.data.events, coverage.data.latestAvailableAt);
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
| Method | Endpoint | API key |
|
|
871
|
+
| --- | --- | --- |
|
|
872
|
+
| `listCongressionalTrades` | `GET /trades` | No |
|
|
873
|
+
| `getCongressionalTradeSummary` | `GET /summary` | No |
|
|
874
|
+
| `getCongressionalLeaderboard` | `GET /leaderboard` | No |
|
|
875
|
+
| `listCongressionalFilingLatency` | `GET /filer-latency` | No |
|
|
876
|
+
| `listCongressionalTradeVolume` | `GET /filer-volume` | No |
|
|
877
|
+
| `getPolitician` | `GET /politicians/:id` | No |
|
|
878
|
+
| `getPoliticianBot` | `GET /politicians/:id/bot` | No |
|
|
879
|
+
| `listCongressionalFilers` | `GET /filers` | Yes |
|
|
880
|
+
| `getCongressionalFiler` | `GET /filers/:filerKey` | Yes |
|
|
881
|
+
| `getCongressionalTrade` | `GET /trades/:eventId` | Yes |
|
|
882
|
+
| `getCongressionalFiling` | `GET /filings/:chamber/:docId` | Yes |
|
|
883
|
+
| `getCongressionalCoverage` | `GET /coverage` | Yes |
|
|
884
|
+
|
|
885
|
+
`getPoliticianBot` returns a `sharedPortfolioId` you can pass to
|
|
886
|
+
`forkPublicPortfolio` to copy that member's bot into your workspace.
|
|
887
|
+
|
|
774
888
|
## Managed watchlist universes
|
|
775
889
|
|
|
776
890
|
`nt.updateWatchlist({watchlistKey, memberId, instrument, amountBasis, chamber, output})`
|
|
@@ -923,6 +1037,23 @@ is missing here, so this list cannot drift from the code.
|
|
|
923
1037
|
| `exportWorkspaceSession()` | Export an anonymous workspace for later use |
|
|
924
1038
|
| `importWorkspaceSession(token)` | Resume an existing anonymous workspace |
|
|
925
1039
|
|
|
1040
|
+
**Congressional trades**
|
|
1041
|
+
|
|
1042
|
+
| Method | Purpose |
|
|
1043
|
+
| --- | --- |
|
|
1044
|
+
| `listCongressionalTrades({ ticker, fromDate, cursor, … })` | Disclosed trades, newest first (no API key) |
|
|
1045
|
+
| `getCongressionalTradeSummary({ … })` | Purchase and sale totals over the same filters (no API key) |
|
|
1046
|
+
| `getCongressionalLeaderboard({ limit })` | Members ranked by their copy bot against SPY (no API key) |
|
|
1047
|
+
| `listCongressionalFilingLatency({ … })` | Days from trade to public disclosure per member (no API key) |
|
|
1048
|
+
| `listCongressionalTradeVolume({ … })` | Disclosed dollar volume per member (no API key) |
|
|
1049
|
+
| `getPolitician(id, { … })` | One member's profile and trading record (no API key) |
|
|
1050
|
+
| `getPoliticianBot(id)` | A member's copy bot and cached backtest (no API key) |
|
|
1051
|
+
| `listCongressionalFilers({ … })` | Members with matching disclosures (API key) |
|
|
1052
|
+
| `getCongressionalFiler(filerKey, { … })` | One member's record by Bioguide ID (API key) |
|
|
1053
|
+
| `getCongressionalTrade(eventId, { asOf })` | One disclosure with its amendment history (API key) |
|
|
1054
|
+
| `getCongressionalFiling(chamber, docId)` | One source filing and its trades (API key) |
|
|
1055
|
+
| `getCongressionalCoverage()` | How much of the public record the dataset holds (API key) |
|
|
1056
|
+
|
|
926
1057
|
**PortfolioHandle** — returned by the `portfolio(...)` builder and by
|
|
927
1058
|
`getPortfolio` / `listPortfolios`.
|
|
928
1059
|
|
|
@@ -1063,7 +1194,9 @@ configures its own timeout, so passing both throws.
|
|
|
1063
1194
|
|
|
1064
1195
|
Portfolio drafting, backtesting, optimization, walk-forward studies, and the
|
|
1065
1196
|
natural-language screener, versioned under `/api/v1/nexustrade`. Market data is
|
|
1066
|
-
available only through the natural-language screener.
|
|
1197
|
+
available only through the natural-language screener. Congressional trade
|
|
1198
|
+
disclosures are the exception: they are read from `/api/political-disclosures`
|
|
1199
|
+
(see [Congressional trades](#congressional-trades)).
|
|
1067
1200
|
The full surface requires a registered API key; anonymous workspaces are limited
|
|
1068
1201
|
to portfolio authoring/forking, backtests, and programmatic agent/chat calls.
|
|
1069
1202
|
Creating a live deployment remains outside this surface.
|
package/dist/cjs/client.js
CHANGED
|
@@ -12,6 +12,7 @@ exports.clientTransport = clientTransport;
|
|
|
12
12
|
exports.createCustomIndicator = createCustomIndicator;
|
|
13
13
|
exports.createPortfolio = createPortfolio;
|
|
14
14
|
const agent_ts_1 = require("./agent.js");
|
|
15
|
+
const congress_ts_1 = require("./congress.js");
|
|
15
16
|
const env_ts_1 = require("./env.js");
|
|
16
17
|
const portfolio_ts_1 = require("./portfolio.js");
|
|
17
18
|
/** Boundary adapter: builder output is JSON by construction. */
|
|
@@ -162,6 +163,15 @@ function sameOrigin(left, right) {
|
|
|
162
163
|
function supportsUpload(transport) {
|
|
163
164
|
return typeof transport.putBytes === "function";
|
|
164
165
|
}
|
|
166
|
+
function supportsPublicApi(transport) {
|
|
167
|
+
return typeof transport.getPublicApi === "function";
|
|
168
|
+
}
|
|
169
|
+
async function readPublicApi(transport, path) {
|
|
170
|
+
if (!supportsPublicApi(transport)) {
|
|
171
|
+
throw new NexusTradeApiError(exports.NO_HTTP_STATUS, "unsupported_transport", "Congressional trade reads require HttpTransport.getPublicApi.");
|
|
172
|
+
}
|
|
173
|
+
return (await transport.getPublicApi(path));
|
|
174
|
+
}
|
|
165
175
|
function assertValidApiKey(apiKey) {
|
|
166
176
|
const invalid = typeof apiKey !== "string" ||
|
|
167
177
|
apiKey.length === 0 ||
|
|
@@ -274,6 +284,10 @@ async function apiErrorFromResponse(response) {
|
|
|
274
284
|
if (body.message)
|
|
275
285
|
message = String(body.message);
|
|
276
286
|
}
|
|
287
|
+
else if (typeof decoded.message === "string" && decoded.message) {
|
|
288
|
+
// Public REST routes answer `{ message }` with no error envelope.
|
|
289
|
+
message = decoded.message;
|
|
290
|
+
}
|
|
277
291
|
}
|
|
278
292
|
catch {
|
|
279
293
|
// Non-JSON error bodies keep the transport-level code/message.
|
|
@@ -290,6 +304,9 @@ function workspaceSessionUrl(baseUrl) {
|
|
|
290
304
|
parsed.hash = "";
|
|
291
305
|
return parsed.toString();
|
|
292
306
|
}
|
|
307
|
+
function publicApiUrl(baseUrl, path) {
|
|
308
|
+
return `${new URL(baseUrl).origin}/api/${path.replace(/^\/+/, "")}`;
|
|
309
|
+
}
|
|
293
310
|
function supportsWorkspaceSession(transport) {
|
|
294
311
|
const candidate = transport;
|
|
295
312
|
return (typeof candidate.exportWorkspaceSession === "function" &&
|
|
@@ -450,6 +467,16 @@ class HttpTransport {
|
|
|
450
467
|
if (options.idempotencyKey !== undefined) {
|
|
451
468
|
headers["Idempotency-Key"] = options.idempotencyKey;
|
|
452
469
|
}
|
|
470
|
+
return this.#send(method, url, headers, payload);
|
|
471
|
+
}
|
|
472
|
+
async getPublicApi(path) {
|
|
473
|
+
const headers = { Accept: "application/json" };
|
|
474
|
+
if (this.#apiKey !== undefined) {
|
|
475
|
+
headers.Authorization = `Bearer ${this.#apiKey}`;
|
|
476
|
+
}
|
|
477
|
+
return this.#send("GET", publicApiUrl(this.#baseUrl, path), headers);
|
|
478
|
+
}
|
|
479
|
+
async #send(method, url, headers, payload) {
|
|
453
480
|
const controller = new AbortController();
|
|
454
481
|
const timer = setTimeout(() => controller.abort(), this.#timeoutSeconds * 1000);
|
|
455
482
|
try {
|
|
@@ -1431,6 +1458,76 @@ class NexusTradeClient {
|
|
|
1431
1458
|
async waitForNlScreen(screenId, options = {}) {
|
|
1432
1459
|
return waitForOperation((id) => this.getNlScreen(id), screenId, options);
|
|
1433
1460
|
}
|
|
1461
|
+
/**
|
|
1462
|
+
* Congressional trade disclosures, newest first. No API key required.
|
|
1463
|
+
*
|
|
1464
|
+
* Defaults to equities first made public in the 30 days ending on the
|
|
1465
|
+
* dataset's last update day. `fromDate` and `toDate` filter on
|
|
1466
|
+
* `firstAvailableAt`. Trade from `availableAt`, when the disclosure became
|
|
1467
|
+
* public, never `transactionDate`.
|
|
1468
|
+
*/
|
|
1469
|
+
async listCongressionalTrades(options = {}) {
|
|
1470
|
+
return readPublicApi(this.transport, `political-disclosures/trades${encodeQuery((0, congress_ts_1.congressionalQueryParams)(options))}`);
|
|
1471
|
+
}
|
|
1472
|
+
/** Purchase and sale totals over the same filters as the feed. No API key required. */
|
|
1473
|
+
async getCongressionalTradeSummary(filters = {}) {
|
|
1474
|
+
return readPublicApi(this.transport, `political-disclosures/summary${encodeQuery((0, congress_ts_1.congressionalQueryParams)(filters))}`);
|
|
1475
|
+
}
|
|
1476
|
+
/** Members ranked by their copy bot's cached backtest against SPY. No API key required. */
|
|
1477
|
+
async getCongressionalLeaderboard(options = {}) {
|
|
1478
|
+
return readPublicApi(this.transport, `political-disclosures/leaderboard${encodeQuery({
|
|
1479
|
+
limit: options.limit === undefined ? undefined : String(options.limit),
|
|
1480
|
+
})}`);
|
|
1481
|
+
}
|
|
1482
|
+
/** Days from trade to public disclosure per member, slowest first. No API key required. */
|
|
1483
|
+
async listCongressionalFilingLatency(filters = {}) {
|
|
1484
|
+
return readPublicApi(this.transport, `political-disclosures/filer-latency${encodeQuery((0, congress_ts_1.congressionalQueryParams)(filters))}`);
|
|
1485
|
+
}
|
|
1486
|
+
/** Disclosed dollar volume per member, largest first. No API key required. */
|
|
1487
|
+
async listCongressionalTradeVolume(filters = {}) {
|
|
1488
|
+
return readPublicApi(this.transport, `political-disclosures/filer-volume${encodeQuery((0, congress_ts_1.congressionalQueryParams)(filters))}`);
|
|
1489
|
+
}
|
|
1490
|
+
/**
|
|
1491
|
+
* One member's profile and whole trading record. No API key required.
|
|
1492
|
+
*
|
|
1493
|
+
* `id` is a Bioguide ID (`"P000197"`) or a page slug (`"nancy-pelosi"`).
|
|
1494
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
1495
|
+
* `instrument` defaults to `"all"`.
|
|
1496
|
+
*/
|
|
1497
|
+
async getPolitician(id, options = {}) {
|
|
1498
|
+
return readPublicApi(this.transport, `political-disclosures/politicians/${encodePathSegment(id)}${encodeQuery((0, congress_ts_1.congressionalQueryParams)(options))}`);
|
|
1499
|
+
}
|
|
1500
|
+
/** A member's copy bot and its cached backtest. No API key required. */
|
|
1501
|
+
async getPoliticianBot(id) {
|
|
1502
|
+
return readPublicApi(this.transport, `political-disclosures/politicians/${encodePathSegment(id)}/bot`);
|
|
1503
|
+
}
|
|
1504
|
+
/** Members with disclosures matching the filters. Requires an API key. */
|
|
1505
|
+
async listCongressionalFilers(filters = {}) {
|
|
1506
|
+
return readPublicApi(this.transport, `political-disclosures/filers${encodeQuery((0, congress_ts_1.congressionalQueryParams)(filters))}`);
|
|
1507
|
+
}
|
|
1508
|
+
/**
|
|
1509
|
+
* One member's summary, activity and trades by Bioguide ID. Requires an API key.
|
|
1510
|
+
*
|
|
1511
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
1512
|
+
* `instrument` defaults to `"all"`.
|
|
1513
|
+
*/
|
|
1514
|
+
async getCongressionalFiler(filerKey, options = {}) {
|
|
1515
|
+
return readPublicApi(this.transport, `political-disclosures/filers/${encodePathSegment(filerKey)}${encodeQuery((0, congress_ts_1.congressionalQueryParams)(options))}`);
|
|
1516
|
+
}
|
|
1517
|
+
/** One disclosure with its amendment history. Requires an API key. */
|
|
1518
|
+
async getCongressionalTrade(eventId, options = {}) {
|
|
1519
|
+
return readPublicApi(this.transport, `political-disclosures/trades/${encodePathSegment(eventId)}${encodeQuery({
|
|
1520
|
+
asOf: options.asOf,
|
|
1521
|
+
})}`);
|
|
1522
|
+
}
|
|
1523
|
+
/** One source filing and every trade it disclosed. Requires an API key. */
|
|
1524
|
+
async getCongressionalFiling(chamber, docId) {
|
|
1525
|
+
return readPublicApi(this.transport, `political-disclosures/filings/${encodePathSegment(chamber)}/${encodePathSegment(docId)}`);
|
|
1526
|
+
}
|
|
1527
|
+
/** How much of the public record the dataset holds. Requires an API key. */
|
|
1528
|
+
async getCongressionalCoverage() {
|
|
1529
|
+
return readPublicApi(this.transport, "political-disclosures/coverage");
|
|
1530
|
+
}
|
|
1434
1531
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
1435
1532
|
async waitForBacktest(backtestId, options = {}) {
|
|
1436
1533
|
return waitForOperation((id) => this.getBacktest(id), backtestId, options);
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Congressional (STOCK Act) disclosure types for the public REST API at
|
|
4
|
+
* `/api/political-disclosures`.
|
|
5
|
+
*
|
|
6
|
+
* `availableAt` is when a disclosure became public. It is the only date a
|
|
7
|
+
* strategy may act on: `transactionDate` is when the member traded, typically
|
|
8
|
+
* weeks before anyone outside Congress could know. Date filters and `sort` use
|
|
9
|
+
* `firstAvailableAt`, when the first version of a disclosure became public.
|
|
10
|
+
*/
|
|
11
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
12
|
+
exports.congressionalQueryParams = congressionalQueryParams;
|
|
13
|
+
/** Query pairs in one fixed order, so both SDKs put the same bytes on the wire. */
|
|
14
|
+
function congressionalQueryParams(options) {
|
|
15
|
+
return {
|
|
16
|
+
q: options.q,
|
|
17
|
+
filerKey: options.filerKey,
|
|
18
|
+
ticker: options.ticker,
|
|
19
|
+
chamber: options.chamber,
|
|
20
|
+
action: options.action,
|
|
21
|
+
instrument: options.instrument,
|
|
22
|
+
sort: options.sort,
|
|
23
|
+
from: options.fromDate,
|
|
24
|
+
to: options.toDate,
|
|
25
|
+
asOf: options.asOf,
|
|
26
|
+
cursor: options.cursor,
|
|
27
|
+
limit: options.limit === undefined ? undefined : String(options.limit),
|
|
28
|
+
};
|
|
29
|
+
}
|