Building an Emerging Market Digital Dollar Account

Building a Digital Dollar Account Powered by Circle

Now let’s walk through the technical steps to implement this solution:

1. Create a Circle Developer Account
2. Create Programmable Wallets (in this case we’ll create a dev-controlled wallet)
3. Deposit USDC into the wallet (you can find the official smart contract for USDC here)

Create a Circle Developer Account

As mentioned previously, our digital dollar account will be represented by Circle’s Programmable Wallets*. Programmable Wallets are part of a host of services offered by Circle under its Web3 Services Console offering. So first we’ll need to create an account using the Circle app.

Select Wallet Infrastructure Model

Next, we need a user wallet. Circle offers two types of Programmable Wallets: user-controlled and dev-controlled. “Control” refers to the party that possesses the private key and thus controls the wallet:

1. User-Controlled Wallets: Wallets controlled by the end user. Transactions such as sending USDC can only be conducted with authorization from the user.
2. Dev-Controlled Wallets: Wallets fully controlled by the developer on behalf of the end user. This creates a fully streamlined experience for the user.

The wallet model you choose depends on whether you want the responsibility of managing and securing the wallet to reside with the user or with the developer. Both wallet models abstract away the blockchain, but dev-controlled wallets give you (the developer) control over managing and securing the wallet. User-controlled wallets leave the control (and responsibility) with the user.

For this tutorial, we’ll use dev-controlled wallets. For a thorough walkthrough of creating and configuring dev-controlled wallets, please read our detailed guide.

Generate Wallets for End-Users

Step 1: Create a Wallet Set

First, we’ll create a wallet set, i.e. a set of wallets controlled by the same cryptographic key. Traditionally, transactions through wallets have been paid for in gas fees, which tend to be unique to a particular blockchain. For instance, if you wanted to make a transfer of USDC on Ethereum, you would need ETH to pay for gas in addition to the USDC amount that you want to transfer.

However, thanks to developments by the Ethereum Foundation and the Circle Gas Station, it’s now possible to abstract away the concept of gas completely. This is made possible by creating wallets powered by Smart Contract Accounts which allow developers to pay gas on behalf of users.

Before we can start, be sure you create and set up your project including creating the ciphertext and adding it to the Configurator page.

Now let’s create our wallet set. To do so, we can use the following API call:

curl --request POST \
     --url 'https://api.circle.com/v1/w3s/developer/walletSets' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer ' \
     --data '
{
  "idempotencyKey": "8f459a01-fa23-479d-8647-6fe05526c0df",
  "name": "Entity WalletSet A",
  "entitySecretCiphertext": ""
}
‘

The output will resemble the following:

