Mesh SDK events

This reference guide lists every SDK event Mesh can fire during a Link session, along with payload details — so you can build precise business logic around user interactions.

Before you start

You have the Mesh SDK initialized and have set up callback functions (see Use Mesh’s callback functions)

Overview

Mesh SDKs offer event tracking that not only provides you insights into user interactions within Link, but also gives you the ability to implement business logic based on those interactions.

SDK Callback Functions

Capturing Mesh’s SDK events varies slightly across platforms (Web, iOS, Android, React Native, Flutter). Please refer to the Use Mesh’s callback functions guide for more platform-specific guidance for setting up callback functions.

Core events

These are the events most integrations act on. Wire these up first — then consult the complete reference below if you need finer-grained tracking.

SDK Event	When it fires	Payload highlights
`pageLoaded`	The first page of Link is fully loaded and visible to the user.	No payload. Use to confirm Link launched successfully.
`integrationConnected`	User successfully connected their exchange or wallet. Triggers the `onIntegrationConnected` callback.	• `integrationName`: The connected integration • `accessToken`: Token payload with credentials — store `tokenId` server-side for MMT return-user flows
`transferPreviewed`	User viewed the preview screen showing transfer details, fees, and routing.	• `symbol`, `amount`, `amountInFiat`, `toAddress` • `fees`: `institutionTransferFee`, `estimatedNetworkGasFee`, `customClientFee` • `previewId`: Unique ID for this preview
`transferInitiated`	User clicked Proceed from the preview — the transfer request was sent to the exchange or wallet for approval.	• `symbol`, `amount`, `toAddress`, `fees` (same structure as `transferPreviewed`)
`transferCompleted`	User reached the Success page at the end of the transfer flow. Triggers the `onTransferFinished` callback. Use `onTransferFinished` for business logic — this event is better suited for analytics.	Full `transferFinished` payload: `status` (pending/succeeded/failed), `transferId`, `txHash`, `symbol`, `amount`, `fromAddress`, `toAddress`, `refundAddress`, `networkName`
`withdrawalRequested`	User confirmed a withdrawal in the Mesh-hosted withdrawal flow, and Link closes. Use it to trigger 2FA or update your UI.	• `transferId`: Mesh’s identifier for the withdrawal • `status`: `pending` or `success` (in practice `pending`) • No money movement details: take those from the withdrawal webhook
`transferExecutionError`	An error occurred while executing the transfer.	• `errorMessage`: Descriptive error message.
`transferNoEligibleAssets`	The user has no assets eligible for this transfer (wrong token, insufficient balance, or unsupported network).	• `arrayOfTokensHeld`: Tokens the user holds, each with `symbol`, `amount`, `amountInFiat`, and `ineligibilityReason`
`close`	User dismissed the Mesh Link modal. Triggers the `onExit` callback.	• `page`: The page the user was on when they exited. `'transferExecutedPage'` means the transfer completed before exit.

Complete event reference

