@0xinsider/sdk 0.14.0-bootstrap.0

package/README.md

@@ -0,0 +1,674 @@
+# @0xinsider/sdk
+
+Official TypeScript SDK for the [0xinsider](https://0xinsider.com) API: analytics for Polymarket sports and esports markets. Wallet grades, large trades, profitable-wallet flows, market intel and OHLC candles, a live SSE feed, and signed webhooks.
+
+The types are generated from the [published OpenAPI document](https://0xinsider.com/api/v1/openapi.json), and a drift check pins the operation table to it, so the SDK cannot silently diverge from the live API surface.
+
+- Website and API keys: https://0xinsider.com/developers
+- Authentication (API keys and OAuth 2.1): https://0xinsider.com/auth.md
+- OpenAPI 3.1: https://0xinsider.com/api/v1/openapi.json
+- Documentation: https://docs.0xinsider.com
+- MCP server: https://api.0xinsider.com/api/v1/mcp
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`, `ReadableStream`, and `node:crypto`). Zero runtime dependencies.
+- Every API call has a 15 s SDK deadline (`DEFAULT_TIMEOUT_MS`). Set `timeoutMs` on the client or per call; `null` disables it. Only the SDK's deadline rejects with `RequestTimeoutError` (no status, body, or request id). An API call cancelled by the caller's `signal` rejects with its exact abort reason, including a caller-owned `TimeoutError`. `streamFeed` has no deadline; signed object downloads use their separate `downloadTimeoutMs` option.
+- API call cancellation stays active while the response body is read and during retry backoff. The first signal to abort determines the rejection; no further attempt starts after cancellation. On runtimes without `AbortSignal.any`, request-owned listeners are removed when the call finishes, including failures; one cancellation signal can be reused across pages without accumulating listeners.
+- `baseUrl` is the server URL, `https://api.0xinsider.com` by default or `https://0xinsider.com/sandbox`; a path on it is kept and the `/api/v1/...` operation paths are appended after it. It must be `https:`; `http:` is accepted only for a loopback host (`localhost`, `127.0.0.1`, `[::1]`). The constructor throws otherwise, so the API key is never sent to an untrusted origin.
+- An API key. Your key looks like `oxi_sk_live_...`. Create one at [0xinsider.com/developers](https://0xinsider.com/developers). The [sandbox](#sandbox) needs none.
+
+## Install
+
+```bash
+npm install @0xinsider/sdk
+```
+
+The first npm release is pending. Until it lands, build the package from this repository and install it from the folder (npm 12 refuses git dependencies by default, so `npm install github:...` does not work):
+
+```bash
+git clone https://github.com/0xinsider/0xinsider-node
+(cd 0xinsider-node && npm ci && npm run build)
+npm install ./0xinsider-node   # from your project, with the path to the clone
+```
+
+The package is ESM-only (`import`, not `require`) and ships its own type declarations.
+
+Try it with no key against the [sandbox](#sandbox):
+
+```bash
+git clone https://github.com/0xinsider/0xinsider-node && cd 0xinsider-node
+npm ci && npm run build && node examples/sandbox.mjs
+```
+
+## Types
+
+Every type comes from the published OpenAPI document
+(https://0xinsider.com/api/v1/openapi.json), generated by
+`scripts/generate.mjs` into `src/schema.ts`. All component schemas
+are exported by name, and five per-operation maps (`OperationPath`,
+`OperationQuery`, `OperationBody`, `OperationData`, `OperationResponse`) type
+every convenience method, `call`, `list` and `paginate` by the operation they
+name: the path parameters it takes, the query keys and values it documents,
+the body it requires, and the envelope it answers with its own `data` and
+`meta` (`BatchResponseMeta` on a batch, `EventReplayMeta` on the replay).
+Nothing takes a type argument any more; the method knows its shape.
+
+```ts
+const trader = await client.getTrader("swisstony", { query: { expand: ["strategy"] } });
+if (trader.object === "trader") {
+  trader.data?.grade; // Grade | null
+  trader.meta.request_id; // ResponseMeta, always present
+}
+
+const explore = await client.exploreMarkets({ sort: "trending", limit: 10 });
+explore.data[0]; // ExploreEntry, and explore.facets is typed too
+explore.data[0].title; // compile error: an ExploreEntry has no title
+
+const batch = await client.batchGetTraders(["swisstony", "0xabc..."], { expand: ["trust"] });
+if (batch.object === "trader_batch") batch.meta.request_cost; // BatchResponseMeta
+
+client.listInsiderRadar({ min_grade: "S" }); // compile error: the route takes min_suspicion and severity
+```
+
+Every method forwards the same transport options, so a conditional read,
+a deadline or a cancellation looks the same everywhere:
+`client.listLargeTradesConditional({ min_grade: "S", since }, { signal, timeoutMs: 5_000, maxRetries: 0, headers: { "If-None-Match": etag } })`.
+A list method such as `listLargeTrades()` throws on a `304`; send
+`If-None-Match` through a `...Conditional` method or `call()`, which return the
+typed `not_modified` result instead.
+
+`call`, `list`, `paginate`, `paginatePages` and `collect` are typed the same
+way when the operation id is a literal. Given an id chosen at runtime, or an
+explicit type argument, they fall back to the loose form (`path`, `query` and
+`body` as plain records, the generic `{ object, data, meta? }` envelope back)
+for the caller that asserts the shape itself.
+
+`npm run check` regenerates from the committed snapshot and compares on every
+push, so a contract change that nobody regenerated fails CI rather than
+shipping as a stale type.
+
+## Quickstart
+
+### REST
+
+```ts
+import { OxinsiderApiClient } from "@0xinsider/sdk";
+
+const client = new OxinsiderApiClient({
+  apiKey: process.env.OXINSIDER_API_KEY, // oxi_sk_live_...
+  // baseUrl defaults to https://api.0xinsider.com
+});
+
+// Single resource: { object, data, meta }
+const trader = await client.getTrader("swisstony");
+console.log(trader.data);
+
+// 1 to 25 traders in one request (POST /api/v1/traders/batch). The body
+// carries `traders` and the optional shared `expand`; `data` keeps request
+// order, one row per input, each `status: "ok"` with `data` or
+// `status: "error"` with that item's own `error`.
+const batch = await client.batchGetTraders(["swisstony", "trd_123"], {
+  expand: ["strategy", "trust"],
+});
+for (const item of batch.data) {
+  if (item.status === "ok") console.log(item.input, item.data?.grade);
+  else console.log(item.input, item.error?.code);
+}
+
+// A list endpoint returns the Stripe-style envelope:
+// { object: "list", data, has_more, next_cursor, meta }
+const board = await client.listLeaderboard({ strategy: "swing_trader", limit: 100 });
+console.log(board.data, board.has_more, board.next_cursor);
+
+// Keep compatibility by default, or opt into rejection of unsupported query
+// names. The SDK exposes the server's diagnostics on response metadata.
+const checked = await client.listLeaderboard(
+  { strategy: "swing_trader" },
+  { strictQuery: true },
+);
+console.log(checked.meta?.effectiveQuery, checked.meta?.queryIgnored);
+
+// OHLC candles for a market (open or resolved):
+const candles = await client.getMarketCandles("0xabc...", {
+  query: { resolution: "1d" },
+});
+
+// Webhook event catalog (self-describing) and one endpoint's delivery log:
+const events = await client.listWebhookEvents();
+const deliveries = await client.listWebhookDeliveries(123, { limit: 50 });
+
+// Any operation by id, typed by the id: path, query, body and the envelope.
+const usage = await client.call("getUsage");
+const holders = await client.call("getMarketHolders", {
+  path: { condition_id: "0x..." },
+  query: { outcome: "yes", limit: 25 },
+});
+```
+
+`getAccountIdentity()` remains available to a valid credential after paid data
+access lapses and returns `credential_status` plus
+`entitlement.paid_data_access` and `entitlement.recovery_action`. Call
+`getUsage()` for the caller's rate-limit, daily-usage and monthly-quota state;
+paid data routes still return `402 subscription_required` until access is
+renewed.
+
+For `listSportsEdgeSignals`, require every row's `category_skill` object and
+compare `meta.category_skill_base_payload_hash` with
+`meta.category_skill_enriched_base_payload_hash` before consuming category
+evidence. The evidence is Polymarket-only, forward-observed, and explicitly
+partial; `degraded` or mismatched hashes must not be treated as a measured edge.
+
+### Observation-only sports cohorts
+
+`listSportsEdgeObservations` exposes the measured `wider_holder`, the
+overlapping `emerging_pile` projection, and provider-confirmed `in_play`
+cohorts without changing the funded `sports-edge-signals` route. The response
+includes `snapshot_as_of` and a
+required snapshot-wide operational/unknown-completeness `degraded` verdict plus
+a per-sport terminal-reason `funnel`; every row is tagged
+`observation_only: true`. Do not route these rows to an order executor.
+
+```ts
+const tennis = await client.listSportsEdgeObservations({
+  cohort: "wider_holder",
+  category: "Tennis",
+  limit: 20,
+});
+
+console.log(tennis.degraded, tennis.data, tennis.funnel.sports);
+const previousEtag = tennis.meta.etag;
+```
+
+Treat `degraded: true` as partial evidence even when a row or the funnel's
+single terminal reason does not independently expose every contributing
+operational or unknown-completeness failure. `capacity_limited` is different:
+it records intentional bounded provider-work admission, remains accountable in
+the funnel, and does not by itself set `degraded: true`.
+
+All category and all-sports cache scopes share one global observation
+provider-work admission. Healthy `wider_holder` requests may reuse a snapshot
+for about 180 seconds. `emerging_pile` projects `wider_holder` rows with finite
+`sharp_pct` in the `[0.75, 0.85)` band, `holder_scan_complete: true`, and a
+kickoff after the first-page projection cutoff. It overlaps the `wider_holder`
+source and is not arrival history or an independent denominator. `in_play`
+never serves a cached observation snapshot older than about 30 seconds and
+fails closed when the provider live-board snapshot is stale or unavailable.
+
+The SDK copies a successful response's weak semantic `ETag` header into
+`meta.etag`; it is client metadata, not an additional field in the server's
+JSON body. The validator covers the stable page payload, including the stable
+page position in `next_cursor`, but excludes request-specific `meta` and, for
+`emerging_pile`, the opaque projection cutoff inside that cursor.
+
+For a conditional request, use `listSportsEdgeObservationsConditional()` so a
+`304` returns the typed `{ object: "not_modified", data: null, meta }` result
+while a `200` retains the full observation response type:
+
+```ts
+import { isApiNotModifiedResponse } from "@0xinsider/sdk";
+
+if (previousEtag) {
+  const conditional = await client.listSportsEdgeObservationsConditional(
+    { cohort: "wider_holder", category: "Tennis", limit: 20 },
+    {
+      headers: { "If-None-Match": previousEtag },
+    },
+  );
+
+  if (isApiNotModifiedResponse(conditional)) {
+    console.log("snapshot unchanged");
+  }
+}
+```
+
+### Beyond the JSON envelope
+
+Most operations answer `{ object, data, meta }` and `call()` reads them. Four do not, and each has its own method, because parsing a Markdown document as JSON only ever produced a confusing error about an invalid `200`:
+
+| The route answers | Method | Returns |
+| --- | --- | --- |
+| `text/markdown` (`context.md`) | `text()`, or `getTraderContextMarkdown` / `getMarketContextMarkdown` | the document as a `string` |
+| JSON-RPC 2.0 (`POST /api/v1/mcp`) | `mcp()` | `{ status, response, sessionId? }` |
+| `201` (`POST /api/v1/agents/register`) | `registerAgent()` | the envelope, `meta.status` `201` |
+| `302` (export download) | `getTraderExportDownloadUrl()` / `downloadTraderExport()` | the presigned URL, or the object response |
+
+```ts
+// Markdown, ready to paste into a prompt.
+const context = await client.getTraderContextMarkdown("0x9d84...1344");
+
+// One MCP JSON-RPC message. A JSON-RPC `error` is RETURNED, not thrown:
+// an unknown tool is an answer, a revoked credential is not.
+const listed = await client.mcp({ method: "tools/list", id: 1 });
+listed.response?.result;          // 200
+const ack = await client.mcp({ method: "notifications/initialized" });
+ack.status;                        // 202, ack.response is null
+
+// A sandbox key, with no account and no credential.
+const registered = await new OxinsiderApiClient().registerAgent();
+registered.meta.status;            // 201
+const sandbox = OxinsiderApiClient.sandbox({ apiKey: registered.data.api_key });
+
+// A finished export. The second request carries no headers at all, so your
+// live key never reaches the object store; the presigned URL authorizes
+// itself. Read expiresAt: links last at most one hour and cannot outlive
+// artifact retention. Request a fresh link while retained, or a new export
+// after the job expires.
+const { response, filename, expiresAt } = await client.downloadTraderExport(address, jobId);
+await pipeline(Readable.fromWeb(response.body), createWriteStream(filename ?? "export.json"));
+```
+
+`meta.status` is on every envelope: `201` on `registerAgent`, `202` on a `submitTraderExport` that queued a new job and `200` on one that returned a job already running, `200` everywhere else. The body is identical either way, so this is the only way to tell them apart.
+
+The object fetch in `downloadTraderExport` has no deadline by default, the way the SSE stream has none: pass `signal` to cancel it or `downloadTimeoutMs` for one of your own, and read `response.body` as a stream rather than buffering a multi-gigabyte file. `getTraderExportDownloadUrl` reads the redirect with `redirect: "manual"`, which browsers answer with an opaque redirect no script can read; it says so rather than guessing, so run downloads from a server runtime.
+
+Signed download URLs last at most 1 hour and never past the export job's `expires_at`. Use the returned `expiresAt`, which comes from the URL's signing fields, rather than assuming every link lasts 1 hour. Request a fresh URL while the job is retained; after `410 export_expired`, submit a new export.
+
+Both `downloadTraderExport` and `downloadWhaleDataset` cancel an object response they cannot return, including a failed HTTP response or a failure while preparing the stream or metadata. They wait up to 2 seconds for that cleanup without buffering the error body. The original failure remains primary; a cleanup rejection or timeout is attached as its `cause`, retaining an existing cause in an `AggregateError`. If a thrown value cannot carry a cause, an `AggregateError` retains the original failure as its first entry and cause. A cleanup timeout means completion is unknown. Once the helper returns, consume or cancel `response.body` yourself.
+
+`REDIRECT_OPERATIONS` and `UNSUPPORTED_OPERATIONS` are exported so you can see what is not wrapped and why. Today that is the public `GET /api/v1/openapi.json` redirect (fetch it directly) and `GET /api/v1/mcp`, which answers `405` by design because the endpoint offers no server-to-client stream.
+
+### Sandbox
+
+`OxinsiderApiClient.sandbox()` talks to `https://0xinsider.com/sandbox`, the second server in the OpenAPI document: no credential, no production data, every documented operation answered with its example or a deterministic sample, and `X-Oxi-Sandbox: true` on every response, which the client lifts to `meta.sandbox`. Every method works without a key, so you can write the integration before you have one. Add `sandbox_status` to a query to get one of the errors the operation documents, as the typed class it would be in production.
+
+```ts
+import { OxinsiderApiClient, RateLimitedError, type Trader } from "@0xinsider/sdk";
+
+const sandbox = OxinsiderApiClient.sandbox(); // no apiKey
+
+const board = await sandbox.listLeaderboard({ limit: 5 });
+console.log(board.data, board.meta.sandbox); // [...], true
+
+// sandbox_status is not in the route's documented query, so this call takes
+// the loose form: an explicit type argument instead of the typed method.
+try {
+  await sandbox.call<Trader>("getTrader", {
+    path: { address: "swisstony" },
+    query: { sandbox_status: 429 },
+  });
+} catch (err) {
+  if (err instanceof RateLimitedError) console.log(err.retryAfterSeconds); // 60
+}
+```
+
+A sandbox key from `POST https://api.0xinsider.com/api/v1/agents/register` (`oxi_sk_test_...`, no account needed) is optional: pass it as `apiKey` and the sandbox checks it. A live key (`oxi_sk_live_...`) is refused by the constructor in sandbox mode, so it is never sent there. Streams and file downloads are not simulated; `streamFeed` on a sandbox client throws the sandbox's own `BadRequestError` saying so. The same client with `sandbox: true` and an explicit `baseUrl` keeps that base's path, so a proxy under a path works the same way.
+
+### Pagination
+
+`paginate()` follows `next_cursor` over the list envelope and yields each item; `paginatePages()` yields whole envelopes when you need `meta` or `total`.
+
+```ts
+import { paginate } from "@0xinsider/sdk";
+
+for await (const trade of paginate(client, "listWhaleTrades", {
+  query: { min_grade: "S", limit: 100 },
+})) {
+  console.log(trade);
+}
+```
+
+The loop ends when a page says `has_more: false`, whatever its `next_cursor` says. A page that says `has_more: true` with no usable `next_cursor`, or one whose `next_cursor` repeats a cursor the walk already requested, is a broken response rather than the end of the collection: the walk throws `PaginationError` (`reason` `missing_cursor` or `repeated_cursor`) before yielding that page and before any duplicate request, with the received `page` on the error so its data is not lost. The last 1,024 cursors are remembered for the repeat check (`CURSOR_HISTORY_LIMIT`), which keeps a long walk's memory flat. A list response whose `has_more` is not a boolean or whose `next_cursor` is not a string throws `InvalidResponseError`.
+
+`maxPages` caps fetches and is checked before any request: a positive integer or `Infinity`; `0`, a negative, fractional or `NaN` value throws `RangeError`. Reaching it is your choice, not exhaustion. Pass a `progress` object to tell the two apart and keep the continuation:
+
+```ts
+import { paginatePages, type PaginationProgress } from "@0xinsider/sdk";
+
+const progress: PaginationProgress = {};
+for await (const page of paginatePages(client, "listWhaleTrades", {
+  query: { min_grade: "S", limit: 100 },
+  maxPages: 3,
+  progress,
+})) {
+  handle(page.data);
+}
+if (progress.stoppedBy === "max_pages") {
+  // the collection has more; continue later from progress.nextCursor
+  saveContinuation(progress.nextCursor);
+}
+```
+
+`signal` cancels between pages.
+
+Progress counts each validated page before it is delivered, including a page
+after which you `break`. It counts pages delivered, not items processed or
+persisted. An early return retains `nextCursor` and leaves `stoppedBy` unset
+unless that delivered page already exhausted the list or reached `maxPages`.
+Reusing a progress object resets its owned fields when the new walk starts.
+During a request, `cursor` names that attempt and `nextCursor` is undefined.
+After a failure or between-page cancellation, `cursor` and `nextCursor` name
+the retry cursor, and `pagesFetched` matches `paginationResumePoint(error)`;
+the original error is rethrown.
+
+
+Pass `strictQuery: true` to `paginate()`, `paginatePages()`, or `collect()` to
+reject an unsupported query name before the first page request. With the
+default compatibility mode, successful responses expose `meta.queryIgnored`
+and `meta.effectiveQuery` when the server received query parameters that were
+ignored or applied. The same option is available on the typed list methods and
+on `client.call()`.
+
+Each page request retries on its own (see [Retries](#retries)). If a page still fails, the walk throws that page's original error, and `paginationResumePoint(err)` returns the cursor to continue from; a `PaginationError` carries the same resume point:
+
+```ts
+import { paginate, paginationResumePoint } from "@0xinsider/sdk";
+
+try {
+  for await (const trade of paginate(client, "listWhaleTrades", { query })) handle(trade);
+} catch (err) {
+  const resume = paginationResumePoint(err); // { cursor, pagesFetched } or undefined
+  if (resume) scheduleLater({ ...query, cursor: resume.cursor });
+  else throw err;
+}
+```
+
+### Polling for new large trades
+
+`since` asks `listLargeTrades` for only the trades recorded after one you
+already hold (#18507). Pair it with `If-None-Match` and a poll that finds
+nothing new is a `304` with no body:
+
+```ts
+import { isApiNotModifiedResponse, paginate } from "@0xinsider/sdk";
+
+let since: string | undefined; // first trade of the last answer that had trades
+let etag: string | undefined;
+for (;;) {
+  const page = await client.listLargeTradesConditional(
+    { since, limit: 100 },
+    { headers: etag ? { "If-None-Match": etag } : {} },
+  );
+  if (!isApiNotModifiedResponse(page)) {
+    etag = page.meta.etag;
+    const trades = [...page.data];
+    if (since && page.has_more && page.next_cursor) {
+      // More than one page is new: read the rest under the same since.
+      for await (const trade of paginate(client, "listLargeTrades", {
+        query: { since, limit: 100, cursor: page.next_cursor },
+      })) trades.push(trade);
+    }
+    for (const trade of trades) handle(trade); // a late trade can repeat: dedupe on id
+    since = page.data[0]?.id ?? since;
+  }
+  await new Promise((resolve) => setTimeout(resolve, 5_000));
+}
+```
+
+"After" is commit order, so a trade recorded late with an earlier `traded_at`
+still arrives, and one whose write is still open arrives on a later poll. Move
+`since` only to the first trade of the first page. A `since` that names no
+trade, or one more than 10,000 trades behind, is a `400` with `error.param`
+`since`: poll once without it and continue from its first trade. `since` works
+with `sort: "recent"` only.
+
+### Live stream (SSE)
+
+`streamFeed()` consumes `GET /api/v1/stream`, parses each `{ seq, published_at, type, ... }` feed envelope, and supports `Last-Event-ID` resume plus per-connection filters (`event`, `condition_id`, `min_grade`). The numeric cursor is cluster-shared across replicas and process restarts while retained; expired, future, or uncovered cursors emit `resync`.
+
+```ts
+import { streamFeed } from "@0xinsider/sdk";
+
+const cursor: { seq?: number } = {};
+for await (const frame of streamFeed(client, {
+  event: ["WhaleTradesInserted"],
+  min_grade: "S",
+  cursor, // cursor.seq tracks the last DELIVERED seq: transport progress, not completed work
+  onResync: (m) => console.log("resync:", m.completeness?.reason),
+})) {
+  if (frame.kind === "event") {
+    console.log(frame.seq, frame.envelope.type);
+  }
+}
+```
+
+Both `streamFeedResilient` and `consumeStreamCheckpointed` honor a valid terminal error's absolute `retry_at` when no usable HTTP `Retry-After` duration exists. The HTTP duration is preferred because it does not depend on clock alignment. Absolute guidance uses your machine's clock once to calculate the remaining wait, so keep it synchronized with the server. Past times mean zero remaining wait; missing or invalid guidance uses local backoff. Positive jitter never shortens the requested wait. The same `maxRetryAfterMs` ceiling defers long waits with `StreamRetryDeferredError` before spending a reconnect, and your signal cancels an in-process wait promptly. Terminal errors never advance a cursor or acknowledgement.
+
+The decoder is bounded and fails visibly rather than skipping bad data. A successful response that is not `text/event-stream`, a data frame whose payload is not JSON or not an object, a frame with no usable sequence (no finite `seq` in the envelope and no finite SSE `id`), or a `resync` frame whose payload is not a resync object throws `StreamProtocolError` (`reason` `unexpected_media_type`, `invalid_json`, `invalid_envelope`, `unusable_sequence`, `invalid_resync`). A frame that has not reached its blank-line delimiter after `maxFrameBytes` (default 1 MiB) throws `frame_too_large` and closes the connection. The error carries `lastSeq` (the last sequence delivered on that connection; a malformed frame never moves the cursor), `frameId`, `event` and `bytes`, and never the raw payload. Comment lines such as `: keep-alive`, LF and CRLF framing, unknown SSE fields and unknown-but-valid envelope `type`s are compatible as before.
+
+`streamFeed()` reads one connection and stops when it ends. For a long-lived consumer, use `streamFeedResilient()`, which reconnects for you:
+
+```ts
+import {
+  streamFeedResilient,
+  StreamProtocolError,
+  StreamReconnectsExhaustedError,
+  StreamRetryDeferredError,
+} from "@0xinsider/sdk";
+
+const controller = new AbortController();
+try {
+  for await (const frame of streamFeedResilient(client, {
+    event: ["WhaleTradesInserted"],
+    signal: controller.signal, // abort to stop; the iterator ends without throwing
+    onReconnect: (attempt, lastSeq, cause) => console.warn("reconnecting", attempt, lastSeq, cause),
+  })) {
+    if (frame.kind === "resync") await refetchCurrentState();
+    else handle(frame.envelope);
+  }
+} catch (err) {
+  if (err instanceof StreamRetryDeferredError) scheduleAt(err.retryAt, () => resume(err.lastSeq));
+  else if (err instanceof StreamReconnectsExhaustedError) resumeLater(err.lastSeq);
+  else if (err instanceof StreamProtocolError) decideRecovery(err.reason, err.lastSeq, err.frameId);
+  else throw err; // 400, 401, 402, 403, 423: fix the request or the key
+}
+```
+
+- **Reconnects** when the server closes the connection, on a network error, a 429, or a 5xx. Each reconnect resumes after the last delivered `seq` (`Last-Event-ID`), so frames are neither repeated nor skipped while the server still retains them.
+- **Waits** for `Retry-After` (delta-seconds or an HTTP-date) plus jitter when the refusal carries one, otherwise a jittered backoff from 1 s up to 30 s. A `Retry-After` past `maxRetryAfterMs` (default 60 s, the same ceiling as REST retries) is not waited out: the loop throws `StreamRetryDeferredError` with `retryAt` (the server's not-before instant) and `lastSeq`, spends no reconnect on it, and never shortens the wait. Pass `maxRetryAfterMs: Infinity` to hold the process for however long the server says; a `monthly_quota_exceeded` refusal names the first of next month, so that is a choice, not the default.
+- **Stops** with the original error on any other 4xx, and with `StreamProtocolError` on a malformed frame or a non-SSE response: resuming from `lastSeq` would replay the same frame, so the decision (resume later, skip past `frameId`, or refetch state and attach live) is yours. After `maxReconnects` (default 10) consecutive connections that delivered nothing, it throws `StreamReconnectsExhaustedError` with `lastSeq`.
+- **Resync:** `resync` markers are yielded unchanged, and the marker's `id` becomes the resume cursor.
+- **No deadline:** `timeoutMs` never applies to the stream. Every connection's body reader is released when it ends.
+
+A `consumeStream(client, { onEvent, onResync }, options)` callback variant is also exported.
+
+#### Acknowledged checkpoints
+
+`cursor.seq` is written before a frame reaches your code, so it says the frame arrived and nothing about whether you finished with it. A handler that throws, then a reconnect from that cursor, resumes *after* the event you failed on. When losing an event would lose work, drive the stream with `consumeStreamCheckpointed()`: it keeps the received cursor for transport progress and adds a separate `StreamCheckpoint` that advances only after your handler and your own durable write have both resolved.
+
+```ts
+import { consumeStreamCheckpointed, StreamHandlerFailedError } from "@0xinsider/sdk";
+
+const checkpoint = { seq: await loadCheckpoint() }; // undefined on a cold start
+try {
+  await consumeStreamCheckpointed(client, {
+    onEvent: async (envelope, seq) => { await applyOnce(seq, envelope); },
+    onResync: async () => { await refetchCurrentState(); },   // awaited barrier
+    onCheckpoint: async (seq) => { await saveCheckpoint(seq); },
+  }, {
+    event: ["WhaleTradesInserted"],
+    lastEventId: checkpoint.seq,
+    checkpoint,
+    signal: controller.signal,
+    onHandlerError: (err, f) => console.warn("handler failed", f.seq, f.attempt, f.willRetry, f.cancelled, err),
+  });
+} catch (err) {
+  if (err instanceof StreamHandlerFailedError) parkForRepair(err.seq, err.replayFrom, err.cause);
+  else throw err; // the same stream errors as streamFeedResilient
+}
+```
+
+- **Order, per event:** `onEvent` is awaited, then `onCheckpoint(seq, "event")` (your durable write), and only then does `checkpoint.seq` become `seq`. A rejection at either step leaves the checkpoint *before* the event.
+- **Replay:** a failure closes the connection, waits a jittered backoff (1 s to 30 s) and reconnects from the checkpoint, so the unacknowledged event is delivered again while the server retains it. After `maxHandlerRetries` (default 3) consecutive failures at the same `seq` it throws `StreamHandlerFailedError` with `seq`, `stage`, `attempts`, the unadvanced `checkpoint` and the `replayFrom` to resume with later.
+- **Resync is a barrier:** `onResync` is awaited and the checkpoint moves to the marker only once it resolves, so an interrupted refresh is retried instead of being recorded as done. The fire-and-forget `StreamOptions.onResync` notification is not awaited and is not a barrier.
+- **Backpressure, not buffering:** nothing is read from the connection while your handler runs. At most one frame is in flight and no queue is kept on your behalf; a slow handler is backpressure on the socket, and falling far enough behind the retained window surfaces as a `resync` marker.
+- **At-least-once:** a replay re-delivers every unacknowledged frame, and a handler that succeeded but whose checkpoint write failed sees its event again. Deduplicate on `seq` or make the side effect idempotent; no client can promise exactly-once side effects.
+- **Abort:** aborting `signal` ends the consumer without throwing. A handler already running is awaited rather than cancelled (pass the same signal into your own work if you want that), and if it and its durable checkpoint write succeed, the checkpoint is committed first. If an awaited event, resync, or checkpoint callback rejects while the signal is aborted, the acknowledgement stays unchanged and the consumer returns, including with zero or exhausted handler retries. `onHandlerError` still receives the original rejection, with `willRetry: false` and optional `cancelled: true`; cancellation spends no handler retry. The flag means cancellation stopped the consumer when the failure was observed, without claiming it caused the rejection, so unrelated failures racing shutdown remain visible. `attempt` remains the 1-based consecutive failure occurrence at that sequence. Without cancellation, bounded retries and `StreamHandlerFailedError` are unchanged. The diagnostic callback is synchronous and must not throw; it may abort the signal to stop the consumer.
+
+### Webhook verification
+
+The backend signs every delivery as `v1=hex(HMAC_SHA256(signing_secret, "<timestamp>.<raw_body>"))`, sent on `x-0xinsider-signature` (the timestamp is on `x-0xinsider-timestamp`). Verify the raw body BEFORE parsing it; re-serializing changes bytes and breaks the HMAC.
+
+```ts
+import { verifySignature, parseWebhookEvent } from "@0xinsider/sdk";
+
+// In your webhook handler (raw body string, not parsed JSON):
+const ok = verifySignature({
+  secret: process.env.WEBHOOK_SIGNING_SECRET!,
+  timestamp: req.headers["x-0xinsider-timestamp"],
+  signature: req.headers["x-0xinsider-signature"],
+  body: rawBody,
+});
+if (!ok) return res.status(400).end();
+
+const event = parseWebhookEvent(rawBody);
+switch (event.type) {
+  case "wallet_grade_changed": // Pro-only
+    console.log(event.data.new_grade);
+    break;
+  case "insider_radar_flag_raised": // Pro-only
+    console.log(event.data.suspicion_score);
+    break;
+  case "whale_trades_inserted": // Pro-only
+    console.log(event.data.count);
+    break;
+}
+```
+
+`verifySignature` enforces a 300-second replay tolerance (`toleranceSeconds` overrides it: a payload exactly that many seconds from `nowSeconds` still passes, one second further fails, and `0` accepts only the current second) and uses a constant-time compare, mirroring the backend exactly. It returns `false` on a bad signature or a malformed timestamp (never throws for those); it throws only on receiver misconfiguration: an empty secret, or a `toleranceSeconds` that is `NaN`, infinite or negative, each of which would otherwise silently turn the replay window off. Treat a `false` as the sender's problem (answer 4xx) and a throw as your own bug (log it). Typed payloads are exported for every event type, including the four Pro-only events (`whale_trades_inserted`, `wallet_grade_changed`, `insider_radar_flag_raised`, `smart_money_flow_detected`), which deliver only to API keys on an active Pro subscription.
+
+### Staged webhook secret rotation
+
+Use the staged operations when the receiver needs time to deploy a new secret:
+
+1. Call `prepareWebhookSecret` and store the one-time `signing_secret`; the current secret keeps working.
+2. Deploy the prepared secret and configure `verifySignature` to accept the comma-separated `v1=` candidates the sender emits during overlap.
+3. Call `activateWebhookSecret`; deliveries carry both the new and previous signatures for one hour.
+4. After the receiver rollout, call `retireWebhookSecret` to end the overlap early.
+
+The endpoint's `secret_rotation.status` is `idle`, `pending`, or `overlap`. `rotateWebhookSecret` remains the immediate replacement path for emergency response and clears staged state. The staged operations are idempotent writes and accept `idempotencyKey`.
+
+## Retries
+
+The client retries a failed request when retrying is safe and can help. `maxRetries` defaults to 2 and can be set on the client or on one call; `0` sends exactly one request.
+
+- **What is retried:** a GET, a read-only POST (`batchGetTraders`, `batchGetMarketIntel`, which resolve their inputs and store nothing), or one of the eight writes the API replays under `Idempotency-Key` (`createWebhook`, `updateWebhook`, `deleteWebhook`, `rotateWebhookSecret`, `prepareWebhookSecret`, `activateWebhookSecret`, `retireWebhookSecret`, `redeliverWebhookDelivery`, exported as `IDEMPOTENT_WRITE_OPERATIONS` and pinned to the OpenAPI contract by the drift check) when it carries a key; each when it fails with 408, 429, 502, 503, or 504, or with a network error before any response. A 408 is the server's own 30-second timeout (`error.code` `request_timeout`, thrown as `ServerTimeoutError` when retries run out); it carries `Retry-After` on a GET, and a keyed write replays safely. `retryEligibility(operation)` returns `"read"`, `"keyed"` or `"never"`.
+- **How long it waits:** the response's `Retry-After` plus up to 250 ms of jitter; delta-seconds and HTTP-date forms both parse (`parseRetryAfter` is exported), and a negative, non-finite or malformed value is treated as absent. Without the header, a jittered exponential backoff from 500 ms, capped at 8 s. A `Retry-After` longer than 60 s (`RETRY_AFTER_CEILING_MS`) is not waited out; the error is thrown for you to schedule from `retryAfterSeconds` or `retryAt`. No wait is ever handed to a timer past Node's 2147483647 ms range, which would fire at once.
+- **What is never retried:** 400, 401, 402, 403, 404, 409, 500, a write without an idempotency key, any write outside the eight above (`verifyWebhook` sends a challenge to your URL each time; `submitTraderExport` starts a job; an MCP call runs a tool), the client's own timeout (`RequestTimeoutError`), or your own abort. A key on one of those writes is refused before the request is sent, because the server would ignore it and the retry it seemed to license could repeat the effect.
+- **Deadline:** all attempts share one `timeoutMs` deadline (15 s by default). A retry that cannot finish before it is not started, so you get the real error, not a timeout. An `AbortSignal` ends a backoff immediately.
+
+Webhook writes accept `idempotencyKey`. It makes the write safe to replay and eligible for retry:
+
+```ts
+await client.call("createWebhook", {
+  body: {
+    name: "Large trades",
+    url: "https://example.com/hooks/0xinsider",
+    event_types: ["whale_trades_inserted"],
+  },
+  idempotencyKey: crypto.randomUUID(), // reuse the SAME key if you retry by hand
+});
+```
+
+The API honours `idempotencyKey` on `createWebhook`, `updateWebhook`, `deleteWebhook`, `rotateWebhookSecret`, `prepareWebhookSecret`, `activateWebhookSecret`, `retireWebhookSecret`, and `redeliverWebhookDelivery`, and nowhere else. On `IdempotencyInProgressError`, retry with the same key and body.
+
+The SDK validates the effective `Idempotency-Key` before sending: it must be nonempty after trimming and at most 255 UTF-8 bytes, including when `maxRetries` is `0`. You can supply it through `headers` using any header-name casing; `idempotencyKey` overrides that header when defined. An invalid effective value throws a configuration error without fetching. Supply a stable nonempty key, or omit both options to send a supported mutation once. The SDK never truncates a key or generates a replacement for you.
+
+Safe replay is not exactly-once. The key lets the server answer a repeat of the same request with the first result; it does not tell you what happened when you never saw a result. After a `RequestTimeoutError`, an exhausted retry budget, or your own abort on a keyed write, the outcome is unknown: reconcile it by sending the same key and the same body once more (the server replays the stored result, or `IdempotencyInProgressError` says it is still running), or by reading the resource (`listWebhooks`, `listWebhookDeliveries`). Never mint a new key for the same intent, and never reuse a key with a different body, which the API answers with 422. Every automatic retry the client makes keeps the key and the exact request bytes.
+
+A delivery that exhausts its retries, or that was queued when its endpoint was disabled, ends as `dead_letter`. Re-enabling the endpoint resends nothing; requeue each one with `client.redeliverWebhookDelivery(webhookId, deliveryId, { idempotencyKey })`.
+
+## Errors
+
+Every readable non-2xx response throws an `OxinsiderApiError`. The SDK dispatches to a specific subclass by the documented error code:
+
+An owned JSON/text body that fails during consumption throws `ResponseBodyReadError`, carrying `responseStatus`, `phase: "response_body"` and original transport `cause`. Its message includes no body or credential. Client deadlines keep `RequestTimeoutError`, caller cancellation keeps its exact reason, and invalid JSON remains a response-contract failure. Already consumed/locked custom-fetch responses and allocation failures keep their local rejection. Body failures gain no automatic retry; reconcile an uncertain write before replaying it.
+
+| Code | Subclass |
+| --- | --- |
+| `bad_request` | `BadRequestError` |
+| `invalid_api_key` | `InvalidApiKeyError` |
+| `subscription_required` | `SubscriptionRequiredError` |
+| `forbidden` | `ForbiddenError` |
+| `not_found` | `NotFoundError` |
+| `account_locked` | `AccountLockedError` |
+| `rate_limited` | `RateLimitedError` (carries `retryAfterSeconds`) |
+| `rate_limit_unavailable` | `RateLimitUnavailableError` (carries `retryAfterSeconds`) |
+| `rate_limit_unavailable` + `reason: database_unavailable` | `DatabaseUnavailableError` (carries `retryAfterSeconds`; the database is temporarily unreachable, nothing is rate-limited) |
+| `internal_error` | `InternalServerError` |
+| `invalid_response` (client-side) | `InvalidResponseError` (a `2xx` whose body does not match the contract, with the body on `received`) |
+
+```ts
+import { RateLimitedError, OxinsiderApiError } from "@0xinsider/sdk";
+
+try {
+  await client.listWhaleTrades({ min_grade: "S" });
+} catch (err) {
+  // Thrown after the client's own retries (see Retries) are exhausted.
+  if (err instanceof RateLimitedError) {
+    await sleep((err.retryAfterSeconds ?? 1) * 1000);
+  } else if (err instanceof OxinsiderApiError) {
+    console.error(err.status, err.code, err.requestId);
+  }
+}
+```
+
+Each error exposes `status`, `code`, `error` (the `{ code, message, doc_url, param }` body), `meta`, `requestId`, `retryAfterSeconds`, and the raw `body`. `requestId` prefers JSON `meta.request_id`, falling back to a nonempty received `X-Request-ID` header. The header never creates a synthetic `meta` object. Every HTTP error retains parsed `Retry-After` guidance, including generic 502/504 errors and plain-text or empty bodies; an absent or invalid header gives `null`. This guidance does not authorize replaying a mutation or change which requests the SDK retries. `retryAt` remains the parsed body `error.retry_at`, or `null`.
+
+Direct error constructors accept optional `ApiErrorTransportMetadata` after their existing arguments. `errorFromResponse(status, body, retryAfterSeconds?, { requestId }?)` preserves the same subclass selection and all existing calls.
+
+## Authentication
+
+Pass `apiKey` to the client constructor. Public operations (`getApiDiscovery`, `getPlatforms`, `getHealth`, `getPickOfTheDayLedger`, and `registerAgent`, which mints the sandbox key) do not require a key; everything else does, and the SDK throws before making a request if a key is missing for a bearer operation, unless the client is in [sandbox](#sandbox) mode, where no operation needs one. Pro-only data (graded webhook events, parts of the stream) requires a key on an active Pro subscription.
+
+## Examples
+
+- [`examples/sandbox.mjs`](examples/sandbox.mjs): no key. The sandbox leaderboard, then a documented `429` on demand.
+- [`examples/sdk-list-s-grade-wallets.ts`](examples/sdk-list-s-grade-wallets.ts): a live key. S-grade wallets, S-grade whale trades with cursor pagination, and a filtered live stream.
+
+## How it is built
+
+`src/schema.ts` is generated from the published [OpenAPI document](https://0xinsider.com/api/v1/openapi.json) by `scripts/generate.mjs`, which keeps the exact bytes it read in `openapi.json` and renders the types with the same generator the 0xinsider app runs (vendored in `scripts/app/`), so they are byte-identical to the app's for the same document. The client itself (`src/client.ts`, `src/stream.ts`, `src/pagination.ts`, `src/retry.ts`, `src/webhooks.ts`, `src/errors.ts`) is hand-written against those types.
+
+```bash
+npm run generate     # fetch the published document; rewrite openapi.json, src/schema.ts, src/provenance.ts
+npm run check        # the committed files match the committed snapshot, and the client table matches it
+npm run check:live   # the same checks against the published document: is this release behind the API?
+npm test             # build, then the unit tests (node:test, no network)
+npm run test:sandbox # live calls against https://0xinsider.com/sandbox, no key
+```
+
+A weekly workflow regenerates from the published document and opens a pull request when it changed. The drift check fails when the document gains or loses an operation, a query parameter or an `Idempotency-Key` route that the hand-written client does not follow, so that pull request says what to add. Releases publish to npm from GitHub Actions through trusted publishing, with a provenance attestation; [RELEASING.md](RELEASING.md) has the steps.
+
+## Provenance
+
+`src/provenance.ts`, generated alongside the types, says which document a release was generated from, and the package exports it: `OPENAPI_SHA256` (the SHA-256 of the document bytes), `OPENAPI_VERSION`, `OPERATION_COUNT`, `OPENAPI_SOURCE`, and `APP_COMMIT`, the `0xinsider/0xinsider` commit that last changed `web/public/api/v1/openapi.json` (or `null` when it could not be resolved).
+
+```ts
+import { OPENAPI_SHA256 } from "@0xinsider/sdk";
+```
+
+Compare `OPENAPI_SHA256` with `curl -s https://0xinsider.com/api/v1/openapi.json | shasum -a 256` to see whether a release is behind the API.
+
+## Other official tools
+
+- Python SDK: `pip install 0xinsider` ([0xinsider/0xinsider-python](https://github.com/0xinsider/0xinsider-python))
+- Go SDK: `go get github.com/0xinsider/0xinsider-go` ([0xinsider/0xinsider-go](https://github.com/0xinsider/0xinsider-go))
+- Rust SDK: crate `oxinsider` ([0xinsider/0xinsider-rust](https://github.com/0xinsider/0xinsider-rust); until its first crates.io release, `cargo add oxinsider --git https://github.com/0xinsider/0xinsider-rust`)
+- CLI and MCP server: `npm install --global @0xinsider/mcp` or `brew install 0xinsider/tap/oxinsider`
+- Remote MCP server: `https://api.0xinsider.com/api/v1/mcp`
+- Agent Plugin and skills: [0xinsider/agent-plugin](https://github.com/0xinsider/agent-plugin)
+- Machine-readable contract: https://0xinsider.com/llms-full.txt and https://0xinsider.com/agents.md
+
+## License
+
+MIT
+
+## Immutable whale datasets
+
+`submitWhaleDataset({ from, to, condition_id?, min_size? })` submits a past
+window up to 31 days. Poll `getWhaleDatasetStatus(jobId)` according to
+`next_action` and `poll_after_s`. `downloadWhaleDataset(jobId)` streams decoded
+NDJSON and verifies the immutable content checksum when the body finishes.
+The signed URL is never sent your API credential. `cancelWhaleDataset(jobId)`
+uses the same owner-scoped lifecycle as trader exports.
+
+Rows contain exact decimal strings and detected whale-alert facts, not all
+provider fills or current wallet grades. For continuation, send the manifest's
+cursor and normalized condition/size filters through
+`client.call("getEventReplaySince", { query })`. Omit null filters and keep the
+`min_size` decimal string unchanged. Deltas
+include already committed post-window arrivals, late trades, and intentional
+overlap: deduplicate on the `wt_` ID (or `payload.whale_alert_id`). This is an
+insertion feed, not updates or deletions. See the OpenAPI manifest for retention,
+row/byte bounds and source coverage.