{"data":{"walletSet":{"id":"018b62c4-a4b4-7bbb-babf-0303e1727fa4","custodyType":"DEVELOPER","name":"Entity WalletSet A","updateDate":"2023-10-24T17:38:56Z","createDate":"2023-10-24T17:38:56Z"}}

Step 2: Deploy a Smart Contract Account (SCA) Dev-Controlled Wallet

To call the API, we will need a new entity ciphertext. You can create this in the same way we created the ciphertext above.

With a new ciphertext in-hand, let’s create wallets in our wallet set.

curl --request POST \
     --url 'https://api.circle.com/v1/w3s/developer/wallets' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer ' \
     --data '
{
  "idempotencyKey": "0189bc61-7fe4-70f3-8a1b-0d14426397cb",
  "blockchains": [
    "MATIC-MUMBAI"
  ],
  "count": 2,
  "entitySecretCiphertext": "",
  "walletSetId": "018b62c4-a4b4-7bbb-babf-0303e1727fa4",
  “accountType”: “SCA”,
}
'

You can see your wallets on the Web3 services platform.

Congratulations! Each of these wallets can represent a unique digital dollar account.

Note that each wallet has a wallet address by which it is represented on the blockchain. Also, every wallet has a unique ID. While making calls to Circle APIs, we use these wallet IDs instead of the wallet addresses.

Step 3: Deposit USDC in the newly created wallet

Now we need to deposit USDC into our wallet. In production, you would use Circle Mint for fiat to USDC conversion. But since we’re working on a testnet, we can get free testnet USDC from the Circle Faucet.

Step 4: Get the USDC balance of the wallet

Now let’s query our wallet for its USDC balance. First, we will get the balances of all the tokens in our wallet.

curl --request GET \
     --url 'https://api.circle.com/v1/w3s/wallets//balances' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer '

This will give us a list of ALL balances available in the wallet.

{"data":{"tokenBalances":[{"token":{"id":"7adb2b7d-c9cd-5164-b2d4-b73b088274dc","blockchain":"MATIC-MUMBAI","tokenAddress":"0x9999f7fea5938fd3b1e26a12c3f2fb024e194f97","standard":"ERC20","name":"USD Coin","symbol":"USDC","decimals":6,"isNative":false,"updateDate":"2023-10-18T14:29:44Z","createDate":"2023-10-18T14:29:44Z"},"amount":"10","updateDate":"2024-03-16T14:23:40Z"}]}}

For our use case, we’ll configure our wallets to only show the USDC balance. Let’s extract the token ID associated with the USDC balance and add it to our list of monitored tokens.

curl --request POST \
     --url https://api.circle.com/v1/w3s/config/entity/monitoredTokens \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ' \
     --header 'content-type: application/json' \
     --data '
{
  "tokenIds": [
    "7adb2b7d-c9cd-5164-b2d4-b73b088274dc"
  ]
}
'

Now let’s query our wallet.

curl --request GET \
     --url 'https://api.circle.com/v1/w3s/wallets//balances' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer '

The response will show the current USDC balance:

{"data":{"tokenBalances":[{"token":{"id":"7adb2b7d-c9cd-5164-b2d4-b73b088274dc","blockchain":"MATIC-MUMBAI","tokenAddress":"0x9999f7fea5938fd3b1e26a12c3f2fb024e194f97","standard":"ERC20","name":"USD Coin","symbol":"USDC","decimals":6,"isNative":false,"updateDate":"2023-10-18T14:29:44Z","createDate":"2023-10-18T14:29:44Z"},"amount":"10","updateDate":"2024-03-16T14:23:40Z"}]}}

Step 5: Perform USDC transfer with gas abstraction

Finally, let’s transfer the USDC.

SCA wallets have gas abstraction enabled. This means that wallets can execute transfers without holding the native gas token, as gas fees are covered by our paymaster smart contract using its reserves. We currently facilitate gasless transactions on Ethereum and Polygon, with future chains planned.

Our next step is to generate a new entity ciphertext by running generate_entity_secret_ciphertext.js and issue a new API request for the transfer.

curl --request POST \
     --url 'https://api.circle.com/v1/w3s/developer/transactions/transfer' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer ' \
     --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "walletId": "",
  "tokenId": "7adb2b7d-c9cd-5164-b2d4-b73b088274dc",
  "destinationAddress": "",
  "amounts": [
    "1"
  ],
  "feeLevel": "MEDIUM",
  "entitySecretCiphertext": ""
}
'

This will output:

{"data":{"id":"9210a3b9-e346-5b06-90d5-0190cbc82a4e","state":"COMPLETE"}} 

If you’re running your own custom neobank app, these API calls can be used to create and maintain digital dollar accounts for your users. Read through the documentation to see all the actions you can take.

Select an On/Off-Ramp

Finally, it’s worth noting that to use USDC (and other cryptocurrencies), you need an on-ramp such as Circle Mint that converts fiat money into digital tokens on the blockchain (and vice versa with an off-ramp). Having a network of financial services that provide on/off-ramps is crucial to the long-term success of USDC-powered applications, so that users can seamlessly exchange USD for USDC.

Conclusion

USDC and Programmable Wallets* empower businesses to deliver payment connectivity and dollar-backed financial services to more people across the globe. We are thrilled to support builders who are channeling their efforts to bring commerce on-chain - unlocking value exchange free from the constraints of legacy rails. We're eager to see your creations with USDC. Don't forget to mention @BuildOnCircle on X when you share your work. Let's continue shaping the future of finance!