> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# Transaction states and errors

> Reference for the states, error reasons, and error details surfaced on Circle Wallets transaction and challenge webhooks and API responses.

## Transaction states

| State | Description |
| - | - |
| `INITIATED` | The transaction has been initiated. |
| `QUEUED` | The transaction is in the processing queue. |
| `CLEARED` | The transaction has passed initial checks and risk screening. |
| `SENT` | The transaction has been identified in the mempool and assigned a transaction hash. |
| `STUCK` | The transaction has been sent to the blockchain but could not be included in a block. See [Resolve stuck transactions](/wallets/transaction-limits-and-optimizations#resolve-stuck-transactions). |
| `CONFIRMED` | The transaction has been identified on a mined block. |
| `COMPLETE` | **Terminal state.** The transaction has successfully completed. |
| `CANCELLED` | **Terminal state.** The transaction has been canceled. Re-initiate to retry. |
| `FAILED` | **Terminal state.** The transaction has failed. Check `errorReason` and `errorDetails` for the cause. Re-initiate to retry. |
| `DENIED` | **Terminal state.** The platform denies the transaction. Check `errorReason` and `errorDetails` for the cause. |

You can cancel a transaction in `INITIATED`, `QUEUED`, or `SENT`. You can
accelerate a transaction in `SENT` or `STUCK`.

<Note>
  `CONFIRMED` may be omitted or arrive out of order. Instant-finality
  blockchains such as Arc skip it entirely (`SENT` → `COMPLETE`); on other
  blockchains, webhook delivery isn't ordered, so `CONFIRMED` may arrive after
  `COMPLETE` or not at all. Treat both as inclusion signals.
</Note>

### Transaction lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> INITIATED
    INITIATED --> QUEUED
    QUEUED --> CLEARED
    CLEARED --> SENT
    SENT --> CONFIRMED
    CONFIRMED --> COMPLETE
    SENT --> COMPLETE : instant finality
    SENT --> STUCK
    STUCK --> SENT : accelerate
    INITIATED --> CANCELLED
    QUEUED --> CANCELLED
    SENT --> CANCELLED
    SENT --> FAILED
    STUCK --> FAILED
    CLEARED --> DENIED
```

## Challenge states

Challenges are the user approval flow for user-controlled wallets. A challenge
in `FAILED` has `errorCode` and `errorMessage` fields describing the failure.
See [Wallets API error codes](/api-reference/wallets/error-codes) for the
`errorCode` values.

| Status | Description |
| - | - |
| `PENDING` | The request has been created but not yet approved by the user. |
| `IN_PROGRESS` | The user has approved the request and it is being executed. |
| `COMPLETED` | The request is complete. |
| `FAILED` | The request failed to execute. Re-initiate to retry. |
| `EXPIRED` | The request expired. Re-initiate to retry. |

### Challenge lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> IN_PROGRESS : user approves
    IN_PROGRESS --> COMPLETED
    IN_PROGRESS --> FAILED
    PENDING --> EXPIRED
```

## Transaction errors

When a transaction enters `FAILED`, `errorReason` categorizes the cause and
`errorDetails` (when present) provides the specific message. For the numeric
error codes returned in API responses, see
[Wallets API error codes](/api-reference/wallets/error-codes).

| errorReason | Description |
| - | - |
| `ESTIMATION_ERROR` | Transaction estimation failed during node execution. See [Estimation error details](#estimation-error-details) for common causes and remedies. |
| `INSUFFICIENT_NATIVE_TOKEN` | The wallet doesn't have enough of the blockchain's native asset to cover [gas fees](/wallets/gas-fees) for all pending transactions. |
| `ABI_SIGNATURE_PARAMS_MISMATCH` | The ABI signature and parameters don't match. |
| `FEE_EXCEEDS_MAX_ALLOWANCE` | The fee exceeds the per-transaction native token limit that protects against unintended sends. |
| `QUERY_NFT_METADATA_ERROR` | The NFT metadata cannot be found. |
| `GAS_LIMIT_TOO_LOW` | The provided `gasLimit` was too low to complete the transaction. |
| `TRANSACTION_UNDER_PRICE` | The transaction's `maxFee` or `priorityFee` is below the current mempool floor when the mempool is full. |
| `FAILED_ON_CHAIN` | The blockchain failed to process the transaction. |
| `FAILED_REORG` | The transaction was dropped because of a blockchain reorg. |
| `INTERNAL_ERROR` | The transaction failed due to an internal error. |
| `PAYMASTER_POLICY_NOT_ACTIVATED` | The Gas Station policy hasn't been set or activated. |
| `PAYMASTER_POLICY_EXCEED_MAX_DAILY_TRANSACTIONS` | The Gas Station policy's max daily transaction limit has been reached. Retry tomorrow or raise the policy limit. |
| `PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_PER_TX` | The transaction exceeds the policy's per-transaction USD spend limit. Reduce the amount or raise the policy limit. |
| `PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_DAILY` | The policy's max daily USD spend limit has been reached. Retry tomorrow or raise the policy limit. |
| `PAYMASTER_POLICY_EXCEED_MAX_NATIVE_TOKEN_DAILY` | The policy's max daily native-token spend limit has been reached. Retry tomorrow or raise the policy limit. |
| `PAYMASTER_POLICY_SENDER_IN_BLOCKLIST` | The sender wallet is blocked by the Gas Station policy. Update the policy blocklist to unblock the wallet. |
| `PAYMASTER_ENTITY_RESTRICTION` | Your account is restricted from using Gas Station. Check your [Gas Station policy](/wallets/gas-station/policy-management) configuration. |
| `SOLANA_ATA_NOT_FOUND` | The recipient's Associated Token Account (ATA) on Solana does not exist. See [Solana ATA sponsorship](/wallets/gas-station/solana-ata-sponsorship) to have Gas Station fund ATA creation, or [create and fund the ATA](/wallets/gas-station/create-solana-ata) yourself. |

## Estimation error details

When a transaction fails with `ESTIMATION_ERROR`, `errorDetails` provides the
specific reason.

### Insufficient balance

The wallet or contract doesn't have enough tokens to complete the transaction.

| errorDetails | Cause | Remedy |
| - | - | - |
| `ERC20: transfer amount exceeds balance` | The wallet doesn't have enough ERC-20 tokens to complete the transfer. | Verify the wallet has sufficient token balance before initiating the transaction. Top up the wallet if needed. |
| `ERC1155: insufficient balance for transfer` | The wallet doesn't have enough ERC-1155 tokens (NFTs or semi-fungible tokens) to transfer. | Check the wallet's ERC-1155 balance for the specific token ID. Ensure the correct token ID and amount are specified. |
| `Insufficient Balance` | General insufficient balance error. The wallet either doesn't have enough gas or doesn't have enough tokens for the transaction. | Verify the contract has sufficient USDC. This may require the contract owner to top up the contract. |

### Blocklist and access control

An account is restricted from performing the requested action.

&#x20;

| errorDetails | Cause | Remedy |
| - | - | - |
| `Blacklistable: account is blacklisted` | The recipient or sender address is on the token contract's denylist. | Verify you're not sending to the token contract address itself. |
| `AccessControl: account ... is missing role ...` | The wallet doesn't have the role or permission required to execute this function on the contract. | Have the contract administrator grant the necessary role, or use an authorized wallet. |

&#x20;

<Warning>
  Tokens sent to their own contract address are permanently locked and can't be
  recovered. Circle keeps the USDC contract address on its denylist to block
  this common mistake.
</Warning>

### Allowance and approval

Token spending approvals are missing or insufficient.

| errorDetails | Cause | Remedy |
| - | - | - |
| `ERC20: transfer amount exceeds allowance` | The contract hasn't been approved to spend enough tokens on behalf of the wallet. | Call the `approve()` function on the token contract to grant sufficient allowance to the spender contract. |
| `ERC20: insufficient allowance` | The spender doesn't have enough allowance to transfer the requested amount. | Increase the token allowance by calling `approve()` or `increaseAllowance()`. |
| `Check allowance` / `Allowance` | Generic allowance error. | Verify and increase token allowance. |

### Signature and authentication

The cryptographic signature is invalid or expired.

| errorDetails | Cause | Remedy |
| - | - | - |
| `EIP2612: invalid signature` | The permit signature is invalid, malformed, or was signed by the wrong key. | Generate a new valid signature using the correct private key and parameters. |
| `Permit: invalid signature` | Invalid permit signature. | Re-sign the permit with correct parameters. |
| `Invalid signature: not attester` | The signature wasn't created by an authorized attester (common in CCTP). | Use a signature from an authorized attester. |
| `Nonce already used` | The nonce in the signed message has already been consumed. | Use a fresh nonce value when creating the signature. |

### Smart account (ERC-4337)

Account abstraction wallets have specific failure modes.

| errorDetails | Cause | Remedy |
| - | - | - |
| `AA33 reverted: Pausable: paused` | The smart account or paymaster is paused. | Wait for the contract to be `unpaused`, or contact the administrator. |
| `AA95 out of gas` | The transaction ran out of gas during execution. | Increase the gas limit for the transaction. |

### Invalid parameters

Transaction parameters are incorrect.

| errorDetails | Cause | Remedy |
| - | - | - |
| `Transfer amount must be greater than zero` / `Amount must be nonzero` | The amount parameter cannot be zero. | Provide a positive amount value. |
| `Amount below minimum` / `USDC amount too small` | The amount is below the minimum required threshold. | Increase the amount to meet minimum requirements. |
| `ERC20: transfer to the zero address` | Cannot transfer tokens to the zero address (0x0). | Provide a valid non-zero recipient address. |
| `ERC721: invalid token ID` | The specified NFT token ID doesn't exist. | Verify the token ID exists and is valid. |
| `Max fee must be less than amount` | The fee exceeds the transaction amount. | Reduce the fee or increase the transaction amount. |
| `Slippage Limit Exceeded` | The price slippage exceeds the allowed tolerance. | Increase slippage tolerance or wait for better market conditions. |
| `Too little received` / `insufficient amountReceived` | The output amount is less than the minimum specified. | Adjust minimum output amount or retry when market conditions are favorable. |

### Timeout and execution

Generic errors during transaction execution.

| errorDetails | Cause | Remedy |
| - | - | - |
| `Fails to perform transaction estimation.` | General estimation failure without specific details. | Review contract state and transaction parameters. Often caused by network fee fluctuation; retry later often helps. |
| `execution aborted (timeout = 10s)` | Estimation took too long and timed out. | An RPC node was likely temporarily unavailable. Retry later often helps. |
| `execution reverted` | Generic revert without a specific reason from the RPC node. | Review contract state and transaction parameters. Often caused by network fee fluctuation; retry later often helps. |

## Troubleshooting failed transactions

If the cause of the failure isn't obvious from `errorReason` or `errorDetails`,
work through these checks:

* **Verify contract addresses.** Confirm the correct contract on the correct
  blockchain.
* **Verify transaction parameters.** Recipient addresses are valid and non-zero,
  token amounts meet minimums, and ABI signatures match the function being
  called.
* **Check balances and allowances.** The wallet has enough of the token being
  transferred; for ERC-20 spending, the contract has enough allowance from
  `approve()`.
* **Review contract state.** The contract isn't paused, and role-based access
  requirements are satisfied.
* **Verify authorization.** The calling wallet has the roles required by the
  contract. Check blocklist status when working with regulated tokens such as
  USDC.
* **Retry time-sensitive operations.** Regenerate expired signatures or nonces.
  Retry after a short delay if the error suggests the RPC node was temporarily
  unavailable.

<Tip>
  For complex reverts where `errorDetails` doesn't provide enough information,
  simulate the failing transaction in [Tenderly](https://tenderly.co/) to step
  through execution and identify where and why it reverts.
</Tip>