### Install Modular Wallets Web SDK Core Package (npm)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

This command installs the core package for the Modular Wallets Web SDK using npm, the package manager for JavaScript. It's the first step to integrate the SDK into your web application, enabling access to smart account functionalities.

```npm
npm install @circle-fin/modular-wallets-core
```

--------------------------------

### Example Webhook Request Headers

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web3-services-notifications-quickstart

Illustrates the essential `X-Circle-Key-Id` and `X-Circle-Signature` headers that are included in Circle webhook notifications, which are crucial for subsequent signature verification steps.

```Text
# Headers
`X-Circle-Key-Id: “879dc113-5ca4-4ff7-a6b7-54652083fcf8”`
`X-Circle-Signature: “MEYCIQCA9EvPbdEJiy7Cw0eY+KQZA/oFi5ZEInPs8CYpyaJexgIhAKtRNnDz9QRQmFKx8QFrvawp+8b9Bs2dQ03xD+XaWVDE”`
```

--------------------------------

### Example Hello World Webhook Test Notification

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web3-services-notifications-quickstart

This JSON payload represents a 'Hello World' test notification received after successfully subscribing an endpoint to Circle's webhook service. It confirms the subscription is active and provides basic notification details like subscription ID, notification ID, type, and timestamp, indicating a successful initial setup.

```JSON
{
  "subscriptionId": "00000000-0000-0000-0000-000000000000",
  "notificationId": "00000000-0000-0000-0000-000000000000",
  "notificationType": "webhooks.test",
  "notification": {
    "hello": "world"
  },
  "timestamp": "2023-07-20T16:18:40.816010685Z",
  "version": 2
}
```

--------------------------------

### Install Dynamic SDK Dependencies (npm)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-integ-dynamic

This snippet provides the `npm` command to install the necessary Dynamic SDK packages: `@dynamic-labs/ethereum` and `@dynamic-labs/sdk-react-core`. These packages are essential for integrating Dynamic's authentication and wallet functionalities into a project.

```Shell
npm install @dynamic-labs/ethereum @dynamic-labs/sdk-react-core
```

--------------------------------

### Example Webhook Notification Payload

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web3-services-notifications-quickstart

Provides an example of a typical JSON payload structure for a Circle webhook notification. This payload, along with the `X-Circle-Signature`, is used to verify the integrity of the received message.

```JSON
{
  "subscriptionId": "890a8cae-46bd-40ad-bd7f-2e49b8dea9da",
  "notificationId": "0bdd3e4b-5070-4530-8ed4-2e2e4c9fd2f0",
  "notificationType": "webhooks.test",
  "notification": {
    "hello": "world"
  },
  "timestamp": "2023-07-12T04: 02: 28.555562821Z",
  "version": 2
}
```

--------------------------------

### Example Response Body for User Token and Encryption Key

Source: https://developers.circle.com/w3s/developer-controlled-wallets/user-controlled-create-your-first-wallet

Illustrates the structure of the initial API response containing a user token and an encryption key, typically received after a successful authentication or setup step.

```JSON
{
  "data": {
    "userToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCC9.eyJkZXZlbG9wZXJFbnRpdHlFbnZpcm9ubWVudCI6IlRFU1QiLCJlbnRpdHlJZCI6IjRlMDdhOGM5LTIxOTAtNDVlNC1hNjc0LWQyMGFkNjg4MWI3YyIsImV4cCI6MTY5MDU1MjcwNywiaWF0IjoxNjkwNTQ5MTA3LCJpbnRlcm5hbFVzZXJJZCI6ImQ2ZjkzODliLWQ5MzUtNWFlYy1iOTVhLWNjNTk1NjA2YWM5NiIsImlzcyI6Imh0dHBzOi8vcHJvZ3JhbW1hYmxlLXdhbGxldC5jaXJjbGUuY29tIiwianRpIjoiMmE0YmJlMzAtZTdkZi00YmM2LThiODMtNTk0NGUyMzE2ODlkIiwic3ViIjoiZXh0X3VzZXJfaWRfOSJ9.dhfByhxZFbJx0XWlzxneadT4RQWdnxLu3FSN9ln65hCDOfavaTL1sc4h-jUR8i4zMmfdURw3FFcQIdSbm-BUg6M7FP_fp-cs9xBbNmRZa31gMd1aKdcajJ9SvlVrfUowYfGXM3VcNF8rtTFtW-gk1-KzU4u10U35XXbbMcW1moxE0Rqx_fKotDgk2VdITuuds5d5TiQzAXECqeCOCtNoDKktMkglltbnLxOaRl2ReZjGt-ctD2V0DbYNO4T_ndPSUDI6qD7dXQRed5uDcezJYoha3Qj3tFGBglEnox2Y6DWTbllqjwmfTGrU8Pr0yz4jQz7suGwmiCzHPxcpYxMzYQ",
    "encryptionKey": "Tlcyxz7Ts9ztRLQq5+pic0MIETblYimOo2d7idV/UFM="
  }
}
```

