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 (without the widget). But:

🚨 CREDIT CARD TRANSACTIONS ARE ONLY SUPPORTED USING THE WIDGET 🚨

The frontend kima-transaction-widget is required for credit-card flows 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, user signs the approval message and approves token transfer (or signs Permit2 typed data for Permit2 tokens).

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.

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.