We refreshed our doc site!
Bookmarked links may have changed
Read release notesThe Circle Web SDK enables user-controlled wallets within your web application. Three authentication methods are supported, namely social logins, email, or PIN, which includes security questions for recovery. This allows you to authenticate your users in a seamless way and create user-controlled wallets for them.
By integrating this client-side SDK, your users can securely create wallets and make transactions using social accounts or email. If you choose the PIN authentication method, your users can input sensitive data, like PINs or security answers, in a secure way. Moreover, the SDK encrypts the request body sent by the application, protecting your users' information.
Note:
The Web and Mobile SDKs preserve the user keyshare with the individual, giving them complete control. You must use the SDKs with the user-controlled wallet product. Additionally, the Web and Mobile SDKs support only the user-controlled wallet product.
At Circle, we understand the importance of end-to-end security for your application and the need to create a tailored and seamless user experience for your end-users. Hence, Circle’s SDK also exposes functionality for you to customize the description and layout. See the Web SDK UI Customization API article to customize the SDK.
Install using npm:
npm install @circle-fin/w3s-pw-web-sdk
You must use Web, iOS, or Android SDKs to access the user-controlled Programmable Wallet product. The SDK secures, manages, and communicates with your server to ensure your user’s keyshare, always stays with them and is not exposed to your servers.
To learn more, see SDK Architecture for User-Controlled Wallets.
The Web SDK supports the API reference enums listed in the following sections.
Enumerates the types of challenges supported.
enum ChallengeType {
RESTORE_PIN,
SET_SECURITY_QUESTIONS,
CREATE_WALLET,
CREATE_TRANSACTION,
ACCELERATE_TRANSACTION,
CANCEL_TRANSACTION,
CONTRACT_EXECUTION,
SIGN_MESSAGE,
SIGN_TYPEDDATA,
UNKNOWN,
}
Enumerates the possible status for a challenge.
enum ChallengeStatus {
COMPLETE,
EXPIRED,
FAILED,
IN_PROGRESS,
PENDING,
}
Enumerates the types of security questions.
enum QuestionType {
DATE,
TEXT,
}
Enumerates the types of error code.
enum ErrorCode {
unknown = -1,
success = 0,
apiParameterMissing = 1,
apiParameterInvalid = 2,
forbidden = 3,
unauthorized = 4,
retry = 9,
customerSuspended = 10,
pending = 11,
invalidSession = 12,
invalidPartnerId = 13,
invalidMessage = 14,
invalidPhone = 15,
userAlreadyExisted = 155101,
userNotFound = 155102,
userTokenNotFound = 155103,
userTokenExpired = 155104,
invalidUserToken = 155105,
userWasInitialized = 155106,
userHasSetPin = 155107,
userHasSetSecurityQuestion = 155108,
userWasDisabled = 155109,
userDoesNotSetPinYet = 155110,
userDoesNotSetSecurityQuestionYet = 155111,
incorrectUserPin = 155112,
incorrectDeviceId = 155113,
incorrectAppId = 155114,
incorrectSecurityAnswers = 155115,
invalidChallengeId = 155116,
invalidApproveContent = 155117,
invalidEncryptionKey = 155118,
userPinLocked = 155119,
securityAnswersLocked = 155120,
notEnoughFunds = 155201,
notEnoughBalance = 155202,
exceedWithdrawLimit = 155203,
minimumFundsRequired = 155204,
invalidTransactionFee = 155205,
rejectedOnAmlScreening = 155206,
tagRequired = 155207,
gasLimitTooLow = 155208,
transactionDataNotEncodedProperly = 155209,
fullNodeReturnedError = 155210,
walletSetupRequired = 155211,
lowerThenMinimumAccountBalance = 155212,
rejectedByBlockchain = 155213,
droppedAsPartOfReorg = 155214,
operationNotSupport = 155215,
amountBelowMinimum = 155216,
wrongNftTokenIdNumber = 155217,
invalidDestinationAddress = 155218,
tokenWalletChainMismatch = 155219,
wrongAmountsNumber = 155220,
walletIsFrozen = 155501,
maxWalletLimitReached = 155502,
walletSetIdMutuallyExclusive = 155503,
metadataUnmatched = 155504,
userCanceled = 155701,
launchUiFailed = 155702,
pinCodeNotMatched = 155703,
insecurePinCode = 155704,
hintsMatchAnswers = 155705,
networkError = 155706,
biometricsSettingNotEnabled = 155708,
deviceNotSupportBiometrics = 155709,
biometricsKeyPermanentlyInvalidated = 155710,
biometricsUserSkip = 155711,
biometricsUserDisableForPin = 155712,
biometricsUserLockout = 155713,
biometricsUserLockoutPermanent = 155714,
biometricsUserNotAllowPermission = 155715,
biometricsInternalError = 155716,
invalidUserTokenFormat= 155718,
walletIdNotFound = 156001,
tokenIdNotFound = 156002,
transactionIdNotFound = 156003,
entityCredentialNotFound = 156004,
walletSetIdNotFound = 156005,
}
The Web SDK supports the interfaces listed in the following sections.
appSettings
<AppSettings> Application settings objectauthentication
<Authentication> Authentication objectsocialLoginConfig
<SocialLoginConfig> Social login configuration objectHolds application settings.
appId
<string> Application ID, retrieved from Circle Web3 Services ConsoleHolds authentication information.
Holds login configuration information.
google
<object> | undefined (optional) Configuration object for Google login.
facebook
<object> | undefined Configuration for Facebook login.
apple
<FirebaseOptions> | undefined (optional) Configuration for Apple login, using Firebase.deviceToken
<string> Token used to identify the devicedeviceEncryptionKey
<string> Encryption key used for the deviceotpToken
<string> | undefined (optional) OTP token for verificationAPPLE
<string> Apple login providerFACEBOOK
<string> Facebook login providerGOOGLE
<string> Google login providerHolds information about a challenge.
challengeId
<string> Challenge IdHolds the result of a challenge.
type
<ChallengeType> Challenge typestatus
<ChallengeStatus> Challenge statusdata
<SignMessageResult | undefined> Sign message responseHolds the result of a sign message or sign typed-data challenge.
signature
<string> Signature result after signingHolds the result of a sign transaction challenge.
signature
<string> Signature result after signingtxHash
<string> Transaction hashsignedTransaction
<string> Signed transactionHolds the result of a social login.
Holds the result of an email login.
Holds the OAuth information.
Holds error information.
code
<integer | undefined> Internal error codemessage
<string> Error messageCallback function for social login completion.
error
<Error> Presents if error occursresult
<SocialLoginResult> | /<EmailLoginResult> | undefined > Presents and contains the result of the social login when the login is completedHolds information about a custom security question.
question
<string> Custom security questiontype
<QuestionType> Type of the questionHolds localization settings.
common
<Common | undefined> The settings for common textsconfirmInitPincode
<ConfirmPincode | undefined> The settings for ConfirmInitPincode
screenconfirmNewPincode
<ConfirmPincode | undefined> The settings for ConfirmNewPincode
screenenterPincode
<EnterPincode | undefined> The settings for EnterPincode
screeninitPincode
<NewPincode | undefined> The settings for InitPincode
screennewPincode
<NewPincode | undefined> The settings for NewPincode
screenrecoverPincode
<RecoverPincode | undefined> The settings for RecoverPincode
screensecurityConfirm
<SecurityConfirm | undefined> The settings for SecurityConfirm
screensecurityIntros
<SecurityIntros | undefined> The settings for SecurityIntros
screensecurityQuestions
<SecurityQuestions | undefined> The settings for SecurityQuestions
screensecuritySummary
<SecuritySummary | undefined> The settings for SecuritySummary
screensocialEmailConfirmationUI
<SocialEmailConfirmationUI | undefined> The settings for socialEmailConfirmationUI
screenHolds localization settings for common texts.
continue
<string | undefined> Continue textshowPin
<string | undefined> Show pin texthidePin
<string | undefined> Hide pin textconfirm
<string | undefined> Confirm textHolds localization settings for ConfirmInitPincode
or ConfirmNewPincode
screen.
headline
<string | undefined> Headline textheadline2
<string | undefined> Headline text 2subhead
<string | undefined> Subhead textHolds localization settings for EnterPincode
screen.
headline
<string | undefined> Headline textheadline2
<string | undefined> Headline text 2subhead
<string | undefined> Subhead textforgotPin
<string | undefined> Forgot pin textHolds localization settings for InitPincode
or NewPincode
screen.
headline
<string | undefined> Headline textheadline2
<string | undefined> Headline text 2subhead
<string | undefined> Subhead textHolds localization settings for RecoverPincode
screen.
headline
<string | undefined> Headline textheadline2
<string | undefined> Headline text 2subhead
<string | undefined> Subhead textanswerInputHeader
<string | undefined> Answer input header textanswerInputPlaceholder
<string | undefined> Answer input placeholder textHolds localization settings for SecurityConfirm
screen.
title
<string | undefined> Title textheadline
<string | undefined> Headline textinputHeadline
<string | undefined> Input headline textinputPlaceholder
<string | undefined> Input placeholder textinputMatch
<string | undefined> Input match textHolds localization settings for SecurityIntros
screen.
headline
<string | undefined> Headline textheadline2
<string | undefined> Headline text 2description
<string | undefined> Description textlink
<string | undefined> Link textHolds localization settings for SecurityQuestions
screen.
title
<string | undefined> Title textquestionHeader
<string | undefined> Question header textquestionPlaceholder
<string | undefined> Question placeholder textrequiredMark
<string | undefined> Required mark textanswerHeader
<string | undefined> Answer header textanswerPlaceholder
<string | undefined> Answer placeholder textanswerHintHeader
<string | undefined> Answer hint header textanswerHintPlaceholder
<string | undefined> Answer hint placeholder textHolds localization settings for SecuritySummary
screen.
title
<string | undefined> Title textquestion
<string | undefined> Question textHolds localization settings for SocialEmailConfirmationUI
screen.
title
<string | undefined> Title textheadline
<string | undefined> Headline textHolds localization settings for TransactionRequest
screen.
title
<string | undefined> Title textsubtitle
<string | undefined> Subtitle textmainCurrency
<object | undefined> Main currency details:
amount
<string | number | undefined> Main currency amountsymbol
<string | undefined> Main currency symbolexchangeValue
<object | undefined> Exchange currency details:
amount
<string | number | undefined> Exchange currency amountsymbol
<string | undefined> Exchange currency symbolfromLabel
<string | undefined> From label textfrom
<string | undefined> From address or label texttoLabel
<string | undefined> To label textto
<string[] | undefined> To addressesnetworkFeeLabel
<string | undefined> Network fee label textnetworkFeeTip
<string | undefined> Network fee tooltip textnetworkFee
<string | undefined> Network fee amountexchangeNetworkFee
<string | undefined> Exchange network fee amounttotalLabel
<string | undefined> Total label texttotal
<string[] | undefined> Total amountsexchangeTotalValue
<string | undefined> Exchange total valuerawTxDescription
<string | undefined> Raw transaction descriptionrawTx
<string | undefined> Raw transaction dataHolds localization settings for a contract interaction screen.
title
<string | undefined> Title textsubtitle
<string | undefined> Subtitle textmainCurrency
<object | undefined> Main currency details:
amount
<string | number | undefined> Main currency amountsymbol
<string | undefined> Main currency symbolexchangeValue
<object | undefined> Exchange value details:
amount
<string | number | undefined> Exchange value amountsymbol
<string | undefined> Exchange value symbolfromLabel
<string | undefined> From label textfrom
<string | undefined> From address or label textcontractAddressLabel
<string | undefined> Contract address label textcontractInfo
<string[] | undefined> Contract informationnetworkFeeLabel
<string | undefined> Network fee label textnetworkFeeTip
<string | undefined> Network fee tooltip textnetworkFee
<string | undefined> Network fee amountexchangeNetworkFee
<string | undefined> Exchange network fee amounttotalLabel
<string | undefined> Total label texttotal
<string[] | undefined> Total amountsexchangeTotalValue
<string | undefined> Exchange total valuedataDetails
<object | undefined> Data details:
dataDetailsLabel
<string | undefined> Data details labelcallData
<object | undefined> Call data:
callDataLabel
<string | undefined> Call data labeldata
<string | undefined> Call data stringabiInfo
<object | undefined> ABI information:
functionNameLabel
<string | undefined> Function name labelfunctionName
<string | undefined> Function name stringparametersLabel
<string | undefined> Parameters labelparameters
<string[] | undefined> Parameters stringsHolds localization settings for a signature request screen.
title
<string | undefined> Title textcontractName
<string | undefined> Contract namecontractUrl
<string | undefined> Contract URLsubtitle
<string | undefined> Subtitle textdescriptionLabel
<string | undefined> Description label textdescription
<string | undefined> Description textHolds localization settings for an email OTP (One-Time Password) screen.
title
<string | undefined> Title textsubtitle
<string | undefined> Subtitle textresendHint
<string | undefined> Resend hint textresend
<string | undefined> Resend button textHolds customization color settings.
backdrop
<string | undefined> Backdrop color, e.g. '#000000'
.backdropOpacity
<number | undefined> Backdrop opacity, e.g. 0.5
.divider
<string | undefined> Divider color, e.g. '#808080'
or 'grey'
.bg
<string | undefined> Background color e.g. '#FFFFFF'
or 'white'
.success
<string | undefined> Success color, e.g. '#008000'
or 'green'
.error
<string | undefined> Error color, e.g. '#FF0000'
or 'red'
.textMain
<string | undefined> Main text color, e.g. '#000000'
or 'black'
.textMain2
<string | undefined> Main text color 2, e.g. '#000000'
or 'black'
.textAuxiliary
<string | undefined> Auxiliary text color, e.g. '#000000'
or 'black'
.textAuxiliary2
<string | undefined> Auxiliary text color 2, e.g. '#000000'
or 'black'
.textSummary
<string | undefined> Summary text color, e.g. '#000000'
or 'black'
.textSummaryHighlight
<string | undefined> Summary highlight text color, e.g. '#000000'
or 'black'
.textPlaceholder
<string | undefined> Placeholder text color, e.g. '#808080'
or 'grey'
.pinDotBase
<string | undefined> Fill color for pincode input dot, e.g. '#FFFFFF'
or 'white'
.pinDotBaseBorder
<string | undefined> Stroke color for pincode input dot, e.g. '#000000'
or 'black'
.pinDotActivated
<string | undefined> Fill color for inputted pincode input dot, e.g. '#0000ff'
or 'blue'
.enteredPinText
<string | undefined> Text color for entered pincode input, e.g. #000000
or black
.inputText
<string | undefined> Text color for text input, e.g. #000000
or black
.inputBorderFocused
<string | undefined> Outline color for text input on focused, e.g. '#0000ff'
or 'blue'
.inputBorderFocusedError
<string | undefined> Outline color for text input when error, e.g. '#FF0000'
or 'red'
.inputBg
<string | undefined> Background color for text input, e.g. '#FFFFFF'
or 'white'
.inputBgDisabled
<string | undefined> Background color for disabled text input, e.g. '#FFFFFF'
or 'white'
.dropdownBg
<string | undefined> Background color for dropdown, e.g. '#FFFFFF'
or 'white'
.dropdownBorderIsOpen
<string | undefined> Outline color for dropdown is open, e.g. '#0000ff'
or 'blue'
.dropdownBorderError
<string | undefined> Outline color for dropdown when error, e.g. '#FF0000'
or 'red'
.mainBtnText
<string | undefined> Text color for primary button, e.g. '#FFFFFF'
or 'white'
.mainBtnTextDisabled
<string | undefined> Text color for disabled primary button, e.g. '#FFFFFF'
or 'white'
.mainBtnTextOnHover
<string | undefined> Text color for primary button on hover, e.g. '#FFFFFF'
or 'white'
.mainBtnBg
<string | undefined> Background color for primary button, e.g. '#000000'
or 'black'
.mainBtnBgOnHover
<string | undefined> Background color for primary button on hover, e.g. '#000000'
or 'black'
.mainBtnBgDisabled
<string | undefined> Background color for disabled primary button, e.g. '#000000'
or 'black'
.secondBtnText
<string | undefined> Text color for secondary button, e.g. '#000000'
or 'black'
.secondBtnTextDisabled
<string | undefined> Text color for disabled secondary button, e.g. '#000000'
or 'black'
.secondBtnTextOnHover
<string | undefined> Text color for secondary button on hover, e.g. '#000000'
or 'black'
.secondBtnBorder
<string | undefined> Outline color for secondary button, e.g. '#000000'
or 'black'
.secondBtnBorderOnHover
<string | undefined> Outline color for secondary button on hover, e.g. '#000000'
or 'black'
.secondBtnBgOnHover
<string | undefined> Background color for secondary button on hover, e.g. '#FFFFFF'
or 'white'
.secondBtnBorderDisabled
<string | undefined> Outline color for disabled secondary button, e.g. '#FFFFFF'
or 'white'
.plainBtnText
<string | undefined> Text color for plain text button, e.g. '#000000'
or 'black'
.plainBtnTextDisabled
<string | undefined> Text color for disabled plain text button, e.g. '#000000'
or 'black'
.plainBtnTextOnHover
<string | undefined> Text color for plain text button on hover, e.g. '#000000'
or 'black'
.plainBtnBg
<string | undefined> Background color for plain text button, e.g. '#FFFFFF'
or 'white'
.plainBtnBgOnHover
<string | undefined> Background color for plain text button on hover, e.g. '#FFFFFF'
or 'white'
.recoverPinHintTitle
<string | undefined> Text color for recover pincode hint title, e.g. '#FFFFFF'
or 'white'
.recoverPinHintTitleBg
<string | undefined> Background color for recover pincode hint title, e.g. '#FFFFFF'
or 'white'
.recoverPinHint
<string | undefined> Text color for recover pincode hint, e.g. '#FFFFFF'
or 'white'
.titleGradients
<string[] | undefined> Background color for linear-gradient text, e.g. ['#B090F5', '#1AA3FF']
.Holds resource urls and properties, such as images or font-family settings. These resource properties should be hosted on a public server. SDK will load these resources from the urls provided.
naviClose
<string | undefined> Close iconnaviBack
<string | undefined> Back iconsecurityIntroMain
<string | undefined> Security intro main imagedropdownArrow
<string | undefined> Dropdown arrow iconselectCheckMark
<string | undefined> Select check mark iconsecurityConfirmMain
<string | undefined> Security confirm main imageerrorInfo
<string | undefined> Error info iconfontFamily
<{ name?: string, url?: string } | undefined> Font family settingsHolds custom links.
learnMoreUrl
<string | undefined> Learn more linkThe Web SDK supports the class definitions listed in the following sections.
Initializes a new instance of W3SSdk
.
Executes a challenge.
challengeId
<string> Challenge ID
onCompleted
<Function> Callback function
error
<Error> Presents if error occursresult
<ChallengeResult> Presents when successSets the application settings.
appSettings
<AppSettings> Application settings objectSets the authentication information.
auth
<Authentication> Authentication objectUpdates the configurations.
configs
<Configs> Configurations objectonSocialLoginComplete
<Function | undefined> Callback function
error
<Error> Presents if error occursresult
<SocialLoginResult> | <\EmailLoginResult> | undefined> Presents and contains the result of the social login when the social login is completedGets the device ID.
Performs a social login.
provider
<SocialLoginProvider> Social login providerVerifies the OTP.
Executes a challenge.
challengeId
<string> Challenge IDonCompleted
<Function | undefined> Callback function
error
<Error> Presents if error occursresult
<ChallengeResult | SignMessageResult | SignTransactionResult | undefined> Presents and contains the result of the challenge when the challenge is completedSets custom security questions.
questions
<SecurityQuestion[] | undefined> Array of SecurityQuestion
requiredCount
<integer | undefined> Required count of SecurityQuestion
. The value is 2 by default.securityConfirmItems
<string[] | undefined> Array of customized disclaimers on SecurityConfirm
screen. The value is undefined
by default.Sets custom localizations
localizations
<Localizations | undefined> Settings of Localizations
Sets custom resources
resources
<Resources | undefined> Settings of Resources
Sets custom theme colors
themeColor
<ThemeColor | undefined> Settings of ThemeColor
Sets custom links
customLinks
<CustomLinks | undefined> Settings of CustomLinks
Sets callback function for ForgotPin button click event
onForgotPin
<Function | undefined> Callback functionshouldCloseModalOnForgotPin
<boolean | undefined> Should close modal on forgot pin click eventSets callback function for Resend OTP Email button click event
onResendOtpEmail
<Function | undefined> Callback functionimport 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')}
value={challengeId}
/>
<Button variant="contained" color="primary" onClick={onSubmit}>
Verify Challenge
</Button>
<ToastContainer />
</div>
)
}
// 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}`)
})