@0xinsider/mcp 2.1.0 → 2.4.0

package/dist/sdk/client.js

@@ -19,12 +19,17 @@
  *  - Extra typed convenience methods for list/candle/webhook-event/stream
  *    surfaces and a typed `Grade` enum.
  */
-import { errorFromResponse, OxinsiderApiError, RequestTimeoutError, } from "./errors.js";
+import { errorFromResponse, OxinsiderApiError, InvalidResponseError, RequestTimeoutError, } from "./errors.js";
+import { RETRY_AFTER_CEILING_MS, retryAfterSeconds, sleepUnlessAborted, } from "./retry.js";
 /**
- * The full V1 operation table. One row per OpenAPI operation that returns a
- * `200`. Kept in lockstep with `web/public/api/v1/openapi.json` by
- * `scripts/check-sdk-openapi-drift.mjs`. Do not add a row without a matching
- * spec operation, and do not remove a spec operation without removing its row.
+ * The full V1 operation table. One row per OpenAPI operation with a
+ * documented 2xx, which since #16137 includes the `201`-only
+ * `registerAgent`; `kind` says which method reads its body. Kept in lockstep
+ * with `web/public/api/v1/openapi.json` by
+ * `scripts/check-sdk-openapi-drift.mjs`, which also checks every row's kind
+ * against the spec. Do not add a row without a matching spec operation, and
+ * do not remove a spec operation without removing its row. A redirect-only
+ * operation belongs in `REDIRECT_OPERATIONS` below, not here.
  */
 export const API_CLIENT_OPERATIONS = [
     { method: "GET", path: "/api/v1/me", operationId: "getAccountIdentity", auth: "bearer" },
@@ -76,6 +81,12 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "getTraderPnl",
         auth: "bearer",
     },
+    {
+        method: "GET",
+        path: "/api/v1/trader/{address}/categories",
+        operationId: "getTraderCategoryRecords",
+        auth: "bearer",
+    },
     // Pre-existing op-table drift (surfaced by test/drift.test.ts, #6915): these
     // 200-returning openapi operations were never mirrored into the client table.
     // Added so the table stays contract-complete against the checked-in spec. All
@@ -94,6 +105,7 @@ export const API_CLIENT_OPERATIONS = [
         path: "/api/v1/trader/{address}/context.md",
         operationId: "getTraderContextMarkdown",
         auth: "bearer",
+        kind: "text",
     },
     {
         method: "POST",
@@ -116,6 +128,18 @@ export const API_CLIENT_OPERATIONS = [
     // Pre-existing gap, fixed here (#7209): the route has shipped in openapi.json,
     // llms-full.txt, agents.md, and the discovery doc, but never in the SDK table --
     // so `drift.test.ts` was RED on main and SDK users had no typed method for it.
+    {
+        method: "GET",
+        path: "/api/v1/sports/pre-game-sides",
+        operationId: "listPreGameSides",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/sports/pre-game-side-observations",
+        operationId: "listPreGameSideObservations",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/sports-edge-signals",
@@ -128,6 +152,48 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "listSportsEdgeObservations",
         auth: "bearer",
     },
+    {
+        method: "GET",
+        path: "/api/v1/games",
+        operationId: "listGames",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/games/{event_slug}",
+        operationId: "getGame",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades",
+        operationId: "listLargeTrades",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/history",
+        operationId: "listLargeTradeHistory",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}/counterparties/executions",
+        operationId: "listLargeTradeCounterpartyExecutions",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}/counterparties/executions/{execution_id}/makers",
+        operationId: "listLargeTradeCounterpartyMakers",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/large-trades/{id}",
+        operationId: "getLargeTrade",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/whale-trades",
@@ -200,6 +266,12 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "getPlatforms",
         auth: "none",
     },
