@agg-build/sdk 1.0.0 → 1.0.1

package/README.md

@@ -345,7 +345,7 @@ None. `@agg-build/sdk` is dependency-light and bundles its own clients for `viem
 ## Links
 
 - Documentation — <https://docs.agg.market/>
-- Demo app — <https://demo.agg.market/>
+- Demo app — <https://agg.market/>
 - React hooks — [`@agg-build/hooks`](https://www.npmjs.com/package/@agg-build/hooks)
 - Trading UI — [`@agg-build/ui`](https://www.npmjs.com/package/@agg-build/ui)
 - Connect / sign-in UX — [`@agg-build/auth`](https://www.npmjs.com/package/@agg-build/auth)

package/dist/index.d.mts

@@ -789,12 +789,35 @@ type ValidateManagedRequest = {
     side: "buy" | "sell";
     amount: number;
 };
+type WithdrawTokenSymbol$1 = "USDC" | "USDC.e" | "USDT";
 type WithdrawManagedRequest = {
+    /** Positive integer string in the token's native decimals (e.g. "100000" = 0.1 USDC). */
     amountRaw: string;
-    tokenSymbol: string;
+    tokenSymbol: WithdrawTokenSymbol$1;
+    /** EVM 0x-prefixed 20-byte recipient address. */
     destinationAddress: string;
-    destinationChainId?: number | undefined;
+    /** EVM chain ID where the recipient should receive funds. Required since v2026.04. */
+    destinationChainId: number;
+};
+type WithdrawalSourceStatus$1 = "pending" | "submitted" | "confirmed" | "failed";
+type WithdrawalSourceItem = {
+    sourceId: string;
+    chainId: number;
+    tokenSymbol: WithdrawTokenSymbol$1;
+    /** On-chain token address on `chainId`. */
+    tokenAddress: string;
+    /**
+     * On-chain decimals for `(chainId, tokenAddress)`. Critical for clients
+     * because `amountRaw` is in source-native decimals (BNB USDC is 18-dec,
+     * EVM USDC is 6-dec).
+     */
+    decimals: number;
+    amountRaw: string;
+    status: WithdrawalSourceStatus$1;
+    txHash: string | null;
+    bridgeOperationId: string | null;
 };
+/** @deprecated Use `WithdrawalSourceItem` from the lifecycle response. */
 type WithdrawalSource = {
     amountRaw: string;
     chainId: number;
@@ -1201,7 +1224,40 @@ interface WsRedeemEvent {
     /** @unit seconds (converted from server ms) */
     timestamp: number;
 }
-type WsServerMessage = WsOrderbookSnapshot | WsOrderbookDelta | WsTrade | WsSubscribed | WsUnsubscribed | WsConnected | WsAuthenticated | WsHeartbeat | WsMarketResolved | WsError | WsOrderSubmitted | WsBalanceUpdate | WsOrderEvent | WsRedeemEvent;
+/** Top-level withdrawal lifecycle states surfaced to partner clients. */
+type WsWithdrawalLifecycleStatus = "pending" | "bridging" | "transferring" | "completed" | "partial" | "failed";
+type WsWithdrawalLegStatus = "planned" | "submitted" | "confirmed" | "failed";
+interface WsWithdrawalLifecycleLeg {
+    sourceChainId: number;
+    destChainId: number;
+    type: "transfer" | "bridge";
+    status: WsWithdrawalLegStatus;
+    amountRaw: string;
+    txHash: string | null;
+    bridgeOperationId: string | null;
+}
+/**
+ * Per-withdrawal lifecycle event. Wire shape is intentionally additive:
+ * consumers should pass through unknown enum values rather than failing.
+ */
+interface WsWithdrawalLifecycleEvent {
+    type: "withdrawal_lifecycle";
+    withdrawalId: string;
+    userId: string;
+    status: WsWithdrawalLifecycleStatus;
+    /** True when `status` is terminal (`completed` / `partial` / `failed`). */
+    terminal: boolean;
+    /** Optional leg delta — present when this event was triggered by a leg flip. */
+    leg?: WsWithdrawalLifecycleLeg;
+    /** All legs at the moment of emission (snapshot). */
+    legs?: WsWithdrawalLifecycleLeg[];
+    /** Failure reason for terminal `failed` / `partial`. */
+    errorMessage?: string;
+    correlationId?: string;
+    /** @unit milliseconds (raw from server — NOT converted like other WS types) */
+    timestamp: number;
+}
+type WsServerMessage = WsOrderbookSnapshot | WsOrderbookDelta | WsTrade | WsSubscribed | WsUnsubscribed | WsConnected | WsAuthenticated | WsHeartbeat | WsMarketResolved | WsError | WsOrderSubmitted | WsBalanceUpdate | WsOrderEvent | WsRedeemEvent | WsWithdrawalLifecycleEvent;
 type WsClientMessage = {
     action: "subscribe";
     channel: "orderbook" | "trades";
@@ -1320,6 +1376,7 @@ interface AggWebSocketCallbacks {
     onBalanceUpdate?: (msg: WsBalanceUpdate) => void;
     onOrderEvent?: (msg: WsOrderEvent) => void;
     onRedeemEvent?: (msg: WsRedeemEvent) => void;
+    onWithdrawalLifecycle?: (msg: WsWithdrawalLifecycleEvent) => void;
     onDiagnostics?: DiagnosticCallback;
     onConnectionStateChange?: (connected: boolean) => void;
 }
@@ -1877,19 +1934,76 @@ interface ValidateManagedResponse {
     bridgeSourceChainId?: number;
     bridgeAmountRaw?: string;
 }
+type WithdrawTokenSymbol = "USDC" | "USDC.e" | "USDT";
 interface WithdrawManagedParams {
+    /** Positive integer string in the token's native decimals (e.g. "100000" = 0.1 USDC). */
     amountRaw: string;
-    tokenSymbol: string;
+    tokenSymbol: WithdrawTokenSymbol;
+    /** EVM 0x-prefixed 20-byte recipient address. */
     destinationAddress: string;
-    destinationChainId?: number;
+    /** EVM chain ID where the recipient should receive funds. Required as of v2026.04. */
+    destinationChainId: number;
+}
+type WithdrawalLifecycleStatus = "pending" | "bridging" | "transferring" | "completed" | "partial" | "failed";
+type WithdrawalSourceStatus = "pending" | "submitted" | "confirmed" | "failed";
+type WithdrawalLegType = "transfer" | "bridge";
+type WithdrawalLegStatus = "planned" | "submitted" | "confirmed" | "failed";
+interface WithdrawalLeg {
+    type: WithdrawalLegType;
+    status: WithdrawalLegStatus;
+    sourceChainId: number;
+    destChainId: number;
+    amountRaw: string;
+    txHash: string | null;
+    bridgeOperationId: string | null;
 }
 interface WithdrawManagedSourceItem {
+    sourceId: string;
     chainId: number;
+    tokenSymbol: WithdrawTokenSymbol;
+    /** On-chain token address on `chainId`. */
+    tokenAddress: string;
+    /**
+     * On-chain decimals for `(chainId, tokenAddress)`. Required to interpret
+     * `amountRaw`: BNB USDC is 18-dec, EVM USDC is 6-dec.
+     */
+    decimals: number;
     amountRaw: string;
-    txHash?: string;
-    bridgeOperationId?: string;
+    status: WithdrawalSourceStatus;
+    txHash: string | null;
+    bridgeOperationId: string | null;
+}
+/**
+ * `pricingStatus === "unquoted"` until the multi-stable quote layer ships;
+ * `expected.*` is `null` in that mode. Do NOT treat null fields as missing.
+ */
+interface WithdrawalExpected {
+    outputRaw: string | null;
+    feeRaw: string | null;
+    etaSeconds: number | null;
 }
 interface WithdrawManagedResponse {
+    withdrawalId: string;
+    status: WithdrawalLifecycleStatus;
+    requested: {
+        tokenSymbol: WithdrawTokenSymbol;
+        amountRaw: string;
+    };
+    destination: {
+        chainId: number;
+        address: string;
+        tokenSymbol: WithdrawTokenSymbol;
+    };
+    legs: WithdrawalLeg[];
+    expected: WithdrawalExpected;
+    pricingStatus: "unquoted" | "quoted";
+    /**
+     * Persisted terminal-state error reason. Always `null` until the
+     * withdrawal reaches `failed` / `partial`. The submit response always
+     * returns `null`; populated values arrive via the GET status endpoint or
+     * via a terminal `withdrawal_lifecycle` WS event.
+     */
+    errorMessage: string | null;
     sources: WithdrawManagedSourceItem[];
 }
 interface DepositAddressesToken {
@@ -2448,6 +2562,14 @@ declare class AggClient {
     redeem(body: RedeemRequest): Promise<RedeemResponse>;
     /** Withdraw funds from managed wallets to an external address. */
     withdrawManaged(params: WithdrawManagedParams): Promise<WithdrawManagedResponse>;
+    /**
+     * Read the current persisted state of a withdrawal. Used as a backfill for
+     * the WS lifecycle channel: the client polls this on hook mount and on WS
+     * reconnect to recover events that fired before the listener was attached
+     * or while the socket was disconnected. Same response shape as
+     * `withdrawManaged`.
+     */
+    getWithdrawalStatus(withdrawalId: string): Promise<WithdrawManagedResponse>;
     /** Trigger an on-chain balance sync for all tracked tokens across all chains. */
     syncManagedBalances(): Promise<SyncBalancesResponse>;
     /** Get managed wallet deposit addresses (EVM + Solana). Returns 202 shape while provisioning. */
@@ -2543,4 +2665,4 @@ declare function aggregateMidpoint(midpoints: (number | null | undefined)[]): nu
 
 declare function createAggClient(options: AggClientOptions): AggClient;
 
-export { type Account, AccountProvider, AccountType, type AggAuthDeliveryMode, type AggAuthProviderType, type AggAuthStartBody, type AggAuthStartResult, type AggAuthVerifyBody, AggClient, type AggClientAuthOptions, type AggClientSessionInput, type AggLinkAccountBody, type AggLinkAccountConfirmResult, type AggLinkAccountResult, type AggSessionUser, AggWebSocket, type AggWebSocketCallbacks, type AggWebSocketOptions, type AggregatedOrderbookLevel, type AggregatedOrderbookResponse, type App, type AppClientConfigResponse, type AttributedOrderbook, type AttributedOrderbookLevel, type AuthCodeResponse, type AuthStatus, type AuthTokenResponse, type AuthUser, type BatchMidpointsResponse, type BatchOrderbooksResponse, CONFIRMED_MATCH_STATUSES, type CancelManagedExecutionResponse, type Candle, CandleBuilder, type CandleInterval, type Category, Chain, type ChartBarsResponse, type ChartCandle, type ChartResolution, type ChartVenueCandles, type ComputeSplitsRequest, type ComputeSplitsResponse, type ComputeSplitsSelection, type CreateApp, type DepositAddressesPendingResponse, type DepositAddressesReadyResponse, type DepositAddressesResponse, type DepositAddressesSupportedChain, type DepositAddressesToken, type DepositStep, type DiagnosticCallback, type DiagnosticEvent, type ExecuteManagedParams, type ExecuteManagedRequest, type ExecuteManagedResponse, type ExecuteTradeRequest, type ExecuteTradeResponse, type ExecutionOrderItem, type ExecutionOrdersQuery, type ExecutionPositionGroup, type ExecutionPositionsQuery, type GetBalanceQuery, type GetBalanceResponse, type GetHoldingsQuery, type GetHoldingsResponse, type GetOrdersParams, type GetOrdersQuery, type GetPositionsParams, type GetPositionsQuery, type HelloResponse, IMAGE_SIZES, ImageSize, type MarkSource, type MarketPriceHistory, MarketStatus, MatchStatus, MatchType, type MatchedMidpoint, type MatchedOrderbookMarket, type MatchingReport, type MidpointItem, type MidpointRow, type NonceResponse, type OrderListItem, type OrderListQuery, OrderStatus, type Orderbook, type OrderbookBatchItemError, type OrderbookBatchItemErrorCode, type OrderbookBatchItemStatus, type OrderbookHistoryPoint, type OrderbookHistoryResponse, type OrderbookLevel, type OrderbookQuoteFill, type OrderbookQuoteParams, type OrderbookQuoteResponse, type OrderbookServiceUnavailableError, type OrderbookState, type OrderbooksOnlyError, type OutcomeMidpoint, type OutcomeMidpointRow, type OutcomeOrderbookResponse, type PaginatedResponse, type PersistedAuthSnapshot, type PositionGroup, type PositionRedeemStatus, type PricePoint, type PricesHistoryResponse, type QuoteManagedParams, type QuoteManagedRequest, type QuoteManagedResponse, type QuoteManagedSplit, type QuoteManagedStep, type QuoteSplit, type QuoteStep, type RampQuote, type RampQuoteRequest, type RampSessionRequest, type RampWidgetSession, type RedeemLegResult, type RedeemLegStatus, type RedeemRequest, type RedeemResponse, type RequestedOrderbookMarket, type SafeParseFailure, type SafeParseResult, type SafeParseSuccess, type ServerWallet, type SettlementSource, type SetupDepositAddressStep, type SetupVenueKeyStep, type SimpleOrderbookLevel, type SmartRouteFill, type SmartRouteParams, type SmartRouteResponse, type SmartRouteSide, type SmartRouteStatus, type SmartRouteVenueFill, type SplitsByAmountResult, type SyncBalancesResponse, type TradeExecutorOrder, type TradeExecutorOrderListResponse, TradeSide$1 as TradeSide, type TradeSplit, type TradeStep, TurnstileChallengeError, type UnifiedBalanceResponse, type UpdateUserBody, type UpsertVenueKey, type UserActivityBridge, type UserActivityDeposit, type UserActivityItem, type UserActivityQuery, type UserActivityTrade, type UserActivityType, type UserActivityUserOp, type UserActivityWithdrawal, type UserHolding, type UserProfile, VENUES, type ValidateBalanceOnClientStep, type ValidateManagedParams, type ValidateManagedRequest, type ValidateManagedResponse, type ValidateTradeRequest, type ValidateTradeResponse, Venue, type VenueEvent, type VenueEventListItem, type VenueEventWithMarkets, type VenueKeySummary, type VenueMarket, type VenueMarketClusterNode, type VenueMarketListItem, type VenueMarketOutcome, type VenueMarketRef, type VenueOrderbookEntry, type VenueOrderbookLevel, type VenuePositionBalance, type VenuePriceInfo, type VenueSoloQuote, type VerifyBody, type VerifyResponse, type WalletChainBalance, type WalletTokenBalance, type WithdrawManagedParams, type WithdrawManagedRequest, type WithdrawManagedResponse, type WithdrawManagedSourceItem, type WithdrawalSource, type WsAttributedLevel, type WsAuthenticated, type WsBalanceUpdate, type WsCandleInterval, type WsClientMessage, type WsConnected, type WsError, type WsHeartbeat, type WsMarkSource, type WsMarketResolved, type WsOrderEvent, type WsOrderEventType, type WsOrderSubmitted, type WsOrderbookDelta, type WsOrderbookSnapshot, type WsRedeemEvent, type WsServerMessage, type WsSubscribed, type WsTrade, type WsUnsubscribed, type WsVenueBook, type WsVenueInfo, type WsVenueLevel, aggregateMidpoint, applyOrderbookDelta, computeBestSplitsByAmount, computeChecksum, createAggClient, enumGuard, formatMarketQuestion, formatOutcomeLabel, getWalletAddressFromUserProfile, hasShape, isEmail, isEnum, isFiniteNonNeg, isNonEmptyString, mergeCandles, mergeClosedCandles, normalizeVenueMarketCluster, optimizedImageUrl, parse, parseEmail, parseEmailStrict, safeParse, snapshotToOrderbook, sortVenues };
+export { type Account, AccountProvider, AccountType, type AggAuthDeliveryMode, type AggAuthProviderType, type AggAuthStartBody, type AggAuthStartResult, type AggAuthVerifyBody, AggClient, type AggClientAuthOptions, type AggClientSessionInput, type AggLinkAccountBody, type AggLinkAccountConfirmResult, type AggLinkAccountResult, type AggSessionUser, AggWebSocket, type AggWebSocketCallbacks, type AggWebSocketOptions, type AggregatedOrderbookLevel, type AggregatedOrderbookResponse, type App, type AppClientConfigResponse, type AttributedOrderbook, type AttributedOrderbookLevel, type AuthCodeResponse, type AuthStatus, type AuthTokenResponse, type AuthUser, type BatchMidpointsResponse, type BatchOrderbooksResponse, CONFIRMED_MATCH_STATUSES, type CancelManagedExecutionResponse, type Candle, CandleBuilder, type CandleInterval, type Category, Chain, type ChartBarsResponse, type ChartCandle, type ChartResolution, type ChartVenueCandles, type ComputeSplitsRequest, type ComputeSplitsResponse, type ComputeSplitsSelection, type CreateApp, type DepositAddressesPendingResponse, type DepositAddressesReadyResponse, type DepositAddressesResponse, type DepositAddressesSupportedChain, type DepositAddressesToken, type DepositStep, type DiagnosticCallback, type DiagnosticEvent, type ExecuteManagedParams, type ExecuteManagedRequest, type ExecuteManagedResponse, type ExecuteTradeRequest, type ExecuteTradeResponse, type ExecutionOrderItem, type ExecutionOrdersQuery, type ExecutionPositionGroup, type ExecutionPositionsQuery, type GetBalanceQuery, type GetBalanceResponse, type GetHoldingsQuery, type GetHoldingsResponse, type GetOrdersParams, type GetOrdersQuery, type GetPositionsParams, type GetPositionsQuery, type HelloResponse, IMAGE_SIZES, ImageSize, type MarkSource, type MarketPriceHistory, MarketStatus, MatchStatus, MatchType, type MatchedMidpoint, type MatchedOrderbookMarket, type MatchingReport, type MidpointItem, type MidpointRow, type NonceResponse, type OrderListItem, type OrderListQuery, OrderStatus, type Orderbook, type OrderbookBatchItemError, type OrderbookBatchItemErrorCode, type OrderbookBatchItemStatus, type OrderbookHistoryPoint, type OrderbookHistoryResponse, type OrderbookLevel, type OrderbookQuoteFill, type OrderbookQuoteParams, type OrderbookQuoteResponse, type OrderbookServiceUnavailableError, type OrderbookState, type OrderbooksOnlyError, type OutcomeMidpoint, type OutcomeMidpointRow, type OutcomeOrderbookResponse, type PaginatedResponse, type PersistedAuthSnapshot, type PositionGroup, type PositionRedeemStatus, type PricePoint, type PricesHistoryResponse, type QuoteManagedParams, type QuoteManagedRequest, type QuoteManagedResponse, type QuoteManagedSplit, type QuoteManagedStep, type QuoteSplit, type QuoteStep, type RampQuote, type RampQuoteRequest, type RampSessionRequest, type RampWidgetSession, type RedeemLegResult, type RedeemLegStatus, type RedeemRequest, type RedeemResponse, type RequestedOrderbookMarket, type SafeParseFailure, type SafeParseResult, type SafeParseSuccess, type ServerWallet, type SettlementSource, type SetupDepositAddressStep, type SetupVenueKeyStep, type SimpleOrderbookLevel, type SmartRouteFill, type SmartRouteParams, type SmartRouteResponse, type SmartRouteSide, type SmartRouteStatus, type SmartRouteVenueFill, type SplitsByAmountResult, type SyncBalancesResponse, type TradeExecutorOrder, type TradeExecutorOrderListResponse, TradeSide$1 as TradeSide, type TradeSplit, type TradeStep, TurnstileChallengeError, type UnifiedBalanceResponse, type UpdateUserBody, type UpsertVenueKey, type UserActivityBridge, type UserActivityDeposit, type UserActivityItem, type UserActivityQuery, type UserActivityTrade, type UserActivityType, type UserActivityUserOp, type UserActivityWithdrawal, type UserHolding, type UserProfile, VENUES, type ValidateBalanceOnClientStep, type ValidateManagedParams, type ValidateManagedRequest, type ValidateManagedResponse, type ValidateTradeRequest, type ValidateTradeResponse, Venue, type VenueEvent, type VenueEventListItem, type VenueEventWithMarkets, type VenueKeySummary, type VenueMarket, type VenueMarketClusterNode, type VenueMarketListItem, type VenueMarketOutcome, type VenueMarketRef, type VenueOrderbookEntry, type VenueOrderbookLevel, type VenuePositionBalance, type VenuePriceInfo, type VenueSoloQuote, type VerifyBody, type VerifyResponse, type WalletChainBalance, type WalletTokenBalance, type WithdrawManagedParams, type WithdrawManagedRequest, type WithdrawManagedResponse, type WithdrawManagedSourceItem, type WithdrawTokenSymbol, type WithdrawalExpected, type WithdrawalLeg, type WithdrawalLegStatus, type WithdrawalLegType, type WithdrawalLifecycleStatus, type WithdrawalSource, type WithdrawalSourceItem, type WithdrawalSourceStatus, type WsAttributedLevel, type WsAuthenticated, type WsBalanceUpdate, type WsCandleInterval, type WsClientMessage, type WsConnected, type WsError, type WsHeartbeat, type WsMarkSource, type WsMarketResolved, type WsOrderEvent, type WsOrderEventType, type WsOrderSubmitted, type WsOrderbookDelta, type WsOrderbookSnapshot, type WsRedeemEvent, type WsServerMessage, type WsSubscribed, type WsTrade, type WsUnsubscribed, type WsVenueBook, type WsVenueInfo, type WsVenueLevel, type WsWithdrawalLegStatus, type WsWithdrawalLifecycleEvent, type WsWithdrawalLifecycleLeg, type WsWithdrawalLifecycleStatus, aggregateMidpoint, applyOrderbookDelta, computeBestSplitsByAmount, computeChecksum, createAggClient, enumGuard, formatMarketQuestion, formatOutcomeLabel, getWalletAddressFromUserProfile, hasShape, isEmail, isEnum, isFiniteNonNeg, isNonEmptyString, mergeCandles, mergeClosedCandles, normalizeVenueMarketCluster, optimizedImageUrl, parse, parseEmail, parseEmailStrict, safeParse, snapshotToOrderbook, sortVenues };

package/dist/index.d.ts

@@ -789,12 +789,35 @@ type ValidateManagedRequest = {
     side: "buy" | "sell";
     amount: number;
 };
+type WithdrawTokenSymbol$1 = "USDC" | "USDC.e" | "USDT";
 type WithdrawManagedRequest = {
+    /** Positive integer string in the token's native decimals (e.g. "100000" = 0.1 USDC). */
     amountRaw: string;
-    tokenSymbol: string;
+    tokenSymbol: WithdrawTokenSymbol$1;
+    /** EVM 0x-prefixed 20-byte recipient address. */
     destinationAddress: string;
-    destinationChainId?: number | undefined;
+    /** EVM chain ID where the recipient should receive funds. Required since v2026.04. */
+    destinationChainId: number;
+};
+type WithdrawalSourceStatus$1 = "pending" | "submitted" | "confirmed" | "failed";
+type WithdrawalSourceItem = {
+    sourceId: string;
+    chainId: number;
+    tokenSymbol: WithdrawTokenSymbol$1;
+    /** On-chain token address on `chainId`. */
+    tokenAddress: string;
+    /**
+     * On-chain decimals for `(chainId, tokenAddress)`. Critical for clients
+     * because `amountRaw` is in source-native decimals (BNB USDC is 18-dec,
+     * EVM USDC is 6-dec).
+     */
+    decimals: number;
+    amountRaw: string;
+    status: WithdrawalSourceStatus$1;
+    txHash: string | null;
+    bridgeOperationId: string | null;
 };
+/** @deprecated Use `WithdrawalSourceItem` from the lifecycle response. */
 type WithdrawalSource = {
     amountRaw: string;
     chainId: number;
@@ -1201,7 +1224,40 @@ interface WsRedeemEvent {
     /** @unit seconds (converted from server ms) */
     timestamp: number;
 }
-type WsServerMessage = WsOrderbookSnapshot | WsOrderbookDelta | WsTrade | WsSubscribed | WsUnsubscribed | WsConnected | WsAuthenticated | WsHeartbeat | WsMarketResolved | WsError | WsOrderSubmitted | WsBalanceUpdate | WsOrderEvent | WsRedeemEvent;
+/** Top-level withdrawal lifecycle states surfaced to partner clients. */
+type WsWithdrawalLifecycleStatus = "pending" | "bridging" | "transferring" | "completed" | "partial" | "failed";
+type WsWithdrawalLegStatus = "planned" | "submitted" | "confirmed" | "failed";
+interface WsWithdrawalLifecycleLeg {
+    sourceChainId: number;
+    destChainId: number;
+    type: "transfer" | "bridge";
+    status: WsWithdrawalLegStatus;
+    amountRaw: string;
+    txHash: string | null;
+    bridgeOperationId: string | null;
+}
+/**
+ * Per-withdrawal lifecycle event. Wire shape is intentionally additive:
+ * consumers should pass through unknown enum values rather than failing.
+ */
+interface WsWithdrawalLifecycleEvent {
+    type: "withdrawal_lifecycle";
+    withdrawalId: string;
+    userId: string;
+    status: WsWithdrawalLifecycleStatus;
+    /** True when `status` is terminal (`completed` / `partial` / `failed`). */
+    terminal: boolean;
+    /** Optional leg delta — present when this event was triggered by a leg flip. */
+    leg?: WsWithdrawalLifecycleLeg;
+    /** All legs at the moment of emission (snapshot). */
+    legs?: WsWithdrawalLifecycleLeg[];
+    /** Failure reason for terminal `failed` / `partial`. */
+    errorMessage?: string;
+    correlationId?: string;
+    /** @unit milliseconds (raw from server — NOT converted like other WS types) */
+    timestamp: number;
+}
+type WsServerMessage = WsOrderbookSnapshot | WsOrderbookDelta | WsTrade | WsSubscribed | WsUnsubscribed | WsConnected | WsAuthenticated | WsHeartbeat | WsMarketResolved | WsError | WsOrderSubmitted | WsBalanceUpdate | WsOrderEvent | WsRedeemEvent | WsWithdrawalLifecycleEvent;
 type WsClientMessage = {
     action: "subscribe";
     channel: "orderbook" | "trades";
@@ -1320,6 +1376,7 @@ interface AggWebSocketCallbacks {
     onBalanceUpdate?: (msg: WsBalanceUpdate) => void;
     onOrderEvent?: (msg: WsOrderEvent) => void;
     onRedeemEvent?: (msg: WsRedeemEvent) => void;
+    onWithdrawalLifecycle?: (msg: WsWithdrawalLifecycleEvent) => void;
     onDiagnostics?: DiagnosticCallback;
     onConnectionStateChange?: (connected: boolean) => void;
 }
@@ -1877,19 +1934,76 @@ interface ValidateManagedResponse {
     bridgeSourceChainId?: number;
     bridgeAmountRaw?: string;
 }
+type WithdrawTokenSymbol = "USDC" | "USDC.e" | "USDT";
 interface WithdrawManagedParams {
+    /** Positive integer string in the token's native decimals (e.g. "100000" = 0.1 USDC). */
     amountRaw: string;
-    tokenSymbol: string;
+    tokenSymbol: WithdrawTokenSymbol;
+    /** EVM 0x-prefixed 20-byte recipient address. */
     destinationAddress: string;
-    destinationChainId?: number;
+    /** EVM chain ID where the recipient should receive funds. Required as of v2026.04. */
+    destinationChainId: number;
+}
+type WithdrawalLifecycleStatus = "pending" | "bridging" | "transferring" | "completed" | "partial" | "failed";
+type WithdrawalSourceStatus = "pending" | "submitted" | "confirmed" | "failed";
+type WithdrawalLegType = "transfer" | "bridge";
+type WithdrawalLegStatus = "planned" | "submitted" | "confirmed" | "failed";
+interface WithdrawalLeg {
+    type: WithdrawalLegType;
+    status: WithdrawalLegStatus;
+    sourceChainId: number;
+    destChainId: number;
+    amountRaw: string;
+    txHash: string | null;
+    bridgeOperationId: string | null;
 }
 interface WithdrawManagedSourceItem {
+    sourceId: string;
     chainId: number;
+    tokenSymbol: WithdrawTokenSymbol;
+    /** On-chain token address on `chainId`. */
+    tokenAddress: string;
+    /**
+     * On-chain decimals for `(chainId, tokenAddress)`. Required to interpret
+     * `amountRaw`: BNB USDC is 18-dec, EVM USDC is 6-dec.
+     */
+    decimals: number;
     amountRaw: string;
-    txHash?: string;
-    bridgeOperationId?: string;
+    status: WithdrawalSourceStatus;
+    txHash: string | null;
+    bridgeOperationId: string | null;
+}
+/**
+ * `pricingStatus === "unquoted"` until the multi-stable quote layer ships;
+ * `expected.*` is `null` in that mode. Do NOT treat null fields as missing.
+ */
+interface WithdrawalExpected {
+    outputRaw: string | null;
+    feeRaw: string | null;
+    etaSeconds: number | null;
 }
 interface WithdrawManagedResponse {
+    withdrawalId: string;
+    status: WithdrawalLifecycleStatus;
+    requested: {
+        tokenSymbol: WithdrawTokenSymbol;
+        amountRaw: string;
+    };
+    destination: {
+        chainId: number;
+        address: string;
+        tokenSymbol: WithdrawTokenSymbol;
+    };
+    legs: WithdrawalLeg[];
+    expected: WithdrawalExpected;
+    pricingStatus: "unquoted" | "quoted";
+    /**
+     * Persisted terminal-state error reason. Always `null` until the
+     * withdrawal reaches `failed` / `partial`. The submit response always
+     * returns `null`; populated values arrive via the GET status endpoint or
+     * via a terminal `withdrawal_lifecycle` WS event.
+     */
+    errorMessage: string | null;
     sources: WithdrawManagedSourceItem[];
 }
 interface DepositAddressesToken {
@@ -2448,6 +2562,14 @@ declare class AggClient {
     redeem(body: RedeemRequest): Promise<RedeemResponse>;
     /** Withdraw funds from managed wallets to an external address. */
     withdrawManaged(params: WithdrawManagedParams): Promise<WithdrawManagedResponse>;
+    /**
+     * Read the current persisted state of a withdrawal. Used as a backfill for
+     * the WS lifecycle channel: the client polls this on hook mount and on WS
+     * reconnect to recover events that fired before the listener was attached
+     * or while the socket was disconnected. Same response shape as
+     * `withdrawManaged`.
+     */
+    getWithdrawalStatus(withdrawalId: string): Promise<WithdrawManagedResponse>;
     /** Trigger an on-chain balance sync for all tracked tokens across all chains. */
     syncManagedBalances(): Promise<SyncBalancesResponse>;
     /** Get managed wallet deposit addresses (EVM + Solana). Returns 202 shape while provisioning. */
@@ -2543,4 +2665,4 @@ declare function aggregateMidpoint(midpoints: (number | null | undefined)[]): nu
 
 declare function createAggClient(options: AggClientOptions): AggClient;
 
-export { type Account, AccountProvider, AccountType, type AggAuthDeliveryMode, type AggAuthProviderType, type AggAuthStartBody, type AggAuthStartResult, type AggAuthVerifyBody, AggClient, type AggClientAuthOptions, type AggClientSessionInput, type AggLinkAccountBody, type AggLinkAccountConfirmResult, type AggLinkAccountResult, type AggSessionUser, AggWebSocket, type AggWebSocketCallbacks, type AggWebSocketOptions, type AggregatedOrderbookLevel, type AggregatedOrderbookResponse, type App, type AppClientConfigResponse, type AttributedOrderbook, type AttributedOrderbookLevel, type AuthCodeResponse, type AuthStatus, type AuthTokenResponse, type AuthUser, type BatchMidpointsResponse, type BatchOrderbooksResponse, CONFIRMED_MATCH_STATUSES, type CancelManagedExecutionResponse, type Candle, CandleBuilder, type CandleInterval, type Category, Chain, type ChartBarsResponse, type ChartCandle, type ChartResolution, type ChartVenueCandles, type ComputeSplitsRequest, type ComputeSplitsResponse, type ComputeSplitsSelection, type CreateApp, type DepositAddressesPendingResponse, type DepositAddressesReadyResponse, type DepositAddressesResponse, type DepositAddressesSupportedChain, type DepositAddressesToken, type DepositStep, type DiagnosticCallback, type DiagnosticEvent, type ExecuteManagedParams, type ExecuteManagedRequest, type ExecuteManagedResponse, type ExecuteTradeRequest, type ExecuteTradeResponse, type ExecutionOrderItem, type ExecutionOrdersQuery, type ExecutionPositionGroup, type ExecutionPositionsQuery, type GetBalanceQuery, type GetBalanceResponse, type GetHoldingsQuery, type GetHoldingsResponse, type GetOrdersParams, type GetOrdersQuery, type GetPositionsParams, type GetPositionsQuery, type HelloResponse, IMAGE_SIZES, ImageSize, type MarkSource, type MarketPriceHistory, MarketStatus, MatchStatus, MatchType, type MatchedMidpoint, type MatchedOrderbookMarket, type MatchingReport, type MidpointItem, type MidpointRow, type NonceResponse, type OrderListItem, type OrderListQuery, OrderStatus, type Orderbook, type OrderbookBatchItemError, type OrderbookBatchItemErrorCode, type OrderbookBatchItemStatus, type OrderbookHistoryPoint, type OrderbookHistoryResponse, type OrderbookLevel, type OrderbookQuoteFill, type OrderbookQuoteParams, type OrderbookQuoteResponse, type OrderbookServiceUnavailableError, type OrderbookState, type OrderbooksOnlyError, type OutcomeMidpoint, type OutcomeMidpointRow, type OutcomeOrderbookResponse, type PaginatedResponse, type PersistedAuthSnapshot, type PositionGroup, type PositionRedeemStatus, type PricePoint, type PricesHistoryResponse, type QuoteManagedParams, type QuoteManagedRequest, type QuoteManagedResponse, type QuoteManagedSplit, type QuoteManagedStep, type QuoteSplit, type QuoteStep, type RampQuote, type RampQuoteRequest, type RampSessionRequest, type RampWidgetSession, type RedeemLegResult, type RedeemLegStatus, type RedeemRequest, type RedeemResponse, type RequestedOrderbookMarket, type SafeParseFailure, type SafeParseResult, type SafeParseSuccess, type ServerWallet, type SettlementSource, type SetupDepositAddressStep, type SetupVenueKeyStep, type SimpleOrderbookLevel, type SmartRouteFill, type SmartRouteParams, type SmartRouteResponse, type SmartRouteSide, type SmartRouteStatus, type SmartRouteVenueFill, type SplitsByAmountResult, type SyncBalancesResponse, type TradeExecutorOrder, type TradeExecutorOrderListResponse, TradeSide$1 as TradeSide, type TradeSplit, type TradeStep, TurnstileChallengeError, type UnifiedBalanceResponse, type UpdateUserBody, type UpsertVenueKey, type UserActivityBridge, type UserActivityDeposit, type UserActivityItem, type UserActivityQuery, type UserActivityTrade, type UserActivityType, type UserActivityUserOp, type UserActivityWithdrawal, type UserHolding, type UserProfile, VENUES, type ValidateBalanceOnClientStep, type ValidateManagedParams, type ValidateManagedRequest, type ValidateManagedResponse, type ValidateTradeRequest, type ValidateTradeResponse, Venue, type VenueEvent, type VenueEventListItem, type VenueEventWithMarkets, type VenueKeySummary, type VenueMarket, type VenueMarketClusterNode, type VenueMarketListItem, type VenueMarketOutcome, type VenueMarketRef, type VenueOrderbookEntry, type VenueOrderbookLevel, type VenuePositionBalance, type VenuePriceInfo, type VenueSoloQuote, type VerifyBody, type VerifyResponse, type WalletChainBalance, type WalletTokenBalance, type WithdrawManagedParams, type WithdrawManagedRequest, type WithdrawManagedResponse, type WithdrawManagedSourceItem, type WithdrawalSource, type WsAttributedLevel, type WsAuthenticated, type WsBalanceUpdate, type WsCandleInterval, type WsClientMessage, type WsConnected, type WsError, type WsHeartbeat, type WsMarkSource, type WsMarketResolved, type WsOrderEvent, type WsOrderEventType, type WsOrderSubmitted, type WsOrderbookDelta, type WsOrderbookSnapshot, type WsRedeemEvent, type WsServerMessage, type WsSubscribed, type WsTrade, type WsUnsubscribed, type WsVenueBook, type WsVenueInfo, type WsVenueLevel, aggregateMidpoint, applyOrderbookDelta, computeBestSplitsByAmount, computeChecksum, createAggClient, enumGuard, formatMarketQuestion, formatOutcomeLabel, getWalletAddressFromUserProfile, hasShape, isEmail, isEnum, isFiniteNonNeg, isNonEmptyString, mergeCandles, mergeClosedCandles, normalizeVenueMarketCluster, optimizedImageUrl, parse, parseEmail, parseEmailStrict, safeParse, snapshotToOrderbook, sortVenues };
+export { type Account, AccountProvider, AccountType, type AggAuthDeliveryMode, type AggAuthProviderType, type AggAuthStartBody, type AggAuthStartResult, type AggAuthVerifyBody, AggClient, type AggClientAuthOptions, type AggClientSessionInput, type AggLinkAccountBody, type AggLinkAccountConfirmResult, type AggLinkAccountResult, type AggSessionUser, AggWebSocket, type AggWebSocketCallbacks, type AggWebSocketOptions, type AggregatedOrderbookLevel, type AggregatedOrderbookResponse, type App, type AppClientConfigResponse, type AttributedOrderbook, type AttributedOrderbookLevel, type AuthCodeResponse, type AuthStatus, type AuthTokenResponse, type AuthUser, type BatchMidpointsResponse, type BatchOrderbooksResponse, CONFIRMED_MATCH_STATUSES, type CancelManagedExecutionResponse, type Candle, CandleBuilder, type CandleInterval, type Category, Chain, type ChartBarsResponse, type ChartCandle, type ChartResolution, type ChartVenueCandles, type ComputeSplitsRequest, type ComputeSplitsResponse, type ComputeSplitsSelection, type CreateApp, type DepositAddressesPendingResponse, type DepositAddressesReadyResponse, type DepositAddressesResponse, type DepositAddressesSupportedChain, type DepositAddressesToken, type DepositStep, type DiagnosticCallback, type DiagnosticEvent, type ExecuteManagedParams, type ExecuteManagedRequest, type ExecuteManagedResponse, type ExecuteTradeRequest, type ExecuteTradeResponse, type ExecutionOrderItem, type ExecutionOrdersQuery, type ExecutionPositionGroup, type ExecutionPositionsQuery, type GetBalanceQuery, type GetBalanceResponse, type GetHoldingsQuery, type GetHoldingsResponse, type GetOrdersParams, type GetOrdersQuery, type GetPositionsParams, type GetPositionsQuery, type HelloResponse, IMAGE_SIZES, ImageSize, type MarkSource, type MarketPriceHistory, MarketStatus, MatchStatus, MatchType, type MatchedMidpoint, type MatchedOrderbookMarket, type MatchingReport, type MidpointItem, type MidpointRow, type NonceResponse, type OrderListItem, type OrderListQuery, OrderStatus, type Orderbook, type OrderbookBatchItemError, type OrderbookBatchItemErrorCode, type OrderbookBatchItemStatus, type OrderbookHistoryPoint, type OrderbookHistoryResponse, type OrderbookLevel, type OrderbookQuoteFill, type OrderbookQuoteParams, type OrderbookQuoteResponse, type OrderbookServiceUnavailableError, type OrderbookState, type OrderbooksOnlyError, type OutcomeMidpoint, type OutcomeMidpointRow, type OutcomeOrderbookResponse, type PaginatedResponse, type PersistedAuthSnapshot, type PositionGroup, type PositionRedeemStatus, type PricePoint, type PricesHistoryResponse, type QuoteManagedParams, type QuoteManagedRequest, type QuoteManagedResponse, type QuoteManagedSplit, type QuoteManagedStep, type QuoteSplit, type QuoteStep, type RampQuote, type RampQuoteRequest, type RampSessionRequest, type RampWidgetSession, type RedeemLegResult, type RedeemLegStatus, type RedeemRequest, type RedeemResponse, type RequestedOrderbookMarket, type SafeParseFailure, type SafeParseResult, type SafeParseSuccess, type ServerWallet, type SettlementSource, type SetupDepositAddressStep, type SetupVenueKeyStep, type SimpleOrderbookLevel, type SmartRouteFill, type SmartRouteParams, type SmartRouteResponse, type SmartRouteSide, type SmartRouteStatus, type SmartRouteVenueFill, type SplitsByAmountResult, type SyncBalancesResponse, type TradeExecutorOrder, type TradeExecutorOrderListResponse, TradeSide$1 as TradeSide, type TradeSplit, type TradeStep, TurnstileChallengeError, type UnifiedBalanceResponse, type UpdateUserBody, type UpsertVenueKey, type UserActivityBridge, type UserActivityDeposit, type UserActivityItem, type UserActivityQuery, type UserActivityTrade, type UserActivityType, type UserActivityUserOp, type UserActivityWithdrawal, type UserHolding, type UserProfile, VENUES, type ValidateBalanceOnClientStep, type ValidateManagedParams, type ValidateManagedRequest, type ValidateManagedResponse, type ValidateTradeRequest, type ValidateTradeResponse, Venue, type VenueEvent, type VenueEventListItem, type VenueEventWithMarkets, type VenueKeySummary, type VenueMarket, type VenueMarketClusterNode, type VenueMarketListItem, type VenueMarketOutcome, type VenueMarketRef, type VenueOrderbookEntry, type VenueOrderbookLevel, type VenuePositionBalance, type VenuePriceInfo, type VenueSoloQuote, type VerifyBody, type VerifyResponse, type WalletChainBalance, type WalletTokenBalance, type WithdrawManagedParams, type WithdrawManagedRequest, type WithdrawManagedResponse, type WithdrawManagedSourceItem, type WithdrawTokenSymbol, type WithdrawalExpected, type WithdrawalLeg, type WithdrawalLegStatus, type WithdrawalLegType, type WithdrawalLifecycleStatus, type WithdrawalSource, type WithdrawalSourceItem, type WithdrawalSourceStatus, type WsAttributedLevel, type WsAuthenticated, type WsBalanceUpdate, type WsCandleInterval, type WsClientMessage, type WsConnected, type WsError, type WsHeartbeat, type WsMarkSource, type WsMarketResolved, type WsOrderEvent, type WsOrderEventType, type WsOrderSubmitted, type WsOrderbookDelta, type WsOrderbookSnapshot, type WsRedeemEvent, type WsServerMessage, type WsSubscribed, type WsTrade, type WsUnsubscribed, type WsVenueBook, type WsVenueInfo, type WsVenueLevel, type WsWithdrawalLegStatus, type WsWithdrawalLifecycleEvent, type WsWithdrawalLifecycleLeg, type WsWithdrawalLifecycleStatus, aggregateMidpoint, applyOrderbookDelta, computeBestSplitsByAmount, computeChecksum, createAggClient, enumGuard, formatMarketQuestion, formatOutcomeLabel, getWalletAddressFromUserProfile, hasShape, isEmail, isEnum, isFiniteNonNeg, isNonEmptyString, mergeCandles, mergeClosedCandles, normalizeVenueMarketCluster, optimizedImageUrl, parse, parseEmail, parseEmailStrict, safeParse, snapshotToOrderbook, sortVenues };

package/dist/index.js

@@ -1015,7 +1015,7 @@ var AggWebSocket = class {
   }
   // ── Message handling ──
   handleMessage(raw) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
     const type = raw.type;
     switch (type) {
       case "orderbook_snapshot":
@@ -1060,6 +1060,9 @@ var AggWebSocket = class {
       case "redeem_event":
         this.handleRedeemEvent(raw);
         break;
+      case "withdrawal_lifecycle":
+        (_l = (_k = this.callbacks).onWithdrawalLifecycle) == null ? void 0 : _l.call(_k, raw);
+        break;
     }
   }
   /**
@@ -2278,6 +2281,23 @@ Issued At: ${issuedAt}`;
       });
     });
   }
