Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Transaction Data

The following information is needed to prepare for and ultimately submit a Kima transaction.

  • The fee amount and feeId

  • The user choice of whether to pay fees from the origin or target chain

  • The message containing the transaction details for the user to sign

  • The origin token amount the user must authorize so Kima can move tokens on behalf of the user

  • The amounts expected when the transaction is submitted

Fortunately, all of these values are calculated by an endpoint exposed by the Kima chain.

Using this endpoint is required as it will return a feeId which must be passed to submit endpoints in the backend (/submit/transfer or /submit/swap).

  • Non-BTC origin transactions submitted to Kima without a feeId or signature will be rejected

  • For non-BTC origin transactions, submitted amounts are validated against the feeId and signed message. Any mismatch will result in rejection.

These are security measures to protect the user and ensure the transaction is legitimate.

Reading token metadata

Use GET /chains to read token metadata for the selected origin token.

  • decimals: use this for amount handling

  • isPermit2: determines whether submit payload must include options.permit2

BTC-origin note

For BTC-origin transactions, GET /submit/fees is still required to get feeId and the submit amount.

Before calling /submit/transfer or /submit/swap, prepare BTC HTLC lock data:

  1. POST /btc/htlc/lock-intent

  2. User broadcasts BTC to the returned htlcAddress

  3. POST /btc/htlc/record using the broadcast txid

The values returned by /btc/htlc/record are then included in the final submit payload.

Using the Kima Backend

GET /submit/fees

Query Params (all required):

  • amount (number): the amount of tokens to transfer

  • originAddress (string): the source user address

  • originChain (string): the chain the user tokens will come from

  • originSymbol (string): the token symbol the user will pay with (or bridge from)

  • targetAddress (string): the receiving address

  • targetChain (string): the destination chain

  • targetSymbol (string): the token symbol being delivered

Example:

Port note: these direct backend examples use the backend's default local port 3001. If your frontend or local proxy exposes the backend on another port such as 4000, use that URL instead.

Example note: this sample uses USDK, which is a testnet token. If you are integrating against mainnet, replace it with a supported mainnet token such as USDC.

Success Response:

Amounts are returned as both numbers representing the amount in whole tokens and as a string representing the integer amount in the smallest unit of the token (e.g. USDC is 6 decimals).

  • feeId (string): a unique identifier for the fee; include this in submit requests

  • feeOrigin* the gas fee for the origin chain

  • feeKimaProcessing* The processing fee (currently 0.05%)

  • feeTarget* the gas fee for the target chain

  • feeTotal* the total fee in USD

  • transactionValues: amounts used for token authorization and for submitting the transaction

    • feeFromOrigin: amounts used when the user selects to pay fees from the origin amount

      • allowanceAmount: the token amount to authorize. For regular ERC-20 tokens this is the value to pass to approve(). For Permit2 tokens, use it when building the Permit2 authorization/signature flow.

      • submitAmount: the amount that needs to be passed to submit endpoints

    • feeFromTarget: amounts used when the user selects to pay fees from the target amount

The response field is still named allowanceAmount, but treat it as the origin token authorization amount. There are 2 variants returned depending on whether the user chooses to pay fees from the origin or target amount.

  • When paying fees from the origin, use transactionValues.feeFromOrigin values.

  • When paying fees from the target, use transactionValues.feeFromTarget.

Example:

Transferring 10 USDK from ARB to SOL with 0.07371 USD in total fees.

When paying fees from the origin

  • The user pays fees on Arbitrum. The total fees are included in the authorization amount.

  • User signs the message I approve the transfer of 10.07371 USDK from ARB to <targetAddress> on SOL. (feeFromOrigin.message)

  • The authorization amount is 10.07371 USDK (feeFromOrigin.allowanceAmount)

  • For regular ERC-20 tokens, use that value in approve(). For Permit2 tokens, use it in the Permit2 authorization flow.

  • The amount sent to submit endpoint is amount RECEIVED on the target chain

  • Therefore the amount sent to submit endpoint is 10 USDK (feeFromOrigin.submitAmount)

    • Also included is the feeId and signature

  • The user receives 10 USDK on Solana

When paying fees from the target chain

  • The user does not pay fees on Arbitrum

  • User signs the message I approve the transfer of 10 USDK from ARB to <targetAddress> on SOL. (feeFromTarget.message)

  • The authorization amount is 10 USDK (feeFromTarget.allowanceAmount)

  • For regular ERC-20 tokens, use that value in approve(). For Permit2 tokens, use it in the Permit2 authorization flow.

  • The amount sent to submit endpoint is 9.926290 USDK (feeFromTarget.submitAmount)

  • The fees are deducted from the amount received on Solana so the user receives 9.926290 USDK on Solana

Save the corresponding submitAmount, message and feeId for later as they are needed to submit the transaction.

If you need the raw fee-calculation API instead of the backend wrapper, the backend currently calls the fee service at POST {{baseUrl}}/v3/fees/calculate. For most integrations, GET /submit/fees remains the recommended entry point.

PreviousUsing the Kima SDK Without the WidgetNextMessage Signing

Last updated