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 containting the transaction details for the user to sign

• The allowance amount the user should approve 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:

http://localhost:3001/submit/fees?amount=10&originAddress=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&originChain=ARB&originSymbol=USDK&targetAddress=5FHwkrdxkjF7xoL2ncGh4AEYs1KyJzz5MeiaHGz8h8GA&targetChain=SOL&targetSymbol=USDK

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 the allowance and submitting the transaction

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

    • allowanceAmount: the token amount that needs to be approved. Can be passed directly to the contract call.

    • 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 allowanceAmount is the one you'll need to pass to the contract call. 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 USDC 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 allowance amount.

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

• The user approves a transfer of 10.07371 USDC on Arbitrum (feeFromOrigin.allowanceAmount)

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

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

  • Also included is the feeId and signature

• The user receives 10 USDC 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 user approves a transfer of 10 USDC on Arbitrum (feeFromTarget.allowanceAmount)

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

• The fees are deducted from the amount recieved on Solana so the user receives 9.926290 USDC on Solana

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

{
  "$schema": "https://fcs.sardis.kima.network/schemas/CalculateFeeResponseV2.json",
  "feeId": "5af06c68-44d6-4079-8e5b-bec1cfa154c7",
  "feeOriginGasFiat": "0.009105",
  "feeOriginGasBigInt": {
    "value": 9105204603000000,
    "decimals": 18
  },
  "feeKimaProcessingFiat": "0.05",
  "feeKimaProcessingBigInt": {
    "value": 50000,
    "decimals": 6
  },
  "feeTargetGasFiat": "0.014605",
  "feeTargetGasBigInt": {
    "value": 14605,
    "decimals": 6
  },
  "feeTotalFiat": "0.07371",
  "feeTotalBigInt": {
    "value": 73710,
    "decimals": 6
  },
  "transactionValues": {
    "feeFromOrigin": {
      "allowanceAmount": {
        "value": 10073710000000000000,
        "decimals": 18
      },
      "submitAmount": {
        "value": 10000000000000000000,
        "decimals": 18
      },
      "message": "I approve the transfer of 10.07371 USDK from ARB to 5FHwkrdxkjF7xoL2ncGh4AEYs1KyJzz5MeiaHGz8h8GA on SOL."
    },
    "feeFromTarget": {
      "allowanceAmount": {
        "value": 10000000,
        "decimals": 6
      },
      "submitAmount": {
        "value": 9926290,
        "decimals": 6
      },
      "message": "I approve the transfer of 10 USDK from ARB to 5FHwkrdxkjF7xoL2ncGh4AEYs1KyJzz5MeiaHGz8h8GA on SOL."
    }
  },
  "peggedTo": "USD",
  "expiration": "2025-05-07T00:24:24Z"
}