Skip to main content

On-ramp tokens

The On-ramp widget is a drop-in solution for web-based games and marketplaces that simplifies the process of purchasing tokens with fiat (e.g. USD) onto the Immutable zkEVM network.

Sections
onramponramp
💡Supported tokens
Only IMX and ETH will be supported to on-ramp into Immutable zkEVM Testnet.

Getting started​

Once you have completed the widget setup, use the WidgetsFactory to create an on-ramp widget. In order to mount the widget, call the mount() function and pass in the id attribute of the target element you wish to mount it to.

import { useEffect } from 'react';
import { checkout } from '@imtbl/sdk';

// create Checkout SDK
const checkoutSDK = new checkout.Checkout();

export function App() {
    // Initialise widgets, create onramp widget and mount
    useEffect(() => {
        (async () => {
            const widgets = await checkoutSDK.widgets({
                config: { theme: checkout.WidgetTheme.DARK },
            });
            const onramp = widgets.create(checkout.WidgetType.ONRAMP)
            onramp.mount("onramp");
        })();
    }, [checkout]);

    return (<div id="onramp" />);
}

Parameters​

The mount() function can also take in parameters to be passed into the widget.

Widget parameters

Parameters are treated as transient and will be reset after the widget is unmounted.

ParameterDescription
tokenAddressThe address of the ERC20 contract to buy.
amountThe ERC20 token amount to buy.
walletProviderNameThe wallet provider name to use for the onramp widget.
import { checkout } from "@imtbl/sdk";

// @ts-ignore
const onramp = widgets.create(checkout.WidgetType.ONRAMP, 
  { config: { theme: checkout.WidgetTheme.DARK }}
);

// add parameters for the onramp widget
onramp.mount('onramp', { tokenAddress: '0xaddress', amount: '10' })

Configuration​

When you first create the widget, you can pass an optional configuration object to set it up. For example, passing in the theme will create the widget with that theme. If this is not passed the configuration will be set by default.

import { checkout } from "@imtbl/sdk";

//@ts-ignore add configuration for the onramp widget
const onramp = widgets.create(checkout.WidgetType.ONRAMP, { config: { theme: checkout.WidgetTheme.DARK }})

// You can update the onramp widget's configuration by calling the update() method
onramp.update({config: {theme: checkout.WidgetTheme.LIGHT}})

Events​

Onramp widget events are emitted when critical actions have been taken by the user or key states have been reached. Below is a table of the possible events for the Onramp Widget.

Event TypeDescriptionEvent Payload
OnRampEventType.SUCCESSA user successfully on-ramped tokens to their wallet.OnRampSuccess
OnRampEventType.FAILUREOn-ramping of tokens failed.OnRampFailed
OnRampEventType.CLOSE_WIDGETThe user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function.

You can use the addListener() function to tap into the events and provider handlers. Use the removeListener() function to stop listening to that event.

import { checkout } from "@imtbl/sdk";

// @ts-ignore
const onramp = widgets.create(checkout.WidgetType.ONRAMP, 
  { config: { theme: checkout.WidgetTheme.DARK }}
);

// add event listeners for the onramp widget
onramp.addListener(checkout.OnRampEventType.SUCCESS, (data: checkout.OnRampSuccess) => {
  console.log("success", data);
});

onramp.addListener(checkout.OnRampEventType.FAILURE, (data: checkout.OnRampFailed) => {
  console.log("failure", data);
});

onramp.addListener(checkout.OnRampEventType.CLOSE_WIDGET, () => {
  onramp.unmount();
});

// remove event listeners for the onramp widget
onramp.removeListener(checkout.OnRampEventType.SUCCESS);

onramp.removeListener(checkout.OnRampEventType.FAILURE);

onramp.removeListener(checkout.OnRampEventType.CLOSE_WIDGET);

Sample code​

This sample code gives you a good starting point for integrating the onramp widget into your application and listening to its events.

import { useEffect, useState } from 'react';
import { checkout } from '@imtbl/sdk';

// create Checkout SDK
const checkoutSDK = new checkout.Checkout();

export function App() {
  const [onramp, setOnramp] =
      useState<checkout.Widget<typeof checkout.WidgetType.ONRAMP>>();

  // Initialise widgets, create onramp widget
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const onramp = widgets.create(checkout.WidgetType.ONRAMP, { config: { theme: checkout.WidgetTheme.DARK }})
      setOnramp(onramp)
    })();
  }, [checkout]);

  // mount onramp widget and add event listeners
  useEffect(() => {
    if(!onramp) return;

    onramp.mount("onramp");

    onramp.addListener(checkout.OnRampEventType.SUCCESS, (data: checkout.OnRampSuccess) => {
      console.log("success", data);
    });
    onramp.addListener(checkout.OnRampEventType.FAILURE, (data: checkout.OnRampFailed) => {
      console.log("failure", data);
    });
    onramp.addListener(checkout.OnRampEventType.CLOSE_WIDGET, () => {
      onramp.unmount();
    });
  }, [onramp])


  return (<div id="onramp" />);
}