Using Kima SDK without the widget

The Kima Widget serves as a reference implementation written in React. If your project uses another framework, or you want to make a custom component, it’s possible to interact with the Kima Transaction Backend directly.

Transaction Flow

1. User selects the origin and target chains and amount

2. User approves Kima to transfer origin tokens

3. The transaction details are submitted to the Kima Transaction Backend

4. The UI polls the Kima GraphQL endpoint for status updates until the transaction has completed

Reference Implementation

The React component on the Kima Github:

@Kimafinance/kima-transaction-widget

Selecting Chains and Amount

The frontend component will need to provide the following information. This will be used to calculate the service fee and the approval for Kima to move tokens on behalf of the user.

• Origin (from)

  • chain: this is the chain the user tokens will come from

  • token: the (stable coin) token the user will pay with (or bridge from)

  • address: the source user address- i.e. the connected user

  • amount: the amount of tokens to transfer

• Target (to)

  • Chain: the destination chain

  • Token: the (stable coin) token being delivered

    • In a payment scenario this will be the same as the origin token

  • Address: the receiving address

    • In a bridge transaction this will be same as the connected user

Supported Chains and Tokens

See the list of chains and tokens in the Supported Blockchains section.

Because the Kima blockchain is a public network, you can interact with it however you see fit. You can choose to become a validator, if you want - see Becoming a Validator for more details - or you can build a variety of applications on top of it.

To make developing on top of Kima simpler, we have created a toolkit - the Kima Software Development Kit (SDK).

We provide:

• a standalone server that you can run locally and use as middleware that sits between the front end of your dApp and the Kima blockchain, submitting requests and returning the response to the front end

• a front-end widget with different configuration options that you can easily integrate into your dApp

Of course, the open ethos of Web3 means that you can develop your own solutions from scratch, but we strongly recommend building with both front end and back end components of our SDK so you can leverage the efforts our development team have made on your behalf.

Troubleshooting

There is an extra step that needs to happen if you are using Kima's tools to transfer to or from Solana wallets. The recipient wallet first needs to be "primed" by sending a small amount of USDK to the wallet before transfers or payments via Kima can take place.

This applies to the testnet only and will not be the case once Kima's mainnet goes live.

This is a web server that works as middleware between the Kima Transaction Widget and Kima Chain. Once it receives a transaction request from the widget, it will submit a transaction to Kima Chain signed by a local wallet.

The server is an Express application and requires minimal setup. Here are the instructions:

Create a wallet for development purposes

We recommend Keplr, which is a widely used wallet for blockchains within the Cosmos ecosystem.

Install it from and make sure you back it up by saving the seed phrase.

You will need to record the mnemonic seed phrase rather than the private key, as the seed phrase is used as an environment variable.

Get some KIMA tokens to use for transaction fees

If you are developing on the KIMA testnet, you can acquire test KIMA tokens from our .

Follow the if you have not used a faucet before.

Clone the repo at:

https://github.com/kima-finance/kima-transaction-backend

Set your environment variables

If you are using Docker, you can add these to the docker-compose; otherwise, create an .env file with the following key pairs:

Copy

A few notes about these environment variables:

KIMA_BACKEND_MNEMONIC is the seed phrase from the wallet you installed.

Neither of these dependencies are mandatory as long as you do not want to invoke the /compliant endpoint.

Install and start

You can run:

npm i

then

npm run dev

but the easiest way to get up and running without any dependency issues is with Docker. Use docker-compose.yml for dev, docker-compose-prod.yml for prod.

Start the server with:

docker compose up

Test the installation

In your terminal, run the following command:

Copy

The server should respond with a valid authtoken with a five-second expiry.

Available routes

POST /auth

The Kima Transaction Widget sends a POST request to this endpoint before it submits a transaction request. Returns JWT as cookie which has 5 seconds of life time. This cookie will be expired after 5 seconds. Kima Transaction Widget will call the second endpoint right after it receives JWT Auth Token.

