Swap Events
The typed event union emitted by swapWithExactIn() and swapWithExactOut() — status, plan preview, and per-step progress.
You are viewing the Nexus SDK v2 docs. For the current SDK, see the v3 docs and the v2 → v3 migration guide.
swapWithExactIn() and swapWithExactOut() accept an onEvent callback (via SwapOperationOptions) that receives a typed SwapEvent. Every event carries a type discriminant, so you can narrow on event.type and then, for progress events, on event.stepType and event.state.
Event union
export type SwapEvent =
| SwapStatusEvent // type: 'status'
| SwapPlanPreviewEvent // type: 'plan_preview'
| SwapPlanConfirmedEvent // type: 'plan_confirmed'
| SwapPlanProgressEvent; // type: 'plan_progress'Status events
export type SwapStatus =
| 'route_building'
| 'route_ready'
| 'awaiting_approval'
| 'approved'
| 'executing'
| 'completed';
export type SwapStatusEvent = {
type: 'status';
status: SwapStatus;
};Plan preview & confirmed events
plan_preview is emitted once the route is planned; plan_confirmed is emitted after the intent is approved. Both carry the same SwapPlan.
export type SwapPlanPreviewEvent = {
type: 'plan_preview';
plan: SwapPlan;
};
export type SwapPlanConfirmedEvent = {
type: 'plan_confirmed';
plan: SwapPlan;
};
export type SwapPlan = {
hasBridge: boolean;
hasDestinationSwap: boolean;
steps: SwapPlanStep[];
};
export type SwapPlanStep =
| SwapSourceSwapStep // type: 'source_swap'
| SwapEoaToEphemeralTransferStep // type: 'eoa_to_ephemeral_transfer'
| SwapBridgeDepositStep // type: 'bridge_deposit'
| SwapBridgeIntentSubmissionStep // type: 'bridge_intent_submission'
| BridgeFillStep // type: 'bridge_fill'
| SwapDestinationSwapStep; // type: 'destination_swap'Progress events
plan_progress events are emitted as each step advances. Narrow first on stepType, then on state. Every progress event carries its step object.
export type SwapPlanProgressEvent =
| SwapSourceSwapProgressEvent
| SwapEoaToEphemeralTransferProgressEvent
| SwapBridgeDepositProgressEvent
| SwapBridgeIntentSubmissionProgressEvent
| SwapBridgeFillProgressEvent
| SwapDestinationSwapProgressEvent;state values each stepType can emit:
stepType | States |
|---|---|
source_swap | wallet_prompted · started · submitted · confirmed · failed |
eoa_to_ephemeral_transfer | wallet_prompted · submitted · confirmed · failed |
bridge_deposit | started · submitted · confirmed · failed |
bridge_intent_submission | started · completed · failed |
bridge_fill | waiting · completed · failed |
destination_swap | wallet_prompted · started · submitted · confirmed · failed |
Field shapes
submitted and confirmed states carry txHash and explorerUrl. failed states carry an error string (and, for tx-based steps, optional txHash/explorerUrl). The bridge steps carry an intentRequestHash instead.
export type SwapSourceSwapProgressEvent =
| { type: 'plan_progress'; stepType: 'source_swap'; state: 'wallet_prompted'; step: SwapSourceSwapStep }
| { type: 'plan_progress'; stepType: 'source_swap'; state: 'started'; step: SwapSourceSwapStep }
| { type: 'plan_progress'; stepType: 'source_swap'; state: 'submitted'; step: SwapSourceSwapStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'source_swap'; state: 'confirmed'; step: SwapSourceSwapStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'source_swap'; state: 'failed'; step: SwapSourceSwapStep; txHash?: Hex; explorerUrl?: string; error: string };
export type SwapEoaToEphemeralTransferProgressEvent =
| { type: 'plan_progress'; stepType: 'eoa_to_ephemeral_transfer'; state: 'wallet_prompted'; step: SwapEoaToEphemeralTransferStep }
| { type: 'plan_progress'; stepType: 'eoa_to_ephemeral_transfer'; state: 'submitted'; step: SwapEoaToEphemeralTransferStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'eoa_to_ephemeral_transfer'; state: 'confirmed'; step: SwapEoaToEphemeralTransferStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'eoa_to_ephemeral_transfer'; state: 'failed'; step: SwapEoaToEphemeralTransferStep; txHash?: Hex; explorerUrl?: string; error: string };
export type SwapBridgeDepositProgressEvent =
| { type: 'plan_progress'; stepType: 'bridge_deposit'; state: 'started'; step: SwapBridgeDepositStep }
| { type: 'plan_progress'; stepType: 'bridge_deposit'; state: 'submitted'; step: SwapBridgeDepositStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'bridge_deposit'; state: 'confirmed'; step: SwapBridgeDepositStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'bridge_deposit'; state: 'failed'; step: SwapBridgeDepositStep; txHash?: Hex; explorerUrl?: string; error: string };
export type SwapBridgeIntentSubmissionProgressEvent =
| { type: 'plan_progress'; stepType: 'bridge_intent_submission'; state: 'started'; step: SwapBridgeIntentSubmissionStep }
| { type: 'plan_progress'; stepType: 'bridge_intent_submission'; state: 'completed'; step: SwapBridgeIntentSubmissionStep; intentRequestHash: Hex }
| { type: 'plan_progress'; stepType: 'bridge_intent_submission'; state: 'failed'; step: SwapBridgeIntentSubmissionStep; intentRequestHash?: Hex; error: string };
export type SwapBridgeFillProgressEvent =
| { type: 'plan_progress'; stepType: 'bridge_fill'; state: 'waiting'; step: BridgeFillStep; intentRequestHash: Hex }
| { type: 'plan_progress'; stepType: 'bridge_fill'; state: 'completed'; step: BridgeFillStep; intentRequestHash: Hex }
| { type: 'plan_progress'; stepType: 'bridge_fill'; state: 'failed'; step: BridgeFillStep; intentRequestHash: Hex; error: string };
export type SwapDestinationSwapProgressEvent =
| { type: 'plan_progress'; stepType: 'destination_swap'; state: 'wallet_prompted'; step: SwapDestinationSwapStep }
| { type: 'plan_progress'; stepType: 'destination_swap'; state: 'started'; step: SwapDestinationSwapStep }
| { type: 'plan_progress'; stepType: 'destination_swap'; state: 'submitted'; step: SwapDestinationSwapStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'destination_swap'; state: 'confirmed'; step: SwapDestinationSwapStep; txHash: Hex; explorerUrl: string }
| { type: 'plan_progress'; stepType: 'destination_swap'; state: 'failed'; step: SwapDestinationSwapStep; txHash?: Hex; explorerUrl?: string; error: string };Step shapes
export type PlanTokenAmount = {
symbol: string;
contractAddress: Hex;
decimals: number;
logo?: string;
amount: string; // human-readable
amountRaw: bigint; // raw integer units
};
export type SwapSourceSwapStep = {
type: 'source_swap';
id: string;
chain: { id: number; name: string; logo: string };
walletPath: 'ephemeral' | 'safe';
swaps: { input: PlanTokenAmount; output: PlanTokenAmount }[];
};
export type SwapEoaToEphemeralTransferStep = {
type: 'eoa_to_ephemeral_transfer';
id: string;
chain: { id: number; name: string; logo: string };
asset: PlanTokenAmount;
};
export type SwapBridgeDepositStep = {
type: 'bridge_deposit';
id: string;
chain: { id: number; name: string; logo: string };
asset: PlanTokenAmount;
};
export type SwapBridgeIntentSubmissionStep = {
type: 'bridge_intent_submission';
id: string;
};
export type BridgeFillStep = {
type: 'bridge_fill';
id: string;
chain: { id: number; name: string; logo: string };
asset: PlanTokenAmount;
};
export type SwapDestinationSwapStep = {
type: 'destination_swap';
id: string;
chain: { id: number; name: string; logo: string };
walletPath: 'ephemeral' | 'safe';
swaps: { input: PlanTokenAmount; output: PlanTokenAmount }[];
};Usage example
const result = await client.swapWithExactIn(swapInput, {
onEvent: (event) => {
switch (event.type) {
case 'status':
console.log('Status:', event.status);
break;
case 'plan_preview':
console.log('Planned steps:', event.plan.steps);
console.log('Has bridge:', event.plan.hasBridge);
break;
case 'plan_progress':
if (event.stepType === 'source_swap' && event.state === 'confirmed') {
console.log('Source swap confirmed:', event.txHash, event.explorerUrl);
}
if (event.stepType === 'destination_swap' && event.state === 'confirmed') {
console.log('Destination swap confirmed:', event.txHash, event.explorerUrl);
}
break;
}
},
});Note
swapAndExecute() emits a superset of these events (SwapAndExecuteEvent), adding a preparing status plus the execute approval and transaction progress events. See the Swap and Execute page.How is this guide?