mode = ModeOptions.bridge

Bridge mode allows your users to transfer similar assets between any chain supported by Kima. I.e. USDC on Arbitrum to USDT on Avalance.

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.dark }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
      />
    </KimaProvider>
  )
}

On testnet it should look something like this. The test tokens are called USDK and can be obtained from the Kima faucet.

Add the widget to your React project using npm or your favorite javascript package manager.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

For the purposes of this example, we'll just add the widget to App.tsx, but it can go anywhere it makes sense for your project.

Open App.tsx, wrap your existing componts with the <KimaProvider> and add the <KimaTransactionWidget> component.

If you don't have one already, you'll need to get a (free) WallectConnect project ID from Reown Cloud and add it to the <KimaProvider> component.

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/index.css'

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId='your-project-id'
      networkOption={NetworkOptions.testnet}
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
      />
    </KimaProvider>
  )
}

export default App

In the following sections, we'll go through the framework specific configuration for Vinalla React and NextJS.

The Kima Transaction Widget is a ready made React component that allows users to transfer like assets between chains using the Kima protocol. Combined with the Kima Transaction Backend, it is the quickest way to integrate Kima into your dApp.

Modes

The Kima Transaction Widget supports 3 modes:

1. Payment

2. Bridge

3. Status

Payment

In Payment Mode, the user can send funds from any chain supprted by Kima to the specified payment address and chain. See the Payment Mode section for more information.

I.e. Pay 12.34 USDC from Polygon or Solana

Bridge

In Bridge Mode, the user is able to send funds to and from any chain supported by Kima. See the Bridge Mode section for more information.

I.e. Send 12.34 USDT on BSC and receive USDC on Arbitrum

Status

Status Mode displays the progress of an existing transaction. See the Status Mode section for more information.

mode = ModeOptions.payment

Payment mode allows your users to pay for a product or service using stablecoins from any chain supported by Kima.

• The payment details are passed into the Widget via the transactionOption prop (required)

• The user can choose to pay from any chain and token supported by Kima. The funds will be transferred to the wallet and chain specified in the transactionOption prop

• The title and subtile can be customized using the titleOption and paymentTitleOption props

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  SupportNetworks,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/dist/index.css'

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.payment}
        kimaBackendUrl='http://localhost:3001'
        titleOption={{
          initialTitle: 'New Purchase'
        }}
        paymentTitleOption={{
          title:
            'Buy MyFirst NFT',
          style: {
            fontSize: '1.2em',
            fontWeight: '500',
            color: '#DDDDDD'
          }
        }}
        transactionOption={{
          targetChain: SupportNetworks.SOLANA,
          targetAddress: "5tvyUUqPMWVGaVsRXHoQWqGw6h9uifM45BHCTQgzwSdr",
          amount: 12.34,
          currency: "USDK",
        }}
      />
    </KimaProvider>
  )
}

export default App

You should see a page that looks like this:

The payment (target) wallet and chain will show on the next step when the user approves the transfer amount.

The procedure for adding the Kima Transaction Widget to a NextJS app is very similar to the React tutorial but you should be aware that you will need to export the widget component as a dynamic component with {ssr: false} so that the application runs the widget on the client side.

To create a new app, you can run npx create-next-app <your-app-name>. Then install the Kima Widget and its peer dependencies.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

If you don't have one already, you'll need to get a (free) WallectConnect project ID from Reown Cloud and add it to the <KimaProvider walletConnectProjectId='your-project-id' /> component.

Within your app directory, create a components directory and inside that create a file named widget.jsx with the following code:

Copy

import dynamic from 'next/dynamic';
import React from 'react';

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions,
} from '@kimafinance/kima-transaction-widget';
import '@kimafinance/kima-transaction-widget/index.css';

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId='your-project-id'
      networkOption={NetworkOptions.testnet}
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
      />
    </KimaProvider>
  )
}

const DynamicApp = dynamic(() => Promise.resolve(App), {
  ssr: false,
});

export default DynamicApp;

You can now use DynamicApp on whatever page you like. In our example, we will create an index page index.jsx in our pages directory and copy the following code:

Copy

import React from 'react';
import DynamicApp from '../components/widget';

const HomePage = () => {
  return <DynamicApp />;
};

export default HomePage;

When you visit localhost:3000 you will see something like this:

