Skip to main content
By the end of this guide, you’ll have a polished, production-ready integration with a well-designed entry point, clean session handling, a great return-user experience, and real-time webhook notifications.
Before you start
  • Your core integration is working end-to-end in sandbox: you can fetch a Link Token, launch the SDK, and handle callbacks
  • You’ve set up Mesh Managed Tokens for return users (see Supercharge return-users)

​
Overview

The Mesh SDK handles the full user journey of connecting accounts and initiating transfers — but there are a few things you’ll want to set up on your side to make the experience seamless from start to finish.

​
For all implementations

Content: A common approach to a button is “Direct deposit” or “Pay with crypto” or “Connect an account”. These are all fine as they set clear expectations. But wherever possible, lead with words that relay the benefit of Mesh (ie. security). This helps users understand not just that this exists, but rather why they should try it (in connected account flows, users can’t misconfigure a transfer and lose assets). An example would be subtext that says “Securely send to the correct address and network” and/or using a shield or some other security-oriented icon. Images: Lead with icons for the top exchanges and wallets (ie. Binance, Coinbase, MetaMask, Phantom, etc.). Many users don’t yet recognize the Mesh brand, so we would not recommend leading with Mesh branding. Return users: Create a dedicated entry point for return users. If someone deposits with Coinbase, chances are they’ll deposit from that same account in the future. So consider placing a “Deposit from Coinbase” button next to the general button whenever a user has successfully connected an account. See the Supercharge return-users guide for more details. Link has a modern, polished design system by default. However, you can configure the interface to closely match your own design system. Fonts, colors, and even loading animations can be updated, making Link appear more native to your platform. This minimizes the seam between your product and Mesh, enhancing the overall experience.
In the Mesh developer dashboard, go to Account > Link Configuration > Interface to make these configurations.
Image

​
Handle a clean end of session

When a user successfully completes a transfer, they will end on a success screen and can click “Done.” This will end the current Link session.
  1. When the user lands back on your product surface, acknowledge a pending transaction. Most clients flash a banner for this (eg. “Deposit pending”).
    1. Why? Crypto users are used to waiting some time to see balances update or payments complete after manually initiating a transaction. But remember, they see a Success screen in Link at the end of a successful flow, so it can be nerve-wracking if they don’t see that reflected in your app instantly.
    2. You can trigger this banner or notification using the onTransferFinished() callback function, whose payload contains data about a pending transfer. See the Mesh Link SDK Events guide for more information on this.

​
Create a delightful return-user experience

Can you imagine having to add your credit card to Apple Pay every single time you wanted to tap-to-pay? That would defeat the whole purpose. But you’re willing to put in the effort to set up Apple Pay because you know it will be effortless every time after that. Mesh is similar… a user must connect their account the first time, but can enjoy 1 or 2 click transactions on subsequent visits.
See the Supercharge return-users guide for instructions on how to capture accessTokens and pass them on subsequent user sessions.

​
Consume Mesh webhooks for real-time notifications of transfer status

Mesh will confirm success to the user (and to you via an SDK event) when the integration confirms successful receipt of the order to Mesh. At that point, the user has done all they need to, so we let them go. However, this does not mean their transaction is complete. Self-custody wallets (eg. MetaMask, Phantom, etc.) typically post to the blockchain almost immediately upon user signing, but centralized exchanges (eg. Binance, Coinbase, etc.) often take some time to do compliance checks, and batch transactions to save on gas fees. Most exchanges post within 30s, but in some instances it could take minutes, hours, or even days. This is why we strongly encourage all clients to consume Mesh webhooks for proactive, real-time notifications regarding transfer status. You can consider a transaction pending until you receive a succeeded event, at which point you can release inventory or credit the user’s account.
Refer to the Transfer status webhooks guide for more information.

​
For “embedded” implementations

If you’re embedding Mesh’s web SDK into a container in your product surface, these tips are for you. You must ensure that the container in which Link is loaded abides by certain minimum & maximum dimensions or you’ll end up with scenarios where buttons are below the fold, or the user must scroll on single screens (up-down or even left-right). Maintaining the intended dimensions of the SDK ensures that the user experience is preserved.
  • Mobile screens:
    • The container should maximize the space available for the iframe
  • Stationary screens:
    • Minimum height of iframe container: 450px
    • Recommended height of iframe container: 665px
Call for a Link Token and initialize an SDK session as soon as the user logs into your app. This allows you to pre-load Link in the background, which will make it render instantly when the user clicks “Deposit” or “Buy” within your app, making it feel native. Link loads fairly quickly, but this can make a difference for users with slower connections or devices. You’ll also want to implement refresh logic to call for a new Link Token and pre-load a new SDK session every 50 mins. The Mesh SDK has a 60min session expiry. If a user doesn’t engage with deposit for 59mins, the session may expire while they’re in it. A 50min rule leaves 10mins of validity on the user session if they start at the end of that refresh window, which should be a very comfortable buffer.
  1. Use connection.closeLink() to kill the active Link session
    1. If embedding Link: remove your custom iframe from the DOM
  2. Request a new Link Token.
  3. Launch a new Link SDK session with a new customIframeId

​
Handle a clean end of session

There are expanded instructions for handling session ends when Link is embedded.
  1. Use the onTransferFinished() callback function to…
  2. Use connection.closeLink() to kill the active Link session and remove your custom iframe from the DOM if embedding Link. Then either…
    1. Keep the container open.
      1. Request a new Link Token. Launch a new Link SDK session with a new customIframeId which lands the user back at the beginning of the Deposit experience. This will show a very brief loading animation. This is typical when Mesh is hosting all crypto deposit activity for your app. Or…
    2. Close the container.
      1. You should still request a new Link Token and launch a new Link SDK session with a new customIframeId in the background so that it renders instantly for any subsequent deposit.
  3. Acknowledge the pending transaction with a banner or some other notification (eg. “Deposit pending”).

