Introducing the Future of Wallet Management with Developer-Controlled Wallets


Welcome to the dynamic world of Web3. Whether you're a seasoned blockchain enthusiast or stepping into the decentralized sphere for the first time, this guide tailored for Developer-Controlled Wallets using Circle's Web3 Services Console awaits.

Harness the power of Web3 technology to provide an unparalleled experience for your users, while maintaining full control and enhanced security over their wallets. Let's take a peek at the standout features that make the Web3 Services Console an irresistible choice for your application

Advanced Security

Benefit from MPC technology, which eliminates single points of failure and enhances security against unauthorized access and theft.

Innovative Blockchain Functionality

Grant users access to digital currencies, NFTs, and other blockchain-powered experiences with ease.

Blockchain Agnostic

Build once, deploy across multiple blockchains, such as Ethereum, Polygon, and Avalanche.

Reliable Operations Monitoring

Built-in transaction logs, user-level monitoring, and error reporting help you troubleshoot and support your users effectively.

Instant Access

Get started immediately, with pay-as-you-go pricing and no upfront fees or contracts.

Before we dive in, there's a special feature we'd like to introduce that can significantly enhance your learning and experimenting experience: our "Try It Out" components.

What are "Try it out" components?

Our "Try It Out" components provide you with an interactive environment where you can directly test API requests in the simplest way possible, without the need for additional tools or platforms.

How does it work?

As you navigate through the tutorial, you'll notice certain steps come with a "Try It Out" option. All you need to do is input the necessary details into the provided fields and send the request. You'll receive instant feedback and can see how the request would function in a real-world setting.

Your data and your security

Your data's security is our utmost priority. When using our "Try It Out" components, data is only stored within the context of the current page. This means a simple page refresh clears all input information and removes it. It's therefore a secure, risk-free environment for you to play around in.

However, if you still have concerns about security or simply don't wish for certain details to be used in any manner, you're not obliged to use this feature. It's an additional offering and in no way mandatory.

Upon completing this tutorial, you also have the option to delete your API key and rotate your Entity Secret should you choose to do so.

Step 1: Setting Up Your Testnet API key

Ready to begin?

A Circle Web3 Services API Key identifies who submits API requests. Circle uses the API Key to authenticate your requests, so only you can interact with Circle using your key. To create an API Key, you first need a Circle Web3 Services account. If you didn't create one yet, use the following link to sign up with your email address. The account is free to use for testing.

Set up your account

Understanding Testnet versus Mainnet Environments

Before you proceed, it's critical to differentiate two fundamental environments in blockchain development: Testnet and Mainnet.


Testnet is akin to a training ground for developers. It's a simulated environment where you can develop, test, and polish your applications with confidence. In this space, you can execute transactions and test various scenarios without any financial implications, as Testnet does not involve real cryptocurrencies or assets.


In contrast, Mainnet is where everything goes live. This network handles actual transactions with genuine digital currencies. Operating on Mainnet means dealing with real-world consequences and genuine assets. The results of actions performed here are immediate and impactful.

While it may seem exciting to leap directly into Mainnet, it is crucial to rigorously test and validate your applications within the Testnet environment first. This precaution ensures that all systems and functionalities operate correctly before you transition to a live environment where stakes are higher. Once you have a thoroughly vetted application in Testnet, you can smoothly migrate to Mainnet operations.

Creating your API key

To proceed with this guide, create a standard API key. Here's how to generate it:

  • 1

    Log in to the console

    First, log in to the Circle Web3 Services console.

  • 2

    Open the API keys page

    After you log in, open the API Keys page, and then click CREATE A KEY.

    List of API keys
  • 3

    Set Up your new API key

    Provide a Key Name for your new API key, and then select Standard Key.

    Create new API key form
  • 4

    Copy and Store safely

    The console displays your key only once after you create it. Make sure to copy the key value and store it in a secure location. You can't retrieve the key value after you close the dialog. If you lose the value, you need to create another key. Never share your key with anyone.

    API key successfully created

The power of Testnet

Now that you have a Testnet API Key, you can:

Test With Assurance

Engage in robust testing of your applications, smart contracts, and other blockchain innovations, all within a safe environment that simulates real-world operations. This sandbox allows for trial and error without any financial stakes, so mistakes carry no monetary risk.

Achieve Broad Compatibility

Testnet serves as a preparatory platform for launches on various blockchains. Whether your focus is on Ethereum, Polygon, or Avalanche, Testnet provides insights into how your applications will perform across different ecosystems.

Encourage Innovation

The Testnet environment is the perfect place to brainstorm and develop new blockchain solutions. Here, you have the license to push boundaries and explore various possibilities without financial constraints.