--------------------------------

### Send Gasless Transaction via Bundler (WebSDK)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

Demonstrates how to construct and send a gasless transaction (user operation) using the bundler client. It includes encoding a token transfer and waiting for the transaction receipt. This example transfers USDC on Polygon Amoy testnet.

```JavaScript
import { encodeTransfer } from '@circle-fin/modular-wallets-core'

// 6. Send a user operation to the bundler.
//    Here we send 1 USDC to a random address
const USDC_CONTRACT_ADDRESS = '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582' //Polygon Amoy testnet
const USDC_DECIMALS = 6
const userOpHash = await bundlerClient.sendUserOperation({
  calls: [encodeTransfer(to, USDC_CONTRACT_ADDRESS, 100000n)],
  paymaster: true,
})

// 7. wait for transaction receipt
const { receipt } = await bundlerClient.waitForUserOperationReceipt({
  hash: userOpHash,
})
```

--------------------------------

### Initialize Wallet SDK and Configure Core Features (Java)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

This snippet demonstrates the initial setup of the Wallet SDK, including its initialization with an endpoint and app ID, setting custom view and layout providers, registering an event listener for specific events like 'forgotPin', and configuring security questions.

```Java
// Set endpoint and app ID
try {
    WalletSdk.init(getApplicationContext(), new WalletSdk.Configuration(endpoint, appId));
} catch (Throwable e){
    e.printStackTrace();
    return;
}

// setViewSetterProvider
WalletSdk.setViewSetterProvider(new MyViewSetterProvider());
// setLayoutProvider
WalletSdk.setLayoutProvider(new MyLayoutProvider(getApplicationContext()));
// Regester EventListener
WalletSdk.addEventListener(new EventListener() {
    @Override
       public void onEvent(ExecuteEvent event) {
           switch (event){
                  case forgotPin:
                    startActivity(forgotPinIntent);
                  break;
           }
       }
});

// setSecurityQuestion
SecurityQuestion[] questions = new SecurityQuestion[]{
                    new SecurityQuestion("What is your father's middle name?"),
                    new SecurityQuestion("What is your favorite sports team?"),
                    new SecurityQuestion("What is your mother's maiden name?"),
                    new SecurityQuestion("What is the name of your first pet?"),
                    new SecurityQuestion("What is the name of the city you were born in?"),
                    new SecurityQuestion("What is the name of the first street you lived on?"),
                    new SecurityQuestion("When is your father's birthday?", SecurityQuestion.InputType.datePicker)};
WalletSdk.setSecurityQuestions(questions);
```

--------------------------------

### Create Wallet Set API Response Example

Source: https://developers.circle.com/w3s/developer-controlled-wallets/developer-controlled-create-your-first-wallet

Example JSON response body after successfully creating a wallet set, including its unique ID, custody type, and creation/update timestamps.

```JSON
{
  "data": {
    "walletSet": {
      "id": "0189bc61-7fe4-70f3-8a1b-0d14426397cb",
      "custodyType": "DEVELOPER",
      "updateDate": "2023-08-03T17:10:51Z",
      "createDate": "2023-08-03T17:10:51Z"
    }
  }
}
```

--------------------------------

### Customize Android Style Resources

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

Example of customizing UI styles in Android's `styles.xml` file. Styles define a collection of attributes that specify the look and format for a View or window, promoting consistency and reducing repetitive attribute declarations.