POST /submit

This is a POST request that submits a cross-chain transaction using the developer wallet whose details are stored. Before the /submit endpoint is called, the JWT will first be validated.

The reponse object will contain a transaction ID which can be used to track the success of the submission.

An example of the request body that should be sent:

Copy

POST /compliant

This is a GET request which will return OK if the address is compliant. Note that this will work only if you have a Xplorisk account.

Copy

In order for Kima to move tokens on behalf of the user an on chain approval needs to happen. An approval has 3 components:

• Owner address: User

• Spender address: Kima Pool

• Total amount: origin token amount plus gas fees

Getting the Kima Pool Address

You can also obtain the pool addresses from the TSS endpoint. Use the type in the chart above to determine which one to use.

GET https://api-testnet.kima.finance/kima-finance/kima-blockchain/kima/tss_pubkey

Success Response:

• tssPubkey (array object)

  • tssPubKey: string

  • ecdsa: string

  • eddsa: string

  • reserved: string

• pagination (object)

  • nextKey: string | null

  • total: number

Note: for Tron, the hex esdsa address must be converted to a base 58 checksum address.

Getting the Service Fee

To calculate the total amount, the service (gas) fees are needed. Kima has an endpoint that estimates the service and gas fees for a given chain.

GET https://fee.kima.finance/fee/{chainName}

Example: https://fee.kima.finance/fee/AVX

Response

• result: boolean

• fee: string: dash delimited list <Amount USD>-<Timestamp>-<Amount Crypto>

• Amount USD: the service fee amount in USD

• Timestamp: Javascript timestamp in milliseconds

• Amount Crypto: the fee amount in the native token of the given chain- i.e. AVAX

Chain Names

Calculating the Service Fee

To calculate the total service fee requires querying for the fees on both the source and target chains using the endpoint described above. There are a couple exceptions:

The fee is ZERO in the following cases as it is handled elsewhere:

• Source or target chain is FIAT

• Target chain is BTC

There is a constant value when the source chain is BTC:

• Source chain is BTC: 0.0004 BTC

Since the source and target chains can be different, the USD amount fee amounts should be used and added together. The user will pay the fee using the source token. Remember, even stable coins are not exactly one USD, so the USD fee amount should be converted into the source token amount using the USD price of the source token.

Code Sample

Putting it all together, the following is a typescript code example that queries the endpoint and calculates the total service fee.

Calling Approve

Once all the info has been collected it’s time to make the on chain call. The exact details of how this is done depends on the origin chain and library used.

This snippet uses the getServiceFee() function mentioned above. The getClientsForChain() and getPoolAdressesForChain() would be utility functions defined elsewhere.

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.

Assuming you are building an app from scratch, you can run npx create-next-app <your-app-name> to create a new app.

You can either run:

npm i @kimafinance/kima-transaction-widget

or else copy this package.json to the root of your directory and then simply run npm i.

Copy

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

Copy

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

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

Exactly as with the basic React implementation, you have all the same configuration options.

Configuration options

Note that in the above example, we have configured the title and payment title text, along with the colour. These are just some of the configuration options we describe below.

Configure the widget's look and feel

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

Theme

The Theme prop allows you not only to switch between light and dark mode but also to specify your font colour and style and background colour:

Copy

Title

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

• Required: false

• Type: TitleOption:

Copy

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.

• Required: false

• Type: PaymentTitleOption

Copy

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.

• Required: false

• Type: string

Configure the widget's functionality

Used to specify the scenario of kima-transaction-widget. Available modes are payment, bridget and status.

Required: true Type: ModeOptions Payment and bridge scenario for the purpose of widget, status mode is for tracking status of specific transaction of kima widget. To use status mode, txId prop should be determined export declare enum ModeOptions { payment = 'payment', bridge = 'bridge', status = 'status' }

TransactionOption

Within the payment scenario, you may optionally want to preset the chain and wallet address where the payment should go, as well as the payment amount.

• Required: false