Iterate Swiftly

Benefit from the ability to quickly refine your projects based on immediate feedback and test insights. The adaptable nature of Testnet supports rapid prototyping and swift iteration, which can lead to faster advancements and better outcomes in your development cycle.

Step 2: Understanding the Entity Secret in Developer-Controlled Wallets

The Entity Secret is an integral component in Developer-Controlled Wallets, serving as a key element in bolstering security.

What is the Entity Secret?

The Entity Secret is a robust 32-byte key engineered to enhance the security mechanisms of Developer Controlled Wallets. Its value lies not only in its complexity but also in the specific security benefits it confers.

The importance of the Entity Secret


The Entity Secret is generated by you and remains known exclusively to you. Consider it as your private password or a cryptographic signature that distinguishes your activities.

Enhanced Security for Critical API Requests

For critical actions such as wallet creation or initiating transactions, the Entity Secret comes into play. Attaching an encrypted version of the Entity Secret to these API requests provides an added authentication factor, reinforcing the security infrastructure.

Dynamic Protection

With a requirement to re-encrypt the Entity Secret for each API request, you avoid the risks associated with having a static key, which could be vulnerable to security breaches. This dynamic approach means that every request is identifiably distinct, providing fortified protection against potential attacks.

Sole Authority

While our platform enables operations using the Entity Secret, it does not store it. This design choice comes with dual implications: First, it ensures you are the sole entity capable of using your private keys, thus preserving absolute control over them. Second, it places the responsibility squarely on your shoulders to secure the Entity Secret conscientiously, as its security is paramount to the overall protection of your Developer-Controlled Wallets.

Balancing Power with Responsibility as a Developer

The Entity Secret embodies the level of trust and authority that our platform confers upon developers. It enables smooth access to the extensive capabilities of developer-controlled wallets, while simultaneously ensuring their security is maintained. However, great power necessitates equally great responsibility. The safeguarding, encryption, and periodic renewal of the Entity Secret are duties that rest with you, the developer.

This dynamic of empowering developers while also entrusting them with critical security tasks reflects the core principles of decentralization intrinsic to the web3 ecosystem. As a developer, you're more than a creator; you assume the role of a guardian of security and a proponent of distributed authority.

Generating the Entity Secret

const crypto = require('crypto')
const secret = crypto.randomBytes(32).toString('hex')

Generate your own Entity Secret

Step 3: Transforming Your Entity Secret into Ciphertext and Initiating Registration

With your Entity Secret now created, we're ready to advance to a critical juncture. You're about to convert the Entity Secret into Ciphertext and register it with the system. This process sets the stage for you to create your first wallet—a milestone to look forward to.

Retrieving Your Entity's Public Key

Begin by acquiring your entity's public key. This key is retrievable via our APIs and is instrumental in the upcoming steps. To obtain it, use your API key for authentication. The entity's public key plays a crucial role as it encrypts your Entity Secret. Once encrypted, the Entity Secret remains secure, ensuring the information is shared exclusively between you and the platform, keeping it out of reach from outsiders.

Fetching your public key

Encrypting the Entity Secret and Encoding in Base64 Format

After obtaining the public key, the next step involves using RSA encryption to secure your Entity Secret. Follow these steps:

  • 1

    Encrypt the Entity Secret

    Employ RSA encryption with the public key to encrypt your Entity Secret. This cryptographic process ensures that the secret is encoded in such a way that only someone with the private key can decrypt it.

  • 2

    Encode as Base64

    After encryption, convert the encrypted data into Base64 format. Encoding in Base64 ensures the encrypted data can be safely conveyed and interpreted in various contexts, including those that may not handle binary data well.

  • 3

    Verify the Ciphertext Length

    Ensure that the generated Ciphertext is 684 characters in length. This specific length confirms the encryption process has been executed properly and that the data will be maintained correctly upon receipt.

The code provided will assist in automating this encryption process, generating a unique Entity Secret Ciphertext every time it is executed. The resulting Ciphertext is what you'll use to interact securely with the platform's API when performing operations that require it.

Encrypt your Entity Secret

const forge = require('node-forge')

const entitySecret = forge.util.hexToBytes('YOUR_ENTITY_SECRET');

const publicKey = forge.pki.publicKeyFromPem('YOUR_PUBLIC_KEY');

const encryptedData = publicKey.encrypt(entitySecret, 'RSA-OAEP', { md:, mgf1: { md:, }, });

Generate Entity Secet Ciphertext

Registering Your Entity Secret Ciphertext