```XML
<resources>
    <style name="circlepw_heading3">
        <item name="android:fontFamily">@font/avenir_heavy</item>
        <item name="android:fontWeight" tools:targetApi="o">600</item>
        <item name="android:textSize">24sp</item>
    </style>
    <style name="circlepw_heading4">
        <item name="android:fontFamily">@font/avenir_heavy</item>
        <item name="android:fontWeight" tools:targetApi="o">600</item>
        <item name="android:textSize">20sp</item>
    </style>
</resources>
```

--------------------------------

### API Reference: GET /user

Source: https://developers.circle.com/w3s/developer-controlled-wallets/user-controlled-create-your-first-wallet

Documentation for the GET /user API endpoint, which retrieves the status of a user's account. This includes details on PIN and security question status, along with failed attempt counts.

```APIDOC
GET /user
Description: Retrieve the status of a user's account.
Endpoint: /api-reference/w3s/user-controlled-wallets/get-user-by-token
Parameters:
  - userToken (string, required): The token identifying the user whose status is to be retrieved.
Response Body Fields:
  - id (string): Unique identifier for the user.
  - status (string): Overall status of the user (e.g., ENABLED).
  - createDate (string): Timestamp of user creation (ISO 8601 format).
  - pinStatus (string): Indicates if the user's PIN is enabled (e.g., ENABLED).
  - pinDetails (object):
    - failedAttempts (integer): Number of failed PIN attempts.
  - securityQuestionStatus (string): Indicates if security questions are enabled (e.g., ENABLED).
  - securityQuestionDetails (object):
    - failedAttempts (integer): Number of failed security question attempts.
```

--------------------------------

### Install Circle Web SDK via npm

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web

This snippet provides the command to install the Circle Web SDK using npm, the package manager for JavaScript. It's the first step to integrate the SDK into a web application project.

```Shell
npm install @circle-fin/w3s-pw-web-sdk
```

--------------------------------

### Customizing Application Text, Icons, and Error Handling in Java

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

This Java code snippet demonstrates how to extend a base class (likely a `ResourceProvider` or similar) to customize various application-wide configurations. It includes examples of providing specific `IconTextConfig` and `TextConfig` objects based on resource keys, defining a custom heading color, handling API error codes, setting date formats, and checking the debug status of the build. Note: The initial part of the `getIconTextConfigs` method is fragmented in the source.

```Java
                            new IconTextConfig(
                                    new RemoteImageSetter(R.drawable.error, "https://path/icon3.svg"),
                                    new TextConfig("I will lose access to my wallet and my digital assets if I forget my answers. "))
                    };
}
   return super.getIconTextConfigs(key);
       }
@Override
        public TextConfig[] getTextConfigs(Resource.TextsKey key) {
            switch (key){
                case securityQuestionHeaders:
                    return new TextConfig[]{
                            new TextConfig("Choose your 1st question"),
                            new TextConfig("Choose your 2nd question")
                    };
                case securitySummaryQuestionHeaders:
                    return new TextConfig[]{
                            new TextConfig("1st Question"),
                            new TextConfig("2nd Question")
                    };
                case newPinCodeHeadline:
                case enterPinCodeHeadline:
                    return new TextConfig[]{
                            new TextConfig("Enter your "),
                            new TextConfig("PIN", getHeadingColor(), null),
                    };
                case securityIntroHeadline:
                    return new TextConfig[]{
                            new TextConfig("Set up your "),
                            new TextConfig("Recovery Method", getHeadingColor(), null),
                    };
            }
            return super.getTextConfigs(key);
        }

        private int getHeadingColor(){
              return Color.parseColor("#0073C3");
        }

        @Override
        public String getErrorString(ApiError.ErrorCode code) {
            switch (code){
                case userCanceled:
                    return context.getString(R.string.user_canceled);
            }
            return super.getErrorString(code);
        }

        @Override
        public String getDateFormat(){
            return Resource.DateFormat.MMDDYYYY_SLASH; // "​​MM/DD/YYYY"
        }

        @Override
        public boolean isDebugging(){
            return BuildConfig.DEBUG;
        }

    }
```

--------------------------------

### API Reference: GET /wallets

Source: https://developers.circle.com/w3s/developer-controlled-wallets/user-controlled-create-your-first-wallet