+    {
+        method: "GET",
+        path: "/api/v1/market/{condition_id}/holders",
+        operationId: "getMarketHolders",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/market/{condition_id}/intel",
@@ -223,6 +295,7 @@ export const API_CLIENT_OPERATIONS = [
         path: "/api/v1/market/{condition_id}/context.md",
         operationId: "getMarketContextMarkdown",
         auth: "bearer",
+        kind: "text",
     },
     {
         method: "GET",
@@ -230,6 +303,22 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "getMarketCandles",
         auth: "bearer",
     },
+    {
+        method: "GET",
+        path: "/api/v1/suspicious-trades",
+        operationId: "listSuspiciousTrades",
+        auth: "bearer",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/suspicious-trades/{id}",
+        operationId: "getSuspiciousTrade",
+        auth: "bearer",
+    },
+    // Deprecated aliases (#16301). Both paths stay live with no retirement
+    // date; responses carry Deprecation and a Link rel="successor-version".
+    // `/api/v1/insider-radar/{id}` also keeps answering `object: "radar_flag"`,
+    // so these entries are what an existing integration must keep exercising.
     {
         method: "GET",
         path: "/api/v1/insider-radar",
@@ -253,6 +342,7 @@ export const API_CLIENT_OPERATIONS = [
         path: "/api/v1/stream",
         operationId: "getStream",
         auth: "bearer",
+        kind: "sse",
     },
     {
         method: "GET",
@@ -296,6 +386,24 @@ export const API_CLIENT_OPERATIONS = [
         operationId: "rotateWebhookSecret",
         auth: "bearer",
     },
+    {
+        method: "POST",
+        path: "/api/v1/webhooks/{id}/rotate-secret/prepare",
+        operationId: "prepareWebhookSecret",
+        auth: "bearer",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/webhooks/{id}/rotate-secret/activate",
+        operationId: "activateWebhookSecret",
+        auth: "bearer",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/webhooks/{id}/rotate-secret/retire",
+        operationId: "retireWebhookSecret",
+        auth: "bearer",
+    },
     {
         method: "GET",
         path: "/api/v1/webhooks/events",
@@ -325,12 +433,7 @@ export const API_CLIENT_OPERATIONS = [
         path: "/api/v1/mcp",
         operationId: "createMcpJsonRpcResponse",
         auth: "bearer",
-    },
-    {
-        method: "GET",
-        path: "/api/v1/mcp",
-        operationId: "openMcpEventStream",
-        auth: "bearer",
+        kind: "jsonrpc",
     },
     {
         method: "GET",
@@ -384,9 +487,100 @@ export const API_CLIENT_OPERATIONS = [
         method: "GET",
         path: "/api/v1/pick-of-the-day/ledger",
         operationId: "getPickOfTheDayLedger",
+        // Keyless since #16459: the commitment ledger is published to be
+        // republished, so a client can read it with no key configured.
+        auth: "none",
+    },
+    {
+        method: "POST",
+        path: "/api/v1/agents/register",
+        operationId: "registerAgent",
+        // `security: []` in the document: minting a sandbox key is the one write
+        // that must work before a caller has any credential.
+        auth: "none",
+    },
+];
+/**
+ * Published operations whose success is a redirect, with the method that
+ * follows it (#16137). These have no 2xx body, so they are absent from
+ * `API_CLIENT_OPERATIONS` and from the generated `schema.ts`;
+ * `scripts/check-sdk-openapi-drift.mjs` requires every redirect-only spec
+ * operation to be declared here, so one cannot go missing in silence again.
+ */
+export const REDIRECT_OPERATIONS = [
+    {
+        method: "GET",
+        path: "/api/v1/trader/{address}/export/download",
+        operationId: "downloadTraderExport",
         auth: "bearer",
+        status: 302,
+        handledBy: "getTraderExportDownloadUrl() resolves the Location; downloadTraderExport() then fetches the object with no Authorization header.",
+    },
+    {
+        method: "GET",
+        path: "/api/v1/openapi.json",
+        operationId: "redirectApiOpenapiSpec",
+        auth: "none",
+        status: 307,
+        handledBy: "No method: the document is public and static, so fetch the URL directly and let your runtime follow the redirect. This package ships the same contract as generated types in schema.ts.",
     },
 ];
+/**
+ * Published operations this client deliberately does not wrap, with the
+ * reason. The drift check requires every remaining spec operation to be
+ * accounted for here, so "unsupported" is always a stated decision.
+ */
+export const UNSUPPORTED_OPERATIONS = [
+    {
+        method: "GET",
+        path: "/api/v1/mcp",
+        operationId: "openMcpEventStream",
+        reason: "The MCP endpoint offers no server-to-client stream: GET answers 405 by design, so a client that reconnects to it would loop (#16354). Post JSON-RPC with mcp() instead.",
+    },
+];
+/**
+ * The writes the API replays under `Idempotency-Key`: a second request with
+ * the same key and the same body returns the first result instead of
+ * repeating the write. Source of truth: the operations declaring the
+ * `Idempotency-Key` header parameter in `web/public/api/v1/openapi.json`,
+ * pinned by `scripts/check-sdk-openapi-drift.mjs` (#16182). Only these are
+ * retried on a transport or 5xx failure, and only when a key is set; a key on
+ * any other operation is refused before the request, since the server would
+ * ignore it and a retry could repeat the side effect (`verifyWebhook` sends
+ * a challenge to your URL each time; `submitTraderExport` starts a job).
+ */
+export const IDEMPOTENT_WRITE_OPERATIONS = [
+    "createWebhook",
+    "updateWebhook",
+    "deleteWebhook",
+    "rotateWebhookSecret",
+    "prepareWebhookSecret",
+    "activateWebhookSecret",
+    "retireWebhookSecret",
+    "redeliverWebhookDelivery",
+];
+/**
+ * POST operations that read and never write (#16182): the batch lookups.
+ * `POST /api/v1/traders/batch` and `POST /api/v1/markets/intel/batch` resolve
+ * their inputs and store nothing (`backend/src/api_v1/handlers/batch.rs`), so
+ * a repeat cannot duplicate a side effect. Each attempt is one request
+ * against the account's quota and one reservation of batch item units, which
+ * is exactly what a retried GET costs, so they are retried like a GET. Every
+ * other POST, PATCH or DELETE is retried only as a keyed write above.
+ */
+export const READ_ONLY_POST_OPERATIONS = [
+    "batchGetTraders",
+    "batchGetMarketIntel",
+];
+const idempotentWrites = new Set(IDEMPOTENT_WRITE_OPERATIONS);
+const readOnlyPosts = new Set(READ_ONLY_POST_OPERATIONS);
+/** The retry class of an operation; see `RetryEligibility`. */
+export function retryEligibility(operation) {
+    if (operation.method === "GET" || readOnlyPosts.has(operation.operationId)) {
+        return "read";
+    }
+    return idempotentWrites.has(operation.operationId) ? "keyed" : "never";
+}
 /**
  * Trader skill grade. Source of truth:
  * `components.schemas.Trader.properties.grade.enum` (S highest, F lowest).
@@ -394,17 +588,28 @@ export const API_CLIENT_OPERATIONS = [
 export const GRADES = ["S", "A", "B", "C", "D", "F"];
 /** Default production API base used when `baseUrl` is omitted. */
 export const DEFAULT_BASE_URL = "https://api.0xinsider.com";
+/**
+ * The sandbox server, the second `servers` entry of the OpenAPI document: no
+ * credential, no production data, every documented operation answered with
+ * its example or a deterministic sample, `?sandbox_status=<code>` for a
+ * documented error, and `X-Oxi-Sandbox: true` on every response. The two
+ * Markdown documents answer `200 text/markdown` there and the export download
+ * answers its `302` to a sample file the sandbox serves itself. `GET
+ * /api/v1/stream` is the one operation it does not simulate and answers 400,
+ * because an SSE stream is a live connection rather than a body.
+ */
+export const SANDBOX_BASE_URL = "https://0xinsider.com/sandbox";
+/** A live secret key starts with this; the sandbox never needs one. */
+const LIVE_KEY_PREFIX = "oxi_sk_live_";
 /** Default per-request deadline; see `ApiClientOptions.timeoutMs`. */
 export const DEFAULT_TIMEOUT_MS = 15_000;
 /** Default retry budget; see `ApiClientOptions.maxRetries`. */
 export const DEFAULT_MAX_RETRIES = 2;
 /** Statuses a retry can fix: rate limited, or a gateway/availability failure. */
-const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const RETRYABLE_STATUSES = new Set([408, 429, 502, 503, 504]);
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_BACKOFF_MS = 8_000;
 const RETRY_JITTER_MS = 250;
-/** A server-requested wait longer than this is the caller's to schedule. */
-const RETRY_AFTER_CEILING_MS = 60_000;
 function assertRetryCount(value, source) {
     if (!Number.isInteger(value) || value < 0) {
         throw new Error(`${source} must be a non-negative integer, got ${String(value)}`);
@@ -413,11 +618,14 @@ function assertRetryCount(value, source) {
 }
 /**
  * Milliseconds to wait before retry `attempt` (0-based), or `null` when the
- * server asked for a wait a retry loop should not hold.
+ * server asked for a wait a retry loop should not hold. The ceiling check
+ * runs on the server's number before jitter is added, so the value handed to
+ * the timer is at most `RETRY_AFTER_CEILING_MS + RETRY_JITTER_MS`, far inside
+ * the timer range (`MAX_TIMER_DELAY_MS`, `retry.ts`).
  */
 function retryDelayMs(attempt, retryAfter) {
     if (retryAfter !== null) {
-        const requested = Math.max(0, retryAfter * 1000);
+        const requested = retryAfter * 1000;
         if (requested > RETRY_AFTER_CEILING_MS)
             return null;
         return requested + Math.random() * RETRY_JITTER_MS;
@@ -425,24 +633,6 @@ function retryDelayMs(attempt, retryAfter) {
     const ceiling = Math.min(RETRY_MAX_BACKOFF_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
     return ceiling / 2 + Math.random() * (ceiling / 2);
 }
-/** Resolve after `ms`, or reject with the signal's reason the moment it aborts. */
-function sleepUnlessAborted(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason);
-            return;
-        }
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(signal?.reason);
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}
 function isLoopbackHost(hostname) {
     const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
     return (host === "localhost" ||
@@ -469,6 +659,28 @@ export function assertTrustedBaseUrl(baseUrl) {
         return url;
     throw new Error(`Refusing to send the API key to ${url.origin}: baseUrl must use https: (http: is accepted only for a loopback host such as localhost or 127.0.0.1).`);
 }
+/**
+ * The server URL as this client stores it: origin plus path, trailing slashes
+ * trimmed, and a trailing `/api/v1` removed once. Every operation path starts
+ * with `/api/v1/`, so a base that already ends in it would double the prefix;
+ * before #16138 such a base worked only because the path was discarded, and
+ * this keeps it working.
+ */
+function normalizeBaseUrl(base) {
+    const trimmed = base.toString().replace(/\/+$/, "");
+    return trimmed.replace(/\/api\/v1$/, "");
+}
+/**
+ * Join an `/api/v1/...` path onto the server URL, keeping the server's own
+ * path (`/sandbox`) exactly once. REST (`buildUrl`) and the SSE stream
+ * (`stream.ts`) both resolve through this, so the two cannot disagree about
+ * where a path-bearing base points (#16138: `new URL("/api/v1/...", base)`
+ * resolved against the origin and dropped `/sandbox`).
+ */
+export function resolveApiUrl(baseUrl, path) {
+    const suffix = path.startsWith("/") ? path : `/${path}`;
+    return new URL(`${baseUrl}${suffix}`);
+}
 /**
  * One signal that aborts on the deadline OR when the caller's signal aborts.
  * Uses native composition where available. The manual fallback removes both
@@ -512,12 +724,137 @@ function composeRequestSignal(timeoutMs, caller) {
     }
     return { signal: controller.signal, dispose };
 }
+/**
+ * `response` with `dispose` deferred to the end of its body: the stream's
+ * close, error or cancellation (#16686). Without a `dispose` (a runtime with
+ * `AbortSignal.any`, or no composition) the response is returned as is.
+ */
+function releaseWhenBodySettles(response, dispose) {
+    if (!dispose)
+        return response;
+    if (!response.body) {
+        dispose();
+        return response;
+    }
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    dispose();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (error) {
+                dispose();
+                controller.error(error);
+            }
+        },
+        cancel(reason) {
+            dispose();
+            return reader.cancel(reason);
+        },
+    });
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/** JSON-RPC methods `POST /api/v1/mcp` answers without a credential. */
+function isKeylessMcpMethod(method) {
+    return (method === "initialize" ||
+        method === "ping" ||
+        method === "tools/list" ||
+        method.startsWith("notifications/"));
+}
 function isTimeoutAbort(error) {
     return (typeof error === "object" &&
         error !== null &&
         "name" in error &&
         error.name === "TimeoutError");
 }
+/** Which method reads each kind of success body, named in the error that refuses the wrong one. */
+const READER_FOR_KIND = {
+    envelope: "call() or list()",
+    text: "text()",
+    jsonrpc: "mcp()",
+    sse: "streamFeed(), streamFeedResilient() or consumeStreamCheckpointed()",
+};
+// --- MCP JSON-RPC (#16137) ---
+/** The MCP methods `POST /api/v1/mcp` accepts, from the operation's request body. */
+export const MCP_METHODS = [
+    "initialize",
+    "notifications/initialized",
+    "notifications/cancelled",
+    "ping",
+    "tools/list",
+    "tools/call",
+];
+function isMcpJsonRpcResponse(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    const candidate = body;
+    return (candidate.jsonrpc === "2.0" &&
+        (typeof candidate.id === "string" ||
+            typeof candidate.id === "number" ||
+            candidate.id === null));
+}
+// --- Export download (#16137) ---
+/** The `downloadTraderExport` row of `REDIRECT_OPERATIONS`, as a request target. */
+const exportDownloadOperation = {
+    method: REDIRECT_OPERATIONS[0].method,
+    path: REDIRECT_OPERATIONS[0].path,
+    operationId: REDIRECT_OPERATIONS[0].operationId,
+    auth: REDIRECT_OPERATIONS[0].auth,
+};
+/**
+ * Read a presigned URL's own expiry, and refuse a destination that would
+ * downgrade the transport. The backend already validates the redirect
+ * against its expected R2 origin; this is the client-side half, so a
+ * redirect can never move a download onto plain `http:`.
+ */
+function presignedTarget(location) {
+    let url;
+    try {
+        url = new URL(location);
+    }
+    catch {
+        throw new InvalidResponseError(302, `The export download redirect is not an absolute URL: ${location}`, null);
+    }
+    if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) {
+        throw new InvalidResponseError(302, `Refusing to follow the export download redirect to ${url.origin}: it must use https: (http: is accepted only for a loopback host).`, null);
+    }
+    const signedAt = url.searchParams.get("X-Amz-Date");
+    const lifetime = url.searchParams.get("X-Amz-Expires");
+    const expiresAt = presignExpiry(signedAt, lifetime);
+    return { url: url.toString(), ...(expiresAt ? { expiresAt } : {}) };
+}
+/** `20260922T101500Z` plus `3600` seconds, as an ISO instant; `null` if either is unreadable. */
+function presignExpiry(signedAt, lifetimeSeconds) {
+    if (!signedAt || !lifetimeSeconds)
+        return null;
+    const parsed = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(signedAt);
+    const seconds = Number(lifetimeSeconds);
+    if (!parsed || !Number.isFinite(seconds))
+        return null;
+    const [, year, month, day, hour, minute, second] = parsed;
+    const signed = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second));
+    return new Date(signed + seconds * 1000).toISOString();
+}
+/** The `filename="..."` of a `Content-Disposition`, or `null`. */
+function filenameFromDisposition(disposition) {
+    if (!disposition)
+        return null;
+    const quoted = /filename\*?=(?:UTF-8'')?"([^"]+)"/i.exec(disposition);
+    if (quoted)
+        return decodeURIComponent(quoted[1]);
+    const bare = /filename\*?=(?:UTF-8'')?([^;]+)/i.exec(disposition);
+    return bare ? decodeURIComponent(bare[1].trim()) : null;
+}
 /** `GET /api/v1/leaderboard` -> parameters -> strategy (`web/public/api/v1/openapi.json`). */
 export const LEADERBOARD_STRATEGIES = [
     "accumulator",
@@ -531,16 +868,48 @@ export const LEADERBOARD_STRATEGIES = [
     "speculator",
     "swing_trader",
 ];
+/**
+ * Body-level `expand` values of `POST /api/v1/traders/batch`. The type is the
+ * operation's own body (`OperationBody["batchGetTraders"]["expand"]`); the
+ * const is the same list as a runtime value for a caller that iterates it.
+ */
+export const BATCH_TRADER_EXPANSIONS = [
+    "strategy",
+    "categories",
+    "quant_metrics",
+    "trust",
+];
 const operationsById = new Map(API_CLIENT_OPERATIONS.map((operation) => [operation.operationId, operation]));
 export class OxinsiderApiClient {
     baseUrl;
     apiKey;
+    sandbox;
     fetchImpl;
     timeoutMs;
     maxRetries;
+    /**
+     * A client for the sandbox server (#16138): `SANDBOX_BASE_URL`, no
+     * credential needed, example data only, never production data. The same
+     * as `new OxinsiderApiClient({ ...options, sandbox: true })`; pass a
+     * sandbox key (`oxi_sk_test_*`) as `apiKey` to have it checked.
+     *
+     * @example
+     * const sandbox = OxinsiderApiClient.sandbox();
+     * const board = await sandbox.listLeaderboard({ limit: 5 }); // no key
+     * board.meta?.sandbox; // true
+     */
+    static sandbox(options = {}) {
+        return new OxinsiderApiClient({ ...options, sandbox: true });
+    }
     constructor(options = {}) {
-        const base = assertTrustedBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
-        this.baseUrl = base.toString().replace(/\/+$/, "");
+        this.sandbox = options.sandbox === true;
+        const base = assertTrustedBaseUrl(options.baseUrl ?? (this.sandbox ? SANDBOX_BASE_URL : DEFAULT_BASE_URL));
+        this.baseUrl = normalizeBaseUrl(base);
+        if (this.sandbox && options.apiKey?.startsWith(LIVE_KEY_PREFIX)) {
+            // The sandbox needs no credential and ignores a live key, so the only
+            // effect of sending one is a secret on the wire for nothing.
+            throw new Error("Refusing to send a live API key (oxi_sk_live_*) to the sandbox: omit apiKey, or pass a sandbox key (oxi_sk_test_*) from POST /api/v1/agents/register.");
+        }
         this.apiKey = options.apiKey;
         this.timeoutMs =
             options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : options.timeoutMs;
@@ -552,29 +921,236 @@ export class OxinsiderApiClient {
         // Bind so a passed-through `globalThis.fetch` keeps its receiver.
         this.fetchImpl = fetchImpl.bind(globalThis);
     }
+    // The implementation signature is what both overloads narrow; `unknown`
+    // here is the widest return both can refine, not a shape a caller sees.
+    async call(operationId, options = {}) {
+        const operation = this.resolveOperation(operationId, "envelope");
+        return this.request(operation, options, async (response) => {
+            if (response.status === 304) {
+                return notModifiedResponse(response);
+            }
+            const envelope = await parseJson(response);
+            if (isApiEnvelope(envelope)) {
+                const etag = response.headers.get("etag");
+                const sandbox = response.headers.get("x-oxi-sandbox") === "true";
+                const queryIgnored = response.headers.get("x-query-ignored");
+                const effectiveQuery = response.headers.get("x-effective-query");
+                // Only ADD to a meta the server actually sent. The contract makes
+                // `meta` required on every envelope, so synthesizing one from `?? {}`
+                // would hand a caller a `ResponseMeta` missing its required fields --
+                // which is what the hand-written type hid before #14278. `status` is
+                // always lifted (#16137): `201` and `202` are load-bearing on
+                // `registerAgent` and `submitTraderExport`, and a caller cannot read
+                // them off a body that looks identical to a 200.
+                if (envelope.meta) {
+                    envelope.meta = {
+                        ...envelope.meta,
+                        status: response.status,
+                        ...(etag ? { etag } : {}),
+                        ...(sandbox ? { sandbox: true } : {}),
+                        ...(queryIgnored ? { queryIgnored } : {}),
+                        ...(effectiveQuery ? { effectiveQuery } : {}),
+                    };
+                }
+                return envelope;
+            }
+            throw new OxinsiderApiError(response.status, envelope);
+        });
+    }
+    async text(operationId, options = {}) {
+        const operation = this.resolveOperation(operationId, "text");
+        return this.request(operation, options, async (response) => response.text(), { accept: "text/markdown, text/plain;q=0.9, */*;q=0.1" });
+    }
     /**
-     * Execute any operation by id. Throws the matching `OxinsiderApiError`
-     * subclass on a non-2xx response, returns a typed `not_modified` result for a
-     * 304, and otherwise returns the parsed `{ object, data, meta }` envelope.
+     * Post one MCP JSON-RPC 2.0 message to `POST /api/v1/mcp` (#16137).
+     *
+     * The endpoint answers a JSON-RPC envelope, not the `{ object, data, meta }`
+     * envelope every other operation uses, so `call()` refuses it. A request
+     * (one carrying `id`) comes back as `status: 200` with `response` set; a
+     * supported notification (no `id`) comes back as `status: 202` with
+     * `response: null`, which is the empty body the server sends. A JSON-RPC
+     * `error` member is a protocol-level failure and is RETURNED, not thrown:
+     * only a non-2xx HTTP status throws, because an unknown tool is an answer
+     * and a revoked credential is not.
+     *
+     * The request is never retried: `tools/call` can have an effect, and the
+     * endpoint honours no `Idempotency-Key`.
+     *
+     * @example
+     * const listed = await client.mcp({ method: "tools/list", id: 1 });
+     * listed.response?.result;
      */
-    async call(operationId, options = {}) {
+    async mcp(request, options = {}) {
+        // `initialize`, `ping`, `tools/list` and the notifications need no
+        // credential (`backend/src/mcp/mod.rs`); only `tools/call` does, so the
+        // local credential check is per method (#16686). A configured key is
+        // still sent on every method.
+        const operation = this.resolveOperation("createMcpJsonRpcResponse", "jsonrpc", !isKeylessMcpMethod(request.method));
+        const { sessionId, protocolVersion, ...transportOptions } = options;
+        const headers = { ...options.headers };
+        if (sessionId !== undefined) {
+            headers["mcp-session-id"] = sessionId;
+        }
+        if (protocolVersion !== undefined) {
+            headers["mcp-protocol-version"] = protocolVersion;
+        }
+        // Set after the spread: an explicit `jsonrpc: undefined` would otherwise
+        // drop the field and the server would answer 400 (#16686).
+        const body = { ...request, jsonrpc: "2.0" };
+        return this.request(operation, { ...transportOptions, headers, body, maxRetries: 0 }, async (response) => {
+            const sessionId = response.headers.get("mcp-session-id");
+            const result = {
+                status: response.status === 202 ? 202 : 200,
+                response: null,
+                ...(sessionId ? { sessionId } : {}),
+            };
+            if (response.status === 202)
+                return result;
+            const parsed = await parseJson(response);
+            if (!isMcpJsonRpcResponse(parsed)) {
+                throw new InvalidResponseError(response.status, "POST /api/v1/mcp returned a body that is not a JSON-RPC 2.0 response: expected an object with jsonrpc \"2.0\" and an id.", parsed);
+            }
+            result.response = parsed;
+            return result;
+        });
+    }
+    /**
+     * Resolve the presigned object URL behind `GET /api/v1/trader/{address}/export/download`
+     * without downloading anything (#16137).
+     *
+     * The route answers `302` with a `Location`, which `call()` treats as an
+     * error. This reads the redirect target and stops there, so a caller can
+     * hand the URL to a download manager or a browser. The returned URL is a
+     * bearer credential in itself: anyone holding it can read the file until it
+     * expires, so do not log it.
+     *
+     * Browser caveat: `fetch` with `redirect: "manual"` yields an opaque
+     * redirect whose `Location` no script can read. The method says so rather
+     * than guessing a URL; run the download from a server runtime.
+     */
+    async getTraderExportDownloadUrl(address, jobId, options = {}) {
+        const operation = exportDownloadOperation;
+        if (!this.apiKey && !this.sandbox) {
+            throw new Error("downloadTraderExport requires an API key (oxi_sk_*)");
+        }
+        return this.request(operation, { ...options, path: { address }, query: { job_id: jobId } }, async (response) => {
+            if (response.type === "opaqueredirect" || response.status === 0) {
+                throw new InvalidResponseError(302, "This runtime hides redirect targets: fetch with redirect: \"manual\" returned an opaque redirect, so the presigned download URL cannot be read. Run the export download from a server runtime (Node 18+, Deno, Bun, a Worker).", null);
+            }
+            const location = response.headers.get("location");
+            if (!location) {
+                throw new InvalidResponseError(response.status, "GET /api/v1/trader/{address}/export/download answered a redirect with no Location header.", null);
+            }
+            return presignedTarget(location);
+        }, {
+            // The 302 IS the success here, so it must not enter the error path.
+            isSuccess: (response) => response.status === 302 || response.type === "opaqueredirect",
+            redirect: "manual",
+        });
+    }
+    /**
+     * Download a finished export (#16137): resolve the `302`, then fetch the
+     * object store directly.
+     *
+     * The second request carries NO headers at all, so the live API key never
+     * reaches the object store; the presigned URL is its own credential. The
+     * body is not buffered -- read `response.body` as a stream and write it
+     * where it belongs.
+     *
+     * There is no default deadline on the object fetch, the way `streamFeed`
+     * has none: a multi-gigabyte export would fail the 15-second REST default
+     * halfway through. Pass `signal` to cancel it, or `downloadTimeoutMs` for
+     * a deadline of your own. `timeoutMs` still bounds the redirect request.
+     *
+     * @example
+     * const { response, filename } = await client.downloadTraderExport(address, jobId);
+     * await pipeline(Readable.fromWeb(response.body), createWriteStream(filename ?? "export.json"));
+     */
+    async downloadTraderExport(address, jobId, options = {}) {
+        const target = await this.getTraderExportDownloadUrl(address, jobId, options);
+        const downloadSignal = composeRequestSignal(options.downloadTimeoutMs ?? null, options.signal);
+        let response;
+        try {
+            // No headers, and no credentials: the presigned URL authorizes itself,
+            // and forwarding the bearer would hand the live API key to the object
+            // store on every download.
+            response = await this.fetchImpl(target.url, {
+                method: "GET",
+                signal: downloadSignal.signal,
+            });
+        }
+        catch (error) {
+            downloadSignal.dispose?.();
+            throw error;
+        }
+        if (!response.ok) {
+            downloadSignal.dispose?.();
+            throw new InvalidResponseError(response.status, `The presigned export URL answered ${response.status}. A presigned link is valid for about an hour; request a fresh one with getTraderExportDownloadUrl.`, null);
+        }
+        // The caller reads the body after this returns, so the composed signal
+        // (caller abort plus `downloadTimeoutMs`) stays wired until the body ends
+        // or is cancelled, not only until the headers arrive (#16686).
+        response = releaseWhenBodySettles(response, downloadSignal.dispose);
+        const contentLength = response.headers.get("content-length");
+        return {
+            ...target,
+            response,
+            contentLength: contentLength === null ? null : Number.parseInt(contentLength, 10),
+            contentType: response.headers.get("content-type"),
+            filename: filenameFromDisposition(response.headers.get("content-disposition")),
+        };
+    }
+    /**
+     * Look up an operation and refuse it when the caller reached for the wrong
+     * reader (#16137): `call()` on a Markdown route used to fail as a bad 200.
+     */
+    resolveOperation(operationId, expected, requireCredential = true) {
         const operation = operationsById.get(operationId);
         if (!operation) {
             throw new Error(`Unknown 0xinsider API operation: ${operationId}`);
         }
-        if (operation.auth === "bearer" && !this.apiKey) {
+        const kind = operation.kind ?? "envelope";
+        if (kind !== expected) {
+            throw new Error(`${operationId} answers a "${kind}" body, not "${expected}": use ${READER_FOR_KIND[kind]}.`);
+        }
+        // The sandbox answers every operation without a credential; production
+        // does not, and the local check saves a round trip that can only be 401.
+        if (requireCredential && operation.auth === "bearer" && !this.apiKey && !this.sandbox) {
             throw new Error(`${operationId} requires an API key (oxi_sk_*)`);
         }
+        return operation;
+    }
+    /**
+     * One request pipeline for every transport: URL and headers, the retry
+     * policy, one deadline shared by every attempt, the typed error hierarchy,
+     * and cancellation held live through body consumption. `consume` runs
+     * inside that window, so a slow body is still covered by the deadline and
+     * by the caller's `signal`.
+     */
+    async request(operation, options, consume, transport = {}) {
+        const operationId = operation.operationId;
         const timeoutMs = options.timeoutMs === undefined ? this.timeoutMs : options.timeoutMs;
         const maxRetries = options.maxRetries === undefined
             ? this.maxRetries
             : assertRetryCount(options.maxRetries, "maxRetries");
         const url = this.buildUrl(operation, options);
-        const headers = this.buildHeaders(operation, options);
+        const headers = this.buildHeaders(operation, options, transport.accept);
         const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        const isSuccess = transport.isSuccess ??
+            ((response) => response.ok || response.status === 304);
+        // A key the server does not read is a false promise of safety: the
+        // request would be retried as though replayable while the route repeats
+        // its effect (#16182). Refuse it here, before anything is sent.
+        const eligibility = retryEligibility(operation);
+        const keyed = headers.has("idempotency-key");
+        if (keyed && eligibility !== "keyed") {
+            throw new Error(`${operationId} does not honour Idempotency-Key; the API replays only ${IDEMPOTENT_WRITE_OPERATIONS.join(", ")}. Remove idempotencyKey: a retry of this request could repeat its side effect.`);
+        }
         // Replaying a write without a key could repeat it (a second webhook
-        // endpoint, say), so only a GET or a keyed write is retried (#14281).
-        const retryable = operation.method === "GET" || headers.has("idempotency-key");
+        // endpoint, say), so only a read or a keyed write is retried (#14281).
+        // `headers` and `body` are built once, above, so every attempt carries
+        // the same key and the same bytes.
+        const retryable = eligibility === "read" || (eligibility === "keyed" && keyed);
         // One deadline for every attempt: a retry that cannot finish before it is
         // not started, so the caller sees the real failure, not a timeout.
         const deadlineAt = timeoutMs === null ? null : Date.now() + timeoutMs;
@@ -598,6 +1174,7 @@ export class OxinsiderApiClient {
                         headers,
                         body,
                         signal: requestSignal.signal,
+                        ...(transport.redirect ? { redirect: transport.redirect } : {}),
                     });
                 }
                 catch (error) {
@@ -610,7 +1187,7 @@ export class OxinsiderApiClient {
                     await sleepUnlessAborted(delay, requestSignal.signal);
                     continue;
                 }
-                if (response.ok || response.status === 304)
+                if (isSuccess(response))
                     break;
                 const errorBody = await parseJson(response);
                 const retryAfter = retryAfterSeconds(response);
@@ -622,22 +1199,7 @@ export class OxinsiderApiClient {
                 }
                 await sleepUnlessAborted(delay, requestSignal.signal);
             }
-            if (response.status === 304) {
-                return notModifiedResponse(response);
-            }
-            const envelope = await parseJson(response);
-            if (isApiEnvelope(envelope)) {
-                const etag = response.headers.get("etag");
-                // Only ADD to a meta the server actually sent. The contract makes
-                // `meta` required on every envelope, so synthesizing one from `?? {}`
-                // would hand a caller a `ResponseMeta` missing its required fields --
-                // which is what the hand-written type hid before #14278.
-                if (etag && envelope.meta) {
-                    envelope.meta = { ...envelope.meta, etag };
-                }
-                return envelope;
-            }
-            throw new OxinsiderApiError(response.status, envelope);
+            return await consume(response);
         }
         catch (error) {
             if (timeoutMs !== null &&
@@ -655,66 +1217,151 @@ export class OxinsiderApiClient {
             requestSignal.dispose?.();
         }
     }
-    /**
-     * Execute a Stripe-style list operation and return the list envelope.
-     * Use `paginate()` (in `pagination.ts`) to auto-follow `next_cursor`.
-     */
     async list(operationId, options = {}) {
         const result = await this.call(operationId, options);
         if (isNotModified(result)) {
             throw new OxinsiderApiError(304, "list() received a 304 not_modified; use call() if you send If-None-Match on a list endpoint");
         }
         if (!isListEnvelope(result)) {
-            throw new OxinsiderApiError(200, `Operation ${operationId} did not return a list envelope`);
+            throw new InvalidResponseError(200, `Operation ${operationId} did not return a list envelope: expected object "list", an array data, a boolean has_more and a string or absent next_cursor`, result);
         }
         return result;
     }
     // --- Typed convenience methods (key surfaces) ---
+    //
+    // Each takes the route's path parameters positionally, its documented
+    // query as `params` (list reads) or `options.query` (single reads), and
+    // the shared transport options: `signal`, `timeoutMs`, `maxRetries`,
+    // `headers` (`If-None-Match` for a conditional read) and `idempotencyKey`
+    // on a keyed write. The result is the operation's own envelope; no method
+    // takes a type argument any more (#16136).
     getTrader(address, options = {}) {
         return this.call("getTrader", { ...options, path: { address } });
     }
     getTraderPnl(address, options = {}) {
         return this.call("getTraderPnl", { ...options, path: { address } });
     }
-    batchGetTraders(identifiers, options = {}) {
-        return this.call("batchGetTraders", {
+    /**
+     * Fetch one wallet's win record per canonical category.
+     *
+     * Counts every settled market at any position size, so it can differ from
+     * `category_strengths` on `getTrader`, which reads the floored calibration
+     * sample. A category under `min_decided_for_win_rate` keeps its `wins` and
+     * `decided` with `win_rate: null` and `status: "not_enough_data"`; a category
+     * the wallet has no settled market in is absent, which means no record rather
+     * than a 0% record. The `Esports` record carries `games`: the wallet's record
+     * per esports title (`LoL`, `CS2`, `Dota 2`, ...) under the same rule, named
+     * as the holder chips name them in `category_win_rate_game`. Pass
+     * `params.category` to filter to one bucket; a filter that reaches Esports
+     * returns its games too.
+     */
+    getTraderCategoryRecords(address, params = {}, options = {}) {
+        return this.call("getTraderCategoryRecords", {
             ...options,
-            body: { identifiers },
+            path: { address },
+            query: params,
         });
     }
-    listLeaderboard(params = {}) {
-        return this.list("listLeaderboard", { query: params });
+    /**
+     * Resolve 1 to 25 traders in one request (`POST /api/v1/traders/batch`).
+     *
+     * `traders` is sent as the request body's `traders` array, the field the
+     * route requires: wallet addresses, usernames, `trd_` ids or integer trader
+     * ids, resolved in input order. Until #16135 this method sent the array as
+     * `identifiers`, a field the route does not declare, so every call was
+     * refused for a missing `traders`. `options.expand` is sent as the body's
+     * `expand` array and applies to every item.
+     *
+     * The response `data` keeps request order and one row per input, duplicates
+     * included; a row is `status: "ok"` with `data`, or `status: "error"` with
+     * the item's own `error` (an unknown identity is a per-item `not_found`, not
+     * a request failure). `meta` is the batch's `BatchResponseMeta`:
+     * `request_cost` and `rate_limit` follow the batch item quota, not the
+     * per-request one.
+     */
+    batchGetTraders(traders, options = {}) {
+        const { expand, ...request } = options;
+        return this.call("batchGetTraders", {
+            ...request,
+            body: expand === undefined ? { traders } : { traders, expand },
+        });
+    }
+    /**
+     * Resolve up to 25 markets' intel in one request
+     * (`POST /api/v1/markets/intel/batch`); `meta` is the batch's own.
+     */
+    batchGetMarketIntel(body, options = {}) {
+        return this.call("batchGetMarketIntel", { ...options, body });
+    }
+    listLeaderboard(params = {}, options = {}) {
+        return this.list("listLeaderboard", { ...options, query: params });
     }
-    listTrendingWallets(params = {}) {
-        return this.list("listTrendingWallets", { query: params });
+    listTrendingWallets(params = {}, options = {}) {
+        return this.list("listTrendingWallets", { ...options, query: params });
     }
-    listWhaleTrades(params = {}) {
-        return this.list("listWhaleTrades", { query: params });
+    listLargeTrades(params = {}, options = {}) {
+        return this.list("listLargeTrades", { ...options, query: params });
     }
-    listWhaleTradeHistory(params = {}) {
-        return this.list("listWhaleTradeHistory", { query: params });
+    listLargeTradeHistory(params = {}, options = {}) {
+        return this.list("listLargeTradeHistory", { ...options, query: params });
     }
-    listPositions(params = {}) {
-        return this.list("listPositions", { query: params });
+    /** @deprecated Use {@link listLargeTrades} (#16304); calls the deprecated `/api/v1/whale-trades`. */
+    listWhaleTrades(params = {}, options = {}) {
+        return this.list("listWhaleTrades", { ...options, query: params });
     }
-    listLargePositions(params = {}) {
-        return this.list("listLargePositions", { query: params });
+    /** @deprecated Use {@link listLargeTradeHistory} (#16304); calls the deprecated `/api/v1/whale-trades/history`. */
+    listWhaleTradeHistory(params = {}, options = {}) {
+        return this.list("listWhaleTradeHistory", { ...options, query: params });
     }
-    listSmartMoneyFlows(params = {}) {
-        return this.list("listSmartMoneyFlows", { query: params });
+    listPositions(params = {}, options = {}) {
+        return this.list("listPositions", { ...options, query: params });
+    }
+    listLargePositions(params = {}, options = {}) {
+        return this.list("listLargePositions", { ...options, query: params });
+    }
+    listSmartMoneyFlows(params = {}, options = {}) {
+        return this.list("listSmartMoneyFlows", { ...options, query: params });
     }
     /** Canonical alias of {@link listSmartMoneyFlows} (epic #6912). */
-    listSharpMoneyFlows(params = {}) {
-        return this.list("listSharpMoneyFlows", { query: params });
+    listSharpMoneyFlows(params = {}, options = {}) {
+        return this.list("listSharpMoneyFlows", { ...options, query: params });
     }
     /**
-     * List the funded-primary sports signals with additive, shadow-only category
-     * evidence. `category_skill` never changes membership, ordering, or sizing.
+     * List covered games: both sides with their provider ids and live scores, the
+     * UTC kickoff, the provider's own status, and every linked Polymarket market
+     * with its condition id and outcome token ids. Ordered by kickoff, then by
+     * `event_slug`, with unscheduled games last. An unknown `sport` or `status`
+     * returns an empty page rather than an error, and the response's `coverage`
+     * names what this deployment serves.
      */
-    listSportsEdgeSignals(params = {}) {
-        return this.list("listSportsEdgeSignals", {
-            query: params,
-        });
+    listGames(params = {}, options = {}) {
+        return this.list("listGames", { ...options, query: params });
+    }
+    /**
+     * Read one game by its `event_slug`, the identity the `live_sports_updated`
+     * webhook pulse carries. A slug outside the published coverage returns 404.
+     */
+    getGame(eventSlug, options = {}) {
+        return this.call("getGame", { ...options, path: { event_slug: eventSlug } });
+    }
+    /**
+     * List upcoming games ranked by the side profitable wallets hold, with
+     * additive, shadow-only category evidence. `category_skill` never changes
+     * membership, ordering, or sizing. Rows carry `side`, `ranked_at`,
+     * `backing_score` and `side_share`; the older `piled_side`,
+     * `signal_created_at`, `conviction_score` and `smart_score` keys carry the
+     * same values and stay on the wire.
+     */
+    listPreGameSides(params = {}, options = {}) {
+        return this.list("listPreGameSides", { ...options, query: params });
+    }
+    /**
+     * @deprecated Use {@link listPreGameSides} (#16310). Kept live; it calls the
+     * deprecated `/api/v1/sports-edge-signals` path, which answers with
+     * `Deprecation` and successor `Link` headers and the same body.
+     */
+    listSportsEdgeSignals(params = {}, options = {}) {
+        return this.list("listSportsEdgeSignals", { ...options, query: params });
     }
     /**
      * Read an explicitly observation-only sports cohort and its accountable
@@ -725,8 +1372,23 @@ export class OxinsiderApiClient {
      * additive wider-holder projection, not an arrival-history or independent
      * denominator view.
      */
+    async listPreGameSideObservations(params, options = {}) {
+        const response = await this.list("listPreGameSideObservations", {
+            ...options,
+            query: params,
+        });
+        return sportsEdgeObservationsResponse(response);
+    }
+    /**
+     * @deprecated Use {@link listPreGameSideObservations} (#16310). Kept live; it
+     * calls the deprecated `/api/v1/sports-edge-observations` path, which answers
+     * with `Deprecation` and successor `Link` headers and the same body.
+     */
     async listSportsEdgeObservations(params, options = {}) {
-        const response = await this.list("listSportsEdgeObservations", { ...options, query: params });
+        const response = await this.list("listSportsEdgeObservations", {
+            ...options,
+            query: params,
+        });
         return sportsEdgeObservationsResponse(response);
     }
     /**
@@ -738,24 +1400,40 @@ export class OxinsiderApiClient {
      * projection cutoff inside `next_cursor` is excluded while its stable page
      * position remains covered.
      */
-    async listSportsEdgeObservationsConditional(params, options = {}) {
-        const response = await this.call("listSportsEdgeObservations", { ...options, query: params });
+    async listPreGameSideObservationsConditional(params, options = {}) {
+        const response = await this.call("listPreGameSideObservations", {
+            ...options,
+            query: params,
+        });
         if (isNotModified(response)) {
             return response;
         }
-        if (!isListEnvelope(response)) {
-            throw new OxinsiderApiError(200, "listSportsEdgeObservations did not return a list envelope");
-        }
         return sportsEdgeObservationsResponse(response);
     }
-    searchMarkets(q, options = {}) {
-        return this.call("searchMarkets", {
+    /**
+     * @deprecated Use {@link listPreGameSideObservationsConditional} (#16310).
+     * Kept live on the deprecated `/api/v1/sports-edge-observations` path.
+     */
+    async listSportsEdgeObservationsConditional(params, options = {}) {
+        const response = await this.call("listSportsEdgeObservations", {
             ...options,
-            query: { q, ...options.query },
+            query: params,
         });
+        if (isNotModified(response)) {
+            return response;
+        }
+        return sportsEdgeObservationsResponse(response);
+    }
+    searchMarkets(q, options = {}) {
+        const { query, ...request } = options;
+        return this.list("searchMarkets", { ...request, query: { ...query, q } });
+    }
+    searchContent(q, options = {}) {
+        const { query, ...request } = options;
+        return this.list("searchContent", { ...request, query: { ...query, q } });
     }
-    exploreMarkets(params = {}) {
-        return this.list("exploreMarkets", { query: params });
+    exploreMarkets(params = {}, options = {}) {
+        return this.list("exploreMarkets", { ...options, query: params });
     }
     getMarketIntel(conditionId, options = {}) {
         return this.call("getMarketIntel", {
@@ -769,37 +1447,98 @@ export class OxinsiderApiClient {
             path: { condition_id: conditionId },
         });
     }
+    /**
+     * One page of a market's graded (S/A/B) holder roster from a complete
+     * provider holder scan: the list a Pick of the Day shows, for any market.
+     * `params.outcome` (`yes` | `no` | `all`), `params.min_grade` (`S` | `A` |
+     * `B`), `params.limit` and `params.cursor` (`mh_` prefix). The page carries
+     * the `market`, `scan` and roster `totals` beside `data`; `total` is the
+     * count matching the filters across every page.
+     */
+    getMarketHolders(conditionId, params = {}, options = {}) {
+        return this.list("getMarketHolders", {
+            ...options,
+            path: { condition_id: conditionId },
+            query: params,
+        });
+    }
     /**
      * Fetch bucketed OHLC candles for a market's outcome tokens.
-     * Resolution defaults to the server default; pass `query.resolution` as
-     * `"1d"` or `"1w"` to override.
+     * Resolution defaults to the server default; pass `params.resolution` as
+     * `"1d"` or `"1w"` to override. `params.from` is exclusive and `params.to`
+     * is inclusive; when both are present, `from` must be less than or equal to
+     * `to`.
      */
-    getMarketCandles(conditionId, options = {}) {
+    getMarketCandles(conditionId, params = {}, options = {}) {
         return this.call("getMarketCandles", {
             ...options,
             path: { condition_id: conditionId },
+            query: params,
         });
     }
+    /**
+     * Fetch one suspicious trade by raw `whale_alerts.id` or the `rf_`-prefixed
+     * id list responses emit. The envelope's `object` is `"suspicious_trade"`.
+     */
+    getSuspiciousTrade(id, options = {}) {
+        return this.call("getSuspiciousTrade", { ...options, path: { id } });
+    }
+    /** List stored trades whose recorded suspicion score meets the flag threshold. */
+    listSuspiciousTrades(params = {}, options = {}) {
+        return this.list("listSuspiciousTrades", { ...options, query: params });
+    }
+    /**
+     * @deprecated Use `getSuspiciousTrade()`; renamed in #16301. This method
+     * keeps calling the deprecated `GET /api/v1/insider-radar/{id}`, which stays
+     * live with no retirement date and still answers `object: "radar_flag"`, so
+     * an integration branching on that envelope keeps working.
+     */
     getInsiderRadarFlag(id, options = {}) {
         return this.call("getInsiderRadarFlag", { ...options, path: { id } });
     }
-    listInsiderRadar(params = {}) {
-        return this.list("listInsiderRadar", { query: params });
+    /**
+     * @deprecated Use `listSuspiciousTrades()`; renamed in #16301. This method
+     * keeps calling the deprecated `GET /api/v1/insider-radar`, which stays live
+     * with no retirement date and answers with `Deprecation` plus a `Link
+     * rel="successor-version"` header.
+     */
+    listInsiderRadar(params = {}, options = {}) {
+        return this.list("listInsiderRadar", { ...options, query: params });
+    }
+    getLargeTrade(id, options = {}) {
+        return this.call("getLargeTrade", { ...options, path: { id } });
+    }
+    /** @deprecated Use {@link getLargeTrade} (#16304); calls the deprecated `/api/v1/whale-trades/{id}`. */
+    getWhaleTrade(id, options = {}) {
+        return this.call("getWhaleTrade", { ...options, path: { id } });
     }
     // --- Webhooks ---
     listWebhooks(options = {}) {
-        return this.call("listWebhooks", options);
+        return this.list("listWebhooks", options);
+    }
+    getWebhook(id, options = {}) {
+        return this.call("getWebhook", { ...options, path: { id } });
+    }
+    createWebhook(body, options = {}) {
+        return this.call("createWebhook", { ...options, body });
+    }
+    updateWebhook(id, body, options = {}) {
+        return this.call("updateWebhook", { ...options, path: { id }, body });
+    }
+    deleteWebhook(id, options = {}) {
+        return this.call("deleteWebhook", { ...options, path: { id } });
     }
     /**
      * Fetch the self-describing webhook event catalog (each entry's `id`,
      * description, payload shape, and active/dormant status).
      */
     listWebhookEvents(options = {}) {
-        return this.call("listWebhookEvents", options);
+        return this.list("listWebhookEvents", options);
     }
     /** List delivery attempts for one webhook endpoint (Stripe-style list). */
-    listWebhookDeliveries(webhookId, params = {}) {
+    listWebhookDeliveries(webhookId, params = {}, options = {}) {
         return this.list("listWebhookDeliveries", {
+            ...options,
             path: { id: webhookId },
             query: params,
         });
@@ -825,9 +1564,44 @@ export class OxinsiderApiClient {
     getApiDiscovery(options = {}) {
         return this.call("getApiDiscovery", options);
     }
+    getPlatforms(options = {}) {
+        return this.call("getPlatforms", options);
+    }
     getAccountIdentity(options = {}) {
         return this.call("getAccountIdentity", options);
     }
+    /**
+     * One wallet's context as Markdown, ready to paste into a model prompt
+     * (`GET /api/v1/trader/{address}/context.md`). The JSON form of the same
+     * read is `getTraderContext`.
+     */
+    getTraderContextMarkdown(address, options = {}) {
+        return this.text("getTraderContextMarkdown", { ...options, path: { address } });
+    }
+    /**
+     * One market's context as Markdown
+     * (`GET /api/v1/market/{condition_id}/context.md`). The JSON form is
+     * `getMarketIntel`.
+     */
+    getMarketContextMarkdown(conditionId, options = {}) {
+        return this.text("getMarketContextMarkdown", {
+            ...options,
+            path: { condition_id: conditionId },
+        });
+    }
+    /**
+     * Mint a sandbox key (`POST /api/v1/agents/register`), the one write that
+     * needs no credential. Answers `201`, which is why the SDK had no method
+     * for it until #16137: the drift gate counted only operations with a
+     * documented `200`. `meta.status` is `201`; `data.api_key` is the
+     * `oxi_sk_test_*` key to pass to `OxinsiderApiClient.sandbox()`.
+     *
+     * Nothing is stored: the key cannot be listed or revoked and does not
+     * expire. Register again for another one.
+     */
+    registerAgent(options = {}) {
+        return this.call("registerAgent", options);
+    }
     getUsage(options = {}) {
         return this.call("getUsage", options);
     }
@@ -862,12 +1636,16 @@ export class OxinsiderApiClient {
     getApiKey() {
         return this.apiKey;
     }
+    /** Whether this client was built in sandbox mode (#16138). */
+    isSandbox() {
+        return this.sandbox;
+    }
     /** The resolved fetch implementation (used by the SSE stream consumer). */
     getFetch() {
         return this.fetchImpl;
     }
     buildUrl(operation, options) {
-        const url = new URL(interpolatePath(operation.path, options.path ?? {}), `${this.baseUrl}/`);
+        const url = resolveApiUrl(this.baseUrl, interpolatePath(operation.path, options.path ?? {}));
         for (const [key, value] of Object.entries(options.query ?? {})) {
             if (value === null || value === undefined) {
                 continue;
@@ -883,9 +1661,9 @@ export class OxinsiderApiClient {
         }
         return url.toString();
     }
-    buildHeaders(operation, options) {
+    buildHeaders(operation, options, accept = "application/json") {
         const headers = new Headers(options.headers);
-        headers.set("accept", "application/json");
+        headers.set("accept", accept);
         if (options.body !== undefined && !headers.has("content-type")) {
             headers.set("content-type", "application/json");
         }
@@ -895,9 +1673,18 @@ export class OxinsiderApiClient {
         if (options.idempotencyKey !== undefined) {
             headers.set("idempotency-key", options.idempotencyKey);
         }
+        if (options.strictQuery) {
+            headers.set("x-query-validation", "strict");
+        }
         return headers;
     }
 }
+/**
+ * Narrow a `call()` result to the typed 304. Takes any envelope-shaped
+ * value, so it works on an `OperationResult<K>` (whose `meta` is the
+ * operation's own type) as well as the loose `ApiClientResponse<T>`
+ * (#16136).
+ */
 export function isApiNotModifiedResponse(response) {
     return response.object === "not_modified";
 }
@@ -925,13 +1712,6 @@ async function parseJson(response) {
         return text;
     }
 }
-function retryAfterSeconds(response) {
-    const header = response.headers.get("retry-after");
-    if (!header)
-        return null;
-    const seconds = Number(header);
-    return Number.isFinite(seconds) ? seconds : null;
-}
 function notModifiedResponse(response) {
     const meta = { status: 304 };
     const etag = response.headers.get("etag");
@@ -942,6 +1722,14 @@ function notModifiedResponse(response) {
     if (requestId) {
         meta.request_id = requestId;
     }
+    const queryIgnored = response.headers.get("x-query-ignored");
+    if (queryIgnored) {
+        meta.queryIgnored = queryIgnored;
+    }
+    const effectiveQuery = response.headers.get("x-effective-query");
+    if (effectiveQuery) {
+        meta.effectiveQuery = effectiveQuery;
+    }
     return { object: "not_modified", data: null, meta };
 }
 function isApiEnvelope(body) {
@@ -950,14 +1738,23 @@ function isApiEnvelope(body) {
         "object" in body &&
         "data" in body);
 }
+/**
+ * Whether `body` is a list envelope whose control fields the walker can act
+ * on: `object: "list"`, an array `data`, a BOOLEAN `has_more`, and a
+ * `next_cursor` that is a string, `null` or absent (#16246: the check used to
+ * accept any `has_more` that was merely present, so a malformed value could
+ * be coerced into "no more pages" or "more pages" by truthiness).
+ */
 export function isListEnvelope(body) {
-    return (typeof body === "object" &&
-        body !== null &&
-        "object" in body &&
-        body.object === "list" &&
-        "data" in body &&
-        Array.isArray(body.data) &&
-        "has_more" in body);
+    if (typeof body !== "object" || body === null)
+        return false;
+    const candidate = body;
+    return (candidate.object === "list" &&
+        Array.isArray(candidate.data) &&
+        typeof candidate.has_more === "boolean" &&
+        (candidate.next_cursor === undefined ||
+            candidate.next_cursor === null ||
+            typeof candidate.next_cursor === "string"));
 }
 function sportsEdgeObservationsResponse(response) {
     const candidate = response;