Once you've taken the necessary steps to safeguard your Entity Secret by converting it to Ciphertext, you'll need to register it within our Web3 Services Console. This action is vital as it authenticates the Ciphertext, effectively setting up a secure foundation for all subsequent interactions using our Developer-Controlled Wallets. The registration links your encrypted key with your developer account, ensuring that you can confidently manage wallet creation and transactions with the assurance of robust security measures in place.

Register your Entity Secret Ciphertext

As you proceed with the registration of your Entity Secret Ciphertext, pay close attention to the recovery file that will be generated. This file is a critical safety measure for your operations. In the event that your Entity Secret is ever lost, the recovery file will act as your fallback, enabling you to regain access to your Developer-Controlled Wallets. Ensure that you store this file securely and in a location that you can access readily if needed.

Guarding your secrets & building trust

By meticulously completing the registration and protection of your Entity Secret, you've not only guaranteed the security of your key but also laid down a bedrock of trust for all activities involving our developer-controlled wallets. We prioritize the safety of your data and are committed to providing a seamless and secure user experience.

Step 4: Crafting Your First API Call - Introducing Wallet Sets

Welcome to a foundational step in utilizing our Web3 Services: initiating your first API call to construct a WalletSet. We'll guide you through the process and clarify what a WalletSet entails within our platform.

Defining a WalletSet

A WalletSet within our ecosystem is a sophisticated grouping of wallets, securely tied together by a singular cryptographic key. Leveraging the Hierarchical Deterministic (HD) wallet technology, WalletSets offer an enhanced way to handle wallet management that spans multiple blockchain networks. This is particularly relevant for Ethereum Virtual Machine (EVM) compatible blockchains, where it is common for wallets on different networks to share the same address, thanks to the underlying technology.

Grasping the concept of idempotency

As we approach the creation of your inaugural WalletSet, it's important to comprehend a critical aspect of our APIs: idempotency keys.

Idempotency is a fundamental concept which guarantees that an operation is repeatable without changing the outcome. This concept is extremely important in API requests to make sure that if a request is accidentally sent more than once, it doesn't result in duplicate operations.

Consider situations like an unstable internet connection leading to multiple unintentional request submissions, or a user who accidentally activates a command several times. Without idempotency, such events might cause numerous unwanted operations.

To prevent this, an idempotency key is used. Each request includes a distinct key that, when recognized by the server within a certain timeframe as a repeat submission, prevents the repeated processing of that request. This mechanism is crucial to preserving the integrity of your operations, ensuring that only intended actions are carried out.

Crafting Your WalletSet

Now that we've got the concept of idempotency covered, let's look at creating your WalletSet.


Think of this as a safety net. By using a unique UUID for every transaction request, you ensure no transaction is mistakenly processed more than once. It's a measure against unintended duplicates.


Remember the encryption we discussed earlier? You'll need to provide this encrypted string for security and authorization.

nameThe name for your new WalletSet.

Let's create our first wallet set!

Create a WalletSet

Utilizing API Logs for Enhanced Monitoring

For a comprehensive overview of each transaction you execute with Circle's Web3 APIs, the Web3 Services Console provides detailed access to API logs. By examining these logs, you gain valuable visibility into how your application interacts with Circle APIs, which can be pivotal for various aspects including troubleshooting, performance optimization, and security oversight by highlighting any abnormal activities. For detailed records of your API interactions, please refer to the API Logs section.

Within the scope of our Quickstart guide, the API log is indispensable for gaining insights into specific API calls and the objects that are created as a result. Think of the API log as a detailed record that allows you to retrieve the unique IDs of objects that have been generated, especially when these IDs are needed for subsequent API interactions. API logs are a crucial educational resource that simplify the debugging process and help you methodically comprehend the intricacies of the API's operations. Hence, the API log is not only instrumental in improving operational workflows but also serves as a valuable asset for your development projects.

Step 5: Creating Your Developer-Controlled Wallets

Ah, the most exhilarating phase: shaping your very first developer-controlled wallet in the vastness of web3. With your prepped API key and Entity Secret Ciphertext, we're only a few steps away from crafting a masterpiece. Let's dive right in!

Understanding the Developer-Controlled Wallet

In web3, a wallet isn't just a storage mechanism for digital tokens or NFTs, but the very essence of user interactions on the blockchain. Essentially, it's a blend of a unique address and accompanying metadata stored on the blockchain.

For developer-controlled wallets:


A unique identifier on a blockchain. Notably, while an address remains distinct, multiple wallets can have the same address across different EVM blockchains.

Custody Type