Documentation for the GET /wallets API endpoint, which retrieves a list of wallets associated with a specific user. This endpoint provides details for each wallet, such as ID, state, address, and blockchain.

```APIDOC
GET /wallets
Description: Retrieve a list of wallets associated with a user.
Endpoint: /api-reference/w3s/developer-controlled-wallets/get-wallets
Parameters:
  - userToken (string, required): The token identifying the user whose wallets are to be listed.
Response Body Fields:
  - data (object):
    - wallets (array of objects):
      - id (string): Unique identifier for the wallet.
      - state (string): Current state of the wallet (e.g., LIVE).
      - walletSetId (string): Identifier for the wallet set.
      - custodyType (string): Type of custody (e.g., ENDUSER).
      - userId (string): ID of the associated user.
      - address (string): Blockchain address of the wallet.
      - addressIndex (integer): Index of the address.
      - blockchain (string): Blockchain network (e.g., MATIC-AMOY).
      - accountType (string): Type of account (e.g., SCA).
      - updateDate (string): Timestamp of last update (ISO 8601 format).
      - createDate (string): Timestamp of creation (ISO 8601 format).
```

--------------------------------

### Example Wallets API Response Body

Source: https://developers.circle.com/w3s/developer-controlled-wallets/create-your-first-wallet-with-email

Illustrates the JSON structure of a successful response containing wallet details from a Circle API endpoint. This example shows a single wallet object with its unique identifier, state, associated user, blockchain, and creation/update timestamps.

```JSON
{
  "data": {
    "wallets": [
      {
        "id": "8a79c80b-4d4f-4032-971a-8bb9f9b0254f",
        "state": "LIVE",
        "walletSetId": "c43221d3-9db1-4cbf-8b18-e1dcae16b55d",
        "custodyType": "ENDUSER",
        "userId": "d8c8f832-5d4f-4123-9a7f-60120c2da5f0",
        "address": "8UFfxP3zzSeqdkZ5iLTmUGzpHPRGnydZ1Vnq5GkzKTep",
        "addressIndex": 0,
        "blockchain": "SOL-DEVNET",
        "accountType": "EOA",
        "updateDate": "2023-07-28T14:43:48Z",
        "createDate": "2023-07-28T14:43:48Z"
      }
    ]
  }
}
```

--------------------------------

### WalletSdk.Configuration Data Structure

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

SDK Configuration for WalletSdk initialization, allowing specification of endpoint, app ID, and optional settings management.

```APIDOC
data class Configuration
  Description: SDK Configuration for WalletSdk init.

  Constructors:
    constructor(endPoint: String?, appId: String?)
      Description: Init with Circle endpoint. SDK will connect to this endpoint.
    constructor(endpoint: String?, appId: String?, settingsManagement: SettingsManagement?)
      Description: Init with Circle endpoint. SDK will connect to this endpoint. The SettingsManagement can bring extra setting flags to use.
```

--------------------------------

### Create or Login with a Passkey (WebSDK)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

Demonstrates how to initialize a passkey transport and create a WebAuthn credential for user registration or login using the '@circle-fin/modular-wallets-core' library. It requires client key and client URL from environment variables.

```JavaScript
import {
    toPasskeyTransport,
    toWebAuthnCredential,
} from '@circle-fin/modular-wallets-core'

// 0. retrieve client key and client url from environment vars
const clientKey = import.meta.env.VITE_CLIENT_KEY as string
const clientUrl = import.meta.env.VITE_CLIENT_URL as string

// 1. register or login with a passkey and
//    Create a Passkey Transport from client key
const passkeyTransport = toPasskeyTransport(clientUrl, clientKey)
const credential = await toWebAuthnCredential({
    transport: passkeyTransport,
    mode: WebAuthnMode.Register, //or WebAuthnMode.Login if login
    username: 'your-username'  //replace with actual username
})
```

--------------------------------

### Define Web App Dependencies in package.json (JSON)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

This `package.json` file outlines the essential dependencies required for the sample web application. It includes core libraries like React, viem for blockchain interactions, and the `@circle-fin/modular-wallets-core` SDK, along with necessary development dependencies for building a modern React-based project.

