JavaScript Browser SDK

meso-js is a library for embedding Meso’s on/off-ramps in your dApp or website. The SDK is available on npm and the repo can be found on Github.

To use the SDK, you must have a partnerId which you can request here.

Take a look the example below for a quickstart. This code assumes you have a page with a Buy Crypto button. When pressed, Meso will be initiated for the user to perform a transfer.

import {
  transfer,
  Environment,
  EventKind,
  type MesoEvent,
} from "@meso-network/meso-js";

const buyCrypto = document.querySelector("button#buy-crypto");

buyCrypto.addEventListener("click", () => {
  transfer({
    partnerId: "YOUR_PARTNER_ID", // Your unique Meso partner ID.
    environment: Environment.SANDBOX, // SANDBOX | PRODUCTION
    sourceAmount: "100", // The amount (in USD) the user will spend
    destinationAsset: Asset.ETH, // The token the user will receive ("ETH" | "SOL" | "USDC")
    network: Network.ETHEREUM_MAINNET, // The network to use for the transfer
    walletAddress: "<WALLET_ADDRESS>", // The user's wallet address obtained at runtime by your application

    // A callback to handle events throughout the integration lifecycle
    onEvent({ kind, payload }: MesoEvent) {
      // Handle events here...
      console.log(kind, payload);
    },

    // A callback to handle having the user verify their wallet ownership by signing a message
    async onSignMessageRequest(message: string) {
      // Have the user sign a message via their wallet and return the result.
      // It is up to you to implement message signing.
    },
  });
});

​

Requirements

To use Meso, you must have a partnerId which you can request here.

​

Installation

Once you have a partner account, you can add the SDK to your application, install it from npm.

pnpm i @meso-network/meso-js

​

Initiating a Transfer

When you are ready to present the user with a Transfer, call the transfer() method from the SDK. This will open an iframe on your page to guide the user through the Transfer.

import { transfer, Asset, Network } from "@meso-network/meso-js";

const { destroy } = transfer({
partnerId: "partner-id", // Your unique Meso partner ID.
sourceAmount: "100", // The amount the user will spend to perform the transfer. For on-ramping, this value will represent a value in `USD`.
destinationAsset: Asset.ETH, // The asset the user will receive in the transfer. For on-ramping, this will be a token such as `ETH` or `SOL`.
network: Network.ETHEREUM_MAINNET, // The network to use for the transfer
walletAddress: "<WALLET_ADDRESS>", // The user's wallet address
// ... other options
});

View the reference to see all configuration options.

​

Requirements

​

Content Security Policy

meso-js can be used in most web browsers and application stacks. However, you will need to ensure your Content Security Policy (CSP) will allow Meso’s iframe and network calls from your page.

Your CSP should enable at least the following rules:

• frame-src

• connect-src

Content-Security-Policy: frame-src https://*.sandbox.meso.network/; connect-src https://*.sandbox.meso.network/;

​

Supported browsers

Meso’s on/off-ramp will work in first-party web applications. For, mobile support (such as webViews) see React Native and iOS.

Meso supports the latest versions of:

• Chrome (Desktop, iOS, Android)

• Safari (macOS)

• Safari (iOS)

• Brave, Arc, and other Chrome-like browsers

• Firefox

If you have issues with specific browsers/environments, contact mailto:support@meso.network.

​

Caveats

​

Next.js and SSR

meso-js will not work in a server-side environment. Ensure you are deferring initialization until your client-side code is ready in the browser. In Next.js, the it is recommended you use client components.

You can also check out an example integration on Github: https://github.com/meso-network/meso-js-nextjs-example

​

Reference

All TypeScript definitions can be found in the meso-js repo.

​

transfer()

The transfer function takes a TransferConfiguration object and returns a TransferInstance which contains the following:

import {
  transfer,
  Environment,
  EventKind,
  type MesoEvent,
} from "@meso-network/meso-js";

const { destroy } = transfer({
partnerId: "YOUR_PARTNER_ID", // Your unique Meso partner ID.
environment: Environment.SANDBOX, // The environment to use for the transfer (sandbox, production)
sourceAmount: "100", // The amount the user will spend to perform the transfer. For on-ramping, this value will represent a value in `USD`.
destinationAsset: Asset.ETH, // The asset the user will receive in the transfer. For on-ramping, this will be a token such as `ETH` or `SOL`.
network: Network.ETHEREUM_MAINNET, // The network to use for the transfer
walletAddress: "<WALLET_ADDRESS>", // The user's wallet address obtained at runtime by your application

  // A callback to handle events throughout the integration lifecycle
  onEvent({ kind, payload }: MesoEvent) {
    // Handle events here...
    console.log(kind, payload);
  },

  // A callback to handle having the user verify their wallet ownership by signing a message
  async onSignMessageRequest(message: string) {
    // Have the user sign a message via their wallet and return the result.
    // It is up to you to implement message signing.
  },

});