This signifies who controls the private key invocation — either the user or the developer. For our purpose, we're focusing on developer-controlled wallets, which are inherently more manageable and tailored for specific app requirements.

With that foundational knowledge, let's get to the hands-on part.

Crafting your wallet

To create a wallet you use the following parameters:


Ensures that a request is executed only once, even if it's received multiple times.


The encrypted form of your Entity Secret, ensuring robust security for your API requests.


The ID of the wallet set that you created in the preceding step.


Specifies the blockchains on which the wallet should be manifested.


The number of wallets you aim to create. Note: The parameter should not exceed 20.

Create your first wallets

And there you have it! By the end of this step, you'll have fully functional developer-controlled wallets, ready to shape web3 experiences.

Step 6: Initiate your first transaction

Now that you have a wallet that contains some Testnet tokens, let's dive into initiating your first transaction. It's simpler than you might think, especially with our streamlined approach.

Getting the tokenId

Before we can proceed, we need to determine the tokenId. You can do this by retrieving the token balances for your wallet.

Get your wallet balance

Key Transaction Parameters:


A unique string that ensures your transaction isn 't processed more than once even if sent multiple times. A critical measure to prevent duplicates.


Specify the amount of tokens you're transferring.


The wallet address where you're sending the tokens.


A crucial security layer, this encrypted string ensures only authorized transactions go through.


This is the id we just extract from your wallet balance. It is the unique identifier for the specific token type you're moving. This id is unique.


Indicates the source of the transaction, i.e., from which wallet you're sending the tokens.

The preceding parameters are just the essentials for initiating a transaction. The endpoint offers a richer, more detailed configuration to cater to a variety of transaction types. For a comprehensive list of the supported parameters, see the official documentation.

Initiate your transaction

Once you've validated your transaction and everything checks out, you're all set. Transactions on the blockchain are immutable, meaning once they're validated, they cannot be reversed or altered. So, always double-check before sending!

Step 7: Validating your transaction

After initiating a transaction through our API, you can look up the transaction hash on the Dev Controlled Wallets Transactions page for in the Web3 Services Console. The transaction hash is a unique identifier for your transaction.

You can validate transactions in multiple ways:

  • Web3 Services Console
  • Blockchain Explorer

This is the preferred method. It enables you to inspect the transaction state directly.

  • 1

    Log in to the Console

    Make sure you're logged in to our Web3 Services Console.

  • 2

    Open the transactions page

    Open the Dev Controlled Wallets Transactions page.

    You can see the state of your transaction directly in the table.

    List of transactions
  • 3

    Open Transaction Details

    For more details about your transaction, click on the relevant line in the transaction details.

Step 8: Congratulations on Your Progress!

First and foremost, thank you for embarking on this journey with us.

Throughout this process, you successfully:

Established your Entity Secret

You took the initiative to generate and secure your unique Entity Secret, ensuring that your interactions remain encrypted and safe.

Created your first Developer Controlled Wallet

By setting up your wallet, you now possess a powerful tool that allows you to engage with web3 networks with full autonomy.

Got Testnet tokens via faucets

You've effectively tapped into the Faucets, filling your wallets with Testnet tokens, a crucial step for practical, risk-free experimentation on Testnet.

Initiated a blockchain transaction & validated it

Not only did you initiate a blockchain transaction, but you also took the proactive step of validating it using blockchain explorers, assuring transparency and trust in every move.

Stay connected & Explore more

Your journey with us doesn't stop here. There's so much more to discover und dive into:

Dive into our documentation

Your comprehensive resource for understanding our web3 tools, technologies, and best practices.

Join our Discord server

Engage, ask, share, and collaborate. Become an integral part of our vibrant developer community.

Sample Apps

Get hands-on with real-world use cases, or gain inspiration for your next big project.

Explore our Expanding Web3 Ecosystem

As our ecosystem flourishes, we're continuously rolling out new tools and platforms. Don't miss out on exploring these complementary products that could significantly enhance your web3 projects.

Engage, Build, Share! Dive into our forums, share your feedback, and keep an eye out for exciting challenges and hackathons. Your unique perspective and skills are valuable, and we're eager to see the innovations you'll introduce to our growing ecosystem.

Your feedback matters

Before you embark further on your journey, we'd love to hear from you. Your feedback shapes the future of our platform and helps us provide a better experience for all developers.

What did you love about the process? Was there something you wish was different? Every insight, no matter how small, matters to us.

Thank you for your trust, dedication, and enthusiasm. Here's to the next chapter in your web3 journey and the marvelous innovations you'll bring forth.

Happy Building! 🚀

© 2023-2024 Circle Technology Services, LLC. All rights reserved.