How-to: Estimate spend fees

The App Kit SDK can provide an estimate of the fees you’ll incur before spending from a Unified Balance.

Prerequisites

Before you begin, ensure that you’ve:

These are required so any example below runs with a valid kit and adapter.

Estimate fees before spending

This sample estimates then spends 1.00 USDC from Base Sepolia to Arc Testnet when you specify explicit amounts from a source blockchain:

For automatic routing (no explicit allocations), see Select source blockchains.

TypeScript

const params = {
  amount: "1.00",
  from: {
    adapter,
    allocations: [{ amount: "1.00", chain: "Base_Sepolia" }],
  },
  to: {
    adapter,
    chain: "Arc_Testnet",
    recipientAddress: "0xRecipientAddress",
  },
};

const estimate = await kit.unifiedBalance.estimateSpend(params);
console.log("Estimated fees:", estimate.fees);

const result = await kit.unifiedBalance.spend(params);

Estimated fees may differ from actual fees due to network conditions at execution time. Review the estimate before proceeding.

Example fee response

The JSON below shows the shape of the fees array.

JSON

{
  "fees": [
    {
      "type": "provider",
      "token": "USDC",
      "amount": "0.00005",
      "allocations": [{ "chain": "Base Sepolia", "amount": "0.00005" }]
    },
    {
      "type": "gasFee",
      "token": "USDC",
      "amount": "3.311005",
      "allocations": [
        { "chain": "Ethereum Sepolia", "amount": "3.30" },
        { "chain": "Base Sepolia", "amount": "0.011005" }
      ]
    },
    {
      "type": "kit",
      "token": "USDC",
      "amount": ".1",
      "allocations": [{ "chain": "Ethereum Sepolia", "amount": ".1" }],
      "recipientAddress": "0x2222222222222222222222222222222222222222"
    }
  ]
}

Fee type values can include:

provider: Protocol transfer fee when the spend is crosschain. Not charged for same-chain spends.
gasFee: Onchain gas paid on source blockchains as part of the spend.
kit: Developer custom fee from your custom fee policy.
forwarder: Forwarding Service fee when the spend uses the forwarder (not shown in the sample above).

See How Unified Balance fees work for a conceptual fee breakdown.

Handle missing Solana ATAs

When you estimate a spend to a Solana recipient, estimateSpend() checks that the recipient has an associated token account (ATA) for the token you spend (USDC or EURC). If the account is missing, it throws an INPUT_VALIDATION_FAILED error instead of returning fees. spend() runs the same check for spends that don’t use the forwarder, and throws before anything is signed. The error message names each missing account, and error.cause.trace.missingTokenAccounts lists them. The SDK doesn’t create ATAs, so create the missing accounts and then call the method again. If the account goes missing only when the mint is submitted, spend() throws a RESUMABLE error. Create the account, then call spend() again with config.retry set to the attestation and signature from error.cause.trace:

TypeScript

import { isKitError } from "@circle-fin/app-kit";

try {
  await kit.unifiedBalance.spend(params);
} catch (error: unknown) {
  if (!isKitError(error) || error.recoverability !== "RESUMABLE") {
    throw error;
  }

  // Create the accounts listed in error.cause.trace.missingTokenAccounts,
  // then retry the mint with the attestation from the failed spend.
  const { attestation, signature } = error.cause?.trace as {
    attestation: string;
    signature: string;
  };

  await kit.unifiedBalance.spend({
    ...params,
    config: { retry: { attestation, signature } },
  });
}

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow

How-to: Estimate spend fees

Prerequisites

Estimate fees before spending

Example fee response

Handle missing Solana ATAs

​Prerequisites

​Estimate fees before spending

​Example fee response

​Handle missing Solana ATAs

Prerequisites

Estimate fees before spending

Example fee response

Handle missing Solana ATAs