@0xmonaco/core 1.1.5 → 1.1.7

package/dist/api/analytics/api.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Analytics API Implementation
+ *
+ * The public explorer analytics: protocol totals and series over a window,
+ * per-market volume, the treasury's all-time net fees, and the builder
+ * directory, figures and leaderboard; wallets, token custody and the vault
+ * deposit and withdrawal feeds. Volume, trade
+ * counts and the spot/perp split count the builders the explorer displays;
+ * fees, active takers, new traders and market volume count every trade.
+ * Public — no authentication required; each client IP has a read budget.
+ *
+ * @example
+ * ```typescript
+ * const week = await sdk.analytics.getProtocolTotals({ window: "7d" });
+ * // Both window ends are inclusive, so the previous window ends 1 ms before
+ * // this one starts; ending at `startTime` itself would count a bucket twice
+ * // whenever the start falls on a bucket boundary.
+ * const previous = await sdk.analytics.getProtocolTotals({ window: "7d", endTime: week.window.startTime - 1 });
+ * ```
+ */
+import type { AnalyticsAPI, AnalyticsWindowParams, GetBuilderResponse, GetBuilderSeriesResponse, GetBuilderTotalsResponse, GetProtocolSeriesResponse, GetProtocolTotalsResponse, GetTokenCustodyResponse, GetTreasuryNetFeesResponse, GetWalletSummaryResponse, ListBuilderLeaderboardParams, ListBuilderLeaderboardResponse, ListBuildersResponse, ListMarketVolumesParams, ListMarketVolumesResponse, ListTokenCustodyResponse, ListVaultDepositsResponse, ListVaultWithdrawalsResponse, ListWalletLeaderboardParams, ListWalletLeaderboardResponse, ListWalletLiquidationsParams, ListWalletLiquidationsResponse, VaultFeedParams } from "@0xmonaco/types";
+import { BaseAPI } from "../base";
+export declare class AnalyticsAPIImpl extends BaseAPI implements AnalyticsAPI {
+    getProtocolTotals(params?: AnalyticsWindowParams): Promise<GetProtocolTotalsResponse>;
+    getProtocolSeries(params?: AnalyticsWindowParams): Promise<GetProtocolSeriesResponse>;
+    listMarketVolumes(params?: ListMarketVolumesParams): Promise<ListMarketVolumesResponse>;
+    getTreasuryNetFees(): Promise<GetTreasuryNetFeesResponse>;
+    listBuilders(): Promise<ListBuildersResponse>;
+    getBuilder(builder: string): Promise<GetBuilderResponse>;
+    getBuilderTotals(builder: string, params?: AnalyticsWindowParams): Promise<GetBuilderTotalsResponse>;
+    getBuilderSeries(builder: string, params?: AnalyticsWindowParams): Promise<GetBuilderSeriesResponse>;
+    listBuilderLeaderboard(params?: ListBuilderLeaderboardParams): Promise<ListBuilderLeaderboardResponse>;
+    listWalletLeaderboard(params?: ListWalletLeaderboardParams): Promise<ListWalletLeaderboardResponse>;
+    getWalletSummary(wallet: string): Promise<GetWalletSummaryResponse>;
+    listWalletLiquidations(wallet: string, params?: ListWalletLiquidationsParams): Promise<ListWalletLiquidationsResponse>;
+    listTokenCustody(): Promise<ListTokenCustodyResponse>;
+    getTokenCustody(token: string): Promise<GetTokenCustodyResponse>;
+    listVaultDeposits(params?: VaultFeedParams): Promise<ListVaultDepositsResponse>;
+    listVaultWithdrawals(params?: VaultFeedParams): Promise<ListVaultWithdrawalsResponse>;
+}

package/dist/api/analytics/api.js