destroy(); // The Meso on/off-ramp is now removed.

​

TransferConfiguration

The transfer method exported from the SDK allows the following configuration options.

​

Environment

The Meso environment to be used for the Transfer. See Environments for more.

• SANDBOX – This uses fake assets and stubbed onboarding data for you to test your integration. No funds are moved in this environment.

• PRODUCTION – This uses real assets, funds, and KYC/user data to perform transfers.

​

Asset

A crypto asset (token) reference.

• ETH

• SOL

• USDC

• POL

​

Network

The network the transfer will run on. Currently, only mainnet is supported.

• ETHEREUM_MAINNET

• SOLANA_MAINNET

• POLYGON_MAINNET

• OP_MAINNET

• ARBITRUM_MAINNET

• BASE_MAINNET

​

Layout

The Layout allows you to provide position and offset values to determine where in the viewport the Meso transfer will render.

Note: Onboarding flows are unaffected by this configuration and will always be centered in the viewport.

• position: Position – The placement of the Meso transfer UI within the viewport

• offset - A single pixel value or an object where both horizontal and vertical axes can be specified.

const layout: Layout = { position: Position.TOP_LEFT };

​

Position

• TOP_RIGHT (default)

• BOTTOM_RIGHT

• BOTTOM_LEFT

• TOP_LEFT

• CENTER

​

AuthenticationStrategy

Depending on your integration, you may have different requirements for users authenticating with Meso. In all scenarios, the user will still be required to perform two-factor authentication (2FA) and, in some cases provide email/password.

• WALLET_VERIFICATION (default) - The user will be required to sign a message to verify ownership of the wallet.

• HEADLESS_WALLET_VERIFICATION - In cases such as embedded wallets, message signing may need be transparent to the user. In these cases, passing will allow you to perform message signing yourself in the background.

• BYPASS_WALLET_VERIFICATION - In the case where pre-deployment smart contract wallets are being used and wallet verification cannot be performed, you can skip wallet verification altogether and rely on Meso’s other authentication mechanisms (such as two-factor auth).

​

onSignMessageRequest

The onSignMessageRequest callback will be fired when the user needs to sign a message to verify ownership of their wallet.

The function takes a message as a string and you are required to return the signed message or undefined if the user rejects the signing or if there is an error.

⚡️ You will have to implement your own signing function.

onSignMessageRequest(async (message: string) => {
  // Have the user sign a message via their wallet and return the result.
  // It is up to you to implement message signing.
  const result = await signMessage(message);

  if (result.isOk()) {
    return result;
  }

  return undefined;

});

​

onEvent

An optional handler to notify you when an event or error occurs. This is useful for tracking the state of the user through the experience.

onEvent((event: MesoEvent) => {
  switch (kind) {
    // The transfer has been approved and will go through, however funds have not yet moved.
    case EventKind.TRANSFER_APPROVED:

    // The transfer has been finalized and the assets have been transferred.
    case EventKind.TRANSFER_COMPLETE:
      console.log(payload.transfer);
      break;

    // There was an issue with the provided configuration
    case EventKind.CONFIGURATION_ERROR:
      console.error(payload.error.message);
      break;

    // The `network` provided in the configuration is not supported
    case EventKind.UNSUPPORTED_NETWORK_ERROR:
      console.error(payload.error.message);
      break;

    // The `destinationAsset` provided in the configuration is not supported
    case EventKind.UNSUPPORTED_ASSET_ERROR:
      console.error(payload.error.message);
      break;

    // A general error has occurred
    case EventKind.ERROR:
      console.error(payload.error.message);
      break;

    case EventKind.READY:
      console.log("The Meso experience is ready.");
      break;

    case EventKind.CLOSE:
      console.log("Meso experience closed.");
  }

});

See MesoEvent for more.

​

MesoEvent

The MesoEvent type contains a kind and, if required, a typed payload.

​

Transfer (type)

An object representing an executed transfer.

​

TransferStatus

• APPROVED: The transfer has been approved and is pending completion. At this point, funds have not yet been moved.

• COMPLETE: The transfer is complete and the user’s funds are available.

• DECLINED: The transfer has failed.

• EXECUTING: The transfer is in flight.

​

MesoError

An error surfaced from the SDK.