```JSON
{
  "name": "quickstart-circle-smart-account",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "viem": "^2.21.27",
    "@circle-fin/modular-wallets-core": "^1.x.x"
  },
  "devDependencies": {
    "@types/react": "^18.0.27",
    "@types/react-dom": "^18.0.10",
    "@vitejs/plugin-react": "^4.3.2",
    "typescript": "^5.0.3",
    "vite": "^5.4.14"
  }
}
```

--------------------------------

### Example Response Body for Challenge ID

Source: https://developers.circle.com/w3s/developer-controlled-wallets/user-controlled-create-your-first-wallet

Shows the JSON structure of the API response containing a `challengeId`, which is used by the Circle Programmable Wallet SDK for PIN and security question setup.

```JSON
{
  "data": {
    "challengeId": "0d1b5f41-1381-50af-983b-f54691415158"
  }
}
```

--------------------------------

### Configure Environment Variables for Web SDK (.env)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

Create an `.env` file in your local directory to store sensitive credentials securely. This snippet shows how to define your `VITE_CLIENT_KEY` and `VITE_CLIENT_URL`, which are crucial for authenticating your web application with the Modular Wallets SDK.

```Text
VITE_CLIENT_KEY=YOUR-CLIENT-KEY
VITE_CLIENT_URL=YOUR-CLIENT-URL
```

--------------------------------

### Node.js SDK: Get Transaction Status

Source: https://developers.circle.com/w3s/developer-controlled-wallets/developer-controlled-transfer-tokens-across-wallets

Illustrates how to use the Circle Developer SDK in Node.js to query the status of a previously initiated transaction. This example retrieves the transaction details using its unique ID.

```Node.js
const response = await circleDeveloperSdk.getTransaction({
  id: '1af639ce-c8b2-54a6-af49-7aebc95aaac1'
})
```

--------------------------------

### Initialize Blockchain Client with Modular Transport (WebSDK)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

Shows how to create a modular transport for a specific blockchain network (e.g., Polygon Amoy) and then initialize a 'viem' public client using this transport. This client is used to interact with the blockchain.

```JavaScript
import { toModularTransport } from '@circle-fin/modular-wallets-core'
import { createPublicClient } from 'viem'
import { polygonAmoy } from 'viem/chains'

// 2. Create modular transport for given chain from client url and client key
const modularTransport = toModularTransport(
  clientUrl + '/polygonAmoy',
  clientKey,
)

// 3. Create client to connect to specified blockchain
const client = createPublicClient({
  chain: polygonAmoy,
  transport: modularTransport,
})
```

--------------------------------

### Retrieve User Transactions

Source: https://developers.circle.com/w3s/developer-controlled-wallets/user-controlled-send-outbound-transfer

This section provides details on how to retrieve a list of transactions associated with a user. It includes an API reference for polling the `GET /transactions` endpoint and a Node.js SDK example demonstrating its usage with a user token.

```APIDOC
GET /transactions
  Description: Retrieve a list of transactions for a user.
  Parameters:
    userToken: string (Required if userId is not provided) - The unique token associated with the user.
    userId: string (Required if userToken is not provided) - The unique identifier of the user.
  Returns: A list of transaction objects.
```

```Node.js
const response = await circleUserSdk.listTransactions({
  userToken: '<USER_TOKEN>',
})
```

--------------------------------

### W3S SDK Initialization and Challenge Handling in Vanilla JavaScript

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web

Comprehensive JavaScript example demonstrating the initialization of the W3S SDK, configuration of application and authentication settings, handling of social login callbacks, and execution of a challenge. It includes a `handleSubmit` function that retrieves a `challengeId` and calls `sdk.execute`, showing both console logging and toast notifications for success/error handling.