• Type: TransactionOption

Copy

kimaBackendUrl

This is one of the few props that is mandatory to set, because this specifies Kima's transaction back end URL. In the bridge example above, we have made the assumption that you have the back end server running locally on localhost:3001.

• Required: true

• Type: string

kimaNodeProviderQuery

Again, this is mandatory because this is used to specify the REST API URL for interactions with the Kima blockchain.

• Required: true

• Type: string

kimaExplorer

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.

It is not mandatory, but it is highly recommended.

Required: false Type: string Default: explorer.kima.finance

txID

Similarly, this is used to show users the progress of their transactions. It is not mandatory and is used only for status mode.

• Required: false

• Type: boolean

• Default: -1

useFIAT

Used to specify whether users should be given the option to transact with fiat currency.

• Required: false

• Type: boolean

• Default: false

autoConnect

This prop is optional and allows you to define whether connection of wallets such as MetaMask should be automatic or manual.

• Required: false

• Type: boolean

• Default: false

Configure Kima Provider

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

walletConnectProjectId

• Required: false

• Type: string

networkOption

Used to specify the network type.

• Required: false

• Type: NetworkOptions

• Default: NetworkOptions.testnet

Kima Use Cases for Developers

As a developer, what can you build with Kima? In order to onboard more users to Web3, we need to simplify the user experience, which means helping them avoid complicated procedures on bridging applications that may or may not be safe to use.

Integrating with Kima's SDK or front-end widget removes the need for your users to leave your dApp and enables them to effortlessly switch funds between networks with the click of a button.

You could think about using Kima for:

Decentralized Exchanges (DEX)

A quick glance at shows that Ethereum's share of TVL is dropping as DEXs choose to deploy on different networks. Allowing users to bridge funds via a plugin on your own website provides them with a seamless user experience, whichever chain they want to use.

eCommerce and Gaming

In-game payments can slow down the user experience and add unwanted friction. If your users also have to bridge their funds between chains, this can introduce frustration and boredom that may lead to them abandoning your game completely. Kima's smooth, intuitive transactions will mean your users barely notice them.

Similarly, buyers on eCommerce sites are more likely to proceed through the sales funnel if their experience is not impeded by having to visit a separate bridging application.

NFT Marketplace

NFT collectors are no longer limited to one or two chains, and some of the coolest up-and-coming collections can be found on minority chains where fees are cheaper and transactions are faster. Make your marketplace effortlessly multi-chain by integrating Kima.

Wallet

Wallet developers looking for an easy, intuitive way for their users to swap assets in-wallet need to look no further than Kima.

Essentially, as the number of networks within the thriving Web3 ecosystem expands, the need for sending value securely and quickly from one chain to another has become a pressing need.

Once the user has approved the token transfer, it’s time to construct the submit request to the Kima Transaction Backend.

Submitting the Transaction

POST /submit Request Body:

• originAddress (Address): sending user address

• originChain (string): sending chain

• targetAddress (Address): receiving user address

• targetChain (string): receiving chain

• targetSymbol (string): receiving token symbol

• amount (number): amount of token to transfer

• fee (number): amount of token that Kima consumes to pay gas fee for pulling & releasing token transactions

• For Bitcoin transactions:

  • Set these to the empty string or zero for non-BTC transactions

  • htlcCreationHash (string): the tx hash locking the funds in the HTLC

  • htlcCreationVout (number): the output index of the locked funds in the HTLC creation transaction

  • htlcExpirationTimestamp (string): the timestamp when the HTLC contract expires and the user can reclaim the funds locked there

  • htclVersion (string)

  • senderPubKey (string): for bitcoin transactions this is the public key of the sender

Success Response:

• height: number

• txIndex: number

• code: number: error code; will be zero when successful

• transactionHash: string

• events: Event[]

  • type: string

  • attributes: Attribute[]

    • key: string

    • value: string

• rawLog?: string

• data?: MsgData[]

• msgResponses: Uint8Array

