@0xinsider/mcp 2.0.1 → 2.1.3

package/dist/sdk/client.d.ts

@@ -19,7 +19,7 @@
  *  - Extra typed convenience methods for list/candle/webhook-event/stream
  *    surfaces and a typed `Grade` enum.
  */
-import type { OperationData, PickOfTheDay, PickOfTheDayArchive, ResponseMeta, SportsEdgeFunnelReport, SportsEdgeObservation, SportsEdgeSignal } from "./schema.js";
+import type { OperationBody, OperationData, OperationPath, OperationQuery, OperationResponse, ResponseMeta } from "./schema.js";
 /**
  * The envelope `meta` as THIS client hands it to a caller: everything the
  * contract declares (`ResponseMeta`), plus `etag`.
@@ -34,21 +34,88 @@ import type { OperationData, PickOfTheDay, PickOfTheDayArchive, ResponseMeta, Sp
 export type ClientResponseMeta = ResponseMeta & {
     /** Lifted from the `ETag` response header by this client. */
     etag?: string;
+    /**
+     * `true` when the response carried `X-Oxi-Sandbox: true`, which every
+     * response of the sandbox server does and no production response does.
+     * Lifted from the header by this client (#16138); absent otherwise.
+     */
+    sandbox?: true;
+    /**
+     * HTTP status of the success response, set by this client (#16137).
+     * `201` on `registerAgent`, `202` on a `submitTraderExport` that queued a
+     * new job, `200` everywhere else.
+     */
+    status?: number;
+    /** Unknown query names reported by the server in compatibility mode. */
+    queryIgnored?: string;
+    /** Normalized query names and values the server actually applied. */
+    effectiveQuery?: string;
 };
 export type ApiClientMethod = "GET" | "POST" | "PATCH" | "DELETE";
 /** Whether an operation requires the `oxi_sk_*` Bearer key. */
 export type AuthMode = "none" | "bearer";
