Widget Events

The widget emits structured events via window.postMessage() from inside the iframe to your parent page. This lets you react to what the user does — most importantly, a completed deposit — in real time, with no polling.

Widget events are for in-browser UX. For reliable server-side accounting, pair them with webhooks.

The event envelope

Every event posted from the widget has this shape:

interface SwapperWidgetEvent {
  type: "SWAPPER_EVENT";       // discriminator — filter on this
  version: "1.0";              // protocol version
  name: WidgetEventName;       // e.g. "transaction_success"
  timestamp: string;           // ISO 8601
  payload: WidgetEventPayload; // event-specific data
}

Field	Description
type	Always "SWAPPER_EVENT" — use it to ignore unrelated postMessages.
version	Protocol version (currently "1.0").
name	Event name (see below).
timestamp	When it was emitted (ISO 8601).
payload	Event-specific data.

Three ways to listen

onEvent (recommended)

Pass a callback in the config — it receives every event:

import { SwapperIframe, WidgetEventName } from "@swapper-finance/deposit-sdk";
import type { TransactionSuccessPayload } from "@swapper-finance/deposit-sdk";

const swapper = new SwapperIframe({
  // ...required config
  onEvent: (event) => {
    if (event.type === WidgetEventName.TRANSACTION_SUCCESS) {
      const payload = event.data as TransactionSuccessPayload;
      console.log("Deposit complete:", payload.txHash);
    }
  },
});

Works with openSwapperModal too.

on() / off()

Register handlers on the instance; "*" catches everything:

swapper.on(WidgetEventName.TRANSACTION_SUCCESS, (event) => { /* … */ });
swapper.on("*", (event) => console.log(event.type, event.data));
swapper.off(WidgetEventName.TRANSACTION_SUCCESS, handler);

Raw window.addEventListener

If you're not using the SDK's listeners (or you embed the widget directly), read the messages yourself:

import { WIDGET_EVENT_PROTOCOL_VERSION, WidgetEventName } from "@swapper-finance/deposit-sdk";
import type { SwapperWidgetEvent, TransactionSuccessPayload } from "@swapper-finance/deposit-sdk";

window.addEventListener("message", (event: MessageEvent) => {
  if (event.data?.type !== "SWAPPER_EVENT") return;
  const message = event.data as SwapperWidgetEvent;
  if (message.version !== WIDGET_EVENT_PROTOCOL_VERSION) return;

  if (message.name === WidgetEventName.TRANSACTION_SUCCESS) {
    const payload = message.payload as TransactionSuccessPayload;
    console.log("Tx:", payload.txHash, "Explorer:", payload.explorerUrl);
  }
});

Event types

WidgetEventName currently defines:

Name	Value	Meaning
TRANSACTION_SUCCESS	"transaction_success"	A deposit completed successfully.
RESIZE	"resize"	The widget's required height changed (flexible height).
CLOSE_REQUEST	"close_request"	The widget is asking the host to close it.

transaction_success

Emitted when a deposit completes.

Field	Type	Description
depositOption	string	Flow used: "walletDeposit", "transferCrypto", or "depositWithCash".
txHash	string?	On-chain transaction hash, when available.
explorerUrl	string?	Block-explorer link for the transaction.
tokenSymbol	string?	Symbol of the received token (e.g. "USDC").
tokenAddress	string?	Contract address of the received token.
chainId	string?	Chain id where the token was received.
amountReceived	string?	Human-readable amount received.

resize

Emitted when flexible height is on and the home page's content height changes. Payload: { height: number } (CSS pixels). The modal/embed animates to this automatically; if you host the iframe yourself, resize it to match.

close_request

The widget requests to be dismissed (e.g. a close affordance was tapped). Handle it by closing your modal/container.

Extensibility

New event names will be added to WidgetEventName over time. Filter by the name string and ignore names you don't recognize — new events can ship without an SDK bump, and old integrations keep working.

Events vs. webhooks

	Widget event	Webhook
Channel	Browser postMessage	Server-to-server HTTP
Latency	Instant	Seconds
Reliability	Lost if the tab closes	Retried, signed
Use for	Live UI updates	Crediting accounts (source of truth)

Use both.