• gasUsed: bigint

• gasWanted: bigint

Chain Names

See the short names in the Supported Blockchains section.

Get Transaction Id

The transaction Id will be needed to get the transaction status. The following code can be used to extract the Id from the submit response.

export function getTransactionId(submitResult: any): number {  
  let txId = -1  
  if (result?.code !== 0) {  
    return txId;  
  }

  for (const event of result.events) {  
    if (event.type === 'transaction_requested') {  
      for (const attr of event.attributes) {  
        if (attr.key === 'txId') {  
          txId = attr.value  
        }  
      }  
    }  
  }

  return txId;  
}

Authentication

Before calling submit a JWT token must be obtained with the body payload. The JWT will be checked against the request body and if it does not match will respond with a 500 error.

Validation

If provided, the Kima Backend will use the Explorisk url defined in the ENV var XPLORISK_URL to get the risk score for the origin and target user addresses. If the score is anything other than low it will respond with a 500 error.

Once the transaction has been submitted to the Kima Transaction Backend, you’ll want to display the transaction progress in the frontend. There are 2 GraphQL queries on the Kima subgraph for this purpose.

• Kima Subgraph url: https://graphql.kima.finance/v1/graphql

Here is a code snippet for regular transactions using plain fetch. See the docs for your favorite graphql client for constructing queries.

const result = await fetch("https://graphql.kima.finance/v1/graphql", {  
  method: "POST",  
  headers: {  
    "Content-Type": "application/json",  
  },  
  body: JSON.stringify({  
    query: `  
      query TransactionDetailsKima($txId: String) {  
        transaction_data(where: { tx_id: { _eq: $txId } }, limit: 1\) {  
          failreason  
          pullfailcount  
          pullhash  
          releasefailcount  
          releasehash  
          txstatus  
          amount  
          creator  
          originaddress  
          originchain  
          originsymbol  
          targetsymbol  
          targetaddress  
          targetchain  
          tx_id  
          kimahash  
        }  
      }`,  
    variables: {  
      txId: txId.toString(),  
    },  
  }),  
}).then((res) => res.json());

For liquidity pool transactions:

const result = await fetch("https://graphql.kima.finance/v1/graphql", {  
  method: "POST",  
  headers: {  
    "Content-Type": "application/json",  
  },  
  body: JSON.stringify({  
    query: `  
      query TransactionDetailsKima($txId: String) {  
        liquidity_transaction_data(where: { tx_id: { _eq: $txId } }, limit: 1\) {  
          failreason  
          pullfailcount  
          pullhash  
          releasefailcount  
          releasehash  
          txstatus  
          amount  
          creator  
          chain  
          providerchainaddress  
          symbol  
          tx_id  
          kimahash  
        }  
      }`,  
    variables: {  
      txId: txId.toString(),  
    },  
  }),  
}).then((res) => res.json());

You can add the widget to your React project simply by running:

yarn add @kimafinance/kima-transaction-widget

There are several configuration options, which we will describe below.

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

You can resolve this by adding a file at the root of your project named config-overrides.js. Paste the following content into the file:

Copy

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/]
  }
}

The easiest way to see the widget working, including the workaround above, is to check out the example in the widget repo.

If you are creating your application from scratch and assuming you are using TypeScript, create a file App.tsx and an Index.tsx.

Bridge scenario

Let's demonstrate the Kima bridging function first, which allows your users to transfer value between chains.

Into your App.tsx paste:

Copy

import React from 'react'

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

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{
          colorMode: ColorModeOptions.dark,
          fontSize: FontSizeOptions.medium
        }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
        kimaNodeProviderQuery='https://api.demo.kima.finance'
        compliantOption={false}
        errorHandler={(e: any) => {
          console.log('error:', e)
        }}
        successHandler={() => {
          console.log('success')
        }}
        closeHandler={() => {
          console.log('closed')
        }}
      />
    </KimaProvider>
  )
}

export default App

Create a simple index.css with the following code:

Copy

