bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 21쪽
ion of the policy.` | Reduce the transaction amount, or raise the policy's per-transaction USD limit. |
| `155251` | `400` | `Exceeded max spend USD daily of the policy.` | Wait for the daily counter to reset, or raise the policy's daily USD spend limit. |
| `155252` | `400` | `Exceeded max native token daily of the policy.` | Wait for the daily counter to reset, or raise the policy's daily native token limit. |
| `155253` | `400` | `Sender is in policy blocklist.` | Remove the sender from the policy's blocklist, or use a wallet not on the blocklist. |
| `155254` | `400` | `Non-EIP1559 chains don't support maxFee/priorityFee.` | Remove `maxFee` and `priorityFee`. Use `gasPrice` for non-EIP-1559 blockchains. |
| `155255` | `400` | `The entity is restricted in paymaster.` | Check the account's [Gas Station policy](/wallets/gas-station/policy-management) configuration. |
| `155256` | `400` | `Default policy for the blockchain is not found in paymaster.` | Configure a default [Gas Station policy](/wallets/gas-station/policy-management) for the blockchain. |
| `155257` | `400` | `The transfer amount is insufficient to make the destination account rent exempted or the balance of the source account is insufficient to remain rent exempted. The source address's remaining balance after transfer must be either zero or at least the rent exemption threshold.` | On Solana, adjust the transfer so the destination reaches the rent exemption threshold and the source balance is either zero or at least the threshold. |
| `155258` | `400` | `The asset amount owned by the wallet is insufficient for the transaction.` | Confirm that the wallet's onchain balance can cover the transaction. Add funds or wait for the balance to update, then retry. |
| `155259` | `400` | `The token address in the destination associated token account does not match the token address in the transaction.` | Use a destination associated token account whose token address matches the transaction's token address. |
| `155260` | `400` | `The account is not valid for the instruction.` | Verify that every account is valid for the Solana instruction. |
| `155261` | `400` | `The seeds provided for creating associated token account are invalid.` | Verify the associated token account inputs and retry with valid seeds. |
| `155262` | `400` | `The account is not found, could be caused by transacting from a new account with zero balance.` | Fund the account and retry. On Solana, an account with zero balance may not exist onchain. |
| `155263` | `400` | `The transaction size is too large, could be caused by too many parameters.` | Reduce the number or size of transaction parameters, or split the operation into multiple transactions. |
| `155264` | `400` | `Wait for pending transactions to be included on the blockchain before submitting new requests. EVM chains restrict the number of queued transactions per sender address.` | Wait for pending transactions to finalize. To increase throughput, distribute transactions across multiple wallets. See [Transaction throughput](/wallets/transaction-limits-and-optimizations). |
## Wallet (`155501`–`155515`)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `155501` | `409` | `Frozen wallets can not be updated or interact with, only query.` | Frozen wallets support query only. |
| `155502` | `403` | `Max amount of wallets (tentative 1M) reached under 1 wallet set.` | Create a new wallet set to add more wallets. |
| `155503` | `400` | `Metadata array length needs to match wallet count in create developer wallets request.` | Match the `metadata` array length to the wallet count in `POST /developer/wallets`. |
| `155504` | `400` | `Metadata array length needs to match number of blockchains in create user wallets request.` | Match the `metadata` array length to the number of blockchains in the create-user-wallet request. |
| `155505` | `400` | `SCA wallet needs to wait for first-time transaction to be queued before processing more transactions.` | Wait for the first SCA transaction to be queued before submitting more. |
| `155506` | `400` | `SCA wallet config is invalid.` | Check the SCA wallet configuration. |
| `155507` | `400` | `SCA account is not supported on the given blockchain.` | Use a supported blockchain. See [supported blockchains](/wallets/supported-blockchains). |
| `155509` | `400` | `Entity needs to setup paymaster policy on Mainnet before SCA account creation. Please check paymaster policy setup` | Configure a single paymaster policy for the blockchain in the Circle Console. |
| `155510` | `400` | `The operation is not supported on the blockchain you specify.` | Use a wallet on a blockchain that supports this operation. |
| `155511` | `400` | `Blockchain is not supported for wallet creation.` | Use a supported blockchain. See [supported blockchains](/wallets/supported-blockchains). |
| `155512` | `404` | `The owner of the SCA wallet can not be found.` | Check whether ownership was transferred or the account is set up correctly. |
| `155515` | `400` | `The provided wallet account type is not supported by this API.` | Use a supported account type. See [account types](/wallets/account-types). |
## Wallet set (`155601`)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `155601` | `400` | `Failed to retrieve wallet set which already exists.` | Retry with a unique wallet set ID. |
## Transaction signing (`155801`–`155808`)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `155801` | `400` | `Transaction or rawTransaction is invalid.` | Provide a valid `transaction` or `rawTransaction`. |
| `155802` | `400` | `Account not found.` | Verify the account in the transaction header. |
| `155803` | `400` | `Not signer account.` | Sign from the account that is the transaction's signer. |
| `155804` | `400` | `Transaction is already signed.` | No action required. |
| `155805` | `400` | `Transaction failed to deserialize.` | Check the transaction format. |
| `155806` | `400` | `The transaction size exceeds blockchain limit.` | Reduce the transaction payload. |
| `155807` | `400` | `The chain ID is not supported for signing.` | Use a supported chain ID for EVM signing. |
| `155808` | `400` | `The chain ID is missing in sign request.` | Include a chain ID in the typed data or transaction. |
## Shared (`156001`–`156030`)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `156001` | `404` | `Cannot find target wallet in the system. Either the specified wallet doesn't exist or it's not accessible to the caller.` | Verify the wallet ID. |
| `156002` | `404` | `Cannot find target token in the system. Either the specified token doesn't exist or it's not accessible to the caller.` | Verify the token ID. |
| `156003` | `404` | `Cannot find target transaction in the system. Either the specified transaction doesn't exist or it's not accessible to the caller.` | Verify the transaction ID. |
| `156004` | `400` | `Reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertext.` | Re-encrypt the entity secret to generate a new ciphertext. |
| `156005` | `404` | `Cannot find target wallet set in the system. Either no such wallet set, or it's not accessible to the caller.` | Verify the wallet set ID. |
| `156006` | `400` | `TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.` | Use a `TEST_API` key for testnets and a `LIVE_API` key for mainnets. |
| `156007` | `401` | `TEST_API key or LIVE_API key is not found for the request.` | Provide a valid API key. |
| `156008` | `400` | `Cannot find target entity config in the system. Either no such entity config, or it's not accessible to the caller.` | Verify the entity config. |
| `156009` | `400` | `Fail to parse id as UUID in url.` | Provide an ID in UUID format. |
| `156010` | `404` | `Cannot find the corresponding entity in the system.` | Verify the entity. |
| `156011` | `404` | `Cannot find target nftTokenId in the system.` | Verify the `nftTokenId`. |
| `156012` | `404` | `Cannot find corresponding pagination cursor in the system.` | Correct the pagination parameters. |
| `156013` | `400` | `The provided entity secret is invalid.` | Create or re-encrypt the entity secret. |
| `156014` | `400` | `Pagination params are invalid. Only UUID format is supported for pageBefore and pageAfter.` | Use UUID format for `pageBefore` and `pageAfter`. |
| `156015` | `409` | `The secret for this entity has already been set.` | No action required. |
| `156016` | `403` | `The entity secret has not been set yet. Please provide encrypted ciphertext in the console.` | Provide encrypted ciphertext in the Circle Console. |
| `156017` | `400` | `The specified blockchain parameters are incorrect.` | Correct the blockchain parameters. |
| `156018` | `403` | `The uploaded recovery file is invalid.` | Upload a valid recovery file. |
| `156019` | `403` | `Current entity secret is invalid. Please rotate the entity secret first.` | Rotate the entity secret in the Circle Console. |
| `156020` | `403` | `Please use a new idempotency key.` | Use a new idempotency key. |
| `156021` | `409` | `A new wallet set ID is required.` | Use a new wallet set ID. |
| `156023` | `409` | `EncodedByHex is true in sign request, but the message is not hex encoded.` | Provide a hex-encoded message, or set `encodedByHex` to `false`. |
| `156024` | `400` | `Data is not a valid JSON string in sign request.` | Provide a valid JSON typed data string. |
| `156025` | `400` | `Invalid message in request.` | Provide a valid EIP-191 message. |
| `156026` | `400` | `Invalid typed data in request.` | Provide valid EIP-712 typed data. |
| `156027` | `400` | `The specified blockchain is either not supported or deprecated.` | Use a supported blockchain. See [supported blockchains](/wallets/supported-blockchains). |
| `156030` | `400` | `Invalid unsigned delegate action in request.` | Provide a valid delegate action. |
## Compliance Engine screening (`280001`–`280002`)
| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `280001` | `400` | `Unsupported blockchain` | Use a supported blockchain. |
| `280002` | `400` | `Invalid blockchain address` | Provide a valid blockchain address. |
# Postman collection
Source: https://developers.circle.com/api-reference/wallets/postman
Use Circle's Postman collection to send API requests and explore the Programmable Wallets APIs.
Circle's Postman collection provides sample requests for the Programmable
Wallets APIs. Run them in [Postman](https://www.postman.com/), an API client.
The collection matches the layout of the
[API reference](/api-reference/wallets/common/ping).
## Run in Postman
Select **Run in Postman** below. Choose one of the following options:
* **Fork**: Copies the collection and keeps a link to the parent.
* **View**: Lets you try the API without importing it.
* **Import**: Copies the collection without keeping a link to Circle's copy.
| Collection | Link |
| :- | :- |
| Wallets | [](https://app.getpostman.com/run-collection/15022472-80b87d8a-844b-422e-9c2a-3a6ce86a2644?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D15022472-80b87d8a-844b-422e-9c2a-3a6ce86a2644%26entityType%3Dcollection%26workspaceId%3D73acd722-fab9-49b0-9382-086659476258) |
## Authorization
To authorize your session, use Circle's Postman variable `apiKey` and add your
API key to the `environment` or `collection` variables. See Postman's
[using variables](https://learning.postman.com/docs/sending-requests/variables/)
guide for details.
For more information about creating an API key, see
[API keys](/api-reference/keys).
## Entity secret
Developer-controlled wallets need an entity secret. Register one first. See the
[Register your entity secret](/wallets/dev-controlled/register-entity-secret)
quickstart.
Add your **hex-encoded entity secret** as a Postman variable. Don't use the
encrypted ciphertext. The collection's helper scripts re-encrypt the secret
before each call to meet Circle's uniqueness rule.
Run the **Get public key for entity** request once. The collection stores the
key as a variable and uses it to encrypt your secret.
# Set monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/create-monitored-tokens
openapi/configurations_1.yaml post /v1/w3s/config/entity/monitoredTokens
Add a new token to the monitored token list.
# Delete monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/delete-monitored-tokens
openapi/configurations_1.yaml post /v1/w3s/config/entity/monitoredTokens/delete
Delete tokens from the monitored token list.
# Get configuration for entity
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/get-entity-config
openapi/configurations_1.yaml get /v1/w3s/config/entity
Get the app ID associated to the entity.
# Get public key for entity
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/get-public-key
openapi/configurations_1.yaml get /v1/w3s/config/entity/publicKey
Get the public key associated with the entity.
# Retrieve existing monitored tokens.
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/list-monitored-tokens
openapi/configurations_1.yaml get /v1/w3s/config/entity/monitoredTokens
Get monitored tokens
# Request testnet tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/request-testnet-tokens
openapi/configurations_1.yaml post /v1/faucet/drips
Request testnet tokens for your wallet.
**Note:** Calling the `/v1/faucet/drips` API requires upgrading to mainnet.
# Update monitored tokens
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens
openapi/configurations_1.yaml put /v1/w3s/config/entity/monitoredTokens
Upsert the monitored token list.
# Update monitored tokens scope
Source: https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens-scope
openapi/configurations_1.yaml put /v1/w3s/config/entity/monitoredTokens/scope
Select between monitoring all tokens or selected tokens added to the monitored tokens list.
# Wallets API rate limits
Source: https://developers.circle.com/api-reference/wallets/rate-limits
Rate limits for the Circle Wallets API
Wallets API endpoints are rate limited per second. The defaults are:
* **GET**: 20 requests per second
* **POST**: 5 requests per second
The following endpoints are limited to 10 requests per second:
* `POST /v1/w3s/developer/wallets`
* `PUT /v1/w3s/developer/wallets/{id}/blockchains/{blockchain}`
* `POST /v1/w3s/transactions/transfer/estimateFee`
* `POST /v1/w3s/transactions/contractExecution/estimateFee`
* `POST /v1/w3s/users/token`
* `POST /v1/w3s/user/sign/transaction`
* `POST /v1/w3s/user/sign/message`
* `POST /v1/w3s/user/sign/typedData`
* `POST /v1/w3s/developer/sign/transaction`
* `POST /v1/w3s/developer/sign/message`
* `POST /v1/w3s/developer/sign/typedData`
* `POST /v1/w3s/developer/sign/delegateAction`
When a request exceeds the rate limit, the API returns HTTP
`429 Too Many Requests`. Cache static values such as token IDs and public keys
on the client to avoid unnecessary calls.
# Transaction states and errors
Source: https://developers.circle.com/api-reference/wallets/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 St프로젝트로 돌아가기
