- Lets users authenticate to your app using their Google account.
- Creates a user-owned wallet and connects it to your app.
- Displays the wallet address and the USDC balance it holds.
Prerequisites
Before you begin, ensure you have:- A Circle Developer Console account.
- A Circle Developer API key:
Console → Keys → Create a key → API key → Standard Key. - A Google account to access the Google Cloud Console.
- Node.js 18+ installed.
Step 1. Configure the Google Console
In this step, you will set up Google OAuth so users can sign in to your app using their Google account.- Log in to the Google Cloud Console
- Click Select a project → New Project, enter a name (for example, “Social Login Test”), and click Create.
- Search for Auth in the Google Cloud Search Bar.
-
Select Google Auth Platform, click Get started, and enter:
App name: for example, “Social Login App”User support email: select your emailAudience: select ExternalContact email addresses: type your email again
-
Select Create OAuth client, and enter:
Application type: select Web applicationClient name: for example, “Web client 1”Authorized redirect URIs: typehttp://localhost:3000
Click Create to complete the Google OAuth setup.Users will be redirected to this URL after they log in with their Google account. - Copy the Google OAuth Client ID, which identifies your app with Google’s OAuth service. You need it for the next two steps.
Important: The above Google OAuth setup only allows your account to login
with Google. If you want other users to authenticate: Select Audience from
your Google Auth Platform menu, and click Publish app, or add more
test users individually.
Step 2. Configure the Circle Console
In this step, you connect your Google OAuth client to your Circle Wallets configuration so users can sign in through your app. You also obtain your App ID, which identifies your user-controlled wallets configuration in the Circle Console.- Log in to the Circle Developer Console.
- Navigate to Wallets → User Controlled → Configurator.
- Click on Authentication Methods → Social Logins, select Google.
Paste your Google OAuth Client ID (from Step 1) into the Client ID (Web) field. - Go to the Configurator page and copy your App ID. You need it for the next step.
Step 3. Create the web application
In this step, you will create a web app that lets users authenticate using Google OAuth, and create a blockchain wallet.3.1. Create the Next.js project
In your terminal:3.2. Install dependencies
Install the user-controlled wallets Web SDK and supporting packages:3.3. Add environment variables
Create a.env.local file in the project directory:
.env.local file and add the following:
.env.local
YOUR_CIRCLE_API_KEYis your Circle Developer API key.YOUR_GOOGLE_WEB_CLIENT_IDis the Google OAuth Client ID created in Step 1.YOUR_CIRCLE_APP_IDis the Circle Wallet App ID obtained in Step 2.
3.4. Simplify the default layout
Replace the contents ofapp/layout.tsx with the minimal layout below:
app/layout.tsx
Next.js requires an
app/layout.tsx file, but the default one created by
create-next-app includes fonts and styling that can cause build errors in
some environments.3.5. Add unified backend route
Create a file namedapp/api/endpoints/route.ts and add the code below:
app/api/endpoints/route.ts
| Handler | Description |
|---|---|
createDeviceToken | calls POST /v1/w3s/users/social/token to create a device-bound session used by the Web SDK for social login authentication. |
initializeUser | calls POST /v1/w3s/user/initialize to create or initialize a user and return a challengeId required for wallet creation. |
listWallets | calls GET /v1/w3s/wallets to retrieve the wallets associated with the authenticated user. |
getTokenBalance | calls GET /v1/w3s/wallets//balances to retrieve digital asset balances for the specified user-controlled wallet. |
This quickstart calls
listWallets and getTokenBalance directly for
simplicity. In production, apps typically store wallet and balance data in a
backend database and keep it in sync using Circle webhooks for scalability.3.6. Add UI and frontend code
Replace the contents ofapp/page.tsx with the code below:
app/page.tsx
Step 4. Run the app flow
- Start the dev server:
- Open http://localhost:3000 in your browser to view the app.
-
Complete the Google authentication and wallet creation flow:
- Click Create device token: The Web SDK generates a unique
deviceId, which identifies the user’s browser. Your backend exchanges thedeviceIdfor temporary verification tokens (deviceToken,deviceEncryptionKey) used by the Web SDK to allow Google authentication. - Click Login with Google: The Web SDK starts the Google OAuth
authentication process. After the user signs in with Google, the SDK sends
the OAuth result to Circle. Circle validates the login and returns a
userTokenandencryptionKey, which together represent an authenticated Circle user session. - Click Initialize user: Your backend initializes the user using the
userToken. If the user hasn’t created a wallet yet, Circle returns achallengeIdto create one. If the user is already initialized, the app loads the existing wallet instead. - Click Create wallet: The Web SDK executes the challenge using the
challengeId. The user approves the action, and Circle creates the wallet.
- Click Create device token: The Web SDK generates a unique
-
Once the flow completes:
- The app displays the wallet address, blockchain, and USDC balance.
- You can verify the user was created in the
Circle Dev Console:
Wallets → User Controlled → Users.
Step 5. Fund the wallet
In this step, you fund the new wallet manually using the Circle Faucet and confirm the updated balance in the app.- Copy the wallet address (
0x...) from the web app UI. - Visit the official Circle Faucet.
- Select Arc Testnet as the blockchain network.
- Paste the wallet address in the Send to field.
- Click Send USDC.
- Return to the app and walk through the flow again.
Note: Use the same Google account to show the same wallet. - The app will display the updated USDC balance.
In this step, you’re acting as the end user to fund your user-controlled
wallet for testing. In production, app developers don’t control user wallets
or private keys. Instead, users typically fund wallets themselves, but apps
may also fund using faucets or airdrops without requiring wallet access.