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.

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

{
  "result": "ok",
  "fee": "0.03-1729530600285-0.00124160"
}

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

See the short names in the Supported blockchains section.

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.

Total Fees USD = source chain gas + target chain gas
Total Fees Source = Total Fees USD x Source Token per USD

Code Sample

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

export enum ChainName {  
  ARBITRUM = 'ARB',  
  AVALANCHE = 'AVX',  
  BSC = 'BSC',  
  BTC = 'BTC'  
  ETHEREUM = 'ETH',  
  FIAT = 'FIAT',  
  OPTIMISM = 'OPT',  
  POLYGON = 'POL',    
  SOLANA = 'SOL',  
  TRON = 'TRX',  
}

const feeURL = 'https://fee.kima.finance';

export async function calcServiceFee(  
  sourceChain: ChainName,  
  targetChain: ChainName  
): Promise<number> {  
    // exceptions  
    if (sourceChain === ChainName.FIAT || targetChain === ChainName.FIAT) {  
      return 0;  
    }

    if (sourceChain === ChainName.BTC) {  
      return 0.0004;  
    }

    if (targetChain === ChainName.BTC) {  
      return 0;  
    }

    const [sourceFee, targetFee] = await Promise.all([
      getServiceFee(sourceChain),  
      getServiceFee(targetChain)  
    ]);

    const fee = sourceFee + targetFee;

    // TODO: convert amount into source token amount  
    // using USD price of source token  
    // Note even stable coins are often not exactly 1:1

    return fee;  
}

async function getServiceFee(chain: ChainName): Promise=number= {  
  const result = await fetch(`${feeURL}/fee/${chain}`)  
    .then(res => res.json());

  // parse the dash separated fee  
  // <Amount USD>-<Timestamp>-<Amount Crypto>
  // we want the USD amount  
  const { fee } = result as { fee: string };  
  const [ amount ] = fee.split('-');  
   
  return +amount;  
}

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.

Example code using typescript and Viem

import { getClientsForChain, getPoolAddressesForChain, getServiceFee } from "../utils";

export async function approve(chain: ChainName, userAddress: Address, amount: number) {  
  const { publicClient, walletClient } = getClientsForChain(chain);  
  const { contractAddress, decimals, poolAddress} = getPoolAddressesForChain(chain);  
   
  // calc total amount including fees  
  const fees = await getServiceFee(chain);  
  const totalAmount = amount + fees;  
  const intAmount = parseUnits(totalAmount.toString(), decimals);  
   
  // simulate approval call  
  const { request } = await publicClient.simulateContract({  
    account: userAddress,  
    address: contractAddress,  
    abi: erc20Abi,  
    functionName: 'approve',  
    args: [ poolAddress, intAmount ]
  });

  const hash = await walletClient.writeContract(request);

  const receipt = await publicClient.waitForTransactionReceipt({ hash });

  return receipt;  
}

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

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.

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());