```javascript
// Assume W3SSdk is globally available
let sdk = new W3SSdk({
  configs: {
    appSettings: { appId: 'someAppId' },
    authentication: {
      userToken: 'someUserToken',
      encryptionKey: 'someEncryptionKey'
    },
    socialLoginConfig: {}
  },
  socialLoginCompleteCallback: (error, result) => {
    if (error) {
      console.error(`Social Login Error: ${error.message ?? 'Error!'}`)
      return
    }
    console.log(`Social Login Success: ${result?.userToken}`)
  }
})

// Initialize settings
const initSettings = () => {
  sdk.setAppSettings({
    appId: 'someAppId',
  })
  sdk.setAuthentication({
    userToken: 'someUserToken',
    encryptionKey: 'someEncryptionKey',
  })
}

// Handle form submission
const handleSubmit = () => {
  const challengeId = document.getElementById('challengeId').value

  sdk.execute(challengeId, (error, result) => {
    if (error) {
      console.error(`Error: ${error?.message ?? 'Error!'}`)
      return
    }
    console.log(`Challenge: ${result?.type}, Status: ${result?.status}`)
  })
}

// Initialization
initSettings()

// Listen for button click event
document.getElementById('submitBtn').addEventListener('click', handleSubmit)sdk.execute(challengeId, (error, result) => {
  if (error) {
    toast.error(`Error: ${error?.message ?? 'Error!'}`)
    return
  }
  toast.success(`Challenge: ${result?.type}, Status: ${result?.status}`)
})
```

--------------------------------

### Customize Android String Resources

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

Example of customizing string resources in Android's `strings.xml` file. This file is used for localizing and defining text elements that can be referenced throughout the application, promoting reusability and easy translation.

```XML
<resources>
    <string name="circlepw_continue">Continue</string>
    <string name="circlepw_next">Next</string>
    <string name="circlepw_question_label">Question:</string>
</resources>
```

--------------------------------

### API Reference: Retrieve Notification Public Key

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web3-services-notifications-quickstart

Documents the `GET /v2/notifications/publicKey/{keyId}` endpoint, which allows retrieval of the public key and algorithm necessary for verifying webhook signatures. This key is identified by the `X-Circle-Key-Id` header from incoming webhooks.

```APIDOC
Endpoint: GET /v2/notifications/publicKey/{keyId}
Description: Retrieves the public key and algorithm used to sign webhook notifications.
Path Parameters:
  keyId (string, UUID): The UUID of the public key to retrieve, typically from the X-Circle-Key-Id header.
Request Headers:
  accept: application/json
  authorization: Bearer <YOUR_API_KEY>
Response Body (application/json):
  {
    "data": {
      "id": "string (UUID)",
      "algorithm": "string (e.g., ECDSA_SHA_256)",
      "publicKey": "string (base64 encoded)",
      "createDate": "string (ISO 8601 datetime)"
    }
  }
```

--------------------------------

### API Flow for User Initialization and Web3 Wallet Creation

Source: https://developers.circle.com/w3s/developer-controlled-wallets/authentication-methods

Outlines the steps to initialize an onboarded user and create a Web3 wallet. It involves an API call to initialize the user, followed by a client-side SDK operation to create the wallet using the challenge ID.

```APIDOC
1. To initialize the user, you send a POST request to the /user/initialize endpoint with userToken included in the request body.
2. Circle returns challengeId in the response.
3. You create a Web3 wallet for your user by passing challengeId to the client-side SDK for execution.
```

--------------------------------

### Example Response Body: Wallet Creation Confirmation

Source: https://developers.circle.com/w3s/developer-controlled-wallets/onboard-users-to-developer-controlled-wallets

A sample JSON response body confirming the successful creation of new wallets. It provides details for each newly created wallet, including its unique ID, current state, associated wallet set, custody type, address, blockchain, and timestamps.

```JSON
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
        "blockchain": "MATIC-AMOY",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      },
      {
        "id": "cda61d8d-7d46-5a39-a8a6-6b4a3d6fdac3",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
        "blockchain": "MATIC-AMOY",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
```

--------------------------------

### Create Circle Smart Account and Bundler Client (WebSDK)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

Illustrates the creation of a Circle Smart Account linked to a WebAuthn credential and the initialization of a bundler client. The bundler client is essential for sending user operations on the specified blockchain.

```JavaScript
import { toCircleSmartAccount } from '@circle-fin/modular-wallets-core'
import {
  createBundlerClient,
  toWebAuthnAccount,
} from 'viem/account-abstraction'

// 4. create a circle smart account
const smartAccount = await toCircleSmartAccount({
  client,
  owner: toWebAuthnAccount({
    credential,
  }),
})

// 5. create a bundler client
const bundlerClient = createBundlerClient({
  smartAccount,
  chain: polygonAmoy,
  transport: modularTransport,
})
```

