user-controlled-wallets-social

Create a user-controlled wallet with Google social login

Use @circle-fin/user-controlled-wallets on the server and @circle-fin/w3s-pw-web-sdk in the browser to authenticate with Google, initialize a user-controlled wallet, and list it.

What a challenge is

In user-controlled wallets, privileged actions (initialize wallets, sign transactions, and similar) do not complete on the server alone. Circle returns a challenge: an authorization request the end user must complete in the browser.

Flow for this sample:

1. Google login (login rail): server issues a device token; the Web SDK runs OAuth and returns a userToken and encryptionKey.
2. Server calls initialize with that userToken. On first login, Circle returns a challengeId to create the wallet.
3. Browser calls sdk.setAuthentication({ userToken, encryptionKey }), then sdk.execute(challengeId, …). When execute succeeds, the wallet exists; this sample then lists it.

A challenge is not an on-chain transaction by itself. It is Circle’s way of requiring end-user approval before a sensitive wallet operation finishes.

Google login is not the challenge. Login only produces session credentials. The challenge runs afterward on first initialize. If the user is already initialized (155106), this sample lists wallets and does not run execute.

What this sample does

Step	What happens	Challenge?
Device token	createDeviceTokenForSocialLogin → persist + configure SDK	No
Login with Google	sdk.performLogin(GOOGLE) → userToken / encryptionKey	No
Initialize (first time)	POST /user/initialize → challengeId → execute	Yes — create wallet
Initialize (again)	155106 already initialized → list wallets	No

This sample creates an SCA wallet on Arc Testnet.

Prerequisites

• Node.js 22+
• A Circle Console app with:
  • API key → CIRCLE_API_KEY
  • App ID → VITE_CIRCLE_APP_ID
• A Google OAuth client ID → VITE_GOOGLE_CLIENT_ID (authorized JavaScript origin / redirect URI = your Vite origin, e.g. http://localhost:5173)

Setup

cp .env.example .env
# fill CIRCLE_API_KEY, VITE_CIRCLE_APP_ID, and VITE_GOOGLE_CLIENT_ID
npm install

Run

Two processes:

npm run server

npm run dev

Open the Vite URL and click Login with Google. On first login, complete the challenge UI when it appears.

Project layout

File	Role
server.ts	API key; device token; initialize (REST); list wallets
src/main.ts	Web SDK: Google login, execute challenge, list wallets
index.html	Minimal UI for the social path