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

Using theKima Backend

To calculate the total amount, the service (gas) fees are needed. The Kima Backend has an endpoint that does all the calculations for you.

/submit/fees?amount=10&originChain=TRX&targetChain=ARB&deductFee=true&originSymbol=USDK

Success Response:

• totalFee (bigint string): sum of all fees in USD

• totalFeeUsd (number): sum of all fees in USD

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

• decimals (number): the number of decimals for the bigint amounts

• deductFee (boolean): whether the fees are deducted from the amount or not

• submitAmount (bigint string): the amount that needs to be passed to the /submit endpoint

• breakdown: individual fees

  • amount: fee amount

  • feeType: 'gas' | 'service'

  • chain: chain short name

{
  "totalFee": "1530000000000000000",
  "totalFeeUsd": 1.53,
  "allowanceAmount": "10000000000000000000",
  "decimals": 18,
  "deductFee": true,
  "submitAmount": "8470000000000000000",
  "breakdown": [
    {
      "amount": 1.32,
      "feeType": "gas",
      "chain": "TRX"
    },
    {
      "amount": 0.21,
      "feeType": "gas",
      "chain": "ARB"
    }
  ]
}

Chain Names

See the short names in the Supported blockchains section.

Using the Kima API

The Kima gas fee estimation endponts can also be called directly. In this case it is necessary to make 2 calls, one for the source chain and one for the target chain. Then the results can be combined to get the total fee.

The Kima API endpoint will soon be updated to perform the same calculations as the Kima Backend. We recommend using the Kima Backend for now.

GET https://fee.kima.network/fee/{chainName}

Example: https://fee.kima.network/fee/AVX

{
  "result": "ok",
  "fee": "0.03-1729530600285-0.00124160"
}

Response

• result: boolean

• fee: string: dash delimited list <Amount USD>-<Timestamp>-<Amount Crypto>

• Amount USD: the service fee amount in USD

• Timestamp: Javascript timestamp in milliseconds

• Amount Crypto: the fee amount in the native token of the given chain- i.e. AVAX

Calculating the Service Fee

To calculate the total service fee requires querying for the fees on both the source and target chains using the endpoint described above. There are a couple exceptions:

The fee is ZERO in the following cases as it is handled elsewhere:

• Source or target chain is FIAT

• Target chain is BTC

There is a constant value when the source chain is BTC:

• Source chain is BTC: 0.0004 BTC

Since the source and target chains can be different, the USD amount fee amounts should be used and added together. The user will pay the fee using the source token. Remember, even stable coins are not exactly one USD, so the USD fee amount should be converted into the source token amount using the USD price of the source token.

Total Fees USD = source chain gas + target chain gas
Total Fees Source = Total Fees USD x Source Token per USD

Code Sample

Putting it all together, the following is a typescript code example that queries the endpoint and calculates the total service fee.

import { parseUnits } from 'viem'

export enum ChainName {
  ARBITRUM = 'ARB',
  AVALANCHE = 'AVX',
  BERA = 'BERA',
  BSC = 'BSC',  
  BTC = 'BTC',  
  ETHEREUM = 'ETH',
  OPTIMISM = 'OPT',
  POLYGON = 'POL',
  SOLANA = 'SOL',
  TRON = 'TRX',
}

// mainnet
// const feeURL = 'https://fee.kima.finance';

// testnet
const feeURL = 'https://fee.sardis.kima.network';

export async function calcServiceFee(
  sourceChain: ChainName,
  targetChain: ChainName,
): Promise<bigint> {
    const [sourceFee, targetFee] = await Promise.all([
      getServiceFee(sourceChain),
      getServiceFee(targetChain)
    ]);

    // use integer math to avoid rounding errors
    const sourceFeeInt = parseUnits(amount, decimals)
    const targetFeeInt = parseUnits(targetFee, decimals)
    const fee = sourceFee + targetFee;

    // TODO: convert amount into source token amount
    // using USD price of source token
    // Note even stable coins are often not exactly 1:1

    return fee;
}

async function getServiceFee(chain: ChainName): Promise<number> {
  const result = await fetch(`${feeURL}/fee/${chain}`)
    .then(res => res.json());

  // parse the dash separated fee
  // <Amount USD>-<Timestamp>-<Amount Crypto>
  // we want the USD amount
  const { fee } = result as { fee: string };
  const [ amount ] = fee.split('-');

  return +amount;
}

Calculate the Approval Amount

Using the Kima Backend

Use the allowanceAmount property returned from the /submit/fees endpoint.

Using the Kima API

The approval amount will be different when deducting the fees or not.

• When deducting the fees, the approval should be just the amount

• Otherwise, the approval should be the amount plus the fees

function getApprovalAmount(
  amount: bigint,
  fees: bigint,
  deductFee: boolean
): bigint {
  return deductFee ? amount : amount + fees;
}

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.