Troubleshoot Unified Balance deposits

Recovery depends on the source transaction receipt. Before a fast deposit burns USDC, you can correct the request and try again. After a successful burn, monitor the existing deposit or escalate it. If the submission result is unclear, check the source blockchain before you try again. Quote and progress states apply only to crosschain FAST deposits. STANDARD same blockchain deposits throw structured errors and don’t return progress.

Don’t call deposit() or depositFor() again while the source transaction is pending or after its receipt confirms the burn. A PENDING result means that the kit submitted the source transaction, but it doesn’t prove that the transaction succeeded. Check the receipt before you choose a recovery action.

The snippets assume that you’ve configured kit and a source adapter. See Use fast deposits for the complete deposit flow.

Identify the failure stage

Start with the result. Use it and the source blockchain history to choose a safe next step.

Observation	Source transaction status	Action
`estimateDeposit()` throws	Not submitted	Correct the request, then estimate again.
`deposit()` throws and no burn transaction was sent	Not submitted	Correct the error, request a fresh estimate, and submit again.
Wallet or RPC error while submitting the transaction	Unknown until you check the source blockchain	Check the wallet activity or block explorer before you submit another deposit.
`progress.status` is `PENDING`	Submitted; receipt not verified by the result	Check the source receipt before you poll IRIS or retry.
`progress.status` is `FAILED`	Burn confirmed; destination relay failed	Check the destination balance, then contact Circle support with the source `txHash`.
`progress.status` is `DONE`	Burn and destination deposit confirmed	Save the destination relay `txHash`. No recovery action is required.

For a fast deposit, txHash identifies different transactions depending on the result:

DONE: the destination relay transaction.
PENDING or FAILED: the source burn transaction.

When the result is PENDING, look up the source txHash and use the source transaction state to choose the next step:

Source transaction state	Action
Successful receipt	The burn occurred. Poll IRIS and don’t submit another deposit.
Reverted receipt	The burn didn’t occur. Correct the cause, request a fresh estimate, and submit again.
Pending	Keep monitoring the source transaction. Don’t submit another deposit.
Replaced	Inspect the replacement transaction before you act. A successful receipt alone doesn’t prove that the burn occurred.
Dropped or not found	Check the signing wallet’s activity and nonce. Don’t retry until you confirm that the transaction can’t be executed. Then request a fresh estimate.

Check what the replacement transaction did. Compare its contract address and call data with the original burn, or look for the burn event:

Same burn succeeded: Poll IRIS with the replacement transaction hash. Don’t submit another deposit.
Still pending: Keep monitoring the replacement. Don’t submit another deposit.
Canceled, unrelated, or reverted: The burn didn’t occur. Request a fresh estimate before you retry.

If a wallet or Remote Procedure Call (RPC) request fails while it submits the burn, the transaction might still have reached the source blockchain. Don’t automatically retry an ambiguous submission. First check the signing wallet’s recent transactions for a matching USDC burn.

Inspect structured errors

Unified Balance operations throw a KitError for request validation, balance, RPC, and onchain failures. Record the error name, message, recoverability, and cause. These fields help you tell a request error from an infrastructure error.

TypeScript

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

type DepositEstimate = Awaited<
  ReturnType<typeof kit.unifiedBalance.estimateDeposit>
>;

try {
  const estimate: DepositEstimate = await kit.unifiedBalance.estimateDeposit({
    from: { adapter, chain: "Ethereum_Sepolia" },
    amount: "10",
    token: "USDC",
    to: { chain: "Arc_Testnet" },
    config: { transferSpeed: "FAST" },
  });

  const result: DepositResult = await kit.unifiedBalance.deposit({
    ...estimate,
    from: { adapter, chain: "Ethereum_Sepolia" },
  });

  console.log(result.progress?.status, result.txHash);
} catch (error: unknown) {
  if (isKitError(error)) {
    console.error({
      name: error.name,
      code: error.code,
      recoverability: error.recoverability,
      message: error.message,
      cause: error.cause,
    });
  }

  throw error;
}