body {
  margin: 0;
  padding: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
    monospace;
}

#root {
  padding-top: 50px;
}

.container {
  max-width: 1440px;
  margin: 40px auto;
  display: flex;
  justify-content: center;
}

In your Index.tsx paste the following code:

Copy

import './index.css'

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'

ReactDOM.render(<App />, document.getElementById('root'))

Start your app with yarn start and you should see the Kima modal on localhost:3000.

It should look something like this:

The example above provides the most basic example of the bridge functionality, with generic styling and configuration.

Note that it makes the assumption that you also have the development server running on port 3001.

Payment scenario

Next, try the Kima Transaction Widget's payment scenario.

Replace the code in App.tsx with the following:

Copy

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  FontSizeOptions,
  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,
          fontSize: FontSizeOptions.medium
        }}
        mode={ModeOptions.payment}
        kimaBackendUrl='https://demo.kima.finance/backend'
        kimaNodeProviderQuery='https://api.kima.finance'
        titleOption={{
          initialTitle: 'New Purchase'
        }}
        paymentTitleOption={{
          title:
            'Buy your custom product here',
          style: {
            fontSize: '1.2em',
            fontWeight: '500',
            color: '#DDDDDD'
          }
        }}
        compliantOption={false}
        errorHandler={(e: any) => {
          console.log('error:', e)
        }}
        successHandler={() => {
          console.log('success')
        }}
        closeHandler={() => {
          console.log('closed')
        }}
      />
    </KimaProvider>
  )
}

export default App

You should see a page that looks like this:

Configuration options

Note that in the above example, we have configured the title and payment title text, along with the colour. These are just some of the configuration options we describe below.

Configure the widget's look and feel

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

Theme

The Theme prop allows you not only to switch between light and dark mode but also to specify your font colour and style and background colour:

Copy

  theme={{
    colorMode: ColorModeOptions.light,
    fontSize: FontSizeOptions.medium,
    fontFamily: 'Sans Serif',
    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.

• Required: false

• Type: TitleOption:

Copy

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.

• Required: false

• Type: PaymentTitleOption

Copy

 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.

• Required: false

• Type: string

Configure the widget's functionality

Used to specify the scenario of kima-transaction-widget. Available modes are payment, bridget and status.

Required: true Type: ModeOptions Payment and bridge scenario for the purpose of widget, status mode is for tracking status of specific transaction of kima widget. To use status mode, txId prop should be determined export declare enum ModeOptions { payment = 'payment', bridge = 'bridge', status = 'status' }

TransactionOption

Within the payment scenario, you may optionally want to preset the chain and wallet address where the payment should go, as well as the payment amount.

• Required: false

• Type: TransactionOption

Copy

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 this specifies Kima's transaction back end URL. In the bridge example above, we have made the assumption that you have the back end server running locally on localhost:3001.

• Required: true

• Type: string

kimaNodeProviderQuery

Again, this is mandatory because this is used to specify the REST API URL for interactions with the Kima blockchain.

• Required: true

• Type: string

kimaExplorer

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.

It is not mandatory, but it is highly recommended.

Required: false Type: string Default: explorer.kima.finance

txID

Similarly, this is used to show users the progress of their transactions. It is not mandatory and is used only for status mode.

• Required: false

• Type: boolean

• Default: -1

useFIAT

Used to specify whether users should be given the option to transact with fiat currency.

• Required: false

• Type: boolean

• Default: false

autoConnect

This prop is optional and allows you to define whether connection of wallets such as MetaMask should be automatic or manual.

• Required: false

• Type: boolean

• Default: false

Configure Kima Provider

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

walletConnectProjectId

Used to specify the WalletConnect project id. A default value is provided, but you can specify your own. To create a project, visit Reown Cloud and sign up for a free account (WalletConnect is now called Reown).

• Required: false

• Type: string

networkOption

Used to specify the network type.

• Required: false

• Type: NetworkOptions

• Default: NetworkOptions.testnet