Website

Errors & Troubleshooting

Symptom (Circle / RPC):

  • ESTIMATION_ERROR, CALL_EXCEPTION, execution reverted, or revert without reason.

  • Circle transaction stays in PENDING_SIGNATURE or PENDING_ESTIMATION then fails.

Why it happens:

  • Calldata is valid, but current pool state (liquidity/price) or allowance/balance makes the call revert.

  • The minAmountIn is too tight vs. real-time price.

  • Wrong adapterData (e.g., feeTier/spacing) for the chosen router.

  • You didn’t pass the exact path/multihop from the quote for multi-hop.

Fixes (checklist):

  1. Pre-simulate using the exact builder output (router, signature, params) against your RPC before sending to Circle.

    • The builder already returns what to call; do not change it.

  2. Use the same numbers from the quote:

    • amountOut → router’s amountIn (RAW tokenIn)

    • minAmountIn → router’s minAmountOut (RAW tokenOut)

    • Never re-compute or format these again.

  3. Relax slippage at quote time (e.g., 0.5 → 0.8) if the pool is volatile.

  4. Adapter data must match router type:

    • Uniswap V3: feeTier(s)

    • Slipstream: tick spacing(s) (quotes show these as feeTier: 50/10 but builder maps them to spacings).

  5. Multi-hop: include both path and multihop segments from the quote in /buildTransaction.

  6. Router address: must be the one returned by the builder (don’t hardcode).

  7. Deadline/flags: these are baked into adapterData by the builder—pass it through unchanged.

Balance / allowance issues

Symptoms:

  • insufficient funds / ERC20: transfer amount exceeds balance

  • allowance too low / approval missing

  • Approval succeeds but swap still fails estimation

Checklist:

  1. Balance: Confirm the tokenIn balance ≥ amountOut (RAW) in the sender wallet.

  2. Allowance:

    • Approve spender = build.routerAddress

    • Amount can be either exact (amountOut) or a large cap (e.g., 1e24) if your policy allows.

    • Wait until the approval transaction is CONFIRMED before sending the swap.

  3. Correct token: Approve the input token (fromTokenAddress), not the output.

  4. Correct wallet: The address that sends the swap must be the one holding the funds and the one that did the approval (EOA or SCA).

  5. Right chain: Balance/allowance must be on chainId you’re swapping on.

Common mistakes

  1. Mixing HUMAN and RAW units

    • /quote → amount is HUMAN (e.g., "100.00").

    • /buildTransaction → amountOut and minAmountIn are RAW (exact values from the quote).

    • Don’t re-parse or parseUnits the builder inputs; just forward them.

  2. Not passing path / multihop for multi-hop

    • If the quote shows a multi-hop route, the build request must include the exact path and multihop array.

  3. Changing router or adapter

    • Do not swap router types between quote and build.

    • Use builder outputs: routerAddress, abiFunctionSignature, abiParameters, adapterAddress, adapterData.

  4. Relying on fee tiers/spacing defaults

    • For V3/Slipstream, always forward hop-level params from the quote.

    • If you omit these, the builder falls back to safe defaults, which may be suboptimal or fail on certain pools.

  5. Too-tight slippage

    • Very tight slippage can fail at estimation time. Start with 0.5% and tune according to asset volatility/liquidity.

  6. Using a different recipient than expected

    • userWallet is the recipient. For SCAs (e.g., Circle), pass the SCA address.

    • Ensure your approval is done from the same wallet that executes the swap.

  7. Calling the router with modified calldata

    • Any modification (parameter order, types, rounding) can break estimation.

    • Always encode with the exact function signature and parameters returned by the builder.

  8. Wrong chain or token addresses

    • Ensure token contracts are correct for chainId 8453 (Base in examples).

    • A checksum mismatch won’t revert, but a wrong contract address will.

  9. Skipping pre-simulation

    • Especially when sending via custodial flows (Circle), always dry-run the router call against RPC to catch issues early.

Quick diagnostics flow

  1. Request: Did you send the right fields? (amount HUMAN for quote; RAW values for build)

  2. Quote: Is multihop non-null? Then you must include path + multihop in build.

  3. Build: Are you using the builder’s routerAddress / signature / parameters as-is?

  4. Allowance: Confirm approval confirmed before swap; spender = routerAddress.

  5. Pre-sim: RPC eth_call using the same calldata; if revert → adjust slippage/params.

  6. Resend: If transient (RPC or upstream), retry with jitter/backoff.

If you still get stuck, log:

  • The quote payload and response,

  • The build payload and response,

  • The exact router call (signature + params), and

  • The RPC/estimation error message (including revert data if available).

PreviousBuildCalldataRequestDtoNextFAQ

Last updated