--------------------------------

### Example Response for Listing Wallets

Source: https://developers.circle.com/w3s/developer-controlled-wallets/developer-controlled-receive-an-inbound-transfer

This JSON object represents a typical successful response from the `GET /wallets` API call. It provides details for a single wallet, including its unique `id`, `state`, `address`, `blockchain`, and `custodyType`, which are essential for identifying and interacting with the wallet.

```JSON
{
  "data": {
    "wallets": [
      {
        "id": "ce714f5b-0d8e-4062-9454-61aa1154869b",
        "state": "LIVE",
        "walletSetId": "0189bc61-7fe4-70f3-8a1b-0d14426397cb",
        "custodyType": "DEVELOPER",
        "address": "0xf5c83e5fede8456929d0f90e8c541dcac3d63835",
        "blockchain": "MATIC-AMOY",
        "accountType": "SCA",
        "updateDate": "2023-08-03T19:33:14Z",
        "createDate": "2023-08-03T19:33:14Z"
      }
    ]
  }
}

```

--------------------------------

### React.js W3S SDK Integration Example

Source: https://developers.circle.com/w3s/developer-controlled-wallets/web

This React.js component demonstrates how to initialize the W3SSdk, configure app settings and authentication, and execute a challenge. It includes state management for configuration parameters and uses `react-toastify` for displaying success or error messages.

```JavaScript
import React, { useCallback, useEffect, useState } from 'react'
import { ToastContainer, toast } from 'react-toastify'
import TextField from '@mui/material/TextField'
import Button from '@mui/material/Button'
import { W3SSdk } from '@circle-fin/w3s-pw-web-sdk'

let sdk: W3SSdk

function App() {
  useEffect(() => {
    sdk = new W3SSdk({
      configs: {
        appSettings: { appId: 'someAppId' },
        authentication: {
          userToken: 'someUserToken',
          encryptionKey: 'someEncryptionKey'
        },
        socialLoginConfig: {}
      },
      socialLoginCompleteCallback: (error, result) => {
        if (error) {
          toast.error(`Social Login Error: ${error.message ?? 'Error!'}`)
          return
        }
        toast.success(`Social Login Success: ${result?.userToken}`)
      }
    })
  }, [])

  const [appId, setAppId] = useState(localStorage.getItem('appId') || 'someAppId')
  const [userToken, setUserToken] = useState(localStorage.getItem('userToken') || 'someUserToken')
  const [encryptionKey, setEncryptionKey] = useState(localStorage.getItem('encryptionKey') || 'someEncryptionKey')
  const [challengeId, setChallengeId] = useState(localStorage.getItem('challengeId') || 'someChallengeId')

  const onChangeHandler = useCallback(
    (setState, key) => (e) => {
      const value = e.target.value
      setState(value)
      localStorage.setItem(key, value)
    },
    []
  )

  const onSubmit = useCallback(() => {
    sdk.setAppSettings({ appId })
    sdk.setAuthentication({ userToken, encryptionKey })

    sdk.execute(challengeId, (error, result) => {
      if (error) {
        toast.error(`Error: ${error?.message ?? 'Error!'}`)
        return
      }
      toast.success(`Challenge: ${result?.type}, Status: ${result?.status}`)
    })
  }, [appId, userToken, encryptionKey, challengeId])

  return (
    <div className="p-4">
      <TextField
        label="App Id"
        onChange={onChangeHandler(setAppId, 'appId')}
        value={appId}
      />
      <TextField
        label="User Token"
        onChange={onChangeHandler(setUserToken, 'userToken')}
        value={userToken}
      />
      <TextField
        label="Encryption Key"
        onChange={onChangeHandler(setEncryptionKey, 'encryptionKey')}
        value={encryptionKey}
      />
      <TextField
        label="Challenge Id"
        onChange={onChangeHandler(setChallengeId, 'challengeId')}
```

--------------------------------

### Customize Android Color Resources

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

Example of customizing color resources in Android's `color.xml` file. This file allows defining custom color values that can be applied to various UI elements, ensuring consistent branding and theming across the application.