SDK Event Type	Description of Occurrence	Payload Details
`pageLoaded`	Triggered when the first page is fully loaded. The first page the user sees may differ based on use case.	No additional payload.
`methodSelected`	Triggered on `HomePage` when the user selects a particular method for their flow.	• `method`: The selected method type (‘embedded’ / ‘manual’ / ‘buy’)
`close`	Triggered when the user exits the Mesh Link modal.	• `page`: the page the user was on when they exited. • Note: In the context of a transfer flow, `page: 'transferExecutedPage'` would indicate the full flow was successful because the user exited from the Success page. If the page is anything else, the flow wasn’t successfully completed.
`integrationSelected`	Triggered when a user selects an integration from the catalog list.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `userSearched?`: true/false if the user searched selected this integration from search results or not.
`legalTermsViewed`	Triggered if a user views the terms of use page in Link.	No additional payload.
`credentialsEntered`	Triggered when a user submits exchange login credentials.	No additional payload.
`integrationMfaRequired`	Triggered when the user is prompted to enter MFA in an exchange authentication flow.	No additional payload.
`integrationMfaEntered`	Triggered when the user enters their MFA code in an exchange authentication flow.	No additional payload.
`integrationOAuthStarted`	Triggered when an exchange’s OAuth window is launched in authentication flow.	No additional payload.
`integrationAccountSelectionRequired`	Triggered if user is prompted to select a specific account within linked exchange.	No additional payload.
`integrationConnected`	Triggered when a user successfully connects to an integration.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `accessToken` payload: The access token to the user account and relevant metadata about the integration
`integrationConnectionError`	Triggered when there is an error in connecting to an integration.	• `errorMessage`: Descriptive error message.
`transferStarted`	Triggered when the user begins the transfer flow. This means they have successfully connected an account and have moved on to either configuring or previewing their transfer. It does not mean they have initiated a transfer of assets.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration.
`transferAssetSelected`	Triggered when the user selects an asset to transfer. This does not relate to assets used for funding operations. This is about the asset being transferred.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `symbol`: Currency symbol
`transferNetworkSelected`	Triggered when the user selects a network to transfer on.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `symbol`: Currency symbol • `networkId`: Selected network identifier • `networkName`: Selected network name
`transferAmountEntered`	Triggered when the user enters an amount to transfer.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `symbol`: Currency symbol • `networkId`: Selected network identifier • `networkName`: Selected network name • `amount`: Amount the user enters for transfer
`transferNoEligibleAssets`	Triggered when there are no assets in the user’s account eligible for the transfer, or Mesh cannot use the assets in the account to fund the transfer.	• `arrayOfTokensHeld`: A list of tokens held in the user’s account • `symbol`: Currency symbol • `amount`: Amount of holding • `amountInFiat`: Amount of holding in fiat • `ineligibilityReason`: Why the token is ineligible. • `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `noAssetsType`:
`transferConfigureError`	This may happen if the session linkToken expires during the configuration flow of a transfer. Very rare.	• `errorMessage`: Descriptive error message. • `requestId`:
`transferPreviewed`	Triggered when a user previews the details of a pending transfer.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `symbol`: Currency symbol • `networkId`: Selected network identifier • `networkName`: Selected network name • `amount`: Crypto amount of the transfer • `amountInFiat` (optional): Amount in fiat currency • `fiatCurrency`: fiat currency symbol for the `amountInFiat` value. • `toAddress`: Destination address • `fees`: • `institutionTransferFee` • `estimatedNetworkGasFee` • `customClientFee` • `fiatPurchaseStrategy`: an enumeration of a fiat funding option used to fund this transaction plus any applicable `tradingFee`. • `cryptocurrencyFundingOptionType`: an enumeration of any funding options used to fund this transaction plus any applicable `cryptocurrencyConversionFee` or `depositFee`. • `previewId`: Unique ID for the preview
`transferPreviewError`	Triggered when there is an error in building a transfer preview.	• `errorMessage`: Descriptive error message.
`linkTransferQRGenerated`	Triggered when the user lands on the Manual QR screen.	• `token` (optional): Token symbol for the transfer • `network` (optional): Network being used • `toAddress` (optional): Destination address • `qrUrl` (optional): Generated QR code URL
`fundingOptionsViewed`	Triggered when the user views the funding options page.	No additional payload.
`fundingOptionsUpdated`	Triggered when the user makes updates to the selected funding options and clicks save (ie. saves a new funding strategy).	No additional payload. When a user saves a new funding strategy, it would build a new Preview, which would fire a new `transferPreviewed` event with new funding options enumerated.
`transferInitiated`	Triggered when the user clicks to Proceed from the Preview screen. This will send a request to transfer to the exchange or wallet, which the user then needs to approve (via 2FA for exchange, or signing for wallet).	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `symbol`: Currency symbol • `networkId`: Selected network identifier • `networkName`: Selected network name • `amount`: Crypto amount of the transfer • `amountInFiat` (optional): Amount in fiat currency • `fiatCurrency`: fiat currency symbol for the `amountInFiat` value. • `toAddress`: Destination address • `fees`: • `institutionTransferFee` • `estimatedNetworkGasFee` • `customClientFee` • `fiatPurchaseStrategy`: an enumeration of a fiat funding option used to fund this transaction plus any applicable `tradingFee`. • `cryptocurrencyFundingOptionType`: an enumeration of any funding options used to fund this transaction plus any applicable `cryptocurrencyConversionFee` or `depositFee`.
`executeFundingStep`	Triggered when there is a success or error on a funding operation before a transfer.	• `fundingOptionType`: The operation that has completed or failed. • `status`: Outcome of the funding operation. • `errorMessage`: Descriptive error message.
`gasIncreaseWarning`	Triggered after funding operations and before initiation of transfer if the cost of gas has gone higher than the buffered estimate shown to the user on the Preview page.	No additional payload.
`transferMfaRequired`	Triggered when the user is prompted to enter an MFA code to perform an exchange transfer.	No additional payload.
`transferMfaEntered`	Triggered when the user submits their MFA code to perform an exchange transfer.	No additional payload.
`transferKycRequired`	Triggered when the user has not completed KYC in the linked account, is prompted to do so before being able to transfer assets.	No additional payload.
`transferExecuted`	Do not use. Obsolete.	Do not use. Obsolete.
`transferCompleted`	Triggered when the user views the Success page at the conclusion of the transfer flow. We recommend using the `onTransferFinished()` callback function to handle the experience when a user returns to your app after a successful transfer.	`transferFinished` payload: • `status`: pending / succeeded / failed • `txId`: A unique client identifier • `transferId`: A unique Mesh identifier • `txHash?`: A unique blockchain identifier • `fromAddress`: Address transfer is sent from • `toAddress`: Address transfer is sent to • `symbol`: Symbol of asset being transferred • `amount`: Amount being transferred • `amountInFiat`: Fiat equivalent of transfer amount • `totalAmountInFiat`: Total amount transferred, including transfer-related fees • `networkId`: Selected network identifier • `networkName`: Selected network name • `refundAddress`: The address that the user can receive back to
`withdrawalRequested`	Triggered when the user confirms a withdrawal in the Mesh-hosted withdrawal flow (`transferType: withdrawal`). Link closes after this event. Use the `onEvent()` callback to trigger any in-app step your withdrawal flow requires (eg. 2FA) and show the user the right screen next. Never send funds based on this event. The send-to address, asset, network, and amount arrive by webhook to your server. See Add Mesh to your withdrawal flow.	• `transferId`: A unique Mesh identifier for the withdrawal • `status`: `pending` or `success`. `success` only if the withdrawal has already completed; in practice it’s `pending`, because your platform hasn’t sent the funds yet. No event is sent if the confirmation fails. • No address or other money movement details
`transferExecutionError`	Triggered when there is an error in executing a transfer.	• `errorMessage`: Descriptive error message.
`seeWhatHappenedClicked`	Triggered when the user clicks the See what happened link on the Transfer Success screen	No additional payload.
`connectionUnavailable`	Triggered when a timeout occurs when attempting to open a wallet on mobile, most likely because the DeFi wallet app is not installed on the device.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `reason`: string
`connectionDeclined`	Triggered when the user rejects a connection request in their wallet, or some error causes an auto-rejection.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `reason`: string. • `networkId`: Selected network identifier • `networkName`: Selected network name • `toAddress`: Address transfer is sent to. • `errorMessage`: Descriptive error message.
`transferDeclined`	Triggered when the user rejects the transfer request in their wallet, or some error causes an auto-rejection.	• `integrationType`: For exchanges, this is the same as the name. For wallets, this is ‘deFiWallet’. • `integrationName`: Name of the selected integration. • `reason`: string • `networkId`: Selected network identifier • `networkName`: Selected network name • `toAddress`: Address transfer is sent to • `symbol`: Symbol of asset being transferred • `amount`: Amount being transferred • `status`: pending / succeeded / failed
`walletMessageSigned`	Triggered when a user signs a message in their wallet to verify ownership.	• `address`: wallet address that signed the message • `isVerified`: true / false indicator of whether the user has signed the exact message sent for signature from this address • `message`: Message that was signed • `signedMessageHash`: The hash of the message signed by the wallet • `timeStamp`: Time stamp of when the signature happened
`verifyDonePage`	Triggered when the user views the Success page after successfully completing the wallet verification flow.	No additional payload.
`verifyWalletRejected`	Triggered when the user rejects the message signature request in their wallet, or some error causes an auto-rejection.	No additional payload.
`done`	Triggered when the user exits Link after successfully completing a read-only account connection flow (ie. for Mesh Verify) or after successfully completing the wallet verification flow (ie. for Mesh Verify).	• `page`: the page the user was on when they exited. • Note: In wallet verification (ie. Mesh Verify) flow, `page: verifyDonePage` would indicate successful completion of the flow. And in a read-only (ie Mesh Portfolio) flow, `page: integrationConnectedPage` would indicate successful completion of the flow.
`registerTransferError`	Shown when we are unable to receive the transfer hash from a self-custody wallet at the conclusion of a transfer flow.	• `errorMessage`: Descriptive error message.

What’s next

For platform-specific setup instructions for consuming these events with callback functions, see Use Mesh’s callback functions.

AI coding reference (llms.txt)

AI coding reference — a compact summary of this page’s APIs, parameters, and patterns for use by AI coding assistants (following the llms.txt standard). Human readers can safely ignore this.llms.txt — Mesh SDK eventsComplete reference of all SDK events fired via the onEvent callback during a Link session.Core events to wire first:

pageLoaded: Link launched successfully. No payload.
integrationConnected: User connected account. Payload: integrationType, integrationName, accessToken (has tokenId).
transferPreviewed: User viewed preview. Payload: symbol, amount, amountInFiat, toAddress, fees (institutionTransferFee, estimatedNetworkGasFee, customClientFee), previewId.
transferInitiated: User clicked Proceed. Same payload structure as transferPreviewed.
transferCompleted: User reached Success page. Triggers onTransferFinished. Use onTransferFinished for business logic; use this event for analytics.
transferNoEligibleAssets: No matching assets. Payload: arrayOfTokensHeld (each has symbol, amount, amountInFiat, ineligibilityReason).
close: User dismissed Link. Payload: page. If page === 'transferExecutedPage' → full flow completed.

Withdrawal event: withdrawalRequested fires when the user confirms a Mesh-hosted withdrawal (transferType: withdrawal); Link then closes. Payload: transferId, status (pending | success; pending in practice). Followed by close. Use it to trigger 2FA or update UI only; it carries no money movement details. Send funds only from the server-side withdrawal webhook.Wallet verification events: walletMessageSigned (payload: signedMessageHash, message, address, timeStamp, isVerified) | verifyWalletRejected | verifyDonePageOther notable events: integrationSelected | transferDeclined | connectionDeclined | transferExecutionError | linkTransferQRGenerated (manual QR deposit) | executeFundingStep | done (read-only or verify flow complete, payload has page)Platform note: onEvent setup varies by platform — see Use Mesh’s callback functions guide for platform-specific initialization.

Guides

API Reference

Mesh SDK events

Overview

SDK Callback Functions

Core events

Complete event reference

What’s next

​Overview

​SDK Callback Functions

​Core events

​Complete event reference

​What’s next

Overview

SDK Callback Functions

Core events

Complete event reference

What’s next