See the Configuration options section for more details on setting up the widget.

Add the widget to your React project using npm or your favorite javascript package manager.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

For the purposes of this example, we'll just add the widget to App.tsx, but it can go anywhere it makes sense for your project.

Open App.tsx, wrap your existing componts with the <KimaProvider> and add the <KimaTransactionWidget> component.

If you don't have one already, you'll need to get a (free) WallectConnect project ID from and add it to the <KimaProvider> component.

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/index.css'

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId='your-project-id'
      networkOption={NetworkOptions.testnet}
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
      />
    </KimaProvider>
  )
}

export default App

Polyfills

Note that if you are using a later version of webpack (>= 5), you will need to polyfill node core modules using react-app-rewired.

This can be resolved by adding a file at the root of your project named config-overrides.js. Paste the following content into the file:

const { ProvidePlugin } = require('webpack')

module.exports = function override(config, env) {
  return {
    ...config,
    module: {
      ...config.module,
      rules: [
        ...config.module.rules,
        {
          test: /\.js$/,
          enforce: 'pre',
          use: ['source-map-loader']
        },
        {
          test: /\.cjs$/,
          type: 'javascript/auto'
        },
        {
          test: /\.wasm$/,
          type: 'webassembly/async'
        },
        {
          test: /\.m?js/,
          type: 'javascript/auto'
        },
        {
          test: /\.m?js/,
          resolve: {
            fullySpecified: false
          },
        },
        {
          test: /\.json$/,
          use: 'json-loader',
          type: 'javascript/auto' // This is important to prevent Webpack 5 from treating JSON as ESM
        }
      ]
    },
    plugins: [
      ...config.plugins,
      new ProvidePlugin({
        Buffer: ['buffer', 'Buffer'],
        process: 'process/browser'
      })
    ],
    resolve: {
      ...config.resolve,
      fallback: {
        assert: 'assert',
        buffer: 'buffer',
        console: 'console-browserify',
        constants: 'constants-browserify',
        crypto: 'crypto-browserify',
        domain: 'domain-browser',
        events: 'events',
        fs: false,
        http: 'stream-http',
        https: 'https-browserify',
        os: 'os-browserify/browser',
        path: 'path-browserify',
        punycode: 'punycode',
        process: 'process/browser',
        querystring: 'querystring-es3',
        stream: 'stream-browserify',
        _stream_duplex: 'readable-stream/duplex',
        _stream_passthrough: 'readable-stream/passthrough',
        _stream_readable: 'readable-stream/readable',
        _stream_transform: 'readable-stream/transform',
        _stream_writable: 'readable-stream/writable',
        string_decoder: 'string_decoder',
        sys: 'util',
        timers: 'timers-browserify',
        tty: 'tty-browserify',
        url: 'url',
        util: 'util',
        vm: 'vm-browserify',
        zlib: 'browserify-zlib'
      }
    },
    experiments: {
      asyncWebAssembly: true
    },
    ignoreWarnings: [/Failed to parse source map/]
  }
}

Example

mode = ModeOptions.status

Status mode displays the progress of a transaction that has already been submitted to Kima. This is useful if the normal flow was interrupted and the status needs to be displayed again. Usually the transaction status view will display automatically after the user approves and submits the transaction.

⚠️ txId is the transaction id returned from the /submit endpoint- not the transaction hash. I.e 22843

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.dark }}
        mode={ModeOptions.status}
        kimaBackendUrl='http://localhost:3001'
        txId={22843}
      />
    </KimaProvider>
  )
}

You would see a page that looks like this:

The transaction status will be displayed on the next step when the user approves the transfer amount.

Configuration options

Configure the widget's look and feel

There are numerous ways to configure the Widget for your own preferences and the look and feel of your dApp, which you can do via the following props:

Theme

The Theme prop controls whether the Widget is in light or dark mode and their background colours:

• Required

• Type: ThemeOptions

  • colorMode (required): ColorModeOptions.light | ColorModeOptions.dark

  • backgroundColorLight (optional): string

  • backgroundColorDark (optional): string

  <KimaTransactionWidget
    theme={{
      colorMode: ColorModeOptions.light,
      backgroundColorLight: '#CCCCCC', // background color of widget when light mode
      backgroundColorDark: '#FFDDFF' // background color of widget when dark mode
    }}
  />

Title

