# Circle Docs: API reference Wallets > Developer documentation for Circle's developer tools > ## 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. ## Wallets - [Wallets API](https://developers.circle.com/api-reference/wallets.md): Create and manage developer-controlled and user-controlled wallets, execute transactions, and sign messages across supported blockchains. - [Postman collection](https://developers.circle.com/api-reference/wallets/postman.md): Use Circle's Postman collection to send API requests and explore the Programmable Wallets APIs. - [Wallets API rate limits](https://developers.circle.com/api-reference/wallets/rate-limits.md): Rate limits for the Circle Wallets API - [Wallets API error codes](https://developers.circle.com/api-reference/wallets/error-codes.md): Descriptions of error codes returned by the Wallets and Compliance Engine APIs. - [Transaction states and errors](https://developers.circle.com/api-reference/wallets/transaction-states-and-errors.md): Reference for the states, error reasons, and error details surfaced on Circle Wallets transaction and challenge webhooks and API responses. ### API overview #### Health - [Ping](https://developers.circle.com/api-reference/wallets/common/ping.md): Checks that the service is running. #### Webhook Subscriptions - [Get all notification subscriptions](https://developers.circle.com/api-reference/wallets/common/get-subscriptions.md): Retrieve an array of existing notification subscriptions. - [Create a notification subscription](https://developers.circle.com/api-reference/wallets/common/create-subscription.md): Create a notification subscription by configuring an endpoint to receive notifications. For details, see the [Notification Flows](https://developers.circle.com/wallets/webhook-notification-flows) guide. - [Retrieve a notification subscription](https://developers.circle.com/api-reference/wallets/common/get-subscription.md): Retrieve an existing notification subscription. - [Update a notification subscription](https://developers.circle.com/api-reference/wallets/common/update-subscription.md): Update subscription endpoint to receive notifications. - [Delete a notification subscription](https://developers.circle.com/api-reference/wallets/common/delete-subscription.md): Delete an existing subscription. - [Get a notification signature public key](https://developers.circle.com/api-reference/wallets/common/get-notification-signature.md): Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle. #### Webhooks - [Inbound transaction notification](https://developers.circle.com/api-reference/wallets/common/transactions-inbound.md): Sent when an inbound transaction changes state. The lifecycle state of the transaction is conveyed by the `state` field on the `notification` object. - [Outbound transaction notification](https://developers.circle.com/api-reference/wallets/common/transactions-outbound.md): Sent when an outbound transaction changes state. The lifecycle state of the transaction is conveyed by the `state` field on the `notification` object. - [Challenge notification](https://developers.circle.com/api-reference/wallets/common/challenges-initialize.md): Sent when a user-controlled wallet challenge changes state. The lifecycle state of the challenge is conveyed by the `state` field on the `notification` object. ### Configurations #### Faucet - [Request testnet tokens](https://developers.circle.com/api-reference/wallets/programmable-wallets/request-testnet-tokens.md): Request testnet tokens for your wallet. #### Monitor Tokens - [Retrieve existing monitored tokens.](https://developers.circle.com/api-reference/wallets/programmable-wallets/list-monitored-tokens.md): Get monitored tokens - [Set monitored tokens](https://developers.circle.com/api-reference/wallets/programmable-wallets/create-monitored-tokens.md): Add a new token to the monitored token list. - [Update monitored tokens](https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens.md): Upsert the monitored token list. - [Update monitored tokens scope](https://developers.circle.com/api-reference/wallets/programmable-wallets/update-monitored-tokens-scope.md): Select between monitoring all tokens or selected tokens added to the monitored tokens list. - [Delete monitored tokens](https://developers.circle.com/api-reference/wallets/programmable-wallets/delete-monitored-tokens.md): Delete tokens from the monitored token list. #### Developer Account - [Get public key for entity](https://developers.circle.com/api-reference/wallets/programmable-wallets/get-public-key.md): Get the public key associated with the entity. - [Get configuration for entity](https://developers.circle.com/api-reference/wallets/programmable-wallets/get-entity-config.md): Get the app ID associated to the entity. ### Developer-controlled #### Wallets - [Create wallets](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-wallet.md): Creates a new developer-controlled wallet or a batch of wallets within a wallet set, given the target blockchain and wallet name. - [List wallets](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallets.md): Retrieves a list of all wallets that fit the specified parameters. - [Retrieve a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet.md): Retrieve an existing wallet - [Update a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/update-wallet.md): Updates info metadata of a wallet. - [List wallets with balances](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallets-with-balances.md): Retrieves a list of all wallets that match the specified parameters. Wallet balances update automatically after each transfer. - [Derive wallet by address](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/derive-wallet-by-address.md): Creates a wallet on the target blockchain using the same address as the source wallet identified by source blockchain and wallet address. If the target wallet already exists, its metadata is updated. - [Get token balance for a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-wallet-balance.md): Fetches the digital asset balance for a single developer-controlled wallet using its unique identifier. - [Derive a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/derive-wallet.md): Derives an EOA (Externally Owned Account) or SCA (Smart Contract Account) wallet using the address of the specified wallet and blockchain. If the target wallet already exists, its metadata will be updated with the provided metadata. This operation is only supported for EVM-based blockchains. - [Get NFTs for a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-wallet-nfts.md): Fetches the info for all NFTs stored in a single developer-controlled wallet, using the wallets unique identifier. #### Signing - [Sign message](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-message.md): Sign a message from a specified developer-controlled wallet. This endpoint supports message signing for 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… - [Sign typed data](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-typed-data.md): | Sign the EIP-712 typed structured data from a specified developer-controlled wallet. To identify the wallet, you must provide either `walletId`, or both `walletAddress` and `blockchain` in the request body. This endpoint only supports Ethereum and EVM-compatible blockchains. Please note that not a… - [Sign transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-transaction.md): Sign a transaction from a specific developer-controlled wallet. - [Sign delegate action](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/sign-delegate-action.md): Sign a delegate action from a specific developer-controlled wallet. #### Transactions - [List transactions](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/list-transactions.md): Lists all transactions. Includes details such as status, source/destination, and transaction hash. - [Get a transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-transaction.md): Retrieves info for a single transaction using it's unique identifier. - [Get the lowest nonce pending transaction for a wallet](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-lowest-nonce-transaction.md): For a nonce-supported blockchain, get the lowest nonce transaction that's in QUEUED or SENT or STUCK state for the provided wallet. - [Get fee parameters of a blockchain](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-fee-parameters.md): Get latest fee parameters of a blockchain with an optional account type (default to 'EOA'). - [Create a transfer transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-transfer.md): Initiates an on-chain digital asset transfer from a specified developer-controlled wallet. - [Validate an address](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-validate-address.md): Confirms that a specified address is valid for a given token on a certain blockchain. - [Estimate fee for a contract execution transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-transaction-estimate-fee.md): Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain. - [Estimate fee for a transfer transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-transfer-estimate-fee.md): Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token. - [Create a contract execution transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-contract-execution.md): Creates a transaction which executes a smart contract. ABI parameters must be passed in the request. Related transactions may be submitted as a batch transaction in a single call. - [Create a wallet upgrade transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-wallet-upgrade.md): Creates a transaction which upgrades a wallet. - [Cancel a transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-cancel.md): Cancels a specified transaction from a developer-controlled wallet. Gas fees may still be incurred. This is a best-effort operation, it won't be effective if the original transaction has already been processed by the blockchain. - [Accelerate a transaction](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-developer-transaction-accelerate.md): Accelerates a specified transaction from a developer-controlled wallet. Additional gas fees may be incurred. #### Wallet Sets - [Get all wallet sets](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet-sets.md): Retrieve an array of existing wallet sets. - [Get a wallet set](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-wallet-set.md): Retrieve an existing wallet set. - [Create a new wallet set](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/create-wallet-set.md): Creates a new developer-controlled wallet set. - [Update a wallet set](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/update-wallet-set.md): Update the name of the wallet set #### Token Lookup - [Get token details](https://developers.circle.com/api-reference/wallets/developer-controlled-wallets/get-token-id.md): 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. ### User-controlled #### Users - [Create a challenge for user initialization with wallet creation](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-with-pin-challenge.md): Creates a challenge for user initialization and creates one or more wallets. - [List users](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-users.md): Get all the users under the entity. - [Get a user by ID](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user.md): Get user by ID. - [List challenges](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-user-challenges.md): List all challenges by status for a user. - [Get a challenge](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-challenge.md): Retrieve a user challenge. - [Get user](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-by-token.md): Retrieve the user by token. #### Wallets - [Create wallets](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-wallet.md): Generates a challenge to create a new user-controlled wallet or a batch of wallets. You must specify the blockchain and wallet name. - [Get token balance for a wallet](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-balance.md): Fetches the digital asset balance for a single user-controlled wallet using its unique identifier. - [Get NFTs for a wallet](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallet-nfts.md): Fetches the info for all NFTs stored in a single user-controlled wallet, using the wallets unique identifier. - [Get a wallet](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-wallet.md): Retrieves info for a single user-controlled wallet using it's unique identifier. - [Update a wallet](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-wallet.md): Updates info for a single user-controlled wallet using it's unique identifier. - [List wallets](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-wallets.md): Retrieves a list of all user-controlled wallets that fit the specified parameters. #### Transactions - [Create a challenge for a transfer](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-transfer-challenge.md): Generates a challenge for initiating an on-chain digital asset transfer from a specified user-controlled wallet. - [Create a Challenge to accelerate a transaction](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-accelerate-challenge.md): 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](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-cancel-challenge.md): Generates a challenge to cancel a specific transaction from a user-controlled wallet. Gas fees may still apply. - [Create a challenge for contract execution](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-contract-execution-challenge.md): Generates a challenge for creating a transaction which executes a smart contract. ABI parameters must be passed in the request. - [Create a challenge for a wallet upgrade](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-transaction-wallet-upgrade-challenge.md): Generates a challenge to create a transaction that upgrades a wallet. - [List transactions](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/list-transactions.md): Lists all transactions. Includes details such as status, source/destination, and transaction hash. - [Get a transaction](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-transaction.md): Retrieves info for a single transaction using it's unique identifier. - [Get the lowest nonce pending transaction for a wallet](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-lowest-nonce-transaction.md): For a nonce-supported blockchain, get the lowest nonce transaction that's in QUEUED or SENT or STUCK state for the provided wallet. - [Estimate fee for a transfer transaction](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transfer-estimate-fee.md): Estimates gas fees that will be incurred for a transfer transaction; given its amount, blockchain, and token. - [Estimate fee for a contract execution transaction](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-transaction-estimate-fee.md): Estimates gas fees that will be incurred for a contract execution transaction, given its ABI parameters and blockchain. - [Validate an address](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-validate-address.md): Confirms that a specified address is valid for a given token on a certain blockchain. #### Signing - [Create a challenge to sign message](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-message.md): 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 differe… - [Create a challenge to sign typed data](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-typed-data.md): 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… - [Create a challenge to sign transaction](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/sign-user-transaction.md): Generate a challenge for signing the transaction from a specific user-controlled wallet. #### PIN Authentication - [Create a user](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user.md): Create a user. - [Create a user token](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-user-token.md): Generate user session and SDK secret key. - [Create a challenge for PIN setup](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-challenge.md): Creates a challenge for PIN setup without setting up the wallets. - [Create a challenge to update PIN](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/update-user-pin-challenge.md): Creates a challenge to update a user's PIN using the current PIN. - [Create a challenge for PIN restore](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-user-pin-restore-challenge.md): Creates a challenge to restore a user's PIN using security questions. #### Token Lookup - [Get token details](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/get-token-id.md): 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. #### Social/ Email Authentication - [Get deviceToken to perform social login](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-social-login.md): Get deviceToken to perform social login in SDK - [Get a deviceToken to log in with email OTP](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/create-device-token-email-login.md): Get a deviceToken to login with email OTP in SDK - [Get a new userToken with the refreshToken](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/refresh-user-token.md): 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](https://developers.circle.com/api-reference/wallets/user-controlled-wallets/resend-otp.md): 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. ### Modular #### Transfers - [List transfers](https://developers.circle.com/api-reference/wallets/buidl/list-transfers.md): Retrieve a list of transfers that fit the specified parameters. - [Retrieve a transfer](https://developers.circle.com/api-reference/wallets/buidl/get-transfer.md): Retrieve an existing transfer. #### UserOps - [List user operations](https://developers.circle.com/api-reference/wallets/buidl/list-user-ops.md): Retrieve a list of all user operations that fit the specified parameters. - [Retrieve a user operation](https://developers.circle.com/api-reference/wallets/buidl/get-user-op.md): Retrieve an existing user operation. #### Wallets - [Get wallet balances](https://developers.circle.com/api-reference/wallets/buidl/list-wallet-balances-by-id.md): Retrieve the balances of a wallet by its ID. - [Get wallet NFTs](https://developers.circle.com/api-reference/wallets/buidl/list-wallet-nfts-by-id.md): Retrieve the NFTs of a wallet by its ID. - [Get wallet balances by blockchain and address](https://developers.circle.com/api-reference/wallets/buidl/list-wallet-balances-by-blockchain-address.md): Retrieve wallet balances by blockchain and address. - [Get wallet NFTs by blockchain and address](https://developers.circle.com/api-reference/wallets/buidl/list-wallet-nfts-by-blockchain-address.md): Retrieve the NFTs of a wallet by applicable blockchain and address. ### Compliance Engine #### Address Screening - [Screen a blockchain address](https://developers.circle.com/api-reference/wallets/compliance/screen-address.md): Create a screening request for a specific blockchain address and chain. ## OpenAPI Specs - [configurations_2](/openapi/configurations_2.yaml) - [configurations_1](/openapi/configurations_1.yaml) - [developer-controlled-wallets](/openapi/developer-controlled-wallets.yaml) - [user-controlled-wallets](/openapi/user-controlled-wallets.yaml) - [buidl-wallets](/openapi/buidl-wallets.yaml) - [compliance](/openapi/compliance.yaml)