@@ -0,0 +1,107 @@
+/**
+ * Analytics API Implementation
+ *
+ * The public explorer analytics: protocol totals and series over a window,
+ * per-market volume, the treasury's all-time net fees, and the builder
+ * directory, figures and leaderboard; wallets, token custody and the vault
+ * deposit and withdrawal feeds. Volume, trade
+ * counts and the spot/perp split count the builders the explorer displays;
+ * fees, active takers, new traders and market volume count every trade.
+ * Public — no authentication required; each client IP has a read budget.
+ *
+ * @example
+ * ```typescript
+ * const week = await sdk.analytics.getProtocolTotals({ window: "7d" });
+ * // Both window ends are inclusive, so the previous window ends 1 ms before
+ * // this one starts; ending at `startTime` itself would count a bucket twice
+ * // whenever the start falls on a bucket boundary.
+ * const previous = await sdk.analytics.getProtocolTotals({ window: "7d", endTime: week.window.startTime - 1 });
+ * ```
+ */
+import { BaseAPI } from "../base";
+import { perpRoutes } from "../perp/routes";
+export class AnalyticsAPIImpl extends BaseAPI {
+    async getProtocolTotals(params) {
+        return await this.makePublicRequest(perpRoutes.analytics.protocolTotals(params), { method: "GET" });
+    }
+    async getProtocolSeries(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.protocolSeries(params), { method: "GET" });
+        return { ...response, points: response.points ?? [] };
+    }
+    async listMarketVolumes(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.marketVolumes(params), { method: "GET" });
+        return { ...response, markets: response.markets ?? [] };
+    }
+    async getTreasuryNetFees() {
+        return await this.makePublicRequest(perpRoutes.analytics.treasuryNetFees(), { method: "GET" });
+    }
+    async listBuilders() {
+        const response = await this.makePublicRequest(perpRoutes.analytics.builders(), { method: "GET" });
+        return { builders: (response.builders ?? []).map(withApplications) };
+    }
+    async getBuilder(builder) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.builder(builder), { method: "GET" });
+        return { builder: withApplications(response.builder) };
+    }
+    async getBuilderTotals(builder, params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.builderTotals(builder, params), {
+            method: "GET",
+        });
+        return { ...response, builder: withApplications(response.builder) };
+    }
+    async getBuilderSeries(builder, params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.builderSeries(builder, params), { method: "GET" });
+        return { ...response, builder: withApplications(response.builder), points: response.points ?? [] };
+    }
+    async listBuilderLeaderboard(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.builderLeaderboard(params), { method: "GET" });
+        return { ...response, rows: (response.rows ?? []).map((row) => ({ ...row, builder: withApplications(row.builder) })) };
+    }
+    async listWalletLeaderboard(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.walletLeaderboard(params), {
+            method: "GET",
+        });
+        return { wallets: response.wallets ?? [] };
+    }
+    async getWalletSummary(wallet) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.walletSummary(wallet), { method: "GET" });
+        // Absent optionals and an empty repeated field are omitted on the wire.
+        return {
+            ...response,
+            totals: response.totals ?? null,
+            builders: (response.builders ?? []).map((row) => ({ ...row, builder: withApplications(row.builder) })),
+            unattributed: response.unattributed ?? null,
+        };
+    }
+    async listWalletLiquidations(wallet, params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.walletLiquidations(wallet, params), { method: "GET" });
+        return { ...response, events: response.events ?? [], nextPageToken: response.nextPageToken ?? "" };
+    }
+    async listTokenCustody() {
+        const response = await this.makePublicRequest(perpRoutes.analytics.tokenCustody(), { method: "GET" });
+        return { ...response, tokens: response.tokens ?? [] };
+    }
+    async getTokenCustody(token) {
+        return await this.makePublicRequest(perpRoutes.analytics.tokenCustodyDetail(token), { method: "GET" });
+    }
+    async listVaultDeposits(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.vaultDeposits(params), { method: "GET" });
+        return {
+            ...response,
+            deposits: (response.deposits ?? []).map((row) => ({ ...row, builder: row.builder ? withApplications(row.builder) : null })),
+            nextPageToken: response.nextPageToken ?? "",
+        };
+    }
+    async listVaultWithdrawals(params) {
+        const response = await this.makePublicRequest(perpRoutes.analytics.vaultWithdrawals(params), { method: "GET" });
+        return {
+            ...response,
+            withdrawals: (response.withdrawals ?? []).map((row) => ({ ...row, builder: row.builder ? withApplications(row.builder) : null })),
+            nextPageToken: response.nextPageToken ?? "",
+        };
+    }
+}
+/** A builder with its application list present, empty when the wire omitted it. */
+function withApplications(builder) {
+    return { ...builder, applications: builder.applications ?? [] };
+}

