Submitting the Transaction

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

Calculate the Submit Amount

Using the Kima Backend

Use the submitAmount property returned from the /submit/fees endpoint.

Using the Kima API

The submit amount should always be the amount the target addreess will receive. This means the submit amount needs to be adjusted based on whether the fees are deducted from the amount or not.

function getSubmitAmount(
  amount: bigint,
  fees: bigint,
  deductFee: boolean
): bigint {
  return deductFee ? amount - fees : amount;
}

Submitting the Transaction

POST /submit Request Body:

• originAddress (Address): sending user address

• originChain (string): sending chain

• originSymbol (string): sending token symbol

• targetAddress (Address): receiving user address

• targetChain (string): receiving chain

• targetSymbol (string): receiving token symbol

• amount (bigint string): amount of token received by the target address

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

• decimals (number): the number of decimals for the bigint amounts

• 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.