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

package/dist/buildercodes/index.d.ts

@@ -5,7 +5,7 @@
  * per-trade revenue share.
  */
 import type { BaseAPI } from "../api";
-import type { ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse } from "./responses";
+import type { ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse, ListBuilderFeeChangesParams, ListBuilderFeeChangesResponse, SetBuilderFeeParams, SetBuilderFeeResponse } from "./responses";
 /**
  * BuilderCodes payout API interface.
  *
@@ -18,6 +18,10 @@ import type { ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, Ge
 export interface BuildercodesAPI extends BaseAPI {
     /** Read this authenticated frontend's enrollment, payout address, and live budget. */
     getConfig(): Promise<GetBuildercodesConfigResponse>;
+    /** Set this frontend's stored builder fee in basis points. */
+    setBuilderFee(params: SetBuilderFeeParams): Promise<SetBuilderFeeResponse>;
+    /** List this frontend's builder-fee audit log, newest first. */
+    listBuilderFeeChanges(params?: ListBuilderFeeChangesParams): Promise<ListBuilderFeeChangesResponse>;
     /** List this authenticated frontend's per-trade BuilderCodes credits, optionally of one payout `kind`. */
     listPayouts(params?: ListBuildercodePayoutsParams): Promise<ListBuildercodePayoutsResponse>;
     /** Summarize this authenticated frontend's BuilderCodes credits by token, and by token and payout kind. */
@@ -67,5 +71,5 @@ export interface BuildercodesAPI extends BaseAPI {
      */
     claimBuildercodeRewards(params: ClaimBuildercodeRewardsParams): Promise<ClaimBuildercodeRewardsResponse>;
 }
-export type { BuildercodePayout, BuildercodePayoutKind, BuildercodePayoutTokenKindTotal, BuildercodePayoutTokenTotal, BuildercodeRewardsBalance, ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse, } from "./responses";
-export { BuildercodePayoutKindSchema, BuildercodePayoutSchema, BuildercodePayoutTokenKindTotalSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, } from "./responses";
+export type { BuildercodePayout, BuildercodePayoutKind, BuildercodePayoutTokenKindTotal, BuildercodePayoutTokenTotal, BuildercodeRewardsBalance, BuilderFeeActorType, BuilderFeeChange, ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse, ListBuilderFeeChangesParams, ListBuilderFeeChangesResponse, SetBuilderFeeParams, SetBuilderFeeResponse, } from "./responses";
+export { BuildercodePayoutKindSchema, BuildercodePayoutSchema, BuildercodePayoutTokenKindTotalSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, BuilderFeeActorTypeSchema, BuilderFeeChangeSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, ListBuilderFeeChangesParamsSchema, ListBuilderFeeChangesResponseSchema, SetBuilderFeeParamsSchema, SetBuilderFeeResponseSchema, } from "./responses";

package/dist/buildercodes/index.js

@@ -4,4 +4,4 @@
  * Types for the BuilderCodes API: reading and claiming an enrolled frontend's
  * per-trade revenue share.
  */
-export { BuildercodePayoutKindSchema, BuildercodePayoutSchema, BuildercodePayoutTokenKindTotalSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, } from "./responses";
+export { BuildercodePayoutKindSchema, BuildercodePayoutSchema, BuildercodePayoutTokenKindTotalSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, BuilderFeeActorTypeSchema, BuilderFeeChangeSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, ListBuilderFeeChangesParamsSchema, ListBuilderFeeChangesResponseSchema, SetBuilderFeeParamsSchema, SetBuilderFeeResponseSchema, } from "./responses";

package/dist/buildercodes/responses.d.ts