package/dist/api/analytics/index.d.ts

@@ -0,0 +1 @@
+export { AnalyticsAPIImpl } from "./api";

package/dist/api/analytics/index.js

@@ -0,0 +1 @@
+export { AnalyticsAPIImpl } from "./api";

package/dist/api/applications/api.d.ts

@@ -56,7 +56,7 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of orders
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     listApplicationOrders(params: ListAppOrdersParams): Promise<ListAppOrdersResponse>;
     /**
@@ -74,7 +74,7 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of users
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     listApplicationUsers(params: ListAppUsersParams): Promise<ListAppUsersResponse>;
     /**
@@ -92,7 +92,7 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of movements
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     listApplicationMovements(params: ListAppMovementsParams): Promise<ListAppMovementsResponse>;
     /**
@@ -110,7 +110,7 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of balances
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     listApplicationBalances(params: ListAppBalancesParams): Promise<ListAppBalancesResponse>;
     /**
@@ -121,7 +121,7 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      *
      * @param params - Optional `since` filter
      * @returns Promise resolving to the application stats
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     getApplicationStats(params: GetAppStatsParams): Promise<GetAppStatsResponse>;
 }

package/dist/api/applications/api.js

@@ -69,7 +69,7 @@ export class ApplicationsAPIImpl extends BaseAPI {
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of orders
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     async listApplicationOrders(params) {
         validate(ListAppOrdersSchema, params);
@@ -99,7 +99,7 @@ export class ApplicationsAPIImpl extends BaseAPI {
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of users
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     async listApplicationUsers(params) {
         validate(ListAppUsersSchema, params);
@@ -127,7 +127,7 @@ export class ApplicationsAPIImpl extends BaseAPI {
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of movements
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     async listApplicationMovements(params) {
         validate(ListAppMovementsSchema, params);
@@ -156,7 +156,7 @@ export class ApplicationsAPIImpl extends BaseAPI {
      *
      * @param params - Pagination and filter options
      * @returns Promise resolving to a paginated list of balances
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     async listApplicationBalances(params) {
         validate(ListAppBalancesSchema, params);
@@ -176,7 +176,7 @@ export class ApplicationsAPIImpl extends BaseAPI {
      *
      * @param params - Optional `since` filter
      * @returns Promise resolving to the application stats
-     * @throws {APIError} When the request fails (404 for an unknown client ID, 429 when rate limited)
+     * @throws {APIError} When the request fails (404 for an unknown, inactive or hidden client ID, 429 when rate limited)
      */
     async getApplicationStats(params) {
         return await this.makePublicRequest(perpRoutes.applications.stats({ clientId: params.clientId, since: params.since }));

package/dist/api/buildercodes/api.d.ts

@@ -14,6 +14,7 @@
  * const result = await sdk.buildercodes.claimBuildercodeRewards({
  *   token: "0x0000000000000000000000000000000000000002",
  *   amount: "1000000",
+ *   idempotencyKey: crypto.randomUUID(), // keep it across retries of this claim
  * });
  * console.log(`Payout remaining: ${result.payoutBalance}`);
  * console.log(`Now tradeable: ${result.tradingBalance}`);
@@ -78,18 +79,24 @@ export declare class BuildercodesAPIImpl extends BaseAPI implements Buildercodes
      * Throws 503 when the matching engine is unreachable, restarting, or slow to
      * answer. Treat that as an UNKNOWN outcome rather than a rejection: the claim
      * is admitted to the sequencer before its reply is sent, so it may still
-     * commit, and there is no idempotency key — a blind retry can claim twice.
-     * Do not retry automatically, and do not settle it with a balance read: an
-     * admitted claim can still be queued, so an unchanged balance does not prove
-     * it will not commit. Treat the claim as pending and reconcile first.
+     * commit.
      *
-     * Because that warning has to hold for code as well as readers, an ambiguous
-     * failure (any 5xx, or a network error with no response at all) is thrown
-     * with `retryable: false`, against the SDK's usual "every 5xx is retryable"
-     * rule, so a caller driving retries off that flag cannot claim twice. A
-     * pre-admission rejection is exempt and stays retryable: a maintenance block,
-     * and a sequencer overload (`code: "OVERLOADED"`), both of which are refused
-     * before the claim is queued and so committed nothing.
+     * Pass `idempotencyKey` to make that retry safe: the same key and claim
+     * retried within 15 minutes returns the first claim's result without moving
+     * money again, so a keyed claim's 5xx keeps the SDK's usual `retryable`
+     * flag. The same key with a different claim throws 409
+     * `IDEMPOTENCY_KEY_CONFLICT`.
+     *
+     * Without a key a blind retry can claim twice. Do not retry automatically,
+     * and do not settle it with a balance read: an admitted claim can still be
+     * queued, so an unchanged balance does not prove it will not commit. Treat
+     * the claim as pending and reconcile first. Because that warning has to hold
+     * for code as well as readers, an unkeyed claim's ambiguous failure (any 5xx,
+     * or a network error with no response at all) is thrown with
+     * `retryable: false`, against the SDK's usual "every 5xx is retryable" rule.
+     * A pre-admission rejection is exempt and stays retryable: a maintenance
+     * block, and a sequencer overload (`code: "OVERLOADED"`), both of which are
+     * refused before the claim is queued and so committed nothing.
      */
     claimBuildercodeRewards(params: ClaimBuildercodeRewardsParams): Promise<ClaimBuildercodeRewardsResponse>;
 }