+  /**
+   * Read the current persisted state of a withdrawal. Used as a backfill for
+   * the WS lifecycle channel: the client polls this on hook mount and on WS
+   * reconnect to recover events that fired before the listener was attached
+   * or while the socket was disconnected. Same response shape as
+   * `withdrawManaged`.
+   */
+  getWithdrawalStatus(withdrawalId) {
+    return __async(this, null, function* () {
+      if (!withdrawalId) {
+        throw new Error("withdrawalId is required");
+      }
+      return this.request(
+        `/execution/withdrawals/${encodeURIComponent(withdrawalId)}`
+      );
+    });
+  }
   /** Trigger an on-chain balance sync for all tracked tokens across all chains. */
   syncManagedBalances() {
     return __async(this, null, function* () {

package/dist/index.mjs

@@ -918,7 +918,7 @@ var AggWebSocket = class {
   }
   // ── Message handling ──
   handleMessage(raw) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
     const type = raw.type;
     switch (type) {
       case "orderbook_snapshot":
@@ -963,6 +963,9 @@ var AggWebSocket = class {
       case "redeem_event":
         this.handleRedeemEvent(raw);
         break;
+      case "withdrawal_lifecycle":
+        (_l = (_k = this.callbacks).onWithdrawalLifecycle) == null ? void 0 : _l.call(_k, raw);
+        break;
     }
   }
   /**
@@ -2181,6 +2184,23 @@ Issued At: ${issuedAt}`;
       });
     });
   }
+  /**
+   * Read the current persisted state of a withdrawal. Used as a backfill for
+   * the WS lifecycle channel: the client polls this on hook mount and on WS
+   * reconnect to recover events that fired before the listener was attached
+   * or while the socket was disconnected. Same response shape as
+   * `withdrawManaged`.
+   */
+  getWithdrawalStatus(withdrawalId) {
+    return __async(this, null, function* () {
+      if (!withdrawalId) {
+        throw new Error("withdrawalId is required");
+      }
+      return this.request(
+        `/execution/withdrawals/${encodeURIComponent(withdrawalId)}`
+      );
+    });
+  }
   /** Trigger an on-chain balance sync for all tracked tokens across all chains. */
   syncManagedBalances() {
     return __async(this, null, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agg-build/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Vanilla TypeScript client for the AGG prediction market aggregator (auth, markets, orderbooks, charts, trading, managed execution, WebSockets). Works in browsers, Node.js, and React Native.",
   "sideEffects": false,
   "license": "MIT",