The Title prop enables you to give the widget whatever title you want and can be configured for each step of the widget.

• Optional

• Type: TitleOption:

  • initialTitle (optional): string

  • confirmTitle (optional): string

  <KimaTransactionWidget
    titleOption={{
        initialTitle: 'New Purchase'
    }}
  />

Payment Title

The PaymentTitle prop allows you to optionally set the title that appears on the payment screen if you are using the Payment component.

• Optional

• Type: PaymentTitleOption

  • title (optional): string

  • style (optional): object

  <KimaTransactionWidget
    paymentTitleOption={{
      title:
        'You can now purchase our NFT on Polygon, using funds from other chains.',
      style: {
        fontSize: '1.2em',
        fontWeight: '500'
      }
    }}
  />

HelpUrl

This is a string, which should be to your own help documentation or FAQ. If unset, the link will default to Kima's help documentation.

• Optional

• Type: string

mode: Configure the widget's functionality

• Required: true

• Type: ModeOptions

  • payment: Payment scenario

  • bridge: Bridge scenario

  • status: mode for tracking the status of a specific Kima transaction

Used to specify the transaction flow scenario of the Widget. See the individual scenarios for more information.

TransactionOption

Sets the default chain, wallet, and amount in the Widget. Required for the Payment mode, optional for the Bridge mode.

• Payment mode: Required, Bridge mode: Optional

• Type: TransactionOption

  • targetChain (optional): SupportNetworks

  • targetAddress (optional): string

  • amount (optional): number

  • currency (optional): string

import { SupportNetworks } from '@kimafinance/kima-transaction-widget'

  <KimaTransactionWidget
    transactionOption={{
      targetChain: SupportNetworks.AVALANCHE, // target chain to receive payment
      targetAddress: '0x8222ADB2A2092c3774105a5F558987265D920C09', // target address to receive payment
      amount: 5 // USDK amount to receive payment
    }}
  />

kimaBackendUrl

This is one of the few props that is mandatory to set, because there are several enpoints which the Widget expects to exist on the Backend. The examples assume the backend server is running locally at localhost:3001. Replace this with the URL of your backend.

• Required: true

• Type: string

For more information see the Kima Transaction Backend section.

kimaExplorer

• Optional

• Type: string

• Default: explorer.kima.network

This is used to specify the URL of Kima's block explorer in the environment you are using. The widget needs this to provide updates to the status screen, as well as allowing users to link to their transactions to view progress.

• Kima Mainnet Explorer: https://explorer.kima.network

• Sardis (Testnet) Explorer: https://explorer.sardis.kima.network

excludeedSourceNetworks, excludeedTargetNetworks

• Optional

• Type: string[]

• Default: []

Chain names to exlude from the widget. Users will not be able to select these chains in the widget. Useful for compliance reasons or to exclude chains not supported by your app.

There is currently no opton to do the opposite- i.e. explicity specify which chains to include.

Excluded target networks will have no effect in payment mode as the target chain, address, and amount are already explicity set.

  <KimaTransactionWidget
    excludedSourceNetworks={['TRX', 'BSC']}
    excludedTargetNetworks={['ETH']}
  />

errorHandler

• Optional

• Type: function

Called when an error occurs. Useful for debugging and logging.

closeHandler

• Optional

• Type: function

Called when the widget is closed.

successHandler

• Optional

• Type: function

Called when the transaction is successful.

txID

Used in Status mode to specify the transaction to track progress for. Only used in status mode, ignored otherwise.

• Status mode: Required, ignored otherwise

• Type: boolean

• Default: -1

Configure Kima Provider

Used to provide the widget with wallet connection and chain switching functionality.

walletConnectProjectId

Used to specify the WalletConnect project id. Visit Reown Cloud and sign up for a free account (WalletConnect is now called Reown) to obtain a project id.

• Required: true

• Type: string

networkOption

Used to specify the network type.

• Required: false

• Type: NetworkOptions

• Default: NetworkOptions.testnet

extneralProvider

If there is already a wallet connection logic elsewhere in your app, an external provider can be passed in. Otherwise, the widget will handle the connection logic on its own.

• Required: false

• Type: ExternalProvider

Compliance

compliantOption

• Required: false

• Type: boolean

• Default: false

If your app requires compliance checks, please contact us for more information. When false (the default), compliance checks are disabled.