package/dist/api/buildercodes/api.js

@@ -14,6 +14,7 @@
  * const result = await sdk.buildercodes.claimBuildercodeRewards({
  *   token: "0x0000000000000000000000000000000000000002",
  *   amount: "1000000",
+ *   idempotencyKey: crypto.randomUUID(), // keep it across retries of this claim
  * });
  * console.log(`Payout remaining: ${result.payoutBalance}`);
  * console.log(`Now tradeable: ${result.tradingBalance}`);
@@ -36,9 +37,9 @@ const MAINTENANCE_BLOCK_ERROR = "OPERATIONS_BLOCKED";
  */
 const OVERLOADED_ENGINE_CODE = "OVERLOADED";
 /**
- * Clear `retryable` on a claim failure whose outcome is UNKNOWN.
+ * Clear `retryable` on an unkeyed claim failure whose outcome is UNKNOWN.
  *
- * A claim is not idempotent and is admitted to the sequencer before its reply
+ * An unkeyed claim is not idempotent and is admitted to the sequencer before its reply
  * is sent, so a 5xx or a dropped connection can arrive after the claim already
  * committed. `APIError` classifies every 5xx and every network failure as
  * `retryable: true`, and the documented consumer pattern retries whenever that
@@ -71,7 +72,7 @@ function markAmbiguousOutcomeNonRetryable(error) {
     }
     error.retryable = false;
     error.suggestion =
-        "The claim's outcome is unknown: it may have committed after this failure. Do not retry automatically, and do not rely on a balance read to decide — an admitted claim can still be queued, so an unchanged balance does not prove it will not commit. Treat the claim as pending and reconcile before issuing another; this endpoint has no idempotency key, so a retry can claim a second time.";
+        "The claim's outcome is unknown: it may have committed after this failure. Do not retry automatically, and do not rely on a balance read to decide — an admitted claim can still be queued, so an unchanged balance does not prove it will not commit. Treat the claim as pending and reconcile before issuing another; this claim carried no idempotencyKey, so a retry can claim a second time. Send one to make retries safe.";
     return error;
 }
 /**
@@ -192,28 +193,43 @@ export class BuildercodesAPIImpl extends BaseAPI {
      * Throws 503 when the matching engine is unreachable, restarting, or slow to
      * answer. Treat that as an UNKNOWN outcome rather than a rejection: the claim
      * is admitted to the sequencer before its reply is sent, so it may still
-     * commit, and there is no idempotency key — a blind retry can claim twice.
-     * Do not retry automatically, and do not settle it with a balance read: an
-     * admitted claim can still be queued, so an unchanged balance does not prove
-     * it will not commit. Treat the claim as pending and reconcile first.
+     * commit.
      *
-     * Because that warning has to hold for code as well as readers, an ambiguous
-     * failure (any 5xx, or a network error with no response at all) is thrown
-     * with `retryable: false`, against the SDK's usual "every 5xx is retryable"
-     * rule, so a caller driving retries off that flag cannot claim twice. A
-     * pre-admission rejection is exempt and stays retryable: a maintenance block,
-     * and a sequencer overload (`code: "OVERLOADED"`), both of which are refused
-     * before the claim is queued and so committed nothing.
+     * Pass `idempotencyKey` to make that retry safe: the same key and claim
+     * retried within 15 minutes returns the first claim's result without moving
+     * money again, so a keyed claim's 5xx keeps the SDK's usual `retryable`
+     * flag. The same key with a different claim throws 409
+     * `IDEMPOTENCY_KEY_CONFLICT`.
+     *
+     * Without a key a blind retry can claim twice. Do not retry automatically,
+     * and do not settle it with a balance read: an admitted claim can still be
+     * queued, so an unchanged balance does not prove it will not commit. Treat
+     * the claim as pending and reconcile first. Because that warning has to hold
+     * for code as well as readers, an unkeyed claim's ambiguous failure (any 5xx,
+     * or a network error with no response at all) is thrown with
+     * `retryable: false`, against the SDK's usual "every 5xx is retryable" rule.
+     * A pre-admission rejection is exempt and stays retryable: a maintenance
+     * block, and a sequencer overload (`code: "OVERLOADED"`), both of which are
+     * refused before the claim is queued and so committed nothing.
      */
     async claimBuildercodeRewards(params) {
         const validated = validate(ClaimBuildercodeRewardsParamsSchema, params);
+        const body = validated.idempotencyKey === undefined
+            ? { token: validated.token, amount: validated.amount }
+            : { token: validated.token, amount: validated.amount, idempotencyKey: validated.idempotencyKey };
         try {
             return await this.makeAuthenticatedRequest("/api/v1/buildercodes/rewards/claim", {
                 method: "POST",
-                body: JSON.stringify({ token: validated.token, amount: validated.amount }),
+                body: JSON.stringify(body),
             });
         }
         catch (error) {
+            // A keyed claim retried under the same key returns the first claim's
+            // result instead of claiming again, so its 5xx keeps the flag `APIError`
+            // gave it.
+            if (validated.idempotencyKey !== undefined) {
+                throw error;
+            }
             throw markAmbiguousOutcomeNonRetryable(error);
         }
     }

