Note: The Web SDK integrates with Viem's interfaces. Commonly used methods, interfaces, enums, etc., from Viem that are relevant to our SDK will be specifically noted in the sections below.
Welcome to Circle's Modular Wallets Web SDK documentation. The SDK enables developers to integrate Circle's Modular Wallets to build secure, scalable Web3 applications by leveraging tools for key management, smart account interactions, gasless transactions, and blockchain communication.
Follow the steps on the NPM package repository to install and set up the Modular Wallets Web SDK.
The following sections detail the SDK's transport mechanisms, client interactions, account management, providers, utilities, interfaces, and types.
Note: The Web SDK integrates with Viem's interfaces. Commonly used methods, interfaces, enums, etc., from Viem that are relevant to our SDK will be specifically noted in the sections below.
Transports handle communication between the SDK and blockchain networks or APIs. They form the foundation for executing requests, such as JSON-RPC calls, ensuring secure and efficient interactions.
Aspect | toModularTransport | toPasskeyTransport |
---|---|---|
Purpose | Handles modular wallet-related blockchain actions. | Handles passkey-based user authentication. |
Service | Talks to Circle Modular Wallet API for wallet operations. | Talks to Circle Relying Party (RP) API for authentication flows. |
Focus | Blockchain and wallet operations (transactions, balances). | WebAuthn-based secure login and registration. |
Interaction | Blockchain-focused (e.g., Arbitrum Sepolia). | Credential-focused (e.g., verifying passkeys). |
Example Use Case | Sending gasless transactions | Registering or logging into a modular wallet. |
The Bundler Client supports the following key actions:
For the full list of actions and detailed documentation, see the Viem Bundler Actions Documentation.
The Public Client supports the following key actions:
For the full list of actions and detailed documentation, see the Viem Public Actions Documentation.
0x${string}
- The recipient address.0x${string}
- The token contract address. Supported tokens and
their information are listed below.Blockchain Network | Token Name (Symbol) | Enum | Contract Address |
---|---|---|---|
Polygon Mainnet | USD Coin (USDC) | ContractAddress.Polygon_USDC | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
Arbitrum Mainnet | USD Coin (USDC) | ContractAddress.Arbitrum_USDC | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |
Arbitrum Mainnet | Arbitrum (ARB) | ContractAddress.Arbitrum_ARB | 0x912CE59144191C1204E64559FE8253a0e49E6548 |
Base Mainnet | USD Coin (USDC) | ContractAddress.Base_USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
Optimism Mainnet | USD Coin (USDC) | ContractAddress.Optimism_USDC | 0x0b2c639c533813f4aa9d7837caf62653d097ff85 |
Optimism Mainnet | Optimism (OP) | ContractAddress.Optimism_OP | 0x4200000000000000000000000000000000000042 |
Unichain Mainnet | USD Coin (USDC) | ContractAddress.Unichain_USDC | 0x078D782b760474a361dDA0AF3839290b0EF57AD6 |
Polygon Amoy Testnet | USD Coin (USDC) | ContractAddres.PolygonAmoy_USDC | 0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582 |
Arbitrum Sepolia Testnet | USD Coin (USDC) | ContractAddress.ArbitrumSepolia_USDC | 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d |
Base Sepolia Testnet | USD Coin (USDC) | ContractAddress.BaseSepolia_USDC | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |
Optimism Sepolia Testnet | USD Coin (USDC) | ContractAddress.OptimismSepolia_USDC | 0x5fd84259d66Cd46123540766Be93DFE6D43130D7 |
Unichain Sepolia Testnet | USD Coin (USDC) | ContractAddress.UnichainSepolia_USDC | 0x31d0220469e10c4E71834a79b1f276d740d3768F |
0x${string}
> - The user operation hash from executing
recovery onchain.0x${string}
> - The user operation hash from registering
the recovery address onchain.0x${string}
> - The ABI-encoded webauthn signature.0x${string}
- The derived address of the recovery key.0x${string}
- The recovery address.0x${string}
- The public key associated with the credential, in
hexadecimal format.type CircleModularWalletClient: Client<
Transport,
Chain | undefined,
Account | undefined,
ExtendedRpcSchema<RpcSchema>,
ModularWalletActions,
>
type CircleSmartAccountImplementation = Assign<
SmartAccountImplementation<
typeof entryPoint07Abi,
"0.7",
{
abi: typeof entryPoint07Abi;
factory: {
abi: typeof CIRCLE_MSCA_6900_V1_EP07_FACTORY_ABI;
address: Address;
};
}
>,
{
getFactoryArgs: NonNullable<
SmartAccountImplementation["getFactoryArgs"]
>;
sign: NonNullable<SmartAccountImplementation["sign"]>;
}
>
CreateAddressMappingReturnType: AddressMappingResponse[]
type CreateAddressMappingRpcSchema = {
Method: "circle_createAddressMapping";
Parameters: [CreateAddressMappingParameters];
ReturnType: CreateAddressMappingReturnType;
}
type CreateRpClientErrorType = CreateClientErrorType | ErrorType
type ExtendedRpcSchema = rpcSchema extends RpcSchema
? [...ModularWalletRpcSchema, ...rpcSchema]
: ModularWalletRpcSchema
GetAddressMappingReturnType: AddressMappingResponse[]
type GetAddressMappingRpcSchema = {
Method: "circle_getAddressMapping";
Parameters: [GetAddressMappingParameters];
ReturnType: GetAddressMappingReturnType;
}
type GetAddressParameters = [
{
metadata?: { name?: string };
scaConfiguration: {
initialOwnershipConfiguration: Omit<
InitialOwnershipConfiguration,
"ownershipContractAddress"
>;
scaCore: string;
};
},
]
type GetAddressReturnType = ModularWallet
type GetAddressRpcSchema = {
Method: "circle_getAddress";
Parameters?: [
{
scaConfiguration: {
initialOwnershipConfiguration: Omit<
InitialOwnershipConfiguration,
"ownershipContractAddress"
>;
scaCore: string;
};
}
];
ReturnType: GetAddressReturnType;
}
type GetLoginOptionsParameters = {
userId: string;
}
type GetLoginOptionsReturnType = CustomPublicKeyCredentialRequestOptions
type GetLoginOptionsRpcSchema = {
Method: "rp_getLoginOptions";
Parameters?: [userId: string];
ReturnType: GetLoginOptionsReturnType;
}
type GetLoginVerificationParameters = {
credential: PublicKeyCredential;
}
type GetLoginVerificationRpcSchema = {
Method: "rp_getLoginVerification";
Parameters?: [authenticationCredential: PublicKeyCredential];
ReturnType: GetLoginVerificationReturnType;
}
type GetRegistrationOptionsParameters = {
username: string;
}
type GetRegistrationOptionsReturnType = CustomPublicKeyCredentialCreationOptions
type GetRegistrationOptionsRpcSchema = {
Method: "rp_getRegistrationOptions";
Parameters?: [username: string];
ReturnType: GetRegistrationOptionsReturnType;
}
type GetRegistrationVerificationParameters = {
credential: PublicKeyCredential;
}
type GetRegistrationVerificationRpcSchema = {
Method: "rp_getRegistrationVerification";
Parameters?: [registrationCredential: PublicKeyCredential];
ReturnType: GetRegistrationVerificationReturnType;
}
type ModularWalletActions = {
getAddress: (
parameters: GetAddressParameters,
) => Promise<GetAddressReturnType>;
}
type ModularWalletRpcSchema = [GetAddressRpcSchema]
type RecoveryActions = {
estimateExecuteRecoveryGas: (
parameters: EstimateExecuteRecoveryGasParameters,
) => Promise<EstimateUserOperationGasReturnType>;
estimateRegisterRecoveryAddressGas: (
parameters: EstimateRegisterRecoveryAddressGasParameters,
) => Promise<EstimateUserOperationGasReturnType>;
executeRecovery: (
parameters: ExecuteRecoveryParameters,
) => Promise<SendUserOperationReturnType>;
registerRecoveryAddress: (
params: RegisterRecoveryAddressParameters,
) => Promise<SendUserOperationReturnType>;
}
type RpActions = {
getLoginOptions: (
parameters: GetLoginOptionsParameters,
) => Promise<GetLoginOptionsReturnType>;
getLoginVerification: (
parameters: GetLoginVerificationParameters,
) => Promise<GetLoginVerificationReturnType>;
getRegistrationOptions: (
parameters: GetRegistrationOptionsParameters,
) => Promise<GetRegistrationOptionsReturnType>;
getRegistrationVerification: (
parameters: GetRegistrationVerificationParameters,
) => Promise<GetRegistrationVerificationReturnType>;
}
type RpClient = Prettify<
Client<
transport,
undefined,
undefined,
rpcSchema extends RpcSchema
? [...RpRpcSchema, ...rpcSchema]
: RpRpcSchema,
RpActions
>
>
type RpClientConfig = Prettify<
Pick<
ClientConfig<transport, undefined, undefined, rpcSchema>,
| "cacheTime"
| "key"
| "name"
| "pollingInterval"
| "rpcSchema"
| "transport"
>
>
type RpRpcSchema = [
GetLoginOptionsRpcSchema,
GetLoginVerificationRpcSchema,
GetRegistrationOptionsRpcSchema,
GetRegistrationVerificationRpcSchema
]
type ToCircleSmartAccountParameters = {
address?: Address;
client: Client;
name?: string;
nonce?: bigint;
owner: WebAuthnAccount;
}
type ToCircleSmartAccountReturnType = Prettify<
SmartAccount<CircleSmartAccountImplementation>
>