Don’t use recoverability alone to decide whether to submit another deposit. First verify whether the source burn occurred.

Resolve request validation errors

Fast deposit configuration errors use the INPUT_VALIDATION_FAILED error name. Fast deposits require an Ethereum Virtual Machine (EVM) source blockchain. Use the field and reason in the error message to correct the request.

Condition	Resolution
`transferSpeed` is `FAST`, but `to` is omitted	Add a supported destination blockchain.
`to` is set, but `transferSpeed` is omitted or `STANDARD`	Set `config.transferSpeed` to `FAST`, or remove `to` for a standard deposit.
`to.chain` isn’t a supported fast deposit destination	Select a destination from the fast deposit support table.
The source is a fast finality destination	Select a supported source blockchain. The kit doesn’t fall back to a standard deposit.
The source isn’t an EVM blockchain	Use a supported EVM source blockchain.
The source and destination use different environments	Use either two mainnet blockchains or two testnet blockchains.
`allowanceStrategy` is set with `to`	Omit `allowanceStrategy`. Fast deposits manage the USDC approval.
`quote` is set for a standard deposit	Remove `quote`, or configure a fast deposit and request a new estimate.

If the preflight check reports an insufficient USDC balance, fund the source wallet with the required amount shown in the error. The required balance includes the deposit amount and forwarder fee. The wallet also needs enough of the source blockchain’s native token to pay for any required approval and the burn gas.

Resolve fee quote errors

The kit validates a supplied fast deposit quote before it submits the source burn. Quote rejection reasons aren’t KitError names. The kit translates them into either INPUT_VALIDATION_FAILED messages that request a new estimate or a fatal internal error.

Resolve caller quote errors

The kit detects these reasons before it submits a source burn for the current call:

Quote rejection reason	Meaning	Action
`QUOTE_EXPIRED`	The quote’s validity window ended.	Request a new estimate.
`NON_ZERO_NONCE`	The quote was already used.	Find the transaction that consumed it. Recover that deposit instead if it matches the current intent.
`SOURCE_DOMAIN_MISMATCH`	The quote belongs to a different source blockchain.	Request an estimate for the intended source blockchain.
`SIGNATURE_INVALID`	The quote signature is invalid.	Discard the quote and request a new estimate.
`QUOTE_ARGS_MISMATCH`	The quote doesn’t match the final deposit parameters.	Request a new estimate after you finalize the amount, source, destination, recipient, and configuration.

Call estimateDeposit() again with the final amount, source, destination, recipient, and transfer configuration. Pass the returned estimate to deposit() without changing its quoted fields:

TypeScript

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

type DepositEstimate = Awaited<
  ReturnType<typeof kit.unifiedBalance.estimateDeposit>
>;

const estimate: DepositEstimate = await kit.unifiedBalance.estimateDeposit({
  from: { adapter, chain: "Ethereum_Sepolia" },
  amount: "10",
  token: "USDC",
  to: { chain: "Arc_Testnet" },
  config: { transferSpeed: "FAST" },
});

const result: DepositResult = await kit.unifiedBalance.deposit({
  ...estimate,
  from: { adapter, chain: "Ethereum_Sepolia" },
});

console.log(result.progress?.status, result.txHash);

Request a quote shortly before submission instead of caching it. If a new quote fails with the same reason, stop retrying and contact Circle support with the full structured error. For NON_ZERO_NONCE, request a new quote only after you confirm that you aren’t trying to recover the deposit that used the old quote.

Report an internal quote error

The following reasons indicate that the kit constructed an invalid forwarding payload:

EMPTY_HOOK_DATA
FORWARD_FEE_WITHOUT_HOOK
FORWARD_HOOK_WITHOUT_FEE