package/dist/api/index.d.ts

@@ -3,6 +3,7 @@
  *
  * This module exports the new simplified APIs for the Monaco SDK.
  */
+export * from "./analytics";
 export * from "./applications/index";
 export * from "./base";
 export * from "./buildercodes";

package/dist/api/index.js

@@ -3,6 +3,7 @@
  *
  * This module exports the new simplified APIs for the Monaco SDK.
  */
+export * from "./analytics";
 export * from "./applications/index";
 export * from "./base";
 export * from "./buildercodes";

package/dist/api/orderbook/api.d.ts

@@ -1,7 +1,10 @@
 import type { OrderbookEvent, OrderbookQuotationMode, TradingMode } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export interface GetOrderbookOptions {
-    /** Number of price levels to return (max 100). Defaults to 10. */
+    /**
+     * Number of price levels per side (max 1000). Defaults to 10. Above 100 the
+     * snapshot comes from the market-data book and carries `bookSeq`.
+     */
     depth?: number;
     /** Trading mode: 'Spot' or 'Margin'. Defaults to 'Spot'. */
     tradingMode?: TradingMode;

package/dist/api/orderbook/api.js

@@ -33,6 +33,8 @@ export class OrderbookAPIImpl extends BaseAPI {
             quoteDecimals: response.quoteDecimals,
             timestamp: response.timestamp,
             sequence: response.sequenceNumber,
+            // Kept as the wire's decimal string: a u64 can exceed Number.MAX_SAFE_INTEGER.
+            ...(response.bookSeq != null ? { bookSeq: response.bookSeq } : {}),
         };
     }
 }

