@0xmonaco/types 1.0.48 → 1.0.50

package/dist/margin-accounts/index.d.ts

@@ -131,17 +131,43 @@ export interface TransferCollateralToParentMarginAccountRequest {
     asset: string;
     amount: string;
 }
+/**
+ * Fund a pair's isolated risk bucket from the parent margin account's
+ * unallocated collateral (no wallet movement; the bucket is created if
+ * needed). What the money becomes when the bucket holds an open position is
+ * stated by `applyToPositionMargin` — the two intents want opposite fates for
+ * the same dollars. Either way the liquidation cushion improves identically.
+ */
 export interface TransferCollateralToIsolatedRiskBucketRequest extends TransferCollateralToParentMarginAccountRequest {
     marginMode?: "ISOLATED";
     tradingPairId: string;
     strategyKey?: string;
     selectedTradingPairIds?: never;
+    /**
+     * `true` (and OMITTED — the default is the human "Adjust Margin" gesture):
+     * the amount is COMMITTED to the sole open position's stored margin.
+     * Effective leverage drops and stays down, initial margin required rises by
+     * the amount, free collateral is unchanged — new orders cannot spend it.
+     *
+     * `false`: plain allocation. Free collateral rises and the next order can
+     * spend it. Programmatic funding loops that top a bucket up to a free
+     * collateral target MUST pass `false`, or each top-up converts into
+     * requirement and the loop never converges.
+     *
+     * On a flat bucket both values are a plain allocation. The response's
+     * `positionMarginCredited` reports what actually happened — a credit can
+     * degrade to a plain allocation when the persisted position row is stale
+     * (close/reopen race).
+     */
+    applyToPositionMargin?: boolean;
 }
 export interface TransferCollateralToCrossRiskBucketRequest extends TransferCollateralToParentMarginAccountRequest {
     marginMode: "CROSS";
     selectedTradingPairIds: string[];
     tradingPairId?: never;
     strategyKey?: never;
+    /** Cross risk is pooled at bucket equity — there is no per-position margin; an explicit `true` is rejected. */
+    applyToPositionMargin?: never;
 }
 export type TransferCollateralToRiskBucketRequest = TransferCollateralToIsolatedRiskBucketRequest | TransferCollateralToCrossRiskBucketRequest;
 export interface TransferCollateralFromParentMarginAccountRequest {
@@ -161,6 +187,16 @@ export interface TransferCollateralResponse {
     newEquity: string;
     newTotalCollateralValue: string;
     newWithdrawableCollateral: string;
+    /**
+     * Whether the transfer was committed to a position's stored margin. Present
+     * only when a position-margin credit was in play: `true` — the credit
+     * landed; `false` — a credit was requested (or defaulted) but degraded to a
+     * plain allocation because the bucket's persisted position row was stale
+     * (close/reopen race) — re-issue the Adjust Margin once the new position
+     * row lands if the commitment still matters. Absent (never null) on plain
+     * allocations, parent deposits, and releases.
+     */
+    positionMarginCredited?: boolean;
 }
 export interface GetMarginAccountMovementsParams {
     movementType?: string;
@@ -237,8 +273,9 @@ export interface MarginAccountsAPI extends BaseAPI {
     getMarginAccountSummary(marginAccountId: string, params?: GetMarginAccountSummaryParams): Promise<MarginAccountSummary>;
     getAvailableCollateral(params?: GetAvailableCollateralParams): Promise<GetAvailableCollateralResponse>;
     /**
-     * @deprecated Prefer transferCollateralToParentMarginAccount() or
-     * transferCollateralToRiskBucket().
+     * @deprecated Use `transferCollateralToRiskBucket` for bucket funding
+     * (which now credits a sole open position's stored margin the same way) and
+     * `transferCollateralToParentMarginAccount` for wallet-to-margin deposits.
      */
     transferCollateralToMarginAccount(marginAccountId: string, request: TransferCollateralRequest): Promise<TransferCollateralResponse>;
     transferCollateralToParentMarginAccount(request: TransferCollateralToParentMarginAccountRequest): Promise<TransferCollateralResponse>;

package/dist/sdk/index.d.ts

@@ -109,7 +109,7 @@ export interface MonacoSDK {
     pitpass: PitpassAPI;
     /** Testnet faucet API */
     faucet: FaucetAPI;
-    /** Public deposit-address registration (sweeper) API */
+    /** Deposit-address registration (sweeper) API; requires a session */
     sweeper: SweeperAPI;
     /** Public whitelist (waitlist) submission API */
     whitelist: WhitelistAPI;

package/dist/sweeper/index.d.ts

@@ -1,43 +1,59 @@
 /**
  * Sweeper Types
  *
- * Types for the public deposit-address registration endpoint. Wire shapes are
+ * Types for the deposit-address registration endpoint. Wire shapes are
  * snake_case; these are the camelCase ergonomic forms.
  *
- * NOTE: This endpoint is **public (unauthenticated)**. The deposit address is
- * derived from the (application, user) pair and its destination is fixed in the
- * contract's own bytecode, so a caller can only ever route funds to the user
- * they already belong to. Abuse is bounded by a per-client rate limit and an
- * active-application check instead of authentication.
+ * NOTE: This endpoint is **authenticated**. The credited address is the calling
+ * session's own rather than a request field, so a caller can only ever register
+ * an address they hold the session key for.
  */
+import type { DepositTarget } from "@0xmonaco/contracts";
 import type { BaseAPI } from "../api";
 /**
  * What happened to the registration.
  *
- * - `registered` — the pair was added; its deposit address is now monitored.
- * - `already_registered` — the pair was known before this call; nothing was
+ * - `registered` — the triple was added; its deposit address is now monitored.
+ * - `already_registered` — the triple was known before this call; nothing was
  *   re-triggered.
  */
 export type RegisterSweeperStatus = "registered" | "already_registered";
-/** Body for a deposit-address registration. */
+/**
+ * Body for a deposit-address registration.
+ *
+ * Deliberately tiny: the application and the credited address both come from
+ * the authenticated session (`login` takes the application's client id), so the
+ * only thing left to say is which ledger to aim at.
+ */
 export interface RegisterSweeperRequest {
     /**
-     * The application's client id — the same identifier rollup deposits carry
-     * and `login` takes. The deposit address is derived from these exact bytes
-     * and the application lookup is an exact string match, so the spelling must
-     * match the registered application precisely.
+     * Which ledger swept deposits ask to be credited to. Defaults to `"spot"`.
+     *
+     * `"margin"` asks for the parent margin account's collateral, skipping the
+     * separate `transferCollateralToParentMarginAccount` step. The target is part
+     * of the address derivation, so the two targets yield two different deposit
+     * addresses for the same pair, each carrying its own request. A `"spot"`
+     * address is never credited to margin.
+     *
+     * `"margin"` is a request rather than a guarantee: a deposit the backend
+     * cannot route to collateral — an unsupported collateral asset, or a margin
+     * account that fails validation — is credited to the spot wallet instead, so
+     * funds are never stranded. Read the balance back rather than treating the
+     * address as proof of where the credit landed.
+     *
+     * An unrecognized value is rejected (400) rather than falling back to spot,
+     * which would return an address pointed at a ledger the caller did not ask
+     * for.
      */
-    clientId: string;
-    /** Address credited on the rollup, and half of the deposit-address derivation */
-    userAddress: string;
+    depositTarget?: DepositTarget;
 }
 /** Result of a deposit-address registration. */
 export interface RegisterSweeperResponse {
-    /** Whether this call added the pair or it was known before */
+    /** Whether this call added the triple or it was known before */
     status: RegisterSweeperStatus;
     /**
-     * The pair's deposit address. Stable, and valid to publish and fund before
-     * any contract exists there.
+     * The deposit address for this (application, user, deposit target) triple.
+     * Stable, and valid to publish and fund before any contract exists there.
      */
     sweeperAddress: string;
     /**
@@ -48,20 +64,26 @@ export interface RegisterSweeperResponse {
     initialSweepCheck: boolean;
 }
 /**
- * Sweeper API interface. The register endpoint is public (no auth required).
+ * Sweeper API interface. The register endpoint requires authentication.
  */
 export interface SweeperAPI extends BaseAPI {
     /**
-     * Registers an (application, user) pair so its deterministic deposit
-     * address is monitored and every ERC20 deposit is swept into the rollup
-     * automatically.
+     * Registers an (application, user, deposit target) triple so its
+     * deterministic deposit address is monitored and every ERC20 deposit is
+     * swept into the rollup automatically.
+     *
+     * The application and the credited address both come from the authenticated
+     * session, so this only ever registers the caller's own address under their
+     * own application. Call it with no arguments for a spot address.
      *
      * Returns immediately with the derived deposit address; the one-time
      * initial balance check runs in the background. Idempotent and safe to
      * retry: re-registering answers `already_registered` with the same address
-     * and never re-triggers the initial check. An unknown client id — any
-     * respelling of a real one included, the lookup is exact — throws (404),
-     * and registrations are lightly rate-limited per client (429).
+     * and never re-triggers the initial check.
+     *
+     * Throws on an unrecognized `depositTarget` (before sending), when the
+     * session's application is no longer active (403), and when the endpoint's
+     * global admission limit is exceeded (429).
      */
-    register(body: RegisterSweeperRequest): Promise<RegisterSweeperResponse>;
+    register(body?: RegisterSweeperRequest): Promise<RegisterSweeperResponse>;
 }

package/dist/sweeper/index.js

@@ -1,12 +1,10 @@
 /**
  * Sweeper Types
  *
- * Types for the public deposit-address registration endpoint. Wire shapes are
+ * Types for the deposit-address registration endpoint. Wire shapes are
  * snake_case; these are the camelCase ergonomic forms.
  *
- * NOTE: This endpoint is **public (unauthenticated)**. The deposit address is
- * derived from the (application, user) pair and its destination is fixed in the
- * contract's own bytecode, so a caller can only ever route funds to the user
- * they already belong to. Abuse is bounded by a per-client rate limit and an
- * active-application check instead of authentication.
+ * NOTE: This endpoint is **authenticated**. The credited address is the calling
+ * session's own rather than a request field, so a caller can only ever register
+ * an address they hold the session key for.
  */

package/dist/validation/margin-accounts.d.ts

@@ -45,6 +45,7 @@ export declare const TransferCollateralToRiskBucketSchema: z.ZodObject<{
         strategyKey: z.ZodOptional<z.ZodString>;
         marginMode: z.ZodOptional<z.ZodLiteral<"ISOLATED">>;
         selectedTradingPairIds: z.ZodOptional<z.ZodNever>;
+        applyToPositionMargin: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         asset: z.ZodString;
         amount: z.ZodString;
@@ -139,6 +140,7 @@ export declare const SimulateRiskBucketOrderRiskSchema: z.ZodObject<{
         strategyKey: z.ZodOptional<z.ZodString>;
         marginMode: z.ZodOptional<z.ZodLiteral<"ISOLATED">>;
         selectedTradingPairIds: z.ZodOptional<z.ZodNever>;
+        applyToPositionMargin: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         tradingPairId: z.ZodUUID;
         side: z.ZodEnum<{

package/dist/validation/margin-accounts.js

@@ -51,6 +51,10 @@ const SelectedCrossTradingPairIdsSchema = z.array(UUIDSchema).min(1, "selectedTr
 const IsolatedRiskBucketRequestSchema = RiskBucketRequestSchema.extend({
     marginMode: z.literal("ISOLATED").optional(),
     selectedTradingPairIds: z.never().optional(),
+    // Omitted defaults server-side to true (the Adjust Margin gesture); false
+    // is the plain allocation programmatic funding loops need. The CROSS form
+    // stays strict-rejected (no per-position margin to commit to).
+    applyToPositionMargin: z.boolean().optional(),
 });
 const CrossRiskBucketScopeSchema = z.object({
     marginMode: z.literal("CROSS"),

package/dist/vault/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Types for vault operations including deposits, withdrawals, and balance management.
  */
+import type { DepositTarget } from "@0xmonaco/contracts";
 import type { Address } from "viem";
 import type { BaseAPI } from "../api/index";
 import type { Balance, TransactionResult, WithdrawalRetryOptions, WithdrawResult } from "./responses";
@@ -13,8 +14,13 @@ import type { Balance, TransactionResult, WithdrawalRetryOptions, WithdrawResult
  *   collateral (auto-creating the account if it does not exist yet). A deposit
  *   that cannot be routed to margin (unsupported asset, etc.) safely falls back
  *   to spot — funds are never lost.
+ *
+ * Re-exported from `@0xmonaco/contracts` rather than redeclared: the same
+ * value selects the on-chain routing hint for a direct deposit and the
+ * derivation of a sweeper deposit address, so one definition keeps the two
+ * from drifting into separately-maintained unions.
  */
-export type DepositTarget = "spot" | "margin";
+export type { DepositTarget };
 /**
  * Options for a deposit.
  */

package/dist/websocket/events/account-events.d.ts

@@ -42,11 +42,14 @@ export interface AccountEventData {
     freeCollateral: string;
     /**
      * Account distress ratio: maintenance margin required over equity (higher is
-     * closer to liquidation, decimal string). When equity is non-positive the
-     * quotient is undefined, so an account that still owes a maintenance
-     * requirement saturates to the max-decimal sentinel
-     * (`79228162514264337593543950335`, maximal distress) and an empty account
-     * with no requirement is `0`. Clamp the sentinel before display.
+     * closer to liquidation, decimal string). The quotient saturates to the
+     * max-decimal sentinel (`79228162514264337593543950335`, maximal distress)
+     * whenever it cannot be computed or represented: an account still owing a
+     * maintenance requirement at zero or negative equity, and equally at
+     * near-zero POSITIVE equity where the true ratio exceeds the decimal range.
+     * An empty account with no requirement is `0`. Clamp the sentinel before
+     * display; treat any value at or above the liquidation threshold as maximal
+     * distress rather than distinguishing the sentinel's causes.
      */
     marginRatio: string;
     /** Maintenance margin required to keep the account solvent (decimal string) */

package/dist/wire/schema.d.ts

@@ -869,6 +869,17 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /**
+         * @deprecated
+         * @description DEPRECATED (0XM-2632): this endpoint overloads two unrelated operations —
+         *      with `trading_pair_id` it allocates into that pair's isolated risk bucket
+         *      (crediting the sole open position's stored margin), without it it performs
+         *      a wallet-debiting deposit to the parent margin account. Use
+         *      `TransferCollateralToRiskBucket` for bucket funding (which now applies the
+         *      same position-margin credit) and `TransferCollateralToParentMarginAccount`
+         *      for wallet-to-margin deposits. Kept for backward compatibility; no removal
+         *      date scheduled.
+         */
         post: operations["transfer_collateral_to_margin_account"];
         delete?: never;
         options?: never;
@@ -1029,6 +1040,15 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /**
+         * @description Fund a risk bucket from the parent margin account's unallocated
+         *      collateral (no wallet movement; the bucket is created if needed). Since
+         *      0XM-2632, funding an ISOLATED bucket that holds an open position also
+         *      credits that position's stored margin — the same behavior as the
+         *      deprecated `TransferCollateralToMarginAccount` Adjust Margin rail — so
+         *      adding collateral to support a position has one behavior on every route.
+         *      A flat isolated bucket and the cross bucket stay plain allocations.
+         */
         post: operations["transfer_collateral_to_risk_bucket"];
         delete?: never;
         options?: never;
@@ -2072,23 +2092,29 @@ export interface paths {
          * Register a deposit address for monitoring
          * @description Register a deposit address for monitoring.
          *
-         *      Every (application, user) pair has a deterministic deposit address. This
-         *      registers the pair so the sweeper service watches that address and
-         *      automatically forwards every ERC20 deposit into the rollup, crediting the
-         *      user under the application.
+         *      Every (application, user, deposit target) triple has a deterministic
+         *      deposit address. This registers the caller's own address so the sweeper
+         *      service watches it and automatically forwards every ERC20 deposit into the
+         *      rollup, crediting the caller under the application.
+         *
+         *      Authenticated, and the whole identity comes from the session: the
+         *      application is the one `login` established the session under, and the
+         *      credited address is the session's own. Neither is a request parameter, so a
+         *      caller can only ever register their own address under their own
+         *      application. The only thing the body carries is which ledger to aim at.
          *
          *      Registration also runs a one-time initial check in the background: any
          *      balance already sitting on the address is swept without waiting for a new
          *      transfer. The response returns immediately with the derived address; it
          *      does not wait for that check.
          *
-         *      Idempotent and safe to retry: re-registering an existing pair returns
+         *      Idempotent and safe to retry: re-registering an existing triple returns
          *      `already_registered` with the same address and never re-triggers the
          *      initial check.
          *
-         *      Lightly rate-limited per client, and the client id must name an existing
-         *      application — the lookup is an exact string match, which is what pins the
-         *      one spelling the deposit address is derived from.
+         *      Globally rate-limited: registration creates durable state, so the endpoint
+         *      admits a bounded number per minute across all callers and answers `429`
+         *      beyond it.
          */
         post: operations["register_deposit_address"];
         delete?: never;
@@ -6512,25 +6538,21 @@ export interface components {
         };
         RegisterRequest: {
             /**
-             * @description The application's client id — the same identifier rollup deposits carry and `login` takes. The deposit address is derived from these exact bytes and the application lookup is an exact string match, so the spelling must match the registered application precisely.
-             * @example 60eb377aab9f4ea18dcdf4747204c792
-             */
-            clientId: string;
-            /**
-             * @description Address credited on the rollup, and half of the deposit address derivation
-             * @example 0x742d35Cc6634C0532925a3b8D4060f31E2C3d8B5
+             * @description Which ledger swept deposits are requested to be credited to. `SPOT` (the default when omitted) credits the spot wallet; `MARGIN` asks for the parent margin account's collateral, skipping the separate collateral transfer. The target is part of the address derivation, so `SPOT` and `MARGIN` yield two different deposit addresses for the same pair, and each address carries its own request. `MARGIN` is a routing request rather than a guarantee: a deposit the matching engine cannot route to collateral — an unsupported collateral asset, or a margin account that fails validation — is credited to the spot wallet instead, so funds are never stranded. A `SPOT` address is never credited to margin.
+             * @example MARGIN
+             * @enum {string|null}
              */
-            userAddress: string;
+            depositTarget?: "SPOT" | "MARGIN" | null;
         };
         RegisterResponse: {
             /**
-             * @description `registered` when the pair was added, `already_registered` when it was known before this call
+             * @description `registered` when the triple was added, `already_registered` when it was known before this call
              * @example registered
              * @enum {string|null}
              */
             status?: "registered" | "already_registered" | null;
             /**
-             * @description The pair's deposit address. Stable, and valid to publish and fund before any contract exists there.
+             * @description The deposit address for this (application, user, deposit target) triple. Stable, and valid to publish and fund before any contract exists there.
              * @example 0xcf1eF339798914EF7Ee4984Ed45BD141D63a65C9
              */
             sweeperAddress?: string | null;
@@ -7355,6 +7377,16 @@ export interface components {
             marginMode?: string | null;
             /** @description Present for cross risk-bucket transfers. */
             selectedTradingPairIds?: string[] | null;
+            /**
+             * @description Whether the transfer was committed to a position's stored margin.
+             *      Present only when a position-margin credit was in play: true — the credit
+             *      landed; false — a credit was requested (or defaulted) but degraded to a
+             *      plain allocation because the bucket's persisted position row was stale
+             *      (close/reopen race) — re-issue the Adjust Margin once the new position
+             *      row lands if the commitment still matters. Absent on plain allocations,
+             *      parent deposits, and releases.
+             */
+            positionMarginCredited?: boolean | null;
         };
         TransferCollateralToParentMarginAccountRequest: {
             asset?: string | null;
@@ -7374,6 +7406,31 @@ export interface components {
             marginMode?: string | null;
             /** @description Trading pair UUIDs selected into the cross risk bucket. Required when marginMode is CROSS. */
             selectedTradingPairIds?: string[] | null;
+            /**
+             * @description What the transferred collateral becomes when the ISOLATED bucket holds an
+             *      open position. The two intents want opposite fates for the same dollars,
+             *      so the caller states theirs:
+             *
+             *      - true (and UNSET — the default is the human "Adjust Margin" gesture):
+             *       the amount is COMMITTED to the position's stored margin. Effective
+             *       leverage drops and stays down, initial margin required rises by the
+             *       amount, free collateral is unchanged — new orders cannot spend it.
+             *      - false: plain allocation. Free collateral rises and the next order can
+             *       spend it. Programmatic funding loops that top a bucket up to a free
+             *       collateral target MUST pass false, or each top-up converts into
+             *       requirement and the loop never converges.
+             *
+             *      Either way the liquidation cushion improves identically (the breach
+             *      check is bucket-equity based). On a FLAT isolated bucket there is no
+             *      position to commit to and both values are a plain allocation. Explicit
+             *      true is rejected for CROSS buckets (cross has no per-position margin);
+             *      unset/false is a plain allocation there.
+             *
+             *      The response reports what actually happened in `position_margin_credited`
+             *      — a credit can degrade to a plain allocation when the persisted position
+             *      row is stale (close/reopen race).
+             */
+            applyToPositionMargin?: boolean | null;
         };
         TransferRewardsRequest: {
             /**
@@ -12008,14 +12065,21 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Application not found */
-            404: {
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The application for this session is not active */
+            403: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Registration rate-limit exceeded */
+            /** @description Registration admission limit exceeded; retry shortly */
             429: {
                 headers: {
                     [name: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/types",
-	"version": "1.0.48",
+	"version": "1.0.50",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,7 +16,7 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.48",
+		"@0xmonaco/contracts": "1.0.50",
 		"zod": "^4.1.12"
 	},
 	"peerDependencies": {