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 |
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 |
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 (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(hastokenId).transferPreviewed: User viewed preview. Payload:symbol,amount,amountInFiat,toAddress,fees(institutionTransferFee, estimatedNetworkGasFee, customClientFee),previewId.transferInitiated: User clicked Proceed. Same payload structure astransferPreviewed.transferCompleted: User reached Success page. TriggersonTransferFinished. UseonTransferFinishedfor business logic; use this event for analytics.transferNoEligibleAssets: No matching assets. Payload:arrayOfTokensHeld(each hassymbol,amount,amountInFiat,ineligibilityReason).close: User dismissed Link. Payload:page. Ifpage === 'transferExecutedPage'→ full flow completed.
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.