@0xmonaco/types 1.0.70 → 1.0.73-develop.af0f5d0

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

@@ -9,7 +9,17 @@ export interface MarginAccountSummary {
     selectedTradingPairIds?: string[];
     tradingPairId?: string;
     strategyKey?: string;
-    accountState: string;
+    /**
+     * The risk bucket's lifecycle state: `NORMAL`, `PENDING_LIQUIDATION`,
+     * `LIQUIDATING`, `BAD_DEBT` or `CLOSED`. Present only on risk-bucket rows —
+     * a parent margin account has no lifecycle of its own; liquidation and bad
+     * debt live in its risk buckets.
+     */
+    riskBucketState?: string;
+    /** The margin account's sub-account key; `default` is the default margin account. */
+    subaccountKey?: string;
+    /** The margin account's state: `ACTIVE`, or `CLOSED` for a closed sub-account. */
+    marginAccountState?: string;
     equity: string;
     initialMarginRequired: string;
     maintenanceMarginRequired: string;
@@ -19,13 +29,20 @@ export interface MarginAccountSummary {
      * The largest amount a transfer-out of this scope will actually accept.
      *
      * Not a clamped `freeCollateral`. Free collateral is equity headroom, and
-     * equity includes realized PnL, accrued funding and mark-to-market gains
-     * that are not principal a transfer can move — so the two can differ
-     * without limit. An unrealized gain never counts toward this figure.
+     * equity includes mark-to-market gains that a transfer cannot move — so the
+     * two can differ without limit. An unrealized gain never counts toward this
+     * figure.
      *
-     * For a risk bucket this is capped by the bucket's allocated collateral;
-     * for a parent margin account, by deposited collateral that no risk bucket
-     * has earmarked. Size transfers against this field, not `freeCollateral`.
+     * For a risk bucket this is the bucket's allocated collateral plus its
+     * realized PnL, less what its positions and resting orders require (the
+     * bucket's allocation may go negative, which is how realized profit leaves
+     * a live bucket); for a parent margin account, net deposits plus settled
+     * realized PnL that no risk bucket has allocated. Every smaller amount is
+     * accepted too. It is zero on a risk bucket that is not `NORMAL` (under
+     * liquidation or frozen as bad debt) and on one whose realized loss has used
+     * up its allocation; the parent margin account is charged at most a risk
+     * bucket's allocation. Size transfers against this field, not
+     * `freeCollateral`.
      */
     withdrawableCollateral: string;
     totalPositionNotional: string;
@@ -90,6 +107,11 @@ export interface MarginAccountSummary {
 export interface ListMarginAccountsParams {
     page?: number;
     pageSize?: number;
+    /**
+     * Keep only risk-bucket rows in this state (see
+     * {@link MarginAccountSummary.riskBucketState}). A parent margin account row
+     * has no state, so any filter excludes it.
+     */
     state?: string;
     tradingPairId?: string;
 }
@@ -118,13 +140,13 @@ export interface GetAvailableCollateralResponse {
      * margin account yet.
      *
      * This is **not** trading headroom for existing cross exposure. It is
-     * bounded by allocation (principal not earmarked by risk buckets) as well
-     * as by margin requirements, and an unrealized gain does not raise it: a
+     * bounded by allocation (net deposits plus settled realized PnL not
+     * allocated to risk buckets) as well as by margin requirements, and an unrealized gain does not raise it: a
      * mark-to-market gain is initial margin against existing cross exposure but
      * may not fund an exit. `MarginAccountSummary.freeCollateral` credits that
      * gain in full and remains the trading-margin headroom for existing cross
      * exposure — but a **new** isolated or first-use position allocates
-     * principal through the same gate this field measures, so size those from
+     * collateral through the same gate this field measures, so size those from
      * this field.
      *
      * Note the two `margin*` fields answer opposite questions:
@@ -158,6 +180,8 @@ export interface TransferCollateralToParentMarginAccountRequest {
  */
 export interface TransferCollateralToIsolatedRiskBucketRequest extends TransferCollateralToParentMarginAccountRequest {
     marginMode?: "ISOLATED";
+    /** The margin account whose bucket is funded: omit for the default account, or name an open sub-account. */
+    marginAccountId?: string;
     tradingPairId: string;
     strategyKey?: string;
     selectedTradingPairIds?: never;
@@ -192,6 +216,8 @@ export interface TransferCollateralToIsolatedRiskBucketRequest extends TransferC
  */
 export interface TransferCollateralToCrossRiskBucketRequest extends TransferCollateralToParentMarginAccountRequest {
     marginMode: "CROSS";
+    /** The margin account whose cross bucket is funded: omit for the default account, or name an open sub-account. */
+    marginAccountId?: string;
     /**
      * Removed. This used to declare — and on every top-up REPLACE — the cross
      * bucket's scope, which let a partial list silently evict every flat pair it
@@ -291,6 +317,8 @@ export interface SimulateOrderRiskRequest {
 }
 export type SimulateIsolatedRiskBucketOrderRiskRequest = SimulateOrderRiskRequest & {
     marginMode?: "ISOLATED";
+    /** The margin account previewed: omit for the default account, or name an open sub-account. */
+    marginAccountId?: string;
     strategyKey?: string;
     selectedTradingPairIds?: never;
 };
@@ -305,6 +333,8 @@ export type SimulateIsolatedRiskBucketOrderRiskRequest = SimulateOrderRiskReques
  */
 export type SimulateCrossRiskBucketOrderRiskRequest = SimulateOrderRiskRequest & {
     marginMode: "CROSS";
+    /** The margin account previewed: omit for the default account, or name an open sub-account. */
+    marginAccountId?: string;
     /**
      * Removed. This used to declare the scope the preview ran against (required,
      * containing `tradingPairId`, covering every open cross position) while the
@@ -416,7 +446,81 @@ export interface SimulateOrderRiskResponse {
      */
     referencePrice?: string;
 }
+/**
+ * Open a margin sub-account: another margin account of the caller, keyed by
+ * `subaccountKey`, with its own collateral and risk buckets. Keys are up to 64
+ * letters, digits, `_`, `-`, `.` or `:`; `copy:` keys are reserved and
+ * `default` names the default margin account. Re-creating the key of a closed
+ * sub-account re-opens it.
+ */
+export interface CreateMarginSubAccountRequest {
+    subaccountKey: string;
+    label?: string;
+}
+export interface CreateMarginSubAccountResponse {
+    marginAccountId: string;
+    subaccountKey: string;
+    marginAccountState: string;
+    label?: string;
+}
+/** One margin account's own PnL (default or sub-account); the owner's accounts sum to the owner-wide figure. */
+export interface MarginAccountPnl {
+    marginAccountId: string;
+    /** Settled on the account plus still held in its open risk buckets. */
+    realizedPnl: string;
+    /** The account's open positions repriced at the latest risk marks. */
+    unrealizedPnl: string;
+}
+export interface CloseMarginSubAccountResponse {
+    marginAccountId: string;
+    /** The default margin account that received the remaining collateral. */
+    defaultMarginAccountId: string;
+    /** Collateral moved to the default margin account. */
+    amount: string;
+}
+/** One side of a collateral transfer: the spot wallet, or a margin account. */
+export type CollateralTransferEndpoint = {
+    wallet: true;
+    marginAccountId?: never;
+    riskBucketId?: never;
+} | {
+    wallet?: never;
+    marginAccountId: string;
+    riskBucketId?: string;
+};
+/**
+ * Move collateral between the spot wallet and the caller's margin accounts.
+ * Supported: wallet to the default margin account and back, and margin
+ * account to margin account.
+ */
+export interface TransferMarginCollateralRequest {
+    asset: string;
+    amount: string;
+    from: CollateralTransferEndpoint;
+    to: CollateralTransferEndpoint;
+}
+export interface TransferMarginCollateralResponse {
+    movementId: string;
+    amount: string;
+    fromMarginAccountId?: string;
+    toMarginAccountId?: string;
+    toRiskBucketId?: string;
+}
 export interface MarginAccountsAPI extends BaseAPI {
+    /**
+     * Open a margin sub-account. Refused past the owner's cap on open sub-accounts (10 at the
+     * first volume tier, up to 50, or an admin override); copy-trading sub-accounts do not count.
+     */
+    createMarginSubAccount(request: CreateMarginSubAccountRequest): Promise<CreateMarginSubAccountResponse>;
+    /**
+     * Close a flat margin sub-account in one call: its flat, solvent risk buckets close and all of
+     * its collateral moves to the default margin account. A risk bucket in liquidation or bad debt
+     * refuses the close.
+     */
+    closeMarginSubAccount(marginAccountId: string): Promise<CloseMarginSubAccountResponse>;
+    /** One of the caller's margin accounts' own realized and unrealized PnL. */
+    getMarginAccountPnl(marginAccountId: string): Promise<MarginAccountPnl>;
+    transferMarginCollateral(request: TransferMarginCollateralRequest): Promise<TransferMarginCollateralResponse>;
     listMarginAccounts(params?: ListMarginAccountsParams): Promise<ListMarginAccountsResponse>;
     getParentMarginAccountSummary(params?: GetMarginAccountSummaryParams): Promise<MarginAccountSummary>;
     /**

package/dist/pitpass/index.d.ts

@@ -4,7 +4,7 @@
  * Types for PitPass TraderCode API: code lookup, rewards balance, and transfer.
  */
 import type { BaseAPI } from "../api";
-import type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
+import type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse } from "./responses";
 /**
  * PitPass TraderCode API interface.
  *
@@ -92,8 +92,9 @@ export interface PitpassAPI extends BaseAPI {
      */
     transferRewards(params: TransferRewardsParams): Promise<TransferRewardsResponse>;
     /**
-     * Read your own referral position: your direct (L1) referrer, total earned,
-     * and most recent reward rows.
+     * Read your own referral position: your referral chain upward (`upline`, L1
+     * then L2 then L3), your direct referrer, total earned, and most recent
+     * reward rows.
      *
      * Self-scoped — the server derives your identity from the session, so you can
      * only ever read your own chain. `referrer` is the empty string when you were
@@ -101,7 +102,7 @@ export interface PitpassAPI extends BaseAPI {
      * identified by their public wallet address (with a `display` handle-or-wallet
      * variant), never an internal id.
      *
-     * @returns Promise resolving to your referrer, total earned, and recent rewards
+     * @returns Promise resolving to your upline, referrer, total earned, and recent rewards
      */
     getMyReferralPosition(): Promise<GetMyReferralPositionResponse>;
     /**
@@ -115,6 +116,20 @@ export interface PitpassAPI extends BaseAPI {
      * @returns Promise resolving to earnings-by-source, the direct-referee roster, and a summary
      */
     getMyReferralDownline(): Promise<GetMyReferralDownlineResponse>;
+    /**
+     * Read one level of your own referral tree: the wallets `parent` directly
+     * referred (yourself when `parent` is omitted), a page at a time, newest
+     * first. Expand a node by calling again with `parent` set to its wallet;
+     * nodes with `refereeCount > 0` are expandable, down to level 3.
+     *
+     * Self-scoped: `parent` must be you or one of your own L1/L2 referees — any
+     * other wallet is a 404. Each wallet appears once, under the referrer that
+     * earns from it.
+     *
+     * @param params - Optional `parent` wallet, `pageSize` (1-200), and `pageToken`
+     * @returns Promise resolving to the page of nodes and the next page token
+     */
+    getMyReferralTree(params?: GetMyReferralTreeParams): Promise<GetMyReferralTreeResponse>;
 }
-export type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetRewardsBalanceResponse, ReferralDirectReferee, ReferralEarningsSource, ReferralEarningsSummary, ReferralRewardEntry, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
-export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export type { GetMyReferralDownlineResponse, GetMyReferralPositionResponse, GetMyReferralTreeParams, GetMyReferralTreeResponse, GetRewardsBalanceResponse, ReferralDirectReferee, ReferralEarningsSource, ReferralEarningsSummary, ReferralRewardEntry, ReferralTreeNode, ReferralUplineEntry, RewardsBalanceEntry, SetTraderCodeParams, TraderCodeAvailabilityReason, TraderCodeAvailabilityResponse, TraderCodeInfoResponse, TraderCodeResponse, TransferRewardsParams, TransferRewardsResponse, } from "./responses";
+export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";

package/dist/pitpass/index.js

@@ -3,4 +3,4 @@
  *
  * Types for PitPass TraderCode API: code lookup, rewards balance, and transfer.
  */
-export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";
+export { GetMyReferralDownlineResponseSchema, GetMyReferralPositionResponseSchema, GetMyReferralTreeParamsSchema, GetMyReferralTreeResponseSchema, GetRewardsBalanceResponseSchema, ReferralDirectRefereeSchema, ReferralEarningsSourceSchema, ReferralEarningsSummarySchema, ReferralRewardEntrySchema, ReferralTreeNodeSchema, ReferralUplineEntrySchema, RewardsBalanceEntrySchema, SetTraderCodeParamsSchema, TraderCodeAvailabilityReasonSchema, TraderCodeAvailabilityResponseSchema, TraderCodeInfoResponseSchema, TraderCodeResponseSchema, TransferRewardsParamsSchema, TransferRewardsResponseSchema, } from "./responses";

package/dist/pitpass/responses.d.ts

@@ -77,6 +77,12 @@ export declare const ReferralRewardEntrySchema: z.ZodObject<{
     rateApplied: z.ZodString;
     createdAt: z.ZodString;
 }, z.core.$strip>;
+/** One ancestor in the caller's referral chain. */
+export declare const ReferralUplineEntrySchema: z.ZodObject<{
+    wallet: z.ZodString;
+    display: z.ZodString;
+    level: z.ZodNumber;
+}, z.core.$strip>;
 /** The caller's own referral position: who referred them and what they've earned. */
 export declare const GetMyReferralPositionResponseSchema: z.ZodObject<{
     referrer: z.ZodString;
@@ -91,6 +97,11 @@ export declare const GetMyReferralPositionResponseSchema: z.ZodObject<{
         rateApplied: z.ZodString;
         createdAt: z.ZodString;
     }, z.core.$strip>>;
+    upline: z.ZodArray<z.ZodObject<{
+        wallet: z.ZodString;
+        display: z.ZodString;
+        level: z.ZodNumber;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** One aggregated earnings row per (source trader, level, token) the caller earns from. */
 export declare const ReferralEarningsSourceSchema: z.ZodObject<{
@@ -136,6 +147,37 @@ export declare const GetMyReferralDownlineResponseSchema: z.ZodObject<{
         level3Earned: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/** Query parameters for reading one level of the caller's referral tree. */
+export declare const GetMyReferralTreeParamsSchema: z.ZodObject<{
+    parent: z.ZodOptional<z.ZodString>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One wallet in the caller's referral tree. */
+export declare const ReferralTreeNodeSchema: z.ZodObject<{
+    wallet: z.ZodString;
+    display: z.ZodString;
+    level: z.ZodNumber;
+    parent: z.ZodString;
+    referredAt: z.ZodString;
+    refereeCount: z.ZodNumber;
+    totalEarned: z.ZodString;
+}, z.core.$strip>;
+/** One page of one level of the caller's referral tree. */
+export declare const GetMyReferralTreeResponseSchema: z.ZodObject<{
+    parent: z.ZodString;
+    parentLevel: z.ZodNumber;
+    nodes: z.ZodArray<z.ZodObject<{
+        wallet: z.ZodString;
+        display: z.ZodString;
+        level: z.ZodNumber;
+        parent: z.ZodString;
+        referredAt: z.ZodString;
+        refereeCount: z.ZodNumber;
+        totalEarned: z.ZodString;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodString;
+}, z.core.$strip>;
 export type RewardsBalanceEntry = z.infer<typeof RewardsBalanceEntrySchema>;
 export type GetRewardsBalanceResponse = z.infer<typeof GetRewardsBalanceResponseSchema>;
 export type TraderCodeResponse = z.infer<typeof TraderCodeResponseSchema>;
@@ -151,3 +193,7 @@ export type ReferralEarningsSource = z.infer<typeof ReferralEarningsSourceSchema
 export type ReferralDirectReferee = z.infer<typeof ReferralDirectRefereeSchema>;
 export type ReferralEarningsSummary = z.infer<typeof ReferralEarningsSummarySchema>;
 export type GetMyReferralDownlineResponse = z.infer<typeof GetMyReferralDownlineResponseSchema>;
+export type ReferralUplineEntry = z.infer<typeof ReferralUplineEntrySchema>;
+export type GetMyReferralTreeParams = z.infer<typeof GetMyReferralTreeParamsSchema>;
+export type ReferralTreeNode = z.infer<typeof ReferralTreeNodeSchema>;
+export type GetMyReferralTreeResponse = z.infer<typeof GetMyReferralTreeResponseSchema>;

package/dist/pitpass/responses.js

@@ -118,11 +118,20 @@ export const ReferralRewardEntrySchema = z.object({
     /** RFC 3339 timestamp when the reward row was recorded. */
     createdAt: z.string(),
 });
+/** One ancestor in the caller's referral chain. */
+export const ReferralUplineEntrySchema = z.object({
+    /** Public wallet address of the ancestor. */
+    wallet: z.string(),
+    /** Human-facing name for the ancestor: their custom handle if claimed, else the wallet. */
+    display: z.string(),
+    /** How far above the caller this ancestor is: 1 (direct referrer), 2, or 3. */
+    level: z.number(),
+});
 /** The caller's own referral position: who referred them and what they've earned. */
 export const GetMyReferralPositionResponseSchema = z.object({
     /**
      * Public wallet address of the caller's direct (L1) referrer. Empty string
-     * when the caller was not referred. Only the direct referrer is exposed.
+     * when the caller was not referred. Same wallet as the first `upline` entry.
      */
     referrer: z.string(),
     /** Human-facing name for the referrer: their custom handle if claimed, else the wallet (empty when not referred). */
@@ -131,6 +140,12 @@ export const GetMyReferralPositionResponseSchema = z.object({
     totalEarned: z.string(),
     /** The caller's most recent reward rows, newest first (bounded server-side). */
     rewards: z.array(ReferralRewardEntrySchema),
+    /**
+     * The caller's referral chain upward, nearest first: L1, L2, then L3. At most
+     * three entries; empty when the caller was not referred. These are the
+     * wallets the caller's own trades pay referral rewards to.
+     */
+    upline: z.array(ReferralUplineEntrySchema),
 });
 /** One aggregated earnings row per (source trader, level, token) the caller earns from. */
 export const ReferralEarningsSourceSchema = z.object({
@@ -179,3 +194,43 @@ export const GetMyReferralDownlineResponseSchema = z.object({
      */
     summary: ReferralEarningsSummarySchema,
 });
+/** Query parameters for reading one level of the caller's referral tree. */
+export const GetMyReferralTreeParamsSchema = z.object({
+    /**
+     * Wallet whose direct referees to list. Omit for your own L1 referees; set to
+     * one of your L1 or L2 referees to expand that node.
+     */
+    parent: z.string().optional(),
+    /** Nodes per page (1-200, default 50). */
+    pageSize: z.number().int().min(1).max(200).optional(),
+    /** Opaque cursor from a previous response's `nextPageToken`. Only valid with the same `parent`. */
+    pageToken: z.string().optional(),
+});
+/** One wallet in the caller's referral tree. */
+export const ReferralTreeNodeSchema = z.object({
+    /** Public wallet address of this referee. */
+    wallet: z.string(),
+    /** Human-facing name: their custom handle if claimed, else the wallet. */
+    display: z.string(),
+    /** Depth below the caller: 1 (you referred them), 2, or 3. */
+    level: z.number(),
+    /** Wallet address of this node's referrer — your own wallet for a level-1 node. */
+    parent: z.string(),
+    /** RFC 3339 time this wallet signed up under its parent. */
+    referredAt: z.string(),
+    /** How many wallets this node has referred. Expandable when above 0; always 0 at level 3. */
+    refereeCount: z.number(),
+    /** What you have earned from this wallet's own trades, RAW atomic units. `0` if they haven't traded. */
+    totalEarned: z.string(),
+});
+/** One page of one level of the caller's referral tree. */
+export const GetMyReferralTreeResponseSchema = z.object({
+    /** Wallet whose referees `nodes` lists — your own wallet when `parent` was omitted. */
+    parent: z.string(),
+    /** Depth of `parent` below you: 0 for yourself, 1 or 2 for an expanded referee. */
+    parentLevel: z.number(),
+    /** The wallets `parent` referred, newest first. */
+    nodes: z.array(ReferralTreeNodeSchema),
+    /** Cursor for the next page; empty when there are no more. */
+    nextPageToken: z.string(),
+});

package/dist/portfolio/index.d.ts

@@ -166,15 +166,15 @@ export interface PortfolioMarginTotal {
      * bound the engine enforces on transfers-out and withdrawals, and therefore
      * also the effective ceiling on funding new isolated or first-use order
      * capacity (allocating collateral to a risk bucket passes through the same
-     * principal-gated door).
+     * capacity-gated door).
      *
      * NOT a clamped `parentAvailableCollateral`: that is an equity figure which
-     * credits settled realized PnL, accrued funding, and unrealized gains that a
-     * transfer-out cannot move. This bound never credits an unrealized gain, and
-     * under the default capacity basis it also excludes non-principal balances —
-     * `min(deposited principal - bucket allocations, freeCollateral - max(unrealizedPnl, 0))`,
-     * floored at zero. Whatever the engine's configured capacity basis, this is
-     * the bound its gates actually enforce. Size transfers-out, withdrawals, and
+     * credits unrealized gains and realized PnL still held in open risk
+     * buckets, which a transfer-out of the parent cannot move. This bound never
+     * credits an unrealized gain; it counts net deposits plus the account's
+     * settled realized PnL and funding, less what risk buckets have allocated —
+     * `min(net deposits + settled realized PnL - bucket allocations, freeCollateral - max(unrealizedPnl, 0))`,
+     * floored at zero. This is the bound the engine's gates actually enforce. Size transfers-out, withdrawals, and
      * new isolated or first-use positions from this field;
      * `parentAvailableCollateral` remains the trading-margin headroom for
      * existing cross exposure.
@@ -196,12 +196,14 @@ export interface PortfolioRiskBucket {
     positionCount: number;
     /**
      * The largest transfer-out of this risk bucket the engine will actually
-     * accept. NOT a clamped `freeCollateral`: capped by the bucket's settled
-     * capacity (its allocated collateral, under the default capacity basis),
-     * and an unrealized gain never raises it. This is the largest
-     * accepted transfer-out, not a promise that every smaller one is accepted —
-     * an underwater flat bucket accepts its full close-out while refusing
-     * partial withdrawals below it.
+     * accept. NOT a clamped `freeCollateral`: the bucket's allocated
+     * collateral plus its realized PnL, less funding paid, unrealized losses
+     * and the margin its positions and resting orders require. Realized profit
+     * can leave a live bucket this way (the bucket's allocation may go
+     * negative); an unrealized gain never raises it. This is the largest
+     * accepted transfer-out, and every smaller amount is accepted too. It is
+     * zero on a risk bucket that is not `NORMAL` and on one whose realized loss
+     * has used up its allocation.
      */
     withdrawableCollateral: string;
     /**
@@ -267,11 +269,31 @@ export interface PortfolioRiskBucket {
      */
     tradingPairId?: string;
 }
+/** One of the caller's open margin accounts in the owner rollup. */
+export interface PortfolioMarginAccount {
+    marginAccountId: string;
+    /** `default` for the default margin account, else the sub-account's key. */
+    subaccountKey: string;
+    /** The account's totals; `withdrawableCollateral` is the persisted reconstruction of the engine's bound. */
+    total: PortfolioMarginTotal;
+}
 export interface PortfolioMargin {
     asOf: string;
     total: PortfolioMarginTotal;
     positions: PortfolioMarginPositionCounts;
     riskBuckets: PortfolioRiskBucket[];
+    /** The margin account `total`, `positions` and `riskBuckets` describe; absent before the first margin account. */
+    marginAccountId?: string;
+    /** With `includeAccounts`: every open margin account, the default one first. */
+    accounts?: PortfolioMarginAccount[];
+    /** With `includeAccounts`: the sum of `accounts`' totals (the owner rollup). */
+    ownerTotal?: PortfolioMarginTotal;
+}
+export interface PortfolioMarginParams {
+    /** One of your margin accounts (default or a sub-account) to describe instead of the default one. */
+    marginAccountId?: string;
+    /** Also return every open margin account's totals and their sum. */
+    includeAccounts?: boolean;
 }
 /** Authoritative, application-scoped portfolio analytics. */
 export interface PortfolioAPI extends BaseAPI {
@@ -279,5 +301,5 @@ export interface PortfolioAPI extends BaseAPI {
     getPerformance(params?: PortfolioPeriodParams): Promise<PortfolioPerformance>;
     getRealizedPnl(params?: PortfolioPeriodParams): Promise<PortfolioRealizedPnl>;
     getAssets(params?: PortfolioPeriodParams): Promise<PortfolioAssets>;
-    getMargin(): Promise<PortfolioMargin>;
+    getMargin(params?: PortfolioMarginParams): Promise<PortfolioMargin>;
 }

package/dist/trading/orders.d.ts

@@ -178,7 +178,7 @@ export interface Order {
     version?: number;
 }
 /** Stable terminal causes for accepted orders that end as CANCELLED. */
-export type OrderTerminalReason = "USER_REQUESTED" | "REPLACED" | "LIQUIDATION" | "INSUFFICIENT_MARGIN" | "REDUCE_ONLY_EXHAUSTED" | "POSITION_CLOSED" | "OCO_SIBLING_TRIGGERED" | "SELF_TRADE_PREVENTION" | "SYSTEM";
+export type OrderTerminalReason = "USER_REQUESTED" | "REPLACED" | "LIQUIDATION" | "INSUFFICIENT_MARGIN" | "REDUCE_ONLY_EXHAUSTED" | "POSITION_CLOSED" | "OCO_SIBLING_TRIGGERED" | "SELF_TRADE_PREVENTION" | "AUTO_DELEVERAGING" | "SYSTEM";
 /**
  * Role of the creator or order
  */

package/dist/trading/responses.d.ts

@@ -159,7 +159,7 @@ export interface ReplaceOrderResponse {
     status: "SUCCESS" | "FAILED";
     /** Operation message */
     message: string;
-    /** Fields that were updated */
+    /** The replacement's price and total quantity (see {@link UpdatedFields}) */
     updatedFields: UpdatedFields;
     /** Original order identifier that was replaced */
     originalOrderId?: string;
@@ -167,12 +167,19 @@ export interface ReplaceOrderResponse {
     matchResult?: MatchResult;
 }
 /**
- * Fields that were updated in the replace operation
+ * The replacement's price and quantity, as the replace operation placed them
  */
 export interface UpdatedFields {
-    /** Updated price (if changed) */
+    /** The replacement's price: the requested price, or the original order's when omitted */
     price?: string;
-    /** Updated quantity (if changed) */
+    /**
+     * The replacement's TOTAL quantity, not its resting size: the requested
+     * quantity, or the original order's total when omitted. A 100-lot with 60
+     * filled reports "100" and rests 40; read the order's `remainingQuantity`
+     * for the resting size. For a margin reduce-only replacement it is the close
+     * size placed (the requested quantity, or the original's remaining quantity
+     * when omitted).
+     */
     quantity?: string;
 }
 /**
@@ -336,7 +343,7 @@ export interface BatchReplaceResult {
     originalOrderId: string;
     /** New order identifier (if successful) */
     newOrderId?: string;
-    /** Fields that were updated (if successful) */
+    /** The replacement's price and total quantity, if successful (see {@link UpdatedFields}) */
     updatedFields?: UpdatedFields;
     /** Match result information if the new order was processed */
     matchResult?: MatchResult;
@@ -435,7 +442,12 @@ export interface BatchReplaceOrderParams {
     orderId: string;
     /** New order price (optional) */
     price?: string;
-    /** New order quantity (optional) */
+    /**
+     * New TOTAL order quantity (optional): the replacement rests this total
+     * minus the already-filled amount, so it must exceed the filled amount.
+     * Omitted, the order keeps its total. A margin reduce-only quantity is a
+     * close size, placed as given.
+     */
     quantity?: string;
     /** For sub-accounts: use master's balance (optional) */
     useMasterBalance?: boolean;

package/dist/validation/copy-trading.d.ts

@@ -70,6 +70,16 @@ export declare const PreviewFollowSchema: z.ZodObject<{
     allocation: z.ZodString;
     tradingPairIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
 }, z.core.$strict>;
+/**
+ * Params for adding margin to one of your copy positions: `amount` moves from
+ * the follow's copy account into the margin of its isolated copy position on
+ * `tradingPairId`. The follow id is sent in the path, the rest in the body.
+ */
+export declare const AddFollowPositionMarginSchema: z.ZodObject<{
+    followId: z.ZodUUID;
+    tradingPairId: z.ZodUUID;
+    amount: z.ZodString;
+}, z.core.$strict>;
 /** Params for the public leaderboard. */
 export declare const ListLeadTradersSchema: z.ZodObject<{
     pageSize: z.ZodOptional<z.ZodNumber>;
@@ -107,6 +117,7 @@ export declare const ListMyFollowersSchema: z.ZodObject<{
 export type UpsertLeadTraderParams = z.input<typeof UpsertLeadTraderSchema>;
 export type UpsertFollowParams = z.input<typeof UpsertFollowSchema>;
 export type PreviewFollowParams = z.input<typeof PreviewFollowSchema>;
+export type AddFollowPositionMarginParams = z.input<typeof AddFollowPositionMarginSchema>;
 export type ListLeadTradersParams = z.input<typeof ListLeadTradersSchema>;
 export type ListLeadTraderClosedTradesParams = z.input<typeof ListLeadTraderClosedTradesSchema>;
 export type ListMyFollowsParams = z.input<typeof ListMyFollowsSchema>;

package/dist/validation/copy-trading.js

@@ -123,6 +123,21 @@ export const PreviewFollowSchema = z
 })
     .strict()
     .superRefine((params, ctx) => termRules(params, ctx));
+/**
+ * Params for adding margin to one of your copy positions: `amount` moves from
+ * the follow's copy account into the margin of its isolated copy position on
+ * `tradingPairId`. The follow id is sent in the path, the rest in the body.
+ */
+export const AddFollowPositionMarginSchema = z
+    .object({
+    /** The follow's id. */
+    followId: UUIDSchema,
+    /** Trading pair of the copy position to add margin to. */
+    tradingPairId: UUIDSchema,
+    /** Margin to add, in quote units, taken from the follow's copy account. */
+    amount: PositiveDecimalStringSchema,
+})
+    .strict();
 /** Params for the public leaderboard. */
 export const ListLeadTradersSchema = z
     .object({