Circle USYC 백서 전문

ation 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.   | 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. |   <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> # Get a deviceToken to log in with email OTP Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-email-login openapi/user-controlled-wallets.yaml post /v1/w3s/users/email/token Get a deviceToken to login with email OTP in SDK # Get deviceToken to perform social login Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-social-login openapi/user-controlled-wallets.yaml post /v1/w3s/users/social/token Get deviceToken to perform social login in SDK # Estimate fee for a contract execution transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transaction-estimate-fee openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/contractExecution/estimateFee Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain. # Estimate fee for a transfer transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transfer-estimate-fee openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/transfer/estimateFee Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token. # Create a user Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user openapi/user-controlled-wallets.yaml post /v1/w3s/users Create a user. # Create a challenge for PIN setup Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/pin Creates a challenge for PIN setup without setting up the wallets. # Create a challenge for PIN restore Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-restore-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/pin/restore Creates a challenge to restore a user's PIN using security questions. # Create a Challenge to accelerate a transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-accelerate-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/{id}/accelerate Generates a challenge to accelerate a specific transaction from a user-controlled wallet. Additional gas fees may apply. # Create a challenge to cancel a transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-cancel-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/{id}/cancel Generates a challenge to cancel a specific transaction from a user-controlled wallet. Gas fees may still apply. # Create a challenge for contract execution Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-contract-execution-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/contractExecution Generates a challenge for creating a transaction which executes a smart contract. ABI parameters must be passed in the request. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. # Create a challenge for a transfer Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-transfer-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/transfer Generates a challenge for initiating an on-chain digital asset transfer from a specified user-controlled wallet. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. # Create a challenge for a wallet upgrade Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-wallet-upgrade-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/transactions/walletUpgrade Generates a challenge to create a transaction that upgrades a wallet. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. # Create wallets Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-wallet openapi/user-controlled-wallets.yaml post /v1/w3s/user/wallets Generates a challenge to create a new user-controlled wallet or a batch of wallets. You must specify the blockchain and wallet name. # Create a challenge for user initialization with wallet creation Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge openapi/user-controlled-wallets.yaml post /v1/w3s/user/initialize Creates a challenge for user initialization and creates one or more wallets. # Validate an address Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-validate-address openapi/user-controlled-wallets.yaml post /v1/w3s/transactions/validateAddress Confirms that a specified address is valid for a given token on a certain blockchain. # Get the lowest nonce pending transaction for a wallet Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-lowest-nonce-transaction openapi/user-controlled-wallets.yaml get /v1/w3s/transactions/lowestNonceTransaction For a nonce-supported blockchain, get the lowest nonce transaction that's in QUEUED or SENT or STUCK state for the provided wallet. # Get token details Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-token-id openapi/user-controlled-wallets.yaml get /v1/w3s/tokens/{id} Fetches details of a specific token given its unique identifier. Every token in your network of wallets has a UUID associated with it, regardless of whether it's already recognized or was added as a monitored token. # Get a transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-transaction openapi/user-controlled-wallets.yaml get /v1/w3s/transactions/{id} Retrieves info for a single transaction using it's unique identifier. # Get a user by ID Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user openapi/user-controlled-wallets.yaml get /v1/w3s/users/{id} Get user by ID. # Get user Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-by-token openapi/user-controlled-wallets.yaml get /v1/w3s/user Retrieve the user by token. # Get a challenge Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-challenge openapi/user-controlled-wallets.yaml get /v1/w3s/user/challenges/{id} Retrieve a user challenge. # Create a user token Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-token openapi/user-controlled-wallets.yaml post /v1/w3s/users/token Generate user session and SDK secret key. # Get a wallet Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-wallet openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id} Retrieves info for a single user-controlled wallet using it's unique identifier. # List transactions Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-transactions openapi/user-controlled-wallets.yaml get /v1/w3s/transactions Lists all transactions. Includes details such as status, source/destination, and transaction hash. # List challenges Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-user-challenges openapi/user-controlled-wallets.yaml get /v1/w3s/user/challenges List all challenges by status for a user. # List users Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-users openapi/user-controlled-wallets.yaml get /v1/w3s/users Get all the users under the entity. # Get token balance for a wallet Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-balance openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id}/balances Fetches the digital asset balance for a single user-controlled wallet using its unique identifier. **Note**: On Aptos, this endpoint only returns balances for tokens stored in primary storage. Tokens held in [AIP-21](https://github.com/aptos-labs/aptos-core/releases/tag/aptos-node-v1.5.0) secondary storage are excluded from balance queries and deposit notifications to prevent incorrect or misleading results from secondary storage-based state changes. # Get NFTs for a wallet Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-nfts openapi/user-controlled-wallets.yaml get /v1/w3s/wallets/{id}/nfts Fetches the info for all NFTs stored in a single user-controlled wallet, using the wallets unique identifier. # List wallets Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallets openapi/user-controlled-wallets.yaml get /v1/w3s/wallets Retrieves a list of all user-controlled wallets that fit the specified parameters. # Get a new userToken with the refreshToken Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/refresh-user-token openapi/user-controlled-wallets.yaml post /v1/w3s/users/token/refresh Get a new userToken with the refreshToken passed over from sdk/performLogin which matches to the current userToken # Resend an OTP email to the user Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/resend-otp openapi/user-controlled-wallets.yaml post /v1/w3s/users/email/resendOTP When the users don’t receive the OTP email, you can call this API to resend OTP email. The prior OTP email would expire after the new one is sent out. # Create a challenge to sign message Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-message openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/message Generates a challenge for signing a message from a specified user-controlled wallet. This endpoint supports Ethereum-based blockchains (using EIP-191), Solana and Aptos (using Ed25519 signatures). Note that Smart Contract Accounts (SCA) are specific to Ethereum and EVM-compatible chains. The difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also check the list of Ethereum Dapps that support SCA: https://eip1271.io/. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. # Create a challenge to sign transaction Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-transaction openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/transaction Generate a challenge for signing the transaction from a specific user-controlled wallet. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. NOTE: This endpoint supports the following blockchains: SOL, SOL-DEVNET, EVM, EVM-TESTNET. Each chain defines its own standard. For more details, see [Signing APIs](https://developers.circle.com/w3s/signing-apis). # Create a challenge to sign typed data Source: https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-typed-data openapi/user-controlled-wallets.yaml post /v1/w3s/user/sign/typedData Generates a challenge for signing the EIP-712 typed structured data from a specified user-controlled wallet. This endpoint only supports Ethereum and EVM-compatible blockchains. Please note that not all Dapps currently support Smart Contract Accounts (SCA); the difference between Ethereum's EOA and SCA can be found in the [account types guide](https://developers.circle.com/wallets/account-types). You can also