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 (stable coin) token the user will pay with (or bridge from)

• targetAddress (string): the receiving address

• targetChain (string): the destination chain

• targetSymbol (string): the (stable coin) token 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

• 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 the /submit endpoint

  • 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 the /submit endpoint is amount RECEIVED on the target chain

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

Chain Names

See the short names in the Supported blockchains 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...

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.