Creating an Ethereum wallet

To create an EVM embedded wallet for your user, call the createEthereumWallet method on your PrivyUser instance.

public protocol PrivyUser {
  // Other privy user methods

  /// Creates an embedded Ethereum wallet for the user.
  func createEthereumWallet(allowAdditional: Bool) async throws -> EmbeddedEthereumWallet
}

Field	Type	Description
allowAdditional	Bool	(Optional, Ethereum only) Ethereum embedded wallets are hierarchical deterministic (HD) wallets, and a user's seed entropy can support multiple separate embedded wallets. If a user already has a wallet and you'd like to create additional HD wallets for them, pass in true for the allowAdditional parameter. Defaults to false.

If a wallet is successfully created for the user, an EmbeddedEthereumWallet object is returned as an encapsulated value of Result.success.

This method will throw if:

• The user is not authenticated
• The user already has 9 or more wallets
• The network call to create the wallet fails
• The user already has an embedded wallet and allowAdditional is not set to true.

The Ethereum wallet

An EmbeddedEthereumWallet is defined as follows:

public protocol EmbeddedEthereumWallet {
 // The wallet's address
 var address: String { get }

 // Recovery method type
 var recoveryMethod: String? { get }

 // HD wallet index
 var hdWalletIndex: Int { get }

 // Chain type - in this case, ChainType.ethereum
 var chainType: ChainType { get }

 // A hook to an EmbeddedEthereumWalletProvider instance for this wallet
 var provider: EmbeddedEthereumWalletProvider { get }
}

Using the wallet

To enable your app to request signatures and transactions from the embedded wallet, Privy Ethereum embedded wallets expose a provider inspired by the EIP-1193 provider standard. This allows you request signatures and transactions from the wallet via a familiar JSON-RPC API (e.g. personal_sign).

Once you have an instance of an EmbeddedEthereumWallet, you can make RPC requests by using the provider: EmbeddedEthereumWalletProvider hook and using its request method. For example, wallet.provider.request(rpcRequest). This request method will suspend and await if the embedded wallet needs to wait for any internal ready state.

public protocol EmbeddedEthereumWalletProvider {
  // Sends a request to the Ethereum provider
  func request(_ request: EthereumRpcRequest) async throws -> String

  // Switch the active chain on this provider
  func switchChain(chainId: Int, rpcUrl: String?)
}

As a parameter to this method, to this method, pass an EthereumRpcRequest object that contains:

• method: the name of the JSON-RPC method for the wallet to execute (e.g. 'personal_sign')
• params: an array of parameters required by your specified method

By default, embedded wallets are connected to the Ethereum mainnet. To send a transaction on a different network, simply call the provider's switchChain method before the transaction request.

public struct EthereumRpcRequest(
  // Ethereum JSON RPC method, reference can be found in the [JSON RPC
  // API](https://ethereum.org/en/developers/docs/apis/json-rpc/).
  public let method: String,

  // Ethereum JSON RPC method params, param reference for each method can
  // be found in the [JSON RPC API]
  // (https://ethereum.org/en/developers/docs/apis/json-rpc/).
  public let params: [String]
)

Supported Ethereum JSON-RPC Methods

The following JSON-RPC methods are supported for the embedded wallet:

JSON-RPC Method	Supported?
personal_sign	✅
eth_sign	✅
eth_signTypedData_v4	✅
eth_signTransaction	✅
eth_sendTransaction	✅
eth_sendRawTransaction	✅
eth_accounts	✅
eth_chainId	✅

Retrieving a user's Ethereum wallets

To retrieve all of a user's EVM wallets:

1. Ensure the user is authenticated
2. Grab the user's embedded EVM wallets.

// check if user is authenticated
if let user = privy.user {
  // Retrieve list of user's embedded Ethereum wallets
  let ethereumWallets = user.embeddedEthereumWallets
  // Grab the desired wallet. Here, we retrieve the first wallet
  guard let ethereumWallet = ethereumWallets.first else {
    // No ETH wallets
    return
  }

  try await ethereumWallet.provider.request(EthereumRpcRequest(...))
}

HD Wallets

Ethereum embedded wallets are hierarchical deterministic (HD) wallets, and a user's seed entropy can support multiple separate embedded wallets.

WARNING

HD wallets are only supported on Ethereum. allowAdditional is not supported for Solana wallets.

Send a request with the new wallet

To send a request to an embedded wallet not at the 0-index, pass the desired wallet address as an optional second parameter to provider.request.

// Retrieve list of user's embedded Ethereum wallets
let ethereumWallets = user.embeddedEthereumWallets

// the target wallet here is looked up by it's position in the list,
// but you may choose to have some application state that includes
// it's address, and look it up that way
let wallet = wallets[1]

// Get RPC provider for wallet
let provider = wallet.provider

let response = try await provider.request(
    RpcRequest(
        method: "personal_sign",
        params: ["The message that is being signed", wallet.address]
    )
)