+/**
+ * How an operation carries its success body, which decides the method that
+ * can read it (#16137). Before this, every row was assumed to answer the
+ * JSON envelope, so `call()` parsed Markdown as JSON and then rejected it as
+ * a bad 200.
+ *
+ *  - `envelope` (the default, and every row that omits `kind`): a JSON
+ *    `{ object, data, meta }` body -> `call()` and `list()`.
+ *  - `text`: a `text/*` body -> `text()`. The two `context.md` reads.
+ *  - `jsonrpc`: a JSON-RPC 2.0 response, or an empty `202` for a
+ *    notification -> `mcp()`. `POST /api/v1/mcp`.
+ *  - `sse`: an open-ended `text/event-stream` -> `streamFeed()` and the
+ *    other consumers in `stream.ts`. Buffering one with `call()` or `text()`
+ *    would never return, so both refuse it.
+ *
+ * `scripts/check-sdk-openapi-drift.mjs` derives the same kind from each
+ * operation's documented success media type and schema and fails on a row
+ * that disagrees, so a route that changes shape cannot keep a stale kind.
+ */
+export type ResponseKind = "envelope" | "text" | "jsonrpc" | "sse";
 export interface ApiClientOperation {
     readonly method: ApiClientMethod;
     readonly path: string;
     readonly operationId: string;
     readonly auth: AuthMode;
+    /** How the success body is carried; absent means `"envelope"`. */
+    readonly kind?: ResponseKind;
+}
+/**
+ * A published operation whose success is a REDIRECT, so it has no success
+ * body and cannot go through `call()` (#16137). Declared here rather than
+ * omitted in silence: the drift check requires every redirect-only spec
+ * operation to appear in `REDIRECT_OPERATIONS` with the method that follows
+ * it, so "the SDK cannot do this" is never the same as "nobody noticed".
+ */
+export interface ApiRedirectOperation {
+    readonly method: ApiClientMethod;
+    readonly path: string;
+    readonly operationId: string;
+    readonly auth: AuthMode;
+    /** The documented redirect status. */
+    readonly status: number;
+    /** How a caller reaches it through this package. */
+    readonly handledBy: string;
+}
+/** A published operation this client deliberately does not wrap. */
+export interface ApiUnsupportedOperation {
+    readonly method: ApiClientMethod;
+    readonly path: string;
+    readonly operationId: string;
+    /** Why there is no method, and what to use instead. */
+    readonly reason: string;
 }
 /**
- * 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 declare const API_CLIENT_OPERATIONS: readonly [{
     readonly method: "GET";
@@ -95,6 +162,11 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/trader/{address}/pnl";
     readonly operationId: "getTraderPnl";
     readonly auth: "bearer";
+}, {
+    readonly method: "GET";
+    readonly path: "/api/v1/trader/{address}/categories";
+    readonly operationId: "getTraderCategoryRecords";
+    readonly auth: "bearer";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/trader/{address}/context";
@@ -105,6 +177,7 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/trader/{address}/context.md";
     readonly operationId: "getTraderContextMarkdown";
     readonly auth: "bearer";
+    readonly kind: "text";
 }, {
     readonly method: "POST";
     readonly path: "/api/v1/trader/{address}/export";
@@ -190,6 +263,11 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/platforms";
     readonly operationId: "getPlatforms";
     readonly auth: "none";
+}, {
+    readonly method: "GET";
+    readonly path: "/api/v1/market/{condition_id}/holders";
+    readonly operationId: "getMarketHolders";
+    readonly auth: "bearer";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/market/{condition_id}/intel";
@@ -210,6 +288,7 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/market/{condition_id}/context.md";
     readonly operationId: "getMarketContextMarkdown";
     readonly auth: "bearer";
+    readonly kind: "text";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/market/{condition_id}/candles";
@@ -235,6 +314,7 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/stream";
     readonly operationId: "getStream";
     readonly auth: "bearer";
+    readonly kind: "sse";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/webhooks";
@@ -270,6 +350,21 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/webhooks/{id}/rotate-secret";
     readonly operationId: "rotateWebhookSecret";
     readonly auth: "bearer";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/v1/webhooks/{id}/rotate-secret/prepare";
+    readonly operationId: "prepareWebhookSecret";
+    readonly auth: "bearer";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/v1/webhooks/{id}/rotate-secret/activate";
+    readonly operationId: "activateWebhookSecret";
+    readonly auth: "bearer";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/v1/webhooks/{id}/rotate-secret/retire";
+    readonly operationId: "retireWebhookSecret";
+    readonly auth: "bearer";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/webhooks/events";
@@ -295,11 +390,7 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/mcp";
     readonly operationId: "createMcpJsonRpcResponse";
     readonly auth: "bearer";
-}, {
-    readonly method: "GET";
-    readonly path: "/api/v1/mcp";
-    readonly operationId: "openMcpEventStream";
-    readonly auth: "bearer";
+    readonly kind: "jsonrpc";
 }, {
     readonly method: "GET";
     readonly path: "/api/v1/reports";
@@ -340,8 +431,98 @@ export declare const API_CLIENT_OPERATIONS: readonly [{
     readonly path: "/api/v1/pick-of-the-day/archive";
     readonly operationId: "getPickOfTheDayArchive";
     readonly auth: "bearer";
+}, {
+    readonly method: "GET";
+    readonly path: "/api/v1/pick-of-the-day/ledger";
+    readonly operationId: "getPickOfTheDayLedger";
+    readonly auth: "none";
+}, {
+    readonly method: "POST";
+    readonly path: "/api/v1/agents/register";
+    readonly operationId: "registerAgent";
+    readonly auth: "none";
 }];
 export type ApiOperationId = (typeof API_CLIENT_OPERATIONS)[number]["operationId"];
+/** Operations whose success body is a `text/*` document; read with `text()`. */
+export type TextOperationId = Extract<(typeof API_CLIENT_OPERATIONS)[number], {
+    kind: "text";
+}>["operationId"];
+/** Operations whose success body is JSON-RPC 2.0; read with `mcp()`. */
+export type JsonRpcOperationId = Extract<(typeof API_CLIENT_OPERATIONS)[number], {
+    kind: "jsonrpc";
+}>["operationId"];
+/** Operations whose success body is an open SSE stream; read through `stream.ts`. */
+export type SseOperationId = Extract<(typeof API_CLIENT_OPERATIONS)[number], {
+    kind: "sse";
+}>["operationId"];
+/**
+ * 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 declare const REDIRECT_OPERATIONS: readonly [{
+    readonly method: "GET";
+    readonly path: "/api/v1/trader/{address}/export/download";
+    readonly operationId: "downloadTraderExport";
+    readonly auth: "bearer";
+    readonly status: 302;
+    readonly handledBy: "getTraderExportDownloadUrl() resolves the Location; downloadTraderExport() then fetches the object with no Authorization header.";
+}, {
+    readonly method: "GET";
+    readonly path: "/api/v1/openapi.json";
+    readonly operationId: "redirectApiOpenapiSpec";
+    readonly auth: "none";
+    readonly status: 307;
+    readonly 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 declare const UNSUPPORTED_OPERATIONS: readonly [{
+    readonly method: "GET";
+    readonly path: "/api/v1/mcp";
+    readonly operationId: "openMcpEventStream";
+    readonly 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 declare const IDEMPOTENT_WRITE_OPERATIONS: readonly ["createWebhook", "updateWebhook", "deleteWebhook", "rotateWebhookSecret", "prepareWebhookSecret", "activateWebhookSecret", "retireWebhookSecret", "redeliverWebhookDelivery"];
+export type IdempotentWriteOperationId = (typeof IDEMPOTENT_WRITE_OPERATIONS)[number];
+/**
+ * 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 declare const READ_ONLY_POST_OPERATIONS: readonly ["batchGetTraders", "batchGetMarketIntel"];
+/**
+ * How `call()` may repeat an operation that failed with 429, 502, 503, 504 or
+ * a network error before any response (#16182):
+ * - `"read"`: a GET or a read-only POST, repeated without conditions.
+ * - `"keyed"`: an `IDEMPOTENT_WRITE_OPERATIONS` member, repeated only when
+ *   the request carries an `Idempotency-Key`, with the same key and the same
+ *   bytes on every attempt.
+ * - `"never"`: any other write; the first failure is thrown.
+ */
+export type RetryEligibility = "read" | "keyed" | "never";
+/** The retry class of an operation; see `RetryEligibility`. */
+export declare function retryEligibility(operation: Pick<ApiClientOperation, "method" | "operationId">): RetryEligibility;
 /**
  * Trader skill grade. Source of truth:
  * `components.schemas.Trader.properties.grade.enum` (S highest, F lowest).
@@ -354,6 +535,8 @@ export interface ApiRequestOptions {
     query?: Record<string, ApiQueryValue>;
     body?: unknown;
     headers?: Record<string, string>;
+    /** Reject query names the operation does not publish before it runs. */
+    strictQuery?: boolean;
     /** Cooperative cancellation; composed with the request deadline. */
     signal?: AbortSignal;
     /**
@@ -368,22 +551,46 @@ export interface ApiRequestOptions {
      */
     maxRetries?: number;
     /**
-     * Sent as the `Idempotency-Key` header. The API honours it on `createWebhook`,
-     * `updateWebhook`, `deleteWebhook`, `rotateWebhookSecret` and
-     * `redeliverWebhookDelivery`: a replay with the same key and body returns the
-     * first result instead of repeating the write.
-     * A write carrying a key is also the only non-GET request the SDK retries.
-     * On `IdempotencyInProgressError`, retry with the SAME key and body.
+     * Sent as the `Idempotency-Key` header. Accepted only on the
+     * `IDEMPOTENT_WRITE_OPERATIONS` (`createWebhook`, `updateWebhook`,
+     * `deleteWebhook`, `rotateWebhookSecret`, `prepareWebhookSecret`,
+     * `activateWebhookSecret`, `retireWebhookSecret`, `redeliverWebhookDelivery`),
+     * where a replay with the same key and body returns the first result
+     * instead of repeating the write; on any other operation `call()` throws
+     * before sending, since the server would ignore the key (#16182). A keyed
+     * write is the only non-read request the SDK retries, always with the
+     * same key and the same body bytes. On `IdempotencyInProgressError`, or
+     * when the outcome is unknown after a timeout or exhausted retries, send
+     * the SAME key and body again to learn what happened; never mint a new key
+     * for the same intent.
      */
     idempotencyKey?: string;
 }
 export interface ApiClientOptions {
     /**
-     * API base, e.g. `https://api.0xinsider.com`. Trailing slashes are trimmed.
+     * The server URL, one of the `servers` in the OpenAPI document:
+     * `https://api.0xinsider.com` (the default) or
+     * `https://0xinsider.com/sandbox`. A path on it is kept, so every operation
+     * path (`/api/v1/...`) is appended after it (#16138: the path used to be
+     * discarded, which sent a sandbox client to the live host). Trailing slashes
+     * are trimmed, and a trailing `/api/v1` is removed once, since the operation
+     * paths carry it.
      */
     baseUrl?: string;
-    /** The `oxi_sk_live_*` secret API key. */
+    /**
+     * The `oxi_sk_live_*` secret API key, or a sandbox key (`oxi_sk_test_*`)
+     * when `sandbox` is set.
+     */
     apiKey?: string;
+    /**
+     * Explicit sandbox mode (#16138). `baseUrl` defaults to
+     * `SANDBOX_BASE_URL` (`https://0xinsider.com/sandbox`), every operation is
+     * allowed without a key, since the sandbox needs no credential, and a live
+     * key (`oxi_sk_live_*`) is refused by the constructor so it is never sent
+     * there. A sandbox key from `POST /api/v1/agents/register` is optional and
+     * is sent when given. `OxinsiderApiClient.sandbox()` builds one.
+     */
+    sandbox?: boolean;
     /** Override the global `fetch` (e.g. for testing or a proxy agent). */
     fetch?: typeof fetch;
     /**
@@ -397,13 +604,18 @@ export interface ApiClientOptions {
      * How many times a failed idempotent request is retried (#14281). Default
      * `DEFAULT_MAX_RETRIES` (2); `0` disables retries.
      *
-     * Retried: a GET, or a write carrying an `Idempotency-Key`, that failed with
-     * 429, 502, 503, 504, or a network error before any response. The wait is the
-     * response's `Retry-After` plus up to 250 ms of jitter when present, otherwise
-     * a jittered exponential backoff from 500 ms capped at 8 s. A `Retry-After`
-     * longer than 60 s is not waited out; the error is thrown so the caller can
-     * schedule it. Never retried: 400, 401, 402, 403, 404, 409, 500, a write
-     * without a key, a timeout, or a caller abort. A retry never starts unless it
+     * Retried: a GET, a read-only POST (`READ_ONLY_POST_OPERATIONS`), or an
+     * `IDEMPOTENT_WRITE_OPERATIONS` write carrying an `Idempotency-Key`, that
+     * failed with 408, 429, 502, 503, 504, or a network error before any
+     * response (`retryEligibility`, #16182). A 408 is the server's own timeout
+     * (`request_timeout`, #16146): it carries `Retry-After` on a GET, and a
+     * keyed write replays safely. The wait is the
+     * response's `Retry-After` (delta-seconds or an HTTP-date, `parseRetryAfter`)
+     * plus up to 250 ms of jitter when present, otherwise a jittered exponential
+     * backoff from 500 ms capped at 8 s. A `Retry-After` longer than
+     * `RETRY_AFTER_CEILING_MS` (60 s) is not waited out; the error is thrown so
+     * the caller can schedule it from `retryAfterSeconds` or `retryAt`. Never retried: 400, 401, 402, 403, 404, 409, 500, a write
+     * without a key, this client's own timeout, or a caller abort. A retry never starts unless it
      * can finish inside `timeoutMs`, and a caller `AbortSignal` ends a backoff at
      * once.
      */
@@ -411,6 +623,14 @@ export interface ApiClientOptions {
 }
 /** Default production API base used when `baseUrl` is omitted. */
 export declare 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. Streams and
+ * file downloads are not simulated there and answer 400.
+ */
+export declare const SANDBOX_BASE_URL = "https://0xinsider.com/sandbox";
 /** Default per-request deadline; see `ApiClientOptions.timeoutMs`. */
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 /** Default retry budget; see `ApiClientOptions.maxRetries`. */
@@ -422,6 +642,14 @@ export declare const DEFAULT_MAX_RETRIES = 2;
  * else throws from the constructor, before any request is sent (#11115).
  */
 export declare function assertTrustedBaseUrl(baseUrl: string): URL;
+/**
+ * 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 declare function resolveApiUrl(baseUrl: string, path: string): URL;
 /**
  * One signal that aborts on the deadline OR when the caller's signal aborts.
  * Uses native composition where available. The manual fallback removes both
@@ -464,11 +692,7 @@ export interface CategorySkillStatusCounts {
     unknown: number;
     degraded: number;
 }
-export interface SportsEdgeSignalsParams extends ListParams {
-    category?: string;
-    horizon_hours?: number;
-    min_grade?: "S" | "A" | "B";
-}
+export type SportsEdgeSignalsParams = OperationQuery["listSportsEdgeSignals"];
 /** Observation cohorts exposed by `listSportsEdgeObservations`. */
 export type SportsEdgeObservationCohort = "wider_holder" | "in_play" | "emerging_pile";
 /** Source of the provider holder snapshot used to build an observation. */
@@ -489,23 +713,14 @@ export type SportsEdgeObservationOutcomeIndex = 0 | 1;
 export type SportsEdgeObservationTopGrade = "S" | "A" | "B";
 /** Canonical sports emitted by observation responses. */
 export type SportsEdgeObservationSport = "Basketball" | "Football" | "Baseball" | "Hockey" | "MMA" | "Boxing" | "Soccer" | "Cricket" | "Golf" | "Tennis" | "Esports" | "Racing" | "Table Tennis" | "Pickleball";
-/** Full list response, including the observation snapshot and accountable funnel. */
-export interface SportsEdgeObservationsResponse extends ApiListEnvelope<SportsEdgeObservation> {
-    next_cursor: string | null;
-    snapshot_as_of: string;
-    /**
-     * Snapshot-wide operational/unknown-completeness verdict. True means treat
-     * the evidence as partial; fully accounted `capacity_limited` rows alone do
-     * not set it.
-     */
-    degraded: boolean;
-    funnel: SportsEdgeFunnelReport;
-    meta: ClientResponseMeta;
-}
-export interface SportsEdgeObservationsParams extends ListParams {
-    cohort: SportsEdgeObservationCohort;
-    category?: string;
-}
+/**
+ * Full list response, including the observation snapshot and accountable
+ * funnel: the operation's own envelope (#16136). `degraded` is the
+ * snapshot-wide verdict; fully accounted `capacity_limited` rows alone do
+ * not set it.
+ */
+export type SportsEdgeObservationsResponse = OperationEnvelope<"listSportsEdgeObservations">;
+export type SportsEdgeObservationsParams = OperationQuery["listSportsEdgeObservations"];
 /**
  * One qualifying category expert on a Pick of the Day's backed side.
  *
@@ -601,10 +816,151 @@ export interface ApiNotModifiedResponse {
         status: 304;
         etag?: string;
         request_id?: string;
+        queryIgnored?: string;
+        effectiveQuery?: string;
         [key: string]: unknown;
     };
 }
 export type ApiClientResponse<T> = ApiEnvelope<T> | ApiNotModifiedResponse;
+/** `etag`, `sandbox` and `status`, lifted by this client onto whichever `meta` the operation declares. */
+export type ClientMeta<M> = M & {
+    /** Lifted from the `ETag` response header by this client. */
+    etag?: string;
+    /** `true` when the response carried `X-Oxi-Sandbox: true` (#16138). */
+    sandbox?: true;
+    /**
+     * The HTTP status of the success response, set by this client (#16137).
+     *
+     * Not every operation answers `200`, and the difference is the answer:
+     * `registerAgent` answers `201`, and `submitTraderExport` answers `202`
+     * when it queued a new job and `200` when it returned one that already
+     * existed. The envelope body is the same shape either way, so without this
+     * a caller could not tell a fresh job from a replayed one.
+     */
+    status?: number;
+};
+/** Operations whose 200 is the JSON envelope (`object`, `data`, `meta`); the two text bodies and the JSON-RPC post are not. */
+export type EnvelopeOperationId = {
+    [K in ApiOperationId]: OperationResponse[K] extends {
+        object: string;
+        data: unknown;
+        meta: unknown;
+    } ? K : never;
+}[ApiOperationId];
+/** Envelope operations that page: `data` is an array and `has_more` is declared. */
+export type ListOperationId = {
+    [K in EnvelopeOperationId]: OperationResponse[K] extends {
+        has_more: boolean;
+        data: readonly unknown[];
+    } ? K : never;
+}[EnvelopeOperationId];
+/** The operation's documented `meta` type. */
+export type OperationMeta<K extends ApiOperationId> = OperationResponse[K] extends {
+    meta: infer M;
+} ? M : never;
+/**
+ * What a 200 resolves to: the operation's own envelope (`object` literal,
+ * `data`, every top-level field such as `has_more` or a list's `totals`) with
+ * its own `meta` type (`BatchResponseMeta` on a batch, `EventReplayMeta` on
+ * the replay, `ResponseMeta` elsewhere) plus this client's lifted `etag` and
+ * `sandbox`.
+ */
+export type OperationEnvelope<K extends EnvelopeOperationId> = Omit<OperationResponse[K], "meta"> & {
+    meta: ClientMeta<OperationMeta<K>>;
+};
+/** A `call()` result: the envelope, or the typed 304 when `If-None-Match` matched. */
+export type OperationResult<K extends EnvelopeOperationId> = OperationEnvelope<K> | ApiNotModifiedResponse;
+/** One item of a list operation's `data`. */
+export type OperationItem<K extends ListOperationId> = OperationData[K] extends readonly (infer I)[] ? I : never;
+/**
+ * `call()` options bound to one operation: `path` is required exactly when
+ * the route has path parameters, `query` is the documented query, `body` is
+ * required exactly when the operation declares a request body, and the
+ * transport options (`signal`, `timeoutMs`, `maxRetries`, `headers`,
+ * `idempotencyKey`) are the shared ones.
+ */
+export type OperationRequestOptions<K extends ApiOperationId> = Omit<ApiRequestOptions, "path" | "query" | "body"> & (OperationPath[K] extends Record<string, never> ? {
+    path?: OperationPath[K];
+} : {
+    path: OperationPath[K];
+}) & {
+    query?: OperationQuery[K];
+} & ([
+    OperationBody[K]
+] extends [never] ? {
+    body?: never;
+} : {
+    body: OperationBody[K];
+});
+/** The transport options a convenience method forwards: everything but the parts it fills itself. */
+export type ConvenienceOptions = Omit<ApiRequestOptions, "path" | "query" | "body">;
+/** The MCP methods `POST /api/v1/mcp` accepts, from the operation's request body. */
+export declare const MCP_METHODS: readonly ["initialize", "notifications/initialized", "notifications/cancelled", "ping", "tools/list", "tools/call"];
+export type McpMethod = (typeof MCP_METHODS)[number];
+/**
+ * One JSON-RPC 2.0 message for `POST /api/v1/mcp`. `jsonrpc` defaults to
+ * `"2.0"`. Omit `id` for a notification, which answers an empty `202`.
+ */
+export interface McpJsonRpcRequest {
+    jsonrpc?: "2.0";
+    /** Echoed exactly in the response. Omit it on a notification. */
+    id?: string | number | null;
+    method: McpMethod;
+    params?: Record<string, unknown>;
+}
+/** The JSON-RPC 2.0 response body, as the operation declares it. */
+export type McpJsonRpcResponse = OperationResponse["createMcpJsonRpcResponse"];
+/** Options for `mcp()`: the shared transport options plus the two MCP headers. */
+export interface McpOptions extends ConvenienceOptions {
+    /** Sent as `Mcp-Session-Id`; use the value a previous response returned. */
+    sessionId?: string;
+    /**
+     * Sent as `MCP-Protocol-Version`. Omit it and the server serves
+     * `2025-03-26`; an unsupported revision is a `400`.
+     */
+    protocolVersion?: string;
+}
+/** What `mcp()` returns: the JSON-RPC response, or the accepted notification. */
+export interface McpResult {
+    /** `200` for a JSON-RPC response, `202` for an accepted notification. */
+    status: 200 | 202;
+    /** The JSON-RPC body, or `null` for the empty `202` a notification receives. */
+    response: McpJsonRpcResponse | null;
+    /** `Mcp-Session-Id`, when the server issued or echoed one. */
+    sessionId?: string;
+}
+/** Where a finished export actually lives, from the `302`'s `Location`. */
+export interface TraderExportDownloadTarget {
+    /**
+     * The presigned object URL. It authorizes itself, so treat it as a
+     * credential: never log it and never share it.
+     */
+    url: string;
+    /**
+     * When the link stops working, read from the URL's own SigV4
+     * `X-Amz-Date` and `X-Amz-Expires`. Absent when the URL does not carry
+     * them; the API signs a one-hour link today.
+     */
+    expiresAt?: string;
+}
+/** The object response, with what its headers said about the file. */
+export interface TraderExportDownload extends TraderExportDownloadTarget {
+    /** Not buffered: read `response.body` as a stream. */
+    response: Response;
+    /** `Content-Length` of the object, or `null` when the store sent none. */
+    contentLength: number | null;
+    contentType: string | null;
+    /** The filename from `Content-Disposition`, or `null`. */
+    filename: string | null;
+}
+export interface TraderExportDownloadOptions extends ConvenienceOptions {
+    /**
+     * A deadline in ms for the OBJECT fetch, which has none by default: an
+     * export can be far larger than a REST read and the 15-second default
+     * would cut it off mid-file. `timeoutMs` still bounds the redirect.
+     */
+    downloadTimeoutMs?: number | null;
+}
 /** Shared paging params accepted by Stripe-style list endpoints. */
 export interface ListParams {
     limit?: number;
@@ -615,77 +971,228 @@ export interface ListParams {
 export declare const LEADERBOARD_STRATEGIES: readonly ["accumulator", "algo_trader", "arbitrageur", "directional", "event_driven", "market_maker", "momentum", "scalper", "speculator", "swing_trader"];
 export type LeaderboardStrategy = (typeof LEADERBOARD_STRATEGIES)[number];
 /**
- * Query parameters for `GET /api/v1/leaderboard`. The board has no `min_grade`:
- * it only holds S, A, and B traders, and the backend drops an unknown query key
- * instead of rejecting it (#10642).
+ * Query parameters for `GET /api/v1/leaderboard`, from the operation
+ * (#16136). The board has no `min_grade`: it only holds S, A, and B traders,
+ * and the backend drops an unknown query key instead of rejecting it
+ * (#10642), which is why the type now refuses one.
  */
-export interface LeaderboardListParams extends ListParams {
-    category?: string;
-    strategy?: LeaderboardStrategy;
-}
+export type LeaderboardListParams = OperationQuery["listLeaderboard"];
 /** Query parameters for `GET /api/v1/leaderboard/trending`. */
-export interface TrendingWalletsParams extends ListParams {
-    window?: "7d" | "30d";
-}
-/** Query parameters shared by the V1 whale-trade list and history reads. */
-export interface WhaleTradeListParams extends ListParams {
-    min_size?: number;
-    category?: string;
-    min_grade?: Grade;
-    /** Keep only rows with persisted suspicion_score >= 60. */
-    suspicious_only?: boolean;
-}
-/** Query parameters for the V1 historical whale-trade replay. */
-export interface WhaleTradeHistoryParams extends WhaleTradeListParams {
-    condition_id?: string;
-    trader?: string;
-    from?: string;
-    to?: string;
-    platform?: "polymarket" | "all";
+export type TrendingWalletsParams = OperationQuery["listTrendingWallets"];
+/** Query parameters of the V1 whale-trade list. */
+export type WhaleTradeListParams = OperationQuery["listWhaleTrades"];
+/** Query parameters of the V1 historical whale-trade replay. */
+export type WhaleTradeHistoryParams = OperationQuery["listWhaleTradeHistory"];
+/** Query parameters of `GET /api/v1/positions`. */
+export type PositionsListParams = OperationQuery["listPositions"];
+/** Query parameters of `GET /api/v1/large-positions`. */
+export type LargePositionsListParams = OperationQuery["listLargePositions"];
+/** Query parameters of the sharp-money flows read and its legacy alias. */
+export type SharpMoneyFlowsParams = OperationQuery["listSharpMoneyFlows"];
+/** Query parameters of `GET /api/v1/insider-radar`: `min_suspicion` and `severity`, not a grade. */
+export type InsiderRadarListParams = OperationQuery["listInsiderRadar"];
+/** Query parameters of `GET /api/v1/markets/explore`. */
+export type ExploreMarketsParams = OperationQuery["exploreMarkets"];
+/**
+ * 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 declare const BATCH_TRADER_EXPANSIONS: readonly ["strategy", "categories", "quant_metrics", "trust"];
+export type BatchTraderExpand = NonNullable<OperationBody["batchGetTraders"]["expand"]>[number];
+/**
+ * Options for `batchGetTraders`. The body is built from the positional
+ * `traders` array and `expand`, so `body` is not accepted here.
+ */
+export interface BatchGetTradersOptions extends ConvenienceOptions {
+    /** Shared expand flags applied to every trader item; sent as the body's `expand`. */
+    expand?: OperationBody["batchGetTraders"]["expand"];
 }
 export declare class OxinsiderApiClient {
     private readonly baseUrl;
     private readonly apiKey?;
+    private readonly sandbox;
     private readonly fetchImpl;
     private readonly timeoutMs;
     private readonly 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?: Omit<ApiClientOptions, "sandbox">): OxinsiderApiClient;
     constructor(options?: ApiClientOptions);
     /**
-     * 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.
-     */
-    call<T>(operationId: ApiOperationId, options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
-    /**
-     * Execute a Stripe-style list operation and return the list envelope.
-     * Use `paginate()` (in `pagination.ts`) to auto-follow `next_cursor`.
-     */
-    list<T>(operationId: ApiOperationId, options?: ApiRequestOptions): Promise<ApiListEnvelope<T>>;
-    getTrader<T = OperationData["getTrader"]>(address: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
-    getTraderPnl<T = OperationData["getTraderPnl"]>(address: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
-    batchGetTraders<T = OperationData["batchGetTraders"]>(identifiers: readonly string[], options?: Omit<ApiRequestOptions, "body">): Promise<ApiClientResponse<T>>;
-    listLeaderboard<T = OperationData["listLeaderboard"][number]>(params?: LeaderboardListParams): Promise<ApiListEnvelope<T>>;
-    listTrendingWallets<T = OperationData["listTrendingWallets"][number]>(params?: TrendingWalletsParams): Promise<ApiListEnvelope<T>>;
-    listWhaleTrades<T = OperationData["listWhaleTrades"][number]>(params?: WhaleTradeListParams): Promise<ApiListEnvelope<T>>;
-    listWhaleTradeHistory<T = OperationData["listWhaleTradeHistory"][number]>(params?: WhaleTradeHistoryParams): Promise<ApiListEnvelope<T>>;
-    listPositions<T = OperationData["listPositions"][number]>(params?: ListParams & {
-        min_grade?: Grade;
-    }): Promise<ApiListEnvelope<T>>;
-    listLargePositions<T = OperationData["listLargePositions"][number]>(params?: ListParams & {
-        min_grade?: Grade;
-    }): Promise<ApiListEnvelope<T>>;
-    listSmartMoneyFlows<T = OperationData["listSmartMoneyFlows"][number]>(params?: ListParams & {
-        min_grade?: Grade;
-    }): Promise<ApiListEnvelope<T>>;
+     * Execute an envelope 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 operation's
+     * own `{ object, data, meta, ... }` envelope (#16136): `path` is required
+     * exactly when the route has path parameters, `query` and `body` are the
+     * documented ones, and `data` and `meta` are the operation's types.
+     *
+     * @example
+     * const trader = await client.call("getTrader", { path: { address } });
+     * if (trader.object === "trader") trader.data.grade; // typed
+     */
+    call<K extends EnvelopeOperationId>(operationId: K, options?: OperationRequestOptions<K>): Promise<OperationResult<K>>;
+    /**
+     * The untyped form, for an operation chosen at runtime or a caller that
+     * asserts the shape itself with `T`: loose `path`, `query` and `body`, and
+     * the generic `{ object, data, meta? }` envelope back. Every convenience
+     * method uses the typed form above; reach for this one only when the
+     * operation id is not a literal.
+     */
+    call<T = unknown>(operationId: ApiOperationId, options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    /**
+     * Read a `text/*` operation's body as a string (#16137).
+     *
+     * `getTraderContextMarkdown` and `getMarketContextMarkdown` answer
+     * `text/markdown`, which `call()` used to parse as JSON and then reject as
+     * an invalid 200. Authentication, the request deadline, retries and the
+     * typed error hierarchy are the same as `call()`; only the body differs.
+     *
+     * @example
+     * const md = await client.text("getTraderContextMarkdown", { path: { address } });
+     */
+    text<K extends TextOperationId>(operationId: K, options?: OperationRequestOptions<K>): Promise<string>;
+    /** The untyped form, for an operation id chosen at runtime. */
+    text(operationId: ApiOperationId, options?: ApiRequestOptions): Promise<string>;
+    /**
+     * 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;
+     */
+    mcp(request: McpJsonRpcRequest, options?: McpOptions): Promise<McpResult>;
+    /**
+     * 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.
+     */
+    getTraderExportDownloadUrl(address: OperationPath["getTraderExportStatus"]["address"], jobId: OperationQuery["getTraderExportStatus"]["job_id"], options?: ConvenienceOptions): Promise<TraderExportDownloadTarget>;
+    /**
+     * 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"));
+     */
+    downloadTraderExport(address: OperationPath["getTraderExportStatus"]["address"], jobId: OperationQuery["getTraderExportStatus"]["job_id"], options?: TraderExportDownloadOptions): Promise<TraderExportDownload>;
+    /**
+     * 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.
+     */
+    private resolveOperation;
+    /**
+     * 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`.
+     */
+    private request;
+    /**
+     * Execute a Stripe-style list operation and return its own list envelope
+     * (`data`, `has_more`, `next_cursor`, and the route's extra fields such as
+     * `facets` or `totals`). Use `paginate()` (in `pagination.ts`) to
+     * auto-follow `next_cursor`.
+     */
+    list<K extends ListOperationId>(operationId: K, options?: OperationRequestOptions<K>): Promise<OperationEnvelope<K>>;
+    /** The untyped form; see the second `call` signature. */
+    list<T = unknown>(operationId: ApiOperationId, options?: ApiRequestOptions): Promise<ApiListEnvelope<T>>;
+    getTrader(address: OperationPath["getTrader"]["address"], options?: Omit<OperationRequestOptions<"getTrader">, "path">): Promise<OperationResult<"getTrader">>;
+    getTraderPnl(address: OperationPath["getTraderPnl"]["address"], options?: Omit<OperationRequestOptions<"getTraderPnl">, "path">): Promise<OperationResult<"getTraderPnl">>;
+    /**
+     * 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: OperationPath["getTraderCategoryRecords"]["address"], params?: OperationQuery["getTraderCategoryRecords"], options?: ConvenienceOptions): Promise<OperationResult<"getTraderCategoryRecords">>;
+    /**
+     * 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: OperationBody["batchGetTraders"]["traders"], options?: BatchGetTradersOptions): Promise<OperationResult<"batchGetTraders">>;
+    /**
+     * Resolve up to 25 markets' intel in one request
+     * (`POST /api/v1/markets/intel/batch`); `meta` is the batch's own.
+     */
+    batchGetMarketIntel(body: OperationBody["batchGetMarketIntel"], options?: ConvenienceOptions): Promise<OperationResult<"batchGetMarketIntel">>;
+    listLeaderboard(params?: LeaderboardListParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listLeaderboard">>;
+    listTrendingWallets(params?: TrendingWalletsParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listTrendingWallets">>;
+    listWhaleTrades(params?: WhaleTradeListParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listWhaleTrades">>;
+    listWhaleTradeHistory(params?: WhaleTradeHistoryParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listWhaleTradeHistory">>;
+    listPositions(params?: PositionsListParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listPositions">>;
+    listLargePositions(params?: LargePositionsListParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listLargePositions">>;
+    listSmartMoneyFlows(params?: OperationQuery["listSmartMoneyFlows"], options?: ConvenienceOptions): Promise<OperationEnvelope<"listSmartMoneyFlows">>;
     /** Canonical alias of {@link listSmartMoneyFlows} (epic #6912). */
-    listSharpMoneyFlows<T = OperationData["listSharpMoneyFlows"][number]>(params?: ListParams & {
-        min_grade?: Grade;
-    }): Promise<ApiListEnvelope<T>>;
+    listSharpMoneyFlows(params?: SharpMoneyFlowsParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listSharpMoneyFlows">>;
     /**
      * List the funded-primary sports signals with additive, shadow-only category
      * evidence. `category_skill` never changes membership, ordering, or sizing.
      */
-    listSportsEdgeSignals(params?: SportsEdgeSignalsParams): Promise<ApiListEnvelope<SportsEdgeSignal>>;
+    listSportsEdgeSignals(params?: SportsEdgeSignalsParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listSportsEdgeSignals">>;
     /**
      * Read an explicitly observation-only sports cohort and its accountable
      * per-sport funnel. This surface is isolated from the funded signals route.
@@ -695,7 +1202,7 @@ export declare class OxinsiderApiClient {
      * additive wider-holder projection, not an arrival-history or independent
      * denominator view.
      */
-    listSportsEdgeObservations(params: SportsEdgeObservationsParams, options?: Omit<ApiRequestOptions, "query">): Promise<SportsEdgeObservationsResponse>;
+    listSportsEdgeObservations(params: SportsEdgeObservationsParams, options?: ConvenienceOptions): Promise<SportsEdgeObservationsResponse>;
     /**
      * Typed conditional-read variant of {@link listSportsEdgeObservations}.
      * Returns the full observation response on 200 or a typed `not_modified`
@@ -705,29 +1212,48 @@ export declare class OxinsiderApiClient {
      * projection cutoff inside `next_cursor` is excluded while its stable page
      * position remains covered.
      */
-    listSportsEdgeObservationsConditional(params: SportsEdgeObservationsParams, options?: Omit<ApiRequestOptions, "query">): Promise<SportsEdgeObservationsResponse | ApiNotModifiedResponse>;
-    searchMarkets<T = OperationData["searchMarkets"]>(q: string, options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
-    exploreMarkets<T = OperationData["getMarketIntel"]>(params?: ListParams): Promise<ApiListEnvelope<T>>;
-    getMarketIntel<T = OperationData["getMarketIntel"]>(conditionId: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
-    getMarketSnapshot<T = OperationData["getMarketSnapshot"]>(conditionId: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
+    listSportsEdgeObservationsConditional(params: SportsEdgeObservationsParams, options?: ConvenienceOptions): Promise<SportsEdgeObservationsResponse | ApiNotModifiedResponse>;
+    searchMarkets(q: OperationQuery["searchMarkets"]["q"], options?: ConvenienceOptions & {
+        query?: Omit<OperationQuery["searchMarkets"], "q">;
+    }): Promise<OperationEnvelope<"searchMarkets">>;
+    searchContent(q: OperationQuery["searchContent"]["q"], options?: ConvenienceOptions & {
+        query?: Omit<OperationQuery["searchContent"], "q">;
+    }): Promise<OperationEnvelope<"searchContent">>;
+    exploreMarkets(params?: ExploreMarketsParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"exploreMarkets">>;
+    getMarketIntel(conditionId: OperationPath["getMarketIntel"]["condition_id"], options?: Omit<OperationRequestOptions<"getMarketIntel">, "path">): Promise<OperationResult<"getMarketIntel">>;
+    getMarketSnapshot(conditionId: OperationPath["getMarketSnapshot"]["condition_id"], options?: Omit<OperationRequestOptions<"getMarketSnapshot">, "path">): Promise<OperationResult<"getMarketSnapshot">>;
+    /**
+     * 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: OperationPath["getMarketHolders"]["condition_id"], params?: OperationQuery["getMarketHolders"], options?: ConvenienceOptions): Promise<OperationEnvelope<"getMarketHolders">>;
     /**
      * 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<T = OperationData["getMarketCandles"]>(conditionId: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
-    getInsiderRadarFlag<T = OperationData["getInsiderRadarFlag"]>(id: string, options?: Omit<ApiRequestOptions, "path">): Promise<ApiClientResponse<T>>;
-    listInsiderRadar<T = OperationData["listWebhooks"]>(params?: ListParams & {
-        min_grade?: Grade;
-    }): Promise<ApiListEnvelope<T>>;
-    listWebhooks<T = OperationData["listWebhooks"]>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    getMarketCandles(conditionId: OperationPath["getMarketCandles"]["condition_id"], params?: OperationQuery["getMarketCandles"], options?: ConvenienceOptions): Promise<OperationResult<"getMarketCandles">>;
+    getInsiderRadarFlag(id: OperationPath["getInsiderRadarFlag"]["id"], options?: ConvenienceOptions): Promise<OperationResult<"getInsiderRadarFlag">>;
+    listInsiderRadar(params?: InsiderRadarListParams, options?: ConvenienceOptions): Promise<OperationEnvelope<"listInsiderRadar">>;
+    getWhaleTrade(id: OperationPath["getWhaleTrade"]["id"], options?: ConvenienceOptions): Promise<OperationResult<"getWhaleTrade">>;
+    listWebhooks(options?: ConvenienceOptions): Promise<OperationEnvelope<"listWebhooks">>;
+    getWebhook(id: OperationPath["getWebhook"]["id"], options?: ConvenienceOptions): Promise<OperationResult<"getWebhook">>;
+    createWebhook(body: OperationBody["createWebhook"], options?: ConvenienceOptions): Promise<OperationResult<"createWebhook">>;
+    updateWebhook(id: OperationPath["updateWebhook"]["id"], body: OperationBody["updateWebhook"], options?: ConvenienceOptions): Promise<OperationResult<"updateWebhook">>;
+    deleteWebhook(id: OperationPath["deleteWebhook"]["id"], options?: ConvenienceOptions): Promise<OperationResult<"deleteWebhook">>;
     /**
      * Fetch the self-describing webhook event catalog (each entry's `id`,
      * description, payload shape, and active/dormant status).
      */
-    listWebhookEvents<T = OperationData["listWebhookEvents"]>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    listWebhookEvents(options?: ConvenienceOptions): Promise<OperationEnvelope<"listWebhookEvents">>;
     /** List delivery attempts for one webhook endpoint (Stripe-style list). */
-    listWebhookDeliveries<T = OperationData["redeliverWebhookDelivery"]>(webhookId: string | number, params?: ListParams): Promise<ApiListEnvelope<T>>;
+    listWebhookDeliveries(webhookId: OperationPath["listWebhookDeliveries"]["id"], params?: OperationQuery["listWebhookDeliveries"], options?: ConvenienceOptions): Promise<OperationEnvelope<"listWebhookDeliveries">>;
     /**
      * Requeue one `dead_letter` delivery with a fresh attempt budget and return
      * the delivery row. Re-enabling a disabled endpoint resends nothing, so this
@@ -736,30 +1262,78 @@ export declare class OxinsiderApiClient {
      * disabled, unverified, or no longer subscribed to the delivery's event type;
      * the error message names the fix. Pass `idempotencyKey` to make a retry safe.
      */
-    redeliverWebhookDelivery<T = OperationData["redeliverWebhookDelivery"]>(webhookId: string | number, deliveryId: string | number, options?: Omit<ApiRequestOptions, "path" | "body">): Promise<ApiClientResponse<T>>;
-    getHealth<T = OperationData["getHealth"]>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
-    getApiDiscovery<T = OperationData["getApiDiscovery"]>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
-    getAccountIdentity(options?: ApiRequestOptions): Promise<ApiClientResponse<{
-        user_id: number;
-        credential_id: number;
-        credential_kind: "api_key" | "oauth_grant";
-        scopes: string[] | null;
-    }>>;
-    getUsage<T = OperationData["getUsage"]>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    redeliverWebhookDelivery(webhookId: OperationPath["redeliverWebhookDelivery"]["id"], deliveryId: OperationPath["redeliverWebhookDelivery"]["delivery_id"], options?: ConvenienceOptions): Promise<OperationResult<"redeliverWebhookDelivery">>;
+    getHealth(options?: ConvenienceOptions): Promise<OperationResult<"getHealth">>;
+    getApiDiscovery(options?: ConvenienceOptions): Promise<OperationResult<"getApiDiscovery">>;
+    getPlatforms(options?: ConvenienceOptions): Promise<OperationResult<"getPlatforms">>;
+    getAccountIdentity(options?: ConvenienceOptions): Promise<OperationResult<"getAccountIdentity">>;
+    /**
+     * 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: OperationPath["getTraderContextMarkdown"]["address"], options?: Omit<OperationRequestOptions<"getTraderContextMarkdown">, "path">): Promise<string>;
+    /**
+     * One market's context as Markdown
+     * (`GET /api/v1/market/{condition_id}/context.md`). The JSON form is
+     * `getMarketIntel`.
+     */
+    getMarketContextMarkdown(conditionId: OperationPath["getMarketContextMarkdown"]["condition_id"], options?: Omit<OperationRequestOptions<"getMarketContextMarkdown">, "path">): Promise<string>;
+    /**
+     * 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?: ConvenienceOptions): Promise<OperationResult<"registerAgent">>;
+    getUsage(options?: ConvenienceOptions): Promise<OperationResult<"getUsage">>;
     /** Fetch today's editorial Pick of the Day (single-object envelope). */
-    getPickOfTheDay<T = PickOfTheDay>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    getPickOfTheDay(options?: ConvenienceOptions): Promise<OperationResult<"getPickOfTheDay">>;
     /** Fetch the Pick of the Day archive with hit-rate (single-object envelope). */
-    getPickOfTheDayArchive<T = PickOfTheDayArchive>(options?: ApiRequestOptions): Promise<ApiClientResponse<T>>;
+    getPickOfTheDayArchive(options?: ConvenienceOptions): Promise<OperationResult<"getPickOfTheDayArchive">>;
+    /**
+     * Fetch the Pick of the Day commitment ledger (single-object envelope).
+     *
+     * Every entry is `sealed` (a live pick: the hash, no side and no price),
+     * `opened` (a settled pick: the nonce and the exact hashed payload) or
+     * `uncommitted` (no commitment; once settled, its unhashed side and price
+     * under `payload`). Verify an opened entry by
+     * appending the hex-decoded `commitment_nonce` to the `payload` bytes as
+     * received and hashing with sha256; do not reserialize the payload, since it
+     * is served byte for byte as it was hashed.
+     */
+    getPickOfTheDayLedger(options?: ConvenienceOptions): Promise<OperationResult<"getPickOfTheDayLedger">>;
     /** Resolve the base URL (used by the SSE stream consumer). */
     getBaseUrl(): string;
     /** The configured API key, if any (used by the SSE stream consumer). */
     getApiKey(): string | undefined;
+    /** Whether this client was built in sandbox mode (#16138). */
+    isSandbox(): boolean;
     /** The resolved fetch implementation (used by the SSE stream consumer). */
     getFetch(): typeof fetch;
     buildUrl(operation: ApiClientOperation, options: ApiRequestOptions): string;
     private buildHeaders;
 }
-export declare function isApiNotModifiedResponse(response: ApiClientResponse<unknown>): response is ApiNotModifiedResponse;
+/**
+ * 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 declare function isApiNotModifiedResponse<R extends {
+    object: string;
+}>(response: R): response is Extract<R, ApiNotModifiedResponse>;
 export declare function interpolatePath(path: string, params: Partial<Record<string, string | number>>): string;
+/**
+ * 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 declare function isListEnvelope<T>(body: unknown): body is ApiListEnvelope<T>;
 //# sourceMappingURL=client.d.ts.map