@@ -12,11 +12,61 @@ export declare const GetBuildercodesConfigResponseSchema: z.ZodObject<{
     payoutAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     buildercodesEnabled: z.ZodBoolean;
     buildercodesBudgetBps: z.ZodNumber;
+    builderFeeEnabled: z.ZodBoolean;
+    builderFeeBps: z.ZodNumber;
+    builderFeeCapBps: z.ZodNumber;
+    changesRemaining: z.ZodNumber;
+    nextChangeAllowedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Schema for changing this frontend's builder fee. */
+export declare const SetBuilderFeeParamsSchema: z.ZodObject<{
+    bps: z.ZodNumber;
+}, z.core.$strip>;
+/** Schema returned after setting this frontend's builder fee. */
+export declare const SetBuilderFeeResponseSchema: z.ZodObject<{
+    builderFeeBps: z.ZodNumber;
+    previousBuilderFeeBps: z.ZodNumber;
+    changesRemaining: z.ZodNumber;
+    nextChangeAllowedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Builder-fee change actor exposed by the audit log. */
+export declare const BuilderFeeActorTypeSchema: z.ZodEnum<{
+    BUILDER: "BUILDER";
+    ADMIN: "ADMIN";
+}>;
+/** One builder-fee audit-log entry. */
+export declare const BuilderFeeChangeSchema: z.ZodObject<{
+    actorType: z.ZodEnum<{
+        BUILDER: "BUILDER";
+        ADMIN: "ADMIN";
+    }>;
+    actor: z.ZodString;
+    oldBps: z.ZodNumber;
+    newBps: z.ZodNumber;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+/** Cursor pagination accepted by the builder-fee change log. */
+export declare const ListBuilderFeeChangesParamsSchema: z.ZodObject<{
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Schema for one page of builder-fee changes, newest first. */
+export declare const ListBuilderFeeChangesResponseSchema: z.ZodObject<{
+    changes: z.ZodArray<z.ZodObject<{
+        actorType: z.ZodEnum<{
+            BUILDER: "BUILDER";
+            ADMIN: "ADMIN";
+        }>;
+        actor: z.ZodString;
+        oldBps: z.ZodNumber;
+        newBps: z.ZodNumber;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodString;
 }, z.core.$strip>;
 /**
- * The payout stream a BuilderCodes credit belongs to. `REVENUE_SHARE` is the
- * frontend's share of Monaco's fee; `BUILDER_FEE` is the frontend's own builder
- * fee, paid by the taker. Both land in the same claimable balance.
+ * The payout stream a BuilderCodes credit belongs to. `REVENUE_SHARE` records
+ * Monaco revenue share; `BUILDER_FEE` records builder fees charged to takers.
  */
 export declare const BuildercodePayoutKindSchema: z.ZodEnum<{
     REVENUE_SHARE: "REVENUE_SHARE";
@@ -127,6 +177,12 @@ export declare const ClaimBuildercodeRewardsResponseSchema: z.ZodObject<{
 export type ClaimBuildercodeRewardsParams = z.infer<typeof ClaimBuildercodeRewardsParamsSchema>;
 export type ClaimBuildercodeRewardsResponse = z.infer<typeof ClaimBuildercodeRewardsResponseSchema>;
 export type GetBuildercodesConfigResponse = z.infer<typeof GetBuildercodesConfigResponseSchema>;
+export type SetBuilderFeeParams = z.infer<typeof SetBuilderFeeParamsSchema>;
+export type SetBuilderFeeResponse = z.infer<typeof SetBuilderFeeResponseSchema>;
+export type BuilderFeeActorType = z.infer<typeof BuilderFeeActorTypeSchema>;
+export type BuilderFeeChange = z.infer<typeof BuilderFeeChangeSchema>;
+export type ListBuilderFeeChangesParams = z.infer<typeof ListBuilderFeeChangesParamsSchema>;
+export type ListBuilderFeeChangesResponse = z.infer<typeof ListBuilderFeeChangesResponseSchema>;
 export type ListBuildercodePayoutsParams = z.infer<typeof ListBuildercodePayoutsParamsSchema>;
 export type BuildercodePayoutKind = z.infer<typeof BuildercodePayoutKindSchema>;
 export type BuildercodePayout = z.infer<typeof BuildercodePayoutSchema>;

package/dist/buildercodes/responses.js

@@ -16,11 +16,46 @@ export const GetBuildercodesConfigResponseSchema = z.object({
     payoutAddress: z.string().nullable().optional(),
     buildercodesEnabled: z.boolean(),
     buildercodesBudgetBps: z.number().int().min(0).max(10_000),
+    builderFeeEnabled: z.boolean(),
+    builderFeeBps: z.number().int().min(0).max(100),
+    builderFeeCapBps: z.number().int().min(0).max(100),
+    changesRemaining: z.number().int().min(0).max(2),
+    nextChangeAllowedAt: z.string().nullable().optional(),
+});
+/** Schema for changing this frontend's builder fee. */
+export const SetBuilderFeeParamsSchema = z.object({
+    bps: z.number().int().min(0).max(100),
+});
+/** Schema returned after setting this frontend's builder fee. */
+export const SetBuilderFeeResponseSchema = z.object({
+    builderFeeBps: z.number().int().min(0).max(100),
+    previousBuilderFeeBps: z.number().int().min(0).max(100),
+    changesRemaining: z.number().int().min(0).max(2),
+    nextChangeAllowedAt: z.string().nullable().optional(),
+});
+/** Builder-fee change actor exposed by the audit log. */
+export const BuilderFeeActorTypeSchema = z.enum(["BUILDER", "ADMIN"]);
+/** One builder-fee audit-log entry. */
+export const BuilderFeeChangeSchema = z.object({
+    actorType: BuilderFeeActorTypeSchema,
+    actor: z.string(),
+    oldBps: z.number().int().min(0).max(100),
+    newBps: z.number().int().min(0).max(100),
+    createdAt: z.string(),
+});
+/** Cursor pagination accepted by the builder-fee change log. */
+export const ListBuilderFeeChangesParamsSchema = z.object({
+    pageSize: z.number().int().min(1).max(100).optional(),
+    pageToken: z.string().optional(),
+});
+/** Schema for one page of builder-fee changes, newest first. */
+export const ListBuilderFeeChangesResponseSchema = z.object({
+    changes: z.array(BuilderFeeChangeSchema),
+    nextPageToken: z.string(),
 });
 /**
- * The payout stream a BuilderCodes credit belongs to. `REVENUE_SHARE` is the
- * frontend's share of Monaco's fee; `BUILDER_FEE` is the frontend's own builder
- * fee, paid by the taker. Both land in the same claimable balance.
+ * The payout stream a BuilderCodes credit belongs to. `REVENUE_SHARE` records
+ * Monaco revenue share; `BUILDER_FEE` records builder fees charged to takers.
  */
 export const BuildercodePayoutKindSchema = z.enum(["REVENUE_SHARE", "BUILDER_FEE"]);
 /** Pagination and filter accepted by the per-trade payout history endpoint. */

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

@@ -65,8 +65,9 @@ export interface CopyTradingAPI extends BaseAPI {
     upsertFollow(params: UpsertFollowParams): Promise<UpsertFollowResponse>;
     /**
      * Stop one of your follows: the leader's fills stop being mirrored. An exit
-     * is never gated beyond ownership, except that a delegated agent session
-     * cannot stop a follow (403).
+     * is never refused for the state of the account or the platform. Only
+     * ownership applies, a delegated agent session cannot stop a follow (403),
+     * and stops have a rate limit of their own (429 past it).
      */
     stopFollow(followId: string): Promise<StopFollowResponse>;
     /**
@@ -106,11 +107,10 @@ export interface CopyTradingAPI extends BaseAPI {
      *
      * Master account sessions only (a delegated agent or a sub-account gets
      * 403); 404 for a follow that is not yours; 409 while the follow is
-     * stopping or once it is stopped, or `COPY_TRADING_UNAVAILABLE` when copy
-     * trading is not available on the platform; 400 `COPY_TRADING_REJECTED`
-     * when the engine refuses (no isolated copy position on the pair, the
-     * position or the margin account is being liquidated, the position has
-     * lost more than its margin, more than the copy account can put in); 429
+     * stopping or once it is stopped; 400 `COPY_TRADING_REJECTED` when the add
+     * is refused (no isolated copy position on the pair, the copy position is
+     * being liquidated or is in bad debt, more than the copy account can put
+     * in); 429
      * over the movement budget withdrawals and collateral transfers share.
      *
      * Not idempotent: a retry after a timeout whose first attempt landed adds

package/dist/delegated-agents/index.d.ts

@@ -1,16 +1,22 @@
 import type { Address } from "viem";
 import type { BaseAPI } from "../api";
-export type DelegatedAgentAction = "CREATE_ORDER" | "CANCEL_ORDER" | "REPLACE_ORDER" | "create_order" | "cancel_order" | "replace_order";
+export type DelegatedAgentAction = "CREATE_ORDER" | "CANCEL_ORDER" | "REPLACE_ORDER" | "READ" | "MANAGE_RISK_BUCKETS" | "create_order" | "cancel_order" | "replace_order" | "read" | "manage_risk_buckets";
 export interface UpsertDelegatedAgentRequest {
     agentAddress: string;
     name?: string;
-    /** Delegation expiry (ISO 8601); ends reads, trading, and session refresh. */
+    /** Delegation expiry (ISO 8601); ends reads, trading, and session refresh. Omit for the default of 14 days from now; at most 180 days ahead. */
     expiresAt?: string;
-    /** Required. An empty list permits no actions. */
+    /**
+     * Required. An empty list permits no order actions. Every delegated session may read the owner's
+     * data, so a list of only `READ` (or none) is a read-only key.
+     */
     allowedActions: DelegatedAgentAction[];
-    /** Required. A matching market OR account permits an order; both scopes empty deny all orders. */
+    /** Required. Each listed scope must match: a listed market AND a listed account. Both empty deny all orders. */
     allowedTradingPairIds: string[];
-    /** Additional account scope. Omit or send [] for market-only scope, not access to every account. */
+    /**
+     * The margin accounts the agent is bound to (a sub-account's own key). Omit or send [] to leave the
+     * account unrestricted.
+     */
     allowedMarginAccountIds?: string[];
     /** Omit or send [] for unrestricted order types. */
     allowedOrderTypes?: Array<"LIMIT" | "MARKET">;
@@ -20,6 +26,8 @@ export interface UpsertDelegatedAgentRequest {
     maxOrderNotional?: string;
     /** @deprecated Unsupported: setting this field causes the server to reject the request. */
     maxOpenOrders?: number;
+    /** Up to 20 IP addresses or CIDR ranges the agent may create its delegated session from. Omit for any. */
+    ipAllowlist?: string[];
 }
 export interface DelegatedAgent {
     id: string;
@@ -38,6 +46,8 @@ export interface DelegatedAgent {
     maxOrderNotional?: string;
     /** @deprecated Legacy data only; no concurrent open-order cap is enforced. */
     maxOpenOrders?: number;
+    /** Normalized IP addresses and CIDR ranges; empty allows any address. */
+    ipAllowlist?: string[];
 }
 export interface ListDelegatedAgentsResponse {
     agents: DelegatedAgent[];

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(),
+});