Using the Kima SDK Without the Widget

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. This page documents that backend-mediated integration path for crypto-origin and BTC-origin flows only. But:

🚨 FIAT TRANSACTIONS ARE ONLY SUPPORTED USING THE WIDGET 🚨

The frontend kima-transaction-widget is required for FIAT-origin flows such as credit-card and bank-transfer transactions because it handles KYC and interactions with 3rd party widgets.

Transaction Flow

1. User selects the origin and target chains and amount.

2. Fetch service fees from Kima (/submit/fees) to get feeId and submit amounts.

3. If origin is not BTC, complete the required token authorization flow:

   • regular ERC-20 tokens: sign the message and send approve()

   • Permit2 tokens: sign the message and also collect the permit2 payload required for submit

4. If origin is BTC, prepare an HTLC lock with backend endpoints:

   • POST /btc/htlc/lock-intent

   • user broadcasts BTC to the returned htlcAddress

   • POST /btc/htlc/record with the broadcast txid

5. Submit the transaction to backend (/submit/transfer or /submit/swap):

   • non-BTC origin: include standard options (feeId, signature, and permit2 when required)

   • BTC origin: include HTLC fields + senderPubKey

6. Poll the transaction status until completion.

FIAT-origin flows are intentionally out of scope for this guide and should be implemented only through the widget.

Permit2 tokens

Use GET /chains token metadata to determine whether the selected token requires Permit2:

• isPermit2=false: standard approve + signature flow

• isPermit2=true: signature is still mandatory, and include options.permit2 (r, s, v, deadline) in submit payload

Permit2 guidance applies to Permit2-enabled EVM tokens. BTC-origin flows use the HTLC path above.

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 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 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 Supported Assets and Supported Tokens.