Approval

In order for Kima to move tokens on behalf of the user an on chain approval needs to happen. An approval has 3 components:

• Owner address: User

• Spender address: Kima Pool

• Total amount: origin token amount plus gas fees

Getting the Kima Pool Address

Using the Kima Backend

GET /chains/pool returns a list of pool addresses and balances for all supported chains.

[
  {
    "chainName": "SOL",
    "poolAddress": "5tvyUUqPMWVGaVsRXHoQWqGw6h9uifM45BHCTQgzwSdr",
    "balance": [
      {
        "amount": "99684.841000000000000000",
        "tokenSymbol": "USDK",
        "decimal": "6"
      }
    ],
    "nativeGasAmount": "70.119964040000000000"
  },
  {
    "chainName": "TRX",
    "poolAddress": "TQ3qmAgUgMwrY9prMiHLZmF43G4Jk8bxNF"
    // ... etc
  }
]

Using the Kima API

Chain	Type	Pool Address
EVM	ecdsa	0x9a721c664f9d69e4da24f91386086fbd81da23c1
Solana	eddsa	5tvyUUqPMWVGaVsRXHoQWqGw6h9uifM45BHCTQgzwSdr
Tron	ecdsa (base58)	TQ3qmAgUgMwrY9prMiHLZmF43G4Jk8bxNF

You can also obtain the pool addresses from the TSS endpoint. Use the type in the chart above to determine which one to use.

GET https://api.sardis.kima.network/kima-finance/kima-blockchain/kima/tss_pubkey

Success Response:

• tssPubkey (array object)

  • tssPubKey: string

  • ecdsa: string

  • eddsa: string

  • reserved: string

• pagination (object)

  • nextKey: string | null

  • total: number

Note: for Tron, the hex ecdsa address must be converted to a base 58 checksum address.

Getting the Service Fee

The fees and allowance amounts are calculated by an endpoint exposed by Kima chain. The this endpoint also returns a feeId which must be included when submitting the transaction.

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=1337&originAddress=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&originChain=BSC&originSymbol=USDK&targetAddress=5FHwkrdxkjF7xoL2ncGh4AEYs1KyJzz5MeiaHGz8h8GA&targetChain=SOL&targetSymbol=USDK

/submit/fees?amount=10&originChain=TRX&targetChain=ARB&deductFee=true&originSymbol=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 the submit request (/submit/transfer or /submit/swap)

• 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

• 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 total fees are added to the amount

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

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

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

• The amount sent to submit endpoints is 10 USDC (feeFromOrigin.submitAmount)

  • Also included is the feeId and signed message

• 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 5FHwkrdxkjF7xoL2ncGh4AEYs1KyJzz5MeiaHGz8h8GA on SOL. (feeFromTarget.message)

• The user approves a transfer of 10 USDC on Arbitrum (feeFromTarget.allowanceAmount)

• The amount sent to submit endpoints 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"
}

Chain Names

See the short names in the Supported Assets section.

Using the Kima API

There is also an endpoint that can be called directly.

POST {{baseUrl}}/v2/fees/calculate

It has all the params and same response as the Backend /submit/fees endpoint except:

• The params are in the body as JSON

• There is an extra param creator which is the Kima address of the developer wallet sending the transaction- kima1...

Permit2 Tokens

Read the selected origin token metadata from GET /chains.

• isPermit2=false: use the standard approve flow shown below.

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

• Permit2 tokens are not supported in mode=light.

BTC-origin flow (approval equivalent)

BTC-origin transactions do not use ERC20 approve. Instead, funds are first locked in a BTC HTLC output and then submitted to Kima with HTLC metadata.

You should still call GET /submit/fees first and keep feeId for the final submit step.

Step 1: Create HTLC lock intent

POST /btc/htlc/lock-intent

Request body:

• senderAddress (string): BTC sender address

• senderPubkey (string): BTC sender public key (hex)

• recipientAddress (string): recipient address used to construct the lock script

• amountSats (string): lock amount in satoshis

• poolAddress (string, optional): explicit BTC recipient in script

• lockBlocks (number, optional): timeout as block delta

• timeout (number, optional): explicit timeout value

Response includes:

• lockId

• htlcAddress

• timeoutHeight

• amountSats

• senderPubkey

Step 2: Broadcast BTC lock transaction

Use the user's BTC wallet/provider to send amountSats to the returned htlcAddress. Save the broadcast transaction hash (txid).

Step 3: Record the broadcast transaction

POST /btc/htlc/record

Request body:

• lockId

• txid

Response returns submit-ready HTLC fields:

• htlcCreationHash

• htlcCreationVout

• htlcExpirationTimestamp

• htlcVersion (currently p2wsh-sha256-cltv-v1)

• senderPubKey

Use these together with:

• htlcAddress and htlcLockId from lock-intent

• htlcAmountSats from the selected lock amount

These values are then sent to POST /submit/transfer or POST /submit/swap.

Calling Approve

Once all the info has been collected it’s time to make the on chain call. The exact details of how this is done depends on the origin chain and library used.

import {
  getClientsForChain,
  getPoolAddressesForChain,
  getServiceFee,
} from "../utils";

export async function approve(
  chain: ChainName,
  userAddress: Address,
  amount: string
) {
  const { publicClient, walletClient } = getClientsForChain(chain);
  const { contractAddress, poolAddress } = getPoolAddressesForChain(chain);

  // simulate approval call
  const { request } = await publicClient.simulateContract({
    account: userAddress,
    address: contractAddress,
    abi: erc20Abi,
    functionName: "approve",
    args: [poolAddress, amount],
  });

  const hash = await walletClient.writeContract(request);

  const receipt = await publicClient.waitForTransactionReceipt({ hash });

  return receipt;
}

The getClientsForChain() and getPoolAdressesForChain() would be utility functions defined elsewhere.