These errors have SERVICE_INTERNAL_ERROR as their error name and FATAL as their recoverability. Requesting another quote with the same SDK and parameters won’t correct the payload. Stop retrying and report the error to Circle support.

Handle fast deposit progress

After it submits the source transaction, the kit waits about 60 seconds for Circle’s relayer. It then returns one of these states:

Status	Meaning	Action
`DONE`	The relayer confirmed the destination deposit.	Store the destination relay `txHash`.
`PENDING`	The wait ended without a confirmed relay. The source transaction receipt isn’t verified.	Check the returned source `txHash`. Poll IRIS only after the receipt succeeds.
`FAILED`	The source burn completed, but the relayer reported a terminal destination failure.	Check the destination balance, then contact Circle support.

PENDING doesn’t by itself mean that the deposit failed or that funds are in transit. The source transaction can still be pending, reverted, or dropped when the kit returns.

Poll a pending deposit

After the source receipt succeeds, query the IRIS messages endpoint with the source Cross-Chain Transfer Protocol (CCTP) domain ID and the source burn transaction hash. For domain IDs, see Supported chains and domains. Mainnet:

Shell

curl "https://iris-api.circle.com/v2/messages/{sourceDomainId}?transactionHash={sourceTxHash}"

Testnet:

Shell

curl "https://iris-api-sandbox.circle.com/v2/messages/{sourceDomainId}?transactionHash={sourceTxHash}"

Use messages[].forwardState to choose the next action:

`forwardState`	Action
`PENDING`, `null`, or omitted	Continue polling with backoff.
`CONFIRMED` or `COMPLETE`	Treat the deposit as complete when `forwardTxHash` is present.
`FAILED`	Stop polling. Check the destination balance, then contact Circle support.

The top-level message status describes the CCTP attestation. It doesn’t confirm that the forwarding transaction completed. Use forwardState and forwardTxHash for the destination deposit.

Escalate a failed deposit

An IRIS FAILED forward state means that Circle’s forwarding attempt failed. Another party might still complete the destination mint using the same CCTP message. Before you contact Circle support, check the recipient’s Unified Balance. If the balance wasn’t credited, provide:

The source burn transaction hash from the deposit result.
The source and destination blockchains.
The deposit account and amount.
The approximate submission time and SDK version.
The structured error or IRIS response, with secrets removed.

Circle support can inspect the existing burn and attestation and determine whether the destination relay can be submitted again. This recovery reuses the existing burn; it doesn’t require a new deposit. The Unified Balance deposit API doesn’t provide a public retry method for an existing source burn. Don’t reuse Bridge Kit’s retry() method with a Unified Balance deposit result, and don’t submit a new deposit as a recovery attempt.

Prevent duplicate deposits

Persist the source transaction hash and deposit state before starting background monitoring.
Prevent duplicate submissions while a wallet request or deposit is pending.
Request a fresh estimate immediately before deposit() or depositFor().
Pass quoted fields to the deposit unchanged.
Use backoff when polling IRIS, and stop when the state is terminal.
Alert on repeated internal quote errors and FAILED relay states instead of retrying them automatically.

Send

Bridge

Swap

Unified Balance

Troubleshoot Unified Balance deposits

Identify the failure stage

Inspect structured errors

Resolve request validation errors

Resolve fee quote errors

Resolve caller quote errors

Report an internal quote error

Handle fast deposit progress

Poll a pending deposit

Escalate a failed deposit

Prevent duplicate deposits

​Identify the failure stage

​Inspect structured errors

​Resolve request validation errors

​Resolve fee quote errors

​Resolve caller quote errors

​Report an internal quote error

​Handle fast deposit progress

​Poll a pending deposit

​Escalate a failed deposit

​Prevent duplicate deposits

Identify the failure stage

Inspect structured errors

Resolve request validation errors

Resolve fee quote errors

Resolve caller quote errors

Report an internal quote error

Handle fast deposit progress

Poll a pending deposit

Escalate a failed deposit

Prevent duplicate deposits