```XML
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="circlepw_text_main">#1A1A1A</color>
    <color name="circlepw_text_auxiliary">#3D3D3D</color>
    <color name="circlepw_text_action">#136FD8</color>
    <color name="circlepw_text_action_pressed">#B3136FD8</color>
</resources>
```

--------------------------------

### Example Response Body: List Wallets

Source: https://developers.circle.com/w3s/developer-controlled-wallets/onboard-users-to-developer-controlled-wallets

A sample JSON response body showing the structure of data returned when querying for a list of wallets. It includes details such as wallet ID, state, wallet set ID, custody type, address, blockchain, and creation/update dates.

```JSON
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "UUID1",
        "name": "User Wallet1",
        "address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
        "blockchain": "MATIC-AMOY",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      },
      {
        "id": "cda61d8d-7d46-5a39-a8a6-6b4a3d6fdac3",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "UUID2",
        "name": "User Wallet1",
        "address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
        "blockchain": "MATIC-AMOY",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
```

--------------------------------

### Generate Test Ethereum Wallet Address

Source: https://developers.circle.com/w3s/developer-controlled-wallets/tx-screening-quickstart

To simulate a real screening scenario, this example provides a test Ethereum wallet address ending in '9999'. This specific suffix is designed to trigger Circle's Sanctions Blocklist in the screening API for demonstration purposes.

```Text
0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999
```

--------------------------------

### Documenting Viem Public Client Actions

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-web-sdk

This section outlines the key actions supported by the Viem Public Client, including retrieving block and transaction information, checking balances, executing contract calls, sending transactions, and verifying messages.

```APIDOC
Public Client Actions:
  getBlock: Retrieves information about a block using its number, hash, or a specific tag.
  getTransaction: Fetches details of a transaction using its hash.
  getBalance: Returns the balance of the specified address.
  call: Executes a "call" to a contract function and retrieves the result without modifying the blockchain state.
  sendTransaction: Submits a signed transaction to the blockchain network for processing.
  verifyMessage: Confirms whether a given message was signed by the specified address.
```

--------------------------------

### Estimate Gas Fees for Recovery Address Registration in TypeScript

Source: https://developers.circle.com/w3s/developer-controlled-wallets/how-to-recover-passkey

This TypeScript example shows how to estimate the gas fees required for registering a recovery address. It uses `recoveryClient.estimateRegisterRecoveryAddressGas` to get an estimate, then calculates the total cost in ETH for display to the user, promoting transparency.

```TypeScript
const registerGasEstimate =
  await recoveryClient.estimateRegisterRecoveryAddressGas({
    account,
    recoveryAddress: recoveryEoa.address,
  })

const costInEth = formatEther(
  registerGasEstimate.totalGas * registerGasEstimate.maxFeePerGas,
)

// Display cost to user
console.log(`Estimated cost: ${costInEth} ETH`)

```

--------------------------------

### Configure Maven Repository for Android SDK (Gradle)

Source: https://developers.circle.com/w3s/developer-controlled-wallets/modular-wallets-quickstart

This Gradle snippet configures a Maven repository within your Android project's `build.gradle` file. It dynamically loads the repository URL and credentials from a `local.properties` file, which is necessary to fetch the Modular Wallets Android SDK dependencies.

```Gradle
repositories {
    ...
    maven {
            Properties properties = new Properties()
            // Load local.properties.
            properties.load(new File(rootDir.absolutePath + "/local.properties").newDataInputStream())

        url properties.getProperty('mwsdk.maven.url')
        credentials {
                username properties.getProperty('mwsdk.maven.username')
                password properties.getProperty('mwsdk.maven.password')
        }
    }
}
```

--------------------------------

### Customize Android Dimension Resources

Source: https://developers.circle.com/w3s/developer-controlled-wallets/android

Example of customizing dimension resources in Android's `dimens.xml` file. This file is used to define standard sizes for UI elements such as margins, padding, and text sizes, aiding in responsive design and consistent layouts across different screen densities.

```XML
<resources>
    <dimen name="circlepw_bottom_bt_margin_top">10dp</dimen>
    <dimen name="circlepw_intro_title_margin_bottom">24dp</dimen>
    <dimen name="circlepw_intro_custom_grab_icon_size">48dp</dimen>
</resources>
```