package/dist/api/perp/routes.d.ts

@@ -1,4 +1,63 @@
 export declare const perpRoutes: {
+    readonly analytics: {
+        readonly protocolTotals: (params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+        }) => string;
+        readonly protocolSeries: (params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+        }) => string;
+        readonly marketVolumes: (params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+            limit?: number;
+        }) => string;
+        readonly treasuryNetFees: () => string;
+        readonly builders: () => string;
+        readonly builder: (builder: string) => string;
+        readonly builderTotals: (builder: string, params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+        }) => string;
+        readonly builderSeries: (builder: string, params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+        }) => string;
+        readonly builderLeaderboard: (params?: {
+            window?: string;
+            startTime?: number;
+            endTime?: number;
+            limit?: number;
+        }) => string;
+        readonly walletLeaderboard: (params?: {
+            limit?: number;
+        }) => string;
+        readonly walletSummary: (wallet: string) => string;
+        readonly walletLiquidations: (wallet: string, params?: {
+            pageSize?: number;
+            pageToken?: string;
+        }) => string;
+        readonly tokenCustody: () => string;
+        readonly tokenCustodyDetail: (token: string) => string;
+        readonly vaultDeposits: (params?: {
+            pageSize?: number;
+            pageToken?: string;
+            token?: string;
+            wallet?: string;
+        }) => string;
+        readonly vaultWithdrawals: (params?: {
+            pageSize?: number;
+            pageToken?: string;
+            token?: string;
+            wallet?: string;
+        }) => string;
+    };
     readonly orders: {
         readonly create: () => string;
         readonly list: (params?: {

package/dist/api/perp/routes.js

@@ -15,6 +15,24 @@ function withQuery(path, params) {
     return query ? `${path}?${query}` : path;
 }
 export const perpRoutes = {
+    analytics: {
+        protocolTotals: (params) => withQuery(`${API_V1}/analytics/protocol/totals`, params),
+        protocolSeries: (params) => withQuery(`${API_V1}/analytics/protocol/series`, params),
+        marketVolumes: (params) => withQuery(`${API_V1}/analytics/markets/volume`, params),
+        treasuryNetFees: () => `${API_V1}/analytics/treasury/net-fees`,
+        builders: () => `${API_V1}/analytics/builders`,
+        builder: (builder) => `${API_V1}/analytics/builders/${encodeURIComponent(builder)}`,
+        builderTotals: (builder, params) => withQuery(`${API_V1}/analytics/builders/${encodeURIComponent(builder)}/totals`, params),
+        builderSeries: (builder, params) => withQuery(`${API_V1}/analytics/builders/${encodeURIComponent(builder)}/series`, params),
+        builderLeaderboard: (params) => withQuery(`${API_V1}/analytics/builder-leaderboard`, params),
+        walletLeaderboard: (params) => withQuery(`${API_V1}/analytics/wallet-leaderboard`, params),
+        walletSummary: (wallet) => `${API_V1}/analytics/wallets/${encodeSegment(wallet)}`,
+        walletLiquidations: (wallet, params) => withQuery(`${API_V1}/analytics/wallets/${encodeSegment(wallet)}/liquidations`, params),
+        tokenCustody: () => `${API_V1}/analytics/tokens`,
+        tokenCustodyDetail: (token) => `${API_V1}/analytics/tokens/${encodeSegment(token)}`,
+        vaultDeposits: (params) => withQuery(`${API_V1}/analytics/deposits`, params),
+        vaultWithdrawals: (params) => withQuery(`${API_V1}/analytics/withdrawals`, params),
+    },
     orders: {
         create: () => `${API_V1}/orders`,
         list: (params) => withQuery(`${API_V1}/orders`, params),

package/dist/api/trades/api.d.ts

@@ -23,6 +23,8 @@ interface RawTradeEvent {
         takerFeeRaw?: string;
         quoteVolumeRaw?: string;
         takerApplicationId?: string;
+        /** The taker's builder fee in raw quote units; "0" when none. */
+        builderFeeRaw?: string;
     };
 }
 /**

package/dist/api/trades/api.js

@@ -21,6 +21,8 @@ export function parseRawTradeEvent(raw) {
             ...(raw.data.takerFeeRaw ? { takerFeeRaw: raw.data.takerFeeRaw } : {}),
             ...(raw.data.quoteVolumeRaw ? { quoteVolumeRaw: raw.data.quoteVolumeRaw } : {}),
             ...(raw.data.takerApplicationId ? { takerApplicationId: raw.data.takerApplicationId } : {}),
+            // Kept when "0": that is a value (no builder fee), not an absence.
+            ...(raw.data.builderFeeRaw !== undefined ? { builderFeeRaw: raw.data.builderFeeRaw } : {}),
         },
     };
 }

package/dist/api/trading/api.d.ts

@@ -41,7 +41,7 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * @param quantity - The order quantity as string
      * @param price - The limit price as string
      * @param options - Optional parameters for the limit order
-     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.tradingMode - Trading mode ("SPOT" or "MARGIN"). Omit it to use the trading pair market type.
      * @param options.useMasterBalance - Whether to use master balance for sub-accounts
      * @param options.expirationDate - Optional expiration date for GTC orders (ISO 8601 format)
      * @param options.timeInForce - Time in force ("GTC", "IOC", or "FOK")
@@ -115,7 +115,7 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
      * @param side - The order side ("BUY" or "SELL")
      * @param quantity - The order quantity as string
      * @param options - Optional parameters for the market order
-     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.tradingMode - Trading mode ("SPOT" or "MARGIN"). Omit it to use the trading pair market type.
      * @param options.slippageTolerance - Tightens the mandatory 1,000 bps price band, as a decimal (e.g., 0.01 for 1%; 0 for best price only). It can only tighten the band, never widen it; omitting it applies the full 1,000 bps band.
      * @returns Promise resolving to CreateOrderResponse with order details
      *
@@ -214,6 +214,10 @@ export declare class TradingAPIImpl extends BaseAPI implements TradingAPI {
     /**
      * Batch cancels specific orders by their IDs.
      *
+     * Every ID gets one entry in `results`, in request order, and the totals
+     * count every ID. An ID that is not one of your live orders comes back as a
+     * failed entry with code `ORDER_NOT_FOUND`.
+     *
      * @param orderIds - Array of order IDs to cancel
      * @returns Promise resolving to BatchCancelOrdersResponse with cancellation details
      * @throws {APIError} When API communication fails

package/dist/api/trading/api.js

@@ -77,7 +77,7 @@ export class TradingAPIImpl extends BaseAPI {
      * @param quantity - The order quantity as string
      * @param price - The limit price as string
      * @param options - Optional parameters for the limit order
-     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.tradingMode - Trading mode ("SPOT" or "MARGIN"). Omit it to use the trading pair market type.
      * @param options.useMasterBalance - Whether to use master balance for sub-accounts
      * @param options.expirationDate - Optional expiration date for GTC orders (ISO 8601 format)
      * @param options.timeInForce - Time in force ("GTC", "IOC", or "FOK")
@@ -131,7 +131,7 @@ export class TradingAPIImpl extends BaseAPI {
             side,
             price,
             quantity,
-            tradingMode: options?.tradingMode || "SPOT",
+            tradingMode: options?.tradingMode,
             useMasterBalance: options?.useMasterBalance,
             expirationDate: options?.expirationDate,
             timeInForce: options?.timeInForce,
@@ -165,7 +165,7 @@ export class TradingAPIImpl extends BaseAPI {
      * @param side - The order side ("BUY" or "SELL")
      * @param quantity - The order quantity as string
      * @param options - Optional parameters for the market order
-     * @param options.tradingMode - Trading mode (e.g., "SPOT")
+     * @param options.tradingMode - Trading mode ("SPOT" or "MARGIN"). Omit it to use the trading pair market type.
      * @param options.slippageTolerance - Tightens the mandatory 1,000 bps price band, as a decimal (e.g., 0.01 for 1%; 0 for best price only). It can only tighten the band, never widen it; omitting it applies the full 1,000 bps band.
      * @returns Promise resolving to CreateOrderResponse with order details
      *
@@ -211,7 +211,7 @@ export class TradingAPIImpl extends BaseAPI {
             slippageToleranceBps: options?.slippageTolerance !== undefined ? Math.round(options.slippageTolerance * 10000) : undefined,
             price: null, // Market orders don't need price
             quantity,
-            tradingMode: options?.tradingMode || "SPOT",
+            tradingMode: options?.tradingMode,
             marginAccountId: options?.marginAccountId,
             marginMode: options?.marginMode,
             riskBucketId: options?.riskBucketId,
@@ -313,6 +313,10 @@ export class TradingAPIImpl extends BaseAPI {
     /**
      * Batch cancels specific orders by their IDs.
      *
+     * Every ID gets one entry in `results`, in request order, and the totals
+     * count every ID. An ID that is not one of your live orders comes back as a
+     * failed entry with code `ORDER_NOT_FOUND`.
+     *
      * @param orderIds - Array of order IDs to cancel
      * @returns Promise resolving to BatchCancelOrdersResponse with cancellation details
      * @throws {APIError} When API communication fails
@@ -460,7 +464,7 @@ export class TradingAPIImpl extends BaseAPI {
                 side: order.side,
                 price: order.price,
                 quantity: order.quantity,
-                tradingMode: order.tradingMode || "SPOT",
+                tradingMode: order.tradingMode,
                 slippageToleranceBps: order.slippageTolerance !== undefined ? Math.round(order.slippageTolerance * 10000) : undefined,
                 useMasterBalance: order.useMasterBalance,
                 expirationDate: order.expirationDate,
@@ -761,7 +765,7 @@ export class TradingAPIImpl extends BaseAPI {
             slippageToleranceBps: options.slippageToleranceBps,
             randomize: options.randomize,
             reduceOnly: options.reduceOnly,
-            tradingMode: options.tradingMode || "SPOT",
+            tradingMode: options.tradingMode,
             marginAccountId: options.marginAccountId,
             riskBucketId: options.riskBucketId,
             marginMode: options.marginMode,