​
Handle user navigation within your app surface

This is only applicable to clients that are using Mesh for multiple user flows. For example, some use Mesh to do all of the following 3 things, each of which result in Link sessions in different places.
  1. Power all or part of their crypto Deposit flow
  2. Add Mesh’s onramp integrations to the lineup of onramps in their Buy flow
  3. Add “connect an account” to their Withdrawal flow for automated address retrieval
  • Pre-load Link in only one of those places (whichever is most common, likely deposit).
  • Persist / maintain that Link session when the user navigates away from that tab.
    • Why? If the user is on “Deposit” and sees a Link SDK session, then clicks to “Buy” or “Withdraw”, you won’t have to load up a new session if they come back.
    • Be sure to follow the normal 50min refresh guidance.
  • If the user starts a new Link session in another area (eg. from the “Buy” tab), kill the original/active SDK session before opening the new one.
    • Why? A user can have two active Link sessions at a time, but it may lead to undesirable edge cases when communicating with wallets and exchange OAuth applications. Since you are persisting the user’s SDK session in one place (eg. the “Deposit” tab), you should kill that session before starting the new one (eg. in the “Buy” tab).
    • Instructions:
      1. Use connection.closeLink() to kill the active Link session (and remove your custom iframe from the DOM if applicable).
      2. Request a new Link Token for the new session.
      3. Launch a new Link SDK session.

​
For iOS implementations

​
Update your iOS app’s plist for smooth wallet connectivity

The Mesh SDK enables seamless connectivity with self-custody wallets by leveraging deep linking to redirect users to their wallet applications for actions such as signing messages or initiating transactions. To ensure proper functionality, your iOS application must include the list of native wallet links in its Info.plist configuration. Native links vs Universal Links, and why you should add wallet native link to your plist:
  • Mesh uses Universal Links for many integrations. Unlike custom URL schemes, Universal Links don’t require adding entries to Info.plist. However, Universal Links depend on proper server configuration (the apple-app-site-association file) and domain verification by Apple. When Universal Links fail—due to configuration issues, the app not being installed, or the user’s first interaction—the system falls back to opening the link in the browser or using custom URL schemes as a fallback mechanism.
  • Each wallet application has its own unique URL scheme (e.g., metamask:// for MetaMask, trust:// for Trust Wallet). These schemes allow the iOS system to route the user to the appropriate application installed on their device.
  • iOS apps must explicitly declare the URL schemes they interact with in the Info.plist file under the LSApplicationQueriesSchemes key. Failing to include these schemes can prevent the app from opening wallet applications, breaking the SDK’s logic and key workflows.
  • This configuration aligns with iOS security best practices by ensuring only verified wallets can be accessed.
  1. Update Info.plist: Add the LSApplicationQueriesSchemes key to your app’s Info.plist file. This key should include all native wallet URL schemes supported by our SDK. Recommended List: 
    <key>LSApplicationQueriesSchemes</key>
<array>
  <string>bitcoin</string>
  <string>bitkeep</string>
  <string>bitcoincom</string>
  <string>bnc</string>
  <string>cbwallet</string>
  <string>dfw</string>
  <string>exodus</string>
  <string>ledgerlive</string>
  <string>metamask</string>
  <string>okx</string>
  <string>phantom</string>
  <string>rabby</string>
  <string>rainbow</string>
  <string>robinhood-wallet</string>
  <string>tpoutside</string>
  <string>tronlinkoutside</string>
  <string>trust</string>
  <string>uniswap</string>
  <string>zengo</string>
</array>
    Note: This list is based on Mesh’s most-used integrations and may change over time. Do not add more than 50 items — this is a hard limit enforced by Apple.
  2. Verify Native Link Functionality: Test the integration to ensure your app properly detects wallet installations and redirects users to the appropriate application.

​
What’s next

Next up: Prepare for go-live — when you’re happy with the experience in sandbox, this guide walks you through getting your production credentials and launching.
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 — Polish the experienceProduction-readiness checklist: entry point design, session lifecycle management, embedded sizing, SDK preloading, return-user UX, webhook consumption, iOS plist for wallet deep links.Entry point: Use action-oriented copy (“Direct deposit”, “Pay with crypto”). Lead with exchange/wallet icons (Binance, Coinbase, MetaMask, Phantom). Add dedicated return-user entry point per connected account.Session lifecycle: Preload Link on user login; refresh every 50 min (Link session expires at 60 min). Refresh cycle: connection.closeLink() → new Link Token → new SDK session with new customIframeId. After transfer: show “Deposit pending” banner via onTransferFinished(), then closeLink(), then either keep container open with new session or close.Embedded sizing: Min height 450px, recommended 665px. Maximize iframe on mobile.Multi-flow apps: Persist Link session when user navigates between tabs. Kill session with closeLink() before starting a new one in a different area.iOS plist (LSApplicationQueriesSchemes): Add native wallet URL schemes. Max 50 items (Apple hard limit):
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>tronlinkoutside</string>
  <string>bitcoin</string>
  <string>zengo</string>
  <string>okx</string>
  <string>uniswap</string>
  <string>rainbow</string>
  <string>bitkeep</string>
  <string>ledgerlive</string>
  <string>dfw</string>
  <string>exodus</string>
  <string>cbwallet</string>
  <string>bnc</string>
  <string>phantom</string>
  <string>trust</string>
  <string>metamask</string>
</array>
Link customization: Dashboard > Account > Link Configuration > Interface for fonts, colors, loading animations.