Welcome to Circle’s Modular Wallets iOS 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 provided in the GitHub repository to install and set up the Modular Wallets iOS SDK.
The following sections detail the SDK’s transport mechanisms, client interactions, account management, utility functions, model structures, and supported blockchain networks.
Transport
request
rpcRequest
: RpcRequest
- The RPC request to be sent.RpcResponse
HttpTransport
HttpTransport
confirms the protocol Transport
and
implements the required methods.ModularTransport
ModularTransport
inherits HttpTransport
and confirms
the protocol ModularRpcApi
.HttpRpcClientOptions
headers
: [String: String]
- Headers to include in the HTTP requests.toModularTransport
ModularTransport
with the provided
client key and URL.clientKey
: String
- The client key for authorization.url
: String
- The URL for the HTTP transport.HttpTransport
- The configured HTTP transport instance.toPasskeyTransport
HttpTransport
with the provided
client key and URL, setting the authorization header.clientKey
: String
- The client key for authorization.url
: String
- The URL of the transport endpoint. Defaults to
CIRCLE_BASE_URL
.HttpTransport
- The configured HTTP transport instance.http
url
: String
- The URL for the HTTP transport.options
: HttpRpcClientOptions?
- Optional configuration options for the
HTTP transport.HttpTransport
- The configured HTTP transport instance.Client
BundlerClient
PaymasterClient
chain
: Chain
- The blockchain that the client interacts with.transport
: Transport
- The transport mechanism used for making RPC
requests.BundlerClient
BundlerClient
is an interface to interact with ERC-4337 Bundlers and
provides the ability to send and retrieve User Operations through Bundler
Actions.Client
.estimateUserOperationGas
account
: SmartAccount
- The smart account to use for User Operation
execution.calls
: [EncodeCallDataArg]
- The calls to execute in the User Operation.paymaster
: Paymaster?
- Optional, sets Paymaster configuration for the
User Operation.estimateFeesPerGas
:
((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?
-
Optional, prepares fee properties for the User Operation request.EstimateUserOperationGasResult
- The result of the gas
estimation.getChainId
Int
- The current chain ID.getSupportedEntryPoints
[String]
- A list of supported EntryPoints.getUserOperation
userOpHash
: String
- The hash of the User Operation.GetUserOperationResult
- User Operation information.getUserOperationReceipt
userOpHash
: String
- The hash of the User Operation.GetUserOperationReceiptResult
- The User Operation receipt.prepareUserOperation
account
: SmartAccount
- The smart account to use for User Operation
execution.calls
: [EncodeCallDataArg]?
- The calls to execute in the User
Operation.partialUserOp
: UserOperationV07
- The partial User Operation to be
completed.paymaster
: Paymaster?
- Optional, sets Paymaster configuration for the
User Operation.estimateFeesPerGas
:
((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?
-
Optional, prepares fee properties for the User Operation request.UserOperationV07
- The prepared User Operation.sendUserOperation
account
: SmartAccount
- The smart account to use for User Operation
execution.calls
: [EncodeCallDataArg]?
- The calls to execute in the User
Operation.partialUserOp
: UserOperationV07
- The partial User Operation to be
completed.paymaster
: Paymaster?
- Optional, sets Paymaster configuration for the
User Operation.estimateFeesPerGas
:
((SmartAccount, BundlerClient, UserOperationV07) async -> EstimateFeesPerGasResult)?
-
Optional, prepares fee properties for the User Operation request.String?
- Optional, the hash of the sent User Operation, or
null
otherwise.waitForUserOperationReceipt
userOpHash
: String
- The User Operation hash.pollingInterval
: Int
(default: 4000
) - The polling interval in
milliseconds.retryCount
: Int
(default: 6
) - The number of retries.timeout
: Int?
- Optional timeout in milliseconds to wait before stopping
polling.GetUserOperationReceiptResult
- The result of the User
Operation receipt retrieval.getBalance
address
: String
- The address to query the balance for. Only wallet
addresses registered with the client key can be retrieved.blockNumber
: BlockNumber
- The block number (default: .latest
).BigInt
- The balance of the address.getBlockNumber
BigInt
- The current block number.getGasPrice
BigInt
- The current gas price (in wei).call
from
: String?
- Optional, the address to send the call from.to
: String
- The contract address or recipient.data
: Data
- A contract hashed method call with encoded arguments.String
- The call data.getCode
address
: String
- The contract address.blockNumber
: BlockNumber
- The block number (default: .latest
).String
- The contract's bytecode.estimateMaxPriorityFeePerGas
eth_maxPriorityFeePerGas
(if supported) or manually calculate
the max priority fee per gas based on the current block base fee per gas + gas
price.BigInt
- An estimate (in wei) for the max priority fee per gas.getBlock
includeTransactions
: Boolean
(default: false
) - Whether or not to
include transactions (as a structured array of Transaction
objects).blockNumber
: BlockNumber
- The block number (default: .latest
).Block
- The block information.PaymasterClient
PaymasterClient
is an interface to interact with
ERC-7677 compliant Paymasters and
provides the ability to sponsor User Operation gas fees.Client
.getPaymasterData
userOp
: T
- The User Operation to retrieve Paymaster data for. Type T
must be a subclass of UserOperation
.entryPoint
: EntryPoint
- The EntryPoint address to target.context
: [String: AnyEncodable]?
- Optional, paymaster-specific fields.GetPaymasterDataResult
- Paymaster-related User Operation
properties.getPaymasterStubData
userOp
: T
- The User Operation to retrieve Paymaster data for. Type T
must be a subclass of UserOperation
.entryPoint
: EntryPoint
- The EntryPoint address to target.context
: [String: AnyEncodable]?
- Optional, paymaster-specific fields.GetPaymasterStubDataResult
- Paymaster-related User Operation
properties.toCircleSmartAccount
client
: Client
- The client used to interact with the blockchain.owner
: Account<SignResult>
- The owner account associated with the
Circle Passkey account.version
: String
(default: "circle_passkey_account_v1"
) - The version
of the Circle Passkey account.name
: String?
(optional, defaults to the format
passkey-yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
) - The wallet name assigned to the
newly registered account.CircleSmartAccount
toWebAuthnAccount
credential
: WebAuthnCredential
- The WebAuthn credential associated with
the account.WebAuthnAccount
- The created WebAuthn account.toWebAuthnCredential
WebAuthnCredential
.transport
: Transport
- The transport used to communicate with the RP
API.userName
: String?
(optional, required for WebAuthnMode.Register
) - The
username of the user.mode
: WebAuthnMode
- The mode of the WebAuthn credential.WebAuthnCredential
BaseError
if userName
is null
for WebAuthnMode.Register
.WebAuthnCredential
id
: String
- The unique identifier for the credential.publicKey
: String
(serialized hex) - The public key associated with the
credential.raw
: PublicKeyCredential
- The raw public key credential.rpId
: String
- The relying party identifier.Account
T
- The type of the signed data.getAddress
String
- The account's address.sign
hex
: String
- The hex data to sign.T
- The signed data.signMessage
message
: String
- The message to sign.T
- The signed message.signTypedData
typedData
: String
- The typed data to sign.T
- The signed typed data.WebAuthnAccount
Account
getAddress
String
- The associated public key.sign
hex
: String
- The hex string to sign.SignResult
- The result of the signing operation.signMessage
message
: String
- The message to sign.SignResult
- The result of the signing operation.signTypedData
jsonData
: String
- The JSON data to sign.SignResult
- The result of the signing operation.SmartAccount
client
: Client
- The client used to interact with the blockchain.entryPoint
: EntryPoint
- The entry point for the smart account.userOperation
: UserOperationConfiguration?
- Configuration for the User
Operation.getAddress
String
- The account address.encodeCalls
args
: [EncodeCallDataArg]
- The call data arguments to encode.String
- The encoded call data.getFactoryArgs
(String, String)?
- A pair containing the factory address and
factory data.getNonce
key
: BigInt?
- Optional key to retrieve the nonce for.BigInt
- The nonce value.getStubSignature
userOp
: T
- The User Operation.String
- The stub signature.sign
hex
: String
- The hex string to sign.String
- The signed string.signMessage
message
: String
- The message to sign.String
- The signed message.signTypedData
typedData
: String
- The typed data to sign.String
- The signed typed data.signUserOperation
chainId
: Long
- The chain ID for the user operation. Defaults to the
chain ID of the client.userOp
: UserOperationV07
- The user operation to sign.String
- The signed user operation.CircleSmartAccount
client
: Client
- The blockchain client.owner
: Account<SignResult>
- The associated owner account.entryPoint
: EntryPoint
- The entry point for the account.wallet
: Wallet information.userOperation
: UserOperationConfiguration?
- Configuration for the User
Operation.SmartAccount
getAddress
String
- The account address.encodeCalls
args
: [EncodeCallDataArg]
- The call data arguments.String?
- The encoded call data.getFactoryArgs
(String, String)?
- The factory arguments.BaseError
if there is no initialization code.getNonce
key
: BigInt?
- Optional key.BigInt
- The nonce value.getStubSignature
userOp
: T
- The User Operation.String
- The stub signature.sign
hex
: String
- The hex string to sign.String
- The signature.BaseError
if signing fails.signMessage
message
: String
- The message to sign.String
- The signature.BaseError
if signing fails.signTypedData
jsonData
: String
- The JSON data to sign.String
- The signature.BaseError
if signing fails.signUserOperation
chainId
: Int
- The chain ID.userOp
: UserOperationV07
- The user operation.String
- The signature.BaseError
if signing fails.getInitCode
String?
- The initialization code.encodeTransfer
to
: String
- The recipient address.token
: String
- The token contract address or the name of Token enum.
Supported tokens and their information are listed below.amount
: BigInt
- The amount to transfer.EncodeTransferResult
- The encoded transfer ABI and contract
address.Blockchain Network | Token Name (Symbol) | Enum | Contract Address |
---|---|---|---|
Arbitrum Mainnet | USD Coin (USDC) | ArbitrumToken.USDC | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |
Arbitrum Mainnet | Arbitrum (ARB) | ArbitrumToken.ARB | 0x912CE59144191C1204E64559FE8253a0e49E6548 |
Base Mainnet | USD Coin (USDC) | BaseToken.USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
Optimism Mainnet | USD Coin (USDC) | OptimismToken.USDC | 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85 |
Optimism Mainnet | Optimism (OP) | OptimismToken.OP | 0x4200000000000000000000000000000000000042 |
Polygon Mainnet | USD Coin (USDC) | PolygonToken.USDC | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
Unichain Mainnet | USD Coin (USDC) | UnichainToken.USDC | 0x078D782b760474a361dDA0AF3839290b0EF57AD6 |
Arbitrum Sepolia Testnet | USD Coin (USDC) | ArbitrumSepoliaToken.USDC | 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d |
Base Sepolia Testnet | USD Coin (USDC) | BaseSepoliaToken.USDC | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |
Optimism Sepolia Testnet | USD Coin (USDC) | OptimismSepoliaToken.USDC | 0x5fd84259d66Cd46123540766Be93DFE6D43130D7 |
Polygon Amoy Testnet | USD Coin (USDC) | PolygonAmoyToken.USDC | 0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582 |
Unichain Sepolia Testnet | USD Coin (USDC) | UnichainSepoliaToken.USDC | 0x31d0220469e10c4E71834a79b1f276d740d3768F |
encodeCallData
arg
: EncodeCallDataArg
- A single call data argument.String
- The encoded call data.args
: [EncodeCallDataArg]
- An array of call data arguments.String
- The encoded call data.encodeFunctionData
functionName
: String
- The name of the ABI function.abiJson
: String
- The ABI JSON.args
: [Any]
- The input arguments for the ABI function.String?
- Optional encoded ABI function data.encodeContractExecution
to
: String
- The target address.abiSignature
: String
- The ABI signature of the function.args
: [Any]
- The arguments for the function.value
: BigInt
- The value to send.String
- The encoded contract execution function data.parseGweiToWei
value
: String
- The Gwei value as a string.BigInt
- The Wei value.parseEtherToWei
value
: String
- The Ether value as a string.BigInt
- The Wei value.SignResult
signature
: String
- The signature generated by the signing operation.webAuthn
: WebAuthnData
- The WebAuthn data associated with the signing
operation.raw
: AuthenticationCredential
- The raw authentication credential used
in the signing operation.WebAuthnData
authenticatorData
: String
- The authenticator data in hexadecimal
format.challengeIndex
: Int
- The index of the challenge in the client data
JSON.clientDataJSON
: String
- The client data JSON.typeIndex
: Int
- The index of the type in the client data JSON.userVerificationRequired
: Boolean
- Indicates whether user verification
is required.EncodeCallDataArg
to
: String
- The target address for the call (required).value
: BigInt?
- The amount of value to send with the call (optional,
defaults to 0).data
: String?
- The call data to be sent (optional, defaults to "0x"
if not provided).abiJson
: String?
- The ABI JSON of the smart contract function
(optional).args
: [AnyEncodable]?
- The arguments for the ABI function (optional).functionName
: String?
- The name of the function to be called
(optional).EstimateUserOperationGasResult
Codable
preVerificationGas
: BigInt?
- The gas used for pre-verification.verificationGasLimit
: BigInt?
- The gas limit for verification.callGasLimit
: BigInt?
- The gas limit for the call.paymasterVerificationGasLimit
: BigInt?
- The gas limit for paymaster
verification.paymasterPostOpGasLimit
: BigInt?
- The gas limit for paymaster
post-operation.EstimateFeesPerGasResult
maxFeePerGas
: BigInt?
- Maximum fee per gas (EIP-1559).maxPriorityFeePerGas
: BigInt?
- Maximum priority fee per gas (EIP-1559).gasPrice
: BigInt?
- Legacy gas price.GetUserOperationReceiptResult
userOpHash
: String?
- The hash of the User Operation.sender
: String?
- The sender address.nonce
: String?
- The nonce value.actualGasCost
: String?
- The actual gas cost in hexadecimal format.actualGasUsed
: String?
- The actual gas used in hexadecimal format.success
: Boolean?
- Indicates whether the operation was successful.paymaster
: String?
- The paymaster address.logs
: [Log]?
- The list of logs.receipt
: UserOperationReceipt
- The User Operation receipt details.GetUserOperationResult
Codable
blockHash
: String?
- The hash of the block containing the operation.blockNumber
: BigInt?
- The number of the block containing the operation.transactionHash
: String?
- The hash of the transaction for the
operation.entryPoint
: String?
- The entry point of the operation.userOperation
: UserOperationType?
- The User Operation.UserOperationReceipt
Codable
transactionHash
: String?
- The transaction hash.transactionIndex
: String?
- The transaction index.blockHash
: String?
- The block hash.blockNumber
: String?
- The block number.from
: String?
- The sender's address.to
: String?
- The recipient's address.cumulativeGasUsed
: String?
- The cumulative gas used.gasUsed
: String?
- The gas used.logs
: [Log]?
- The list of logs.logsBloom
: String?
- The bloom filter for logs.status
: String?
- The status of the operation.effectiveGasPrice
: String?
- The effective gas price.Log
Codable
removed
: Boolean?
- Indicates whether the log was removed.logIndex
: String?
- The index of the log.transactionIndex
: String?
- The index of the transaction.transactionHash
: String?
- The transaction hash.blockHash
: String?
- The block hash.blockNumber
: String?
- The block number.address
: String?
- The address of the contract generating the log.data
: String?
- The log data.topics
: [String]?
- The list of topics.GetPaymasterDataResult
Codable
paymaster
: String?
- The Paymaster address for entry point version 0.7.paymasterData
: String?
- The Paymaster data for entry point version 0.7.paymasterPostOpGasLimit
: BigInt?
- The gas limit for the Paymaster
post-operation for entry point version 0.7.paymasterVerificationGasLimit
: BigInt?
- The gas limit for the Paymaster
verification for entry point version 0.7.paymasterAndData
: String?
- The Paymaster and associated data for entry
point version 0.6.GetPaymasterStubDataResult
Codable
paymaster
: String?
- The Paymaster address for entry point version 0.7.paymasterData
: String?
- The Paymaster data for entry point version 0.7.paymasterPostOpGasLimit
: BigInt?
- The gas limit for the Paymaster
post-operation for entry point version 0.7.paymasterVerificationGasLimit
: BigInt?
- The gas limit for the Paymaster
verification for entry point version 0.7.paymasterAndData
: String?
- The Paymaster and associated data for entry
point version 0.6.isFinal
: Boolean?
- Indicates whether the caller does not need to call
getPaymasterData
.sponsor
: SponsorInfo?
- Sponsor information associated with the
Paymaster.Block
Codable
number
: BigUInt
- The block number.hash
: Data
- The block hash.parentHash
: Data
- The parent block hash.nonce
: Data?
- The block nonce (optional).sha3Uncles
: Data
- The SHA3 hash of the uncles.logsBloom
: EthereumBloomFilter?
- The bloom filter for the logs
(optional).transactionsRoot
: Data
- The root of the transactions trie.stateRoot
: Data
- The root of the state trie.receiptsRoot
: Data
- The root of the receipts trie.miner
: EthereumAddress?
- The address of the miner.difficulty
: BigUInt
- The difficulty of the block.totalDifficulty
: BigUInt?
- The total difficulty of the chain up to this
block.extraData
: Data
- Extra data included in the block.size
: BigUInt
- The size of the block.gasLimit
: BigUInt
- The gas limit of the block.gasUsed
: BigUInt
- The gas used in the block.baseFeePerGas
: BigUInt?
- The base fee per gas (optional, present in
EIP-1559 blocks).timestamp
: Date
- The timestamp of the block.transactions
: [TransactionInBlock]
- The list of transactions in the
block.uncles
: [Data]
- The list of uncle blocks.EncodeTransferResult
encodeTransfer
.data
: String
- The encoded data.to
: String
- The token address.EntryPoint
address
: String
- The address of the entry point.v07
- Represents the entry point version 0.7 with its respective address.Paymaster
PaymasterClient
, it uses the provided Paymaster
Client for sponsorship.true
, it assumes that the Bundler Client supports
Paymaster RPC methods (e.g. getPaymasterData
) and uses them for
sponsorship.True
paymasterContext
: [String: AnyEncodable]?
- Optional context for the
Paymaster.Client
client
: PaymasterClient
- The Paymaster Client used for sponsorship.paymasterContext
: [String: AnyEncodable]?
- Optional context for the
Paymaster.PublicKeyCredential
RegistrationCredential
AuthenticationCredential
id
: String
- The unique identifier for the credential.type
: String
- The type of the credential.authenticatorAttachment
: String
- The attachment type of the
authenticator.response
: AuthenticatorResponse
- The response from the authenticator.clientExtensionResults
: AuthenticationExtensionsClientOutputs?
-
Optional client extension results.RegistrationCredential
PublicKeyCredential
rawId
: String
- The raw identifier for the credential.authenticatorAttachment
: String
- The attachment type of the
authenticator.type
: String
- The type of the credential.id
: String
- The unique identifier for the credential.response
: AuthenticatorAttestationResponse
- The attestation response
from the authenticator.clientExtensionResults
: AuthenticationExtensionsClientOutputs?
-
Optional client extension results.AuthenticationCredential
PublicKeyCredential
rawId
: String
- The raw identifier for the credential.authenticatorAttachment
: String
- The attachment type of the
authenticator.type
: String
- The type of the credential.id
: String
- The unique identifier for the credential.response
: AuthenticatorAssertionResponse
- The assertion response from
the authenticator.clientExtensionResults
: AuthenticationExtensionsClientOutputs?
-
Optional client extension results.UserOperation
UserOperationV07
sender
: String?
- The address of the sender.nonce
: BigInt?
- The nonce of the operation.callData
: String?
- The data to be sent in the call.callGasLimit
: BigInt?
- The gas limit for the call.verificationGasLimit
: BigInt?
- The gas limit for verification.preVerificationGas
: BigInt?
- The gas used before verification.maxPriorityFeePerGas
: BigInt?
- The maximum priority fee per gas.maxFeePerGas
: BigInt?
- The maximum fee per gas.signature
: String?
- The signature of the operation.UserOperationV07
UserOperation
sender
: String?
- The address of the sender.nonce
: BigInt?
- The nonce of the operation.callData
: String?
- The data to be sent in the call.callGasLimit
: BigInt?
- The gas limit for the call.verificationGasLimit
: BigInt?
- The gas limit for verification.preVerificationGas
: BigInt?
- The gas used before verification.maxPriorityFeePerGas
: BigInt?
- The maximum priority fee per gas.maxFeePerGas
: BigInt?
- The maximum fee per gas.signature
: String?
- The signature of the operation.factory
: String?
- The factory address.factoryData
: String?
- The data for the factory.paymaster
: String?
- The Paymaster address.paymasterVerificationGasLimit
: BigInt?
- The gas limit for Paymaster
verification.paymasterPostOpGasLimit
: BigInt?
- The gas limit for Paymaster
post-operation.paymasterData
: String?
- The data for the Paymaster.WebAuthnMode
Register
- Mode for registering a new credential.Login
- Mode for logging in with an existing credential.ArbitrumToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
ARB
BaseToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
OptimismToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
OP
PolygonToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
UnichainToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
ArbitrumSepoliaToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
BaseSepoliaToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
OptimismSepoliaToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
PolygonAmoyToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
UnichainSepoliaToken
encodeTransfer
. The format is {chain}_{symbol}
.USDC
ModularWallet
Codable
id
: String?
- The unique identifier of the wallet.address
: String?
- The blockchain address of the wallet.blockchain
: String?
- The blockchain network the wallet is associated
with.state
: String?
- The current state of the wallet.name
: String?
- The name of the wallet.scaCore
: String?
- The SCA (Strong Customer Authentication) core
identifier.scaConfiguration
: ScaConfiguration?
- The SCA configuration associated
with the wallet.createDate
: String?
- The creation date of the wallet.updateDate
: String?
- The last update date of the wallet.getInitCode
String?
- The initialization code from the SCA configuration,
if available.Chain
Arbitrum
ArbitrumSepolia
Base
BaseSepolia
Optimism
OptimismSepolia
Polygon
PolygonAmoy
Unichain
UnichainSepolia
chainId
: Int
- The unique identifier for the blockchain.