@0xmonaco/types 1.0.58 → 1.0.59

package/dist/auth/index.d.ts

@@ -31,10 +31,24 @@ export interface AuthAPI extends BaseAPI {
     /**
      * Signs a challenge message using the wallet client.
      *
-     * Signs the provided message using the wallet's private key.
-     * This is used in the authentication flow to prove ownership of the wallet.
+     * Asks the connected wallet to authorize the message, proving control of the
+     * address. An EOA signs it with its private key (EIP-191 `personal_sign`). A
+     * smart-contract wallet such as a Safe has no private key and returns a
+     * signature its own contract will accept, which the server checks under
+     * EIP-1271; the wallet client handles that difference, and the returned value
+     * is submitted unchanged either way.
      *
-     * @param message - The message to sign
+     * The returned signature is therefore not guaranteed to be 65 bytes — a
+     * contract signature is usually longer — so callers must not assume the
+     * EOA shape.
+     *
+     * Note the scope. Server-side EIP-1271 verification is deliberately narrow:
+     * it is offered only to a wallet holding a BuilderCodes payout bucket, on a
+     * deployment with the contract-wallet flag on and a chain RPC endpoint
+     * configured. An ordinary smart-contract trading account is not covered — it
+     * still takes the recovery path, which it cannot satisfy.
+     *
+     * @param message - The message to authorize
      * @returns Promise resolving to the signature
      */
     signChallenge(message: string): Promise<string>;

package/dist/buildercodes/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * BuilderCodes Types
+ *
+ * Types for the BuilderCodes API: reading and claiming an enrolled frontend's
+ * per-trade revenue share.
+ */
+import type { BaseAPI } from "../api";
+import type { ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse } from "./responses";
+/**
+ * BuilderCodes payout API interface.
+ *
+ * BuilderCodes is Monaco's per-trade frontend revenue share: an enrolled
+ * frontend earns a configured share of the net take on every fill its users
+ * generate, accruing to a reserved payout bucket owned by the frontend's
+ * configured payout wallet. Accrual is internal accounting only — this API is
+ * how that balance is claimed into a tradeable (and then withdrawable) balance.
+ */
+export interface BuildercodesAPI extends BaseAPI {
+    /** Read this authenticated frontend's enrollment, payout address, and live budget. */
+    getConfig(): Promise<GetBuildercodesConfigResponse>;
+    /** List this authenticated frontend's per-trade BuilderCodes credits. */
+    listPayouts(params?: ListBuildercodePayoutsParams): Promise<ListBuildercodePayoutsResponse>;
+    /** Summarize this authenticated frontend's BuilderCodes credits by token. */
+    getPayoutSummary(): Promise<GetBuildercodePayoutSummaryResponse>;
+    /** Read the authenticated wallet's available reserved reward balances. */
+    getRewardsBalance(): Promise<GetBuildercodeRewardsBalanceResponse>;
+    /**
+     * Claim accrued BuilderCodes payout balance into a trading balance.
+     *
+     * Moves the specified amount of a payout token out of the authenticated
+     * caller's reserved payout bucket and into their trading balance under the
+     * authenticated application, from where the ordinary withdrawal flow applies.
+     * Ledger-only — no on-chain transaction and no gas, and the funds are
+     * immediately tradeable.
+     *
+     * The payout wallet may be an EOA or a smart-contract wallet. An EOA answers
+     * the signature challenge directly; a multisig such as a Safe authenticates by
+     * EIP-1271 contract signature instead. That path is offered only to a wallet
+     * holding a BuilderCodes payout bucket, only while `contract_wallet_auth_enabled`
+     * is on, and only where the deployment has a chain RPC endpoint configured —
+     * otherwise login is EOA-only and a contract payout wallet can neither call
+     * this endpoint nor withdraw afterwards.
+     *
+     * The bucket is resolved from the authenticated caller's own wallet address,
+     * so a caller can only ever claim their own accrued balance. A wallet that
+     * has never been an enrolled frontend's payout address has nothing to claim.
+     * A wallet that *used to be* a payout address keeps what it accrued back then
+     * and can still claim it — payout-address changes are not retroactive.
+     *
+     * Throws 403 when the caller is refused: BuilderCodes is not enabled, or
+     * the session is a delegated agent — which is rejected before the feature is
+     * checked, so it is a permanent restriction on that session type, not a
+     * rollout state. Throws 409 when the payout balance is insufficient for the
+     * requested amount. Throws 503 when the matching engine is unreachable,
+     * restarting, or slow to answer — an UNKNOWN outcome, not a rejection: the
+     * claim is admitted to the sequencer before its reply is sent, so it may
+     * still commit, and with no idempotency key a blind retry can claim twice.
+     * Do not retry automatically: a balance read cannot settle it, because an
+     * admitted claim may still be queued. Ambiguous failures are thrown
+     * with `retryable: false` so retry logic driven off that flag cannot claim
+     * twice. Two pre-admission rejections stay retryable because they committed
+     * nothing: a maintenance block (`OPERATIONS_BLOCKED`) and a sequencer
+     * overload (`OVERLOADED`).
+     *
+     * @param params - Payout token address and raw-unit amount to claim
+     * @returns Promise resolving to the post-claim payout and trading balances
+     */
+    claimBuildercodeRewards(params: ClaimBuildercodeRewardsParams): Promise<ClaimBuildercodeRewardsResponse>;
+}
+export type { BuildercodePayout, BuildercodePayoutTokenTotal, BuildercodeRewardsBalance, ClaimBuildercodeRewardsParams, ClaimBuildercodeRewardsResponse, GetBuildercodePayoutSummaryResponse, GetBuildercodeRewardsBalanceResponse, GetBuildercodesConfigResponse, ListBuildercodePayoutsParams, ListBuildercodePayoutsResponse, } from "./responses";
+export { BuildercodePayoutSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, } from "./responses";

package/dist/buildercodes/index.js

@@ -0,0 +1,7 @@
+/**
+ * BuilderCodes Types
+ *
+ * Types for the BuilderCodes API: reading and claiming an enrolled frontend's
+ * per-trade revenue share.
+ */
+export { BuildercodePayoutSchema, BuildercodePayoutTokenTotalSchema, BuildercodeRewardsBalanceSchema, ClaimBuildercodeRewardsParamsSchema, ClaimBuildercodeRewardsResponseSchema, GetBuildercodePayoutSummaryResponseSchema, GetBuildercodeRewardsBalanceResponseSchema, GetBuildercodesConfigResponseSchema, ListBuildercodePayoutsParamsSchema, ListBuildercodePayoutsResponseSchema, } from "./responses";

package/dist/buildercodes/responses.d.ts

@@ -0,0 +1,94 @@
+/**
+ * BuilderCodes Response Types
+ *
+ * Types for the BuilderCodes earnings and payout API responses and requests.
+ * All types are derived from Zod schemas for runtime validation.
+ */
+import { z } from "zod";
+/** Schema for this frontend's current BuilderCodes program state. */
+export declare const GetBuildercodesConfigResponseSchema: z.ZodObject<{
+    applicationId: z.ZodString;
+    enrolled: z.ZodBoolean;
+    payoutAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    buildercodesEnabled: z.ZodBoolean;
+    buildercodesBudgetBps: z.ZodNumber;
+}, z.core.$strip>;
+/** Pagination accepted by the per-trade payout history endpoint. */
+export declare const ListBuildercodePayoutsParamsSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** One per-trade BuilderCodes credit. Amounts are RAW atomic units. */
+export declare const BuildercodePayoutSchema: z.ZodObject<{
+    tradeId: z.ZodString;
+    payoutAddress: z.ZodString;
+    token: z.ZodString;
+    amount: z.ZodString;
+    appliedBps: z.ZodNumber;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+/** Schema for the paginated per-trade payout history. */
+export declare const ListBuildercodePayoutsResponseSchema: z.ZodObject<{
+    payouts: z.ZodArray<z.ZodObject<{
+        tradeId: z.ZodString;
+        payoutAddress: z.ZodString;
+        token: z.ZodString;
+        amount: z.ZodString;
+        appliedBps: z.ZodNumber;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}, z.core.$strip>;
+/** One token-denominated BuilderCodes earnings total. */
+export declare const BuildercodePayoutTokenTotalSchema: z.ZodObject<{
+    token: z.ZodString;
+    totalAmount: z.ZodString;
+    payoutCount: z.ZodNumber;
+    lastCreditedAt: z.ZodString;
+}, z.core.$strip>;
+/** Schema for this frontend's payout summary. */
+export declare const GetBuildercodePayoutSummaryResponseSchema: z.ZodObject<{
+    totalPayouts: z.ZodNumber;
+    lastCreditedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    byToken: z.ZodArray<z.ZodObject<{
+        token: z.ZodString;
+        totalAmount: z.ZodString;
+        payoutCount: z.ZodNumber;
+        lastCreditedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** One available balance in the reserved BuilderCodes reward bucket. */
+export declare const BuildercodeRewardsBalanceSchema: z.ZodObject<{
+    token: z.ZodString;
+    available: z.ZodString;
+}, z.core.$strip>;
+/** Schema for the caller wallet's reserved BuilderCodes balances. */
+export declare const GetBuildercodeRewardsBalanceResponseSchema: z.ZodObject<{
+    balances: z.ZodArray<z.ZodObject<{
+        token: z.ZodString;
+        available: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Schema for the claim-BuilderCodes-rewards request body. */
+export declare const ClaimBuildercodeRewardsParamsSchema: z.ZodObject<{
+    token: z.ZodString;
+    amount: z.ZodString;
+}, z.core.$strip>;
+/** Schema for the claim-BuilderCodes-rewards response. */
+export declare const ClaimBuildercodeRewardsResponseSchema: z.ZodObject<{
+    payoutBalance: z.ZodString;
+    tradingBalance: z.ZodString;
+}, z.core.$strip>;
+export type ClaimBuildercodeRewardsParams = z.infer<typeof ClaimBuildercodeRewardsParamsSchema>;
+export type ClaimBuildercodeRewardsResponse = z.infer<typeof ClaimBuildercodeRewardsResponseSchema>;
+export type GetBuildercodesConfigResponse = z.infer<typeof GetBuildercodesConfigResponseSchema>;
+export type ListBuildercodePayoutsParams = z.infer<typeof ListBuildercodePayoutsParamsSchema>;
+export type BuildercodePayout = z.infer<typeof BuildercodePayoutSchema>;
+export type ListBuildercodePayoutsResponse = z.infer<typeof ListBuildercodePayoutsResponseSchema>;
+export type BuildercodePayoutTokenTotal = z.infer<typeof BuildercodePayoutTokenTotalSchema>;
+export type GetBuildercodePayoutSummaryResponse = z.infer<typeof GetBuildercodePayoutSummaryResponseSchema>;
+export type BuildercodeRewardsBalance = z.infer<typeof BuildercodeRewardsBalanceSchema>;
+export type GetBuildercodeRewardsBalanceResponse = z.infer<typeof GetBuildercodeRewardsBalanceResponseSchema>;

package/dist/buildercodes/responses.js

@@ -0,0 +1,92 @@
+/**
+ * BuilderCodes Response Types
+ *
+ * Types for the BuilderCodes earnings and payout API responses and requests.
+ * All types are derived from Zod schemas for runtime validation.
+ */
+import { z } from "zod";
+/** Schema for this frontend's current BuilderCodes program state. */
+export const GetBuildercodesConfigResponseSchema = z.object({
+    applicationId: z.string().uuid(),
+    enrolled: z.boolean(),
+    // Nullable, not merely absent: `payout_address` is an `optional` proto field
+    // with no skip-serializing, so the server sends an explicit `null` when no
+    // address is configured. `.optional()` alone accepts `undefined` and would
+    // throw on that valid response. Matches `lastCreditedAt` below.
+    payoutAddress: z.string().nullable().optional(),
+    buildercodesEnabled: z.boolean(),
+    buildercodesBudgetBps: z.number().int().min(0).max(10_000),
+});
+/** Pagination accepted by the per-trade payout history endpoint. */
+export const ListBuildercodePayoutsParamsSchema = z.object({
+    page: z.number().int().min(1).max(10_000).optional(),
+    pageSize: z.number().int().min(1).max(100).optional(),
+});
+/** One per-trade BuilderCodes credit. Amounts are RAW atomic units. */
+export const BuildercodePayoutSchema = z.object({
+    tradeId: z.string().uuid(),
+    payoutAddress: z.string(),
+    token: z.string(),
+    amount: z.string(),
+    appliedBps: z.number().int(),
+    createdAt: z.string(),
+});
+/** Schema for the paginated per-trade payout history. */
+export const ListBuildercodePayoutsResponseSchema = z.object({
+    payouts: z.array(BuildercodePayoutSchema),
+    total: z.number().int().nonnegative(),
+    page: z.number().int().positive(),
+    pageSize: z.number().int().positive(),
+    totalPages: z.number().int().nonnegative(),
+});
+/** One token-denominated BuilderCodes earnings total. */
+export const BuildercodePayoutTokenTotalSchema = z.object({
+    token: z.string(),
+    totalAmount: z.string(),
+    payoutCount: z.number().int().nonnegative(),
+    lastCreditedAt: z.string(),
+});
+/** Schema for this frontend's payout summary. */
+export const GetBuildercodePayoutSummaryResponseSchema = z.object({
+    totalPayouts: z.number().int().nonnegative(),
+    lastCreditedAt: z.string().nullable().optional(),
+    byToken: z.array(BuildercodePayoutTokenTotalSchema),
+});
+/** One available balance in the reserved BuilderCodes reward bucket. */
+export const BuildercodeRewardsBalanceSchema = z.object({
+    token: z.string(),
+    available: z.string(),
+});
+/** Schema for the caller wallet's reserved BuilderCodes balances. */
+export const GetBuildercodeRewardsBalanceResponseSchema = z.object({
+    balances: z.array(BuildercodeRewardsBalanceSchema),
+});
+/** Schema for the claim-BuilderCodes-rewards request body. */
+export const ClaimBuildercodeRewardsParamsSchema = z.object({
+    /**
+     * Payout token contract address (0x-prefixed) to claim. BuilderCodes shares
+     * accrue in the quote token of the traded pair.
+     */
+    token: z
+        .string()
+        .trim()
+        .min(1, "token is required")
+        .regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x-prefixed EVM address"),
+    /**
+     * Amount to claim, in RAW atomic units of the token. Must be a positive
+     * integer string and no greater than the accrued payout balance — the server
+     * rejects an over-claim with 409 rather than moving a partial amount.
+     */
+    amount: z
+        .string()
+        .trim()
+        .min(1, "amount is required")
+        .refine((v) => /^\d+$/.test(v) && BigInt(v) > 0n, "amount must be a positive integer string"),
+});
+/** Schema for the claim-BuilderCodes-rewards response. */
+export const ClaimBuildercodeRewardsResponseSchema = z.object({
+    /** Your BuilderCodes payout-bucket balance after the claim, RAW atomic units. */
+    payoutBalance: z.string(),
+    /** Your trading balance for the token after the claim, RAW atomic units. */
+    tradingBalance: z.string(),
+});

package/dist/index.d.ts

@@ -7,6 +7,7 @@
 export * from "./api";
 export * from "./applications";
 export * from "./auth";
+export * from "./buildercodes";
 export * from "./contracts";
 export * from "./delegated-agents";
 export * from "./faucet";

package/dist/index.js

@@ -8,6 +8,7 @@
 export * from "./api";
 export * from "./applications";
 export * from "./auth";
+export * from "./buildercodes";
 export * from "./contracts";
 export * from "./delegated-agents";
 export * from "./faucet";

package/dist/positions/index.d.ts

@@ -107,6 +107,38 @@ export interface Position {
      * an understated partial.
      */
     cumFees?: string;
+    /**
+     * Opaque, non-negative producer-owned row version for this position
+     * (0XM-2673). Compare only within the same `positionId`; higher is newer.
+     *
+     * The same number the WebSocket `positions` snapshot and a RANKED live
+     * `position_update` frame carry, so this read can be ranked against them.
+     * Some live frames are deliberately unranked and omit `version` even when
+     * their state matches this row.
+     * `0` is the unranked legacy sentinel and never participates in ordering:
+     * treat it exactly as an absent version and fall back to a full field
+     * comparison rather than ranking it as oldest.
+     *
+     * The merge rule is PER FIELD GROUP, never per payload. On an EQUAL version
+     * skip the versioned fields as an idempotent redelivery — EXCEPT
+     * `isolatedMargin`, which the WebSocket positions snapshot overlays from an
+     * independent live matching-engine read rather than from the versioned row,
+     * so it can reflect a later command than the version names and must be
+     * taken from the newer payload. Also still take
+     * `markPrice`, `unrealizedPnl`, `liquidationPrice`, `leverage`,
+     * `maintenanceMarginRequired` and `initialMarginRequired` from the newer
+     * payload: those six are re-derived on every read rather than served from
+     * the versioned row, carry no version, and the version does not advance for
+     * them. Five move with the oracle mark; `leverage` does not, but the live
+     * surfaces derive it while the persisted row serves its stored column, so it
+     * can still disagree at an unchanged version.
+     * Discarding a whole payload on an equal version freezes displayed PnL
+     * until the position's next real mutation.
+     *
+     * A response served from live matching-engine state reports `0`: the engine
+     * holds the state but not the version, so it cannot rank itself.
+     */
+    version?: number;
 }
 export interface ListPositionsParams {
     marginAccountId?: string;

package/dist/sdk/index.d.ts

@@ -1,6 +1,7 @@
 import type { Address, PublicClient, TransactionReceipt, WalletClient } from "viem";
 import type { ApplicationsAPI } from "../applications";
 import type { AuthAPI, AuthState } from "../auth/index";
+import type { BuildercodesAPI } from "../buildercodes";
 import type { DelegatedAgentsAPI } from "../delegated-agents";
 import type { FaucetAPI } from "../faucet";
 import type { FeesAPI } from "../fees";
@@ -111,6 +112,8 @@ export interface MonacoSDK {
     subAccounts: SubAccountsAPI;
     /** PitPass TraderCode referral and rewards API */
     pitpass: PitpassAPI;
+    /** BuilderCodes frontend revenue-share payout API */
+    buildercodes: BuildercodesAPI;
     /** Testnet faucet API */
     faucet: FaucetAPI;
     /** Deposit-address registration (sweeper) API; requires a session */

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

@@ -8,6 +8,7 @@
  * Detected broadcast lag closes the connection with 1013 and requires resync.
  * A lost terminal position update need not have a later replacement.
  */
+import type { MarginMode } from "../../margin-accounts";
 /**
  * Position side. The server emits `LONG` or `SHORT` for an open position.
  */
@@ -55,6 +56,50 @@ export interface PositionEventData {
     isolatedMargin: string;
     /** Effective leverage (decimal string) */
     leverage: string;
+    /**
+     * Risk bucket that scopes this position's margin (UUID) — the same
+     * `riskBucketId` REST returns (0XM-2668). Omitted only for a legacy
+     * unbucketed position, and on a terminal frame whose close came back through
+     * the durable log rather than in-band.
+     */
+    riskBucketId?: string;
+    /**
+     * Margin mode of `riskBucketId`: `CROSS` or `ISOLATED`, the same `marginMode`
+     * REST returns (0XM-2668). Omitted for a position with no risk bucket, since
+     * there is then no mode to report.
+     *
+     * Do NOT infer it from `riskBucketId` in either direction. The two are
+     * resolved from different sources — the bucket id from the position, the mode
+     * from the risk engine when it holds the position and from the bucket row
+     * otherwise — so an id can arrive with no mode: a terminal row whose bucket
+     * record is unavailable, a read taken while the engine is unreachable, or a
+     * producer older than this field. Treat a missing mode as unknown and leave
+     * the position's mode unchanged; defaulting it to `CROSS` mis-renders an
+     * isolated position's backing.
+     *
+     * VERSIONED: a position's mode changes only on a real mutation, never on an
+     * oracle tick. See `version`.
+     */
+    marginMode?: MarginMode | (string & {});
+    /**
+     * Maintenance margin this position requires at `markPrice` (decimal string),
+     * the same `maintenanceMarginRequired` REST returns (0XM-2668). `"0"` when
+     * the position has no open exposure, so a terminal frame reports zero rather
+     * than omitting it.
+     *
+     * UNVERSIONED: re-derived from the oracle mark on every frame. See `version`
+     * for the whole unversioned group.
+     */
+    maintenanceMarginRequired?: string;
+    /**
+     * Initial margin this position requires at `markPrice` (decimal string),
+     * honoring both its effective leverage and the market initial-margin floor —
+     * the same `initialMarginRequired` REST returns (0XM-2668). `"0"` when the
+     * position has no open exposure.
+     *
+     * UNVERSIONED, for the same reason as `maintenanceMarginRequired`.
+     */
+    initialMarginRequired?: string;
     /** Trade that caused the update, when driven by a fill (UUID). Omitted otherwise. */
     tradeId?: string;
     /** Order that caused the update, when driven by an order (UUID). Omitted otherwise. */
@@ -65,8 +110,77 @@ export interface PositionEventData {
      * `margin_reduced`, `margin_collateral_transfer`.
      */
     reason: string;
-    /** Timestamp when the position state was updated (ISO 8601) */
+    /**
+     * When the position was last MUTATED (ISO 8601) — a fill, collateral
+     * transfer, funding settlement or close.
+     *
+     * Read from the producer's own record of the mutation, never stamped while
+     * the frame is serialized (0XM-2668), so two frames for a position nothing
+     * has changed repeat one timestamp and a valuation-only oracle reprice does
+     * not move it. Do not use it as a reconciliation key — that is `version`'s
+     * job; this is display metadata.
+     *
+     * It matches a REST read of the same OPEN position exactly. Two cases come
+     * from the server's persistence clock instead and differ by the persistence
+     * lag: a TERMINAL row (this frame carries the engine's close instant, a
+     * terminal REST read carries the stored one), and any position read after a
+     * matching-engine restart. Accurate to that lag, not to the microsecond.
+     *
+     * A third case is not lag-bounded: while the server's matching engine is
+     * unreachable, a REST read of an OPEN position falls back to that row's
+     * lifecycle timestamps and can report the position's opening instant until
+     * funding settles. This frame is unaffected — it is built from engine state
+     * — so a REST value OLDER than a frame you already hold is expected during
+     * that window, and the frame is the fresher one.
+     */
     updatedAt: string;
+    /**
+     * Opaque, non-negative producer-owned row version for this position
+     * (0XM-2673). Compare only within the same `positionId`; higher is newer.
+     *
+     * Carried on RANKED live frames and on the subscribe-time `positions`
+     * snapshot, so a client can rank the two against each other on
+     * `positionId + version`. Not every live frame is ranked — see below — so
+     * an unranked frame is not comparable with a snapshot row even when their
+     * state matches.
+     * Absent means UNRANKED, never "oldest", and it does NOT tell you whether
+     * anything was persisted. Four cases reach it: the frame came from a
+     * producer that predates this field; the emit path wrote no row;
+     * the path DID write the row but re-reads live risk state after sequencing
+     * (funding, `margin_added`/`margin_reduced`), so the mutation did advance
+     * the persisted version; or the frame is a different projection of the row
+     * than persistence stores (terminal frames report `size` 0 and
+     * `LIQUIDATED`, while the stored row keeps its size and records `CLOSED`).
+     * In the last two, a REST read or a fresh snapshot ranks the mutation.
+     * Fall back to a full field comparison rather than ranking it lowest.
+     *
+     * The merge rule is PER FIELD GROUP, never per frame. On a higher version
+     * apply everything. On an EQUAL version skip the versioned fields as an
+     * idempotent redelivery — EXCEPT `isolatedMargin`, which the subscribe-time
+     * snapshot overlays from an independent live matching-engine read rather
+     * than from the versioned row, so it can reflect a later command than the
+     * version names and must be taken from the newer payload or you retain
+     * stale backing. Also still take `markPrice`, `unrealizedPnl`,
+     * `liquidationPrice`, `leverage`, `maintenanceMarginRequired` and
+     * `initialMarginRequired` from the newer frame: those six are re-derived
+     * per frame rather than served from the versioned row, carry no version,
+     * and the version does not advance for them. Five move with the oracle
+     * mark; `leverage` does not — it is opening notional over posted margin —
+     * but the live surfaces derive it while a persisted read serves the row's
+     * stored column, so it can still disagree at an unchanged version. Discarding an equal-version frame wholesale
+     * freezes displayed unrealized PnL until the position's next real
+     * mutation — up to the one-hour funding interval.
+     *
+     * A frame is ranked only when it is a faithful projection of the row
+     * persisted at that sequence: in practice the FILLS THAT LEAVE A POSITION
+     * OPEN. Unranked are (a) frames that re-read live risk state after their
+     * command was sequenced, since a later command can overtake that read —
+     * the `funding` and `margin_added`/`margin_reduced` frames — and (b)
+     * TERMINAL frames, which report `size` 0 and `LIQUIDATED` while the stored
+     * row keeps its size and records `CLOSED`. Those mutations still advance
+     * the persisted version, so REST and a fresh snapshot rank them.
+     */
+    version?: number;
 }
 /**
  * Position event emitted when a user's position state changes.

package/dist/wire/operations.d.ts

@@ -10,6 +10,6 @@
  * hand-written SDK surface. CI regenerates it and fails on a diff, identical to
  * the `schema.ts` wire-types tripwire (MON-1476), so it can never go stale.
  */
-export declare const OPERATION_IDS: readonly ["attach_position_tp_sl", "batch_cancel_all", "batch_cancel_all_by_pair", "batch_cancel_orders", "batch_close_all_positions", "batch_create_orders", "batch_replace_orders", "cancel_conditional_order", "cancel_order", "cancel_twap_order", "check_trader_code_availability", "clear_trader_code", "close_position", "create_challenge", "create_delegated_session", "create_order", "create_sub_account_limit", "create_twap_order", "delete_sub_account_limit", "get_application_config", "get_application_stats", "get_available_collateral", "get_candles", "get_conditional_order", "get_faucet_info", "get_funding_state", "get_index_price", "get_margin_account_movements", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_trader_code", "get_open_interest", "get_order_by_id", "get_orderbook_snapshot", "get_orders", "get_parent_margin_account_movements", "get_parent_margin_account_summary", "get_perp_market_config", "get_perp_market_summary", "get_portfolio_assets", "get_portfolio_chart", "get_portfolio_margin", "get_portfolio_performance", "get_portfolio_realized_pnl", "get_portfolio_stats", "get_portfolio_summary", "get_position", "get_position_pnl_history", "get_position_risk", "get_pulse", "get_rewards_balance", "get_screener", "get_self_trade_prevention_default", "get_sub_account_limits", "get_sweeper_chains", "get_trade_by_id", "get_trader_code_info", "get_trades", "get_trading_pair_by_id", "get_twap_order", "get_twap_order_tca", "get_user_balance_by_asset", "get_user_balances", "get_user_movements", "get_user_profile", "get_user_trades", "get_withdrawal", "health_check", "initiate_withdrawal", "list_all_funding_history", "list_application_balances", "list_application_movements", "list_application_orders", "list_application_users", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_funding_history", "list_funding_payments", "list_margin_accounts", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "submit_whitelist", "transfer_collateral_from_margin_account", "transfer_collateral_from_parent_margin_account", "transfer_collateral_to_margin_account", "transfer_collateral_to_parent_margin_account", "transfer_collateral_to_risk_bucket", "transfer_rewards", "update_sub_account_limit", "upsert_delegated_agent", "verify_signature"];
+export declare const OPERATION_IDS: readonly ["attach_position_tp_sl", "batch_cancel_all", "batch_cancel_all_by_pair", "batch_cancel_orders", "batch_close_all_positions", "batch_create_orders", "batch_replace_orders", "cancel_conditional_order", "cancel_order", "cancel_twap_order", "check_trader_code_availability", "claim_buildercode_rewards", "clear_trader_code", "close_position", "create_challenge", "create_delegated_session", "create_order", "create_sub_account_limit", "create_twap_order", "delete_sub_account_limit", "get_application_config", "get_application_stats", "get_available_collateral", "get_buildercode_payout_summary", "get_buildercode_rewards_balance", "get_buildercodes_config", "get_candles", "get_conditional_order", "get_faucet_info", "get_funding_state", "get_index_price", "get_margin_account_movements", "get_margin_account_summary", "get_mark_price", "get_market_metadata", "get_market_stats", "get_my_fee_tier", "get_my_trader_code", "get_open_interest", "get_order_by_id", "get_orderbook_snapshot", "get_orders", "get_parent_margin_account_movements", "get_parent_margin_account_summary", "get_perp_market_config", "get_perp_market_summary", "get_portfolio_assets", "get_portfolio_chart", "get_portfolio_margin", "get_portfolio_performance", "get_portfolio_realized_pnl", "get_portfolio_stats", "get_portfolio_summary", "get_position", "get_position_pnl_history", "get_position_risk", "get_pulse", "get_rewards_balance", "get_screener", "get_self_trade_prevention_default", "get_sub_account_limits", "get_sweeper_chains", "get_trade_by_id", "get_trader_code_info", "get_trades", "get_trading_pair_by_id", "get_twap_order", "get_twap_order_tca", "get_user_balance_by_asset", "get_user_balances", "get_user_movements", "get_user_profile", "get_user_trades", "get_withdrawal", "health_check", "initiate_withdrawal", "list_all_funding_history", "list_application_balances", "list_application_movements", "list_application_orders", "list_application_users", "list_buildercode_payouts", "list_conditional_orders", "list_delegated_agent_owners", "list_delegated_agents", "list_funding_history", "list_funding_payments", "list_margin_accounts", "list_pending_withdrawals", "list_position_history", "list_positions", "list_sub_accounts_with_balances", "list_trading_pairs", "list_twap_orders", "mint_tokens", "refresh_session", "register_deposit_address", "replace_order", "revoke_delegated_agent", "revoke_session", "set_self_trade_prevention_default", "set_trader_code", "simulate_fees", "simulate_order_risk", "simulate_parent_margin_order_risk", "simulate_risk_bucket_order_risk", "submit_whitelist", "transfer_collateral_from_margin_account", "transfer_collateral_from_parent_margin_account", "transfer_collateral_to_margin_account", "transfer_collateral_to_parent_margin_account", "transfer_collateral_to_risk_bucket", "transfer_rewards", "update_sub_account_limit", "upsert_delegated_agent", "verify_signature"];
 /** Union of every OpenAPI operationId in the spec. */
 export type OperationId = (typeof OPERATION_IDS)[number];

package/dist/wire/operations.js

@@ -22,6 +22,7 @@ export const OPERATION_IDS = [
     "cancel_order",
     "cancel_twap_order",
     "check_trader_code_availability",
+    "claim_buildercode_rewards",
     "clear_trader_code",
     "close_position",
     "create_challenge",
@@ -33,6 +34,9 @@ export const OPERATION_IDS = [
     "get_application_config",
     "get_application_stats",
     "get_available_collateral",
+    "get_buildercode_payout_summary",
+    "get_buildercode_rewards_balance",
+    "get_buildercodes_config",
     "get_candles",
     "get_conditional_order",
     "get_faucet_info",
@@ -88,6 +92,7 @@ export const OPERATION_IDS = [
     "list_application_movements",
     "list_application_orders",
     "list_application_users",
+    "list_buildercode_payouts",
     "list_conditional_orders",
     "list_delegated_agent_owners",
     "list_delegated_agents",