EcosystemWallet.Create

Create an instance of EcosystemWallet using a user's email, phone number or OAuth. This wallet type facilitates secure user authentication through OTP verification, making it suitable for client-facing applications where handling private keys directly is not ideal.

Login Methods

Ecosystem Wallets support a variety of login methods:

  • Email (OTP Login)
  • Phone (OTP Login)
  • Socials (Google, Apple, Facebook, Telegram, Farcaster, Line etc.)
  • SIWE (Sign-In with Ethereum)
  • Custom Auth (OIDC Compatible)
  • Custom Auth (Generic Auth Endpoint)
  • Guest (Onboard easily, link other accounts later)

Usage

// NOTE: All creation examples below may take in an `ecosystemPartnerId` if you are the ecosystem partner integrating with a third-party ecosystem
// Email
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", email: "userEmail");
// Phone
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", phoneNumber: "+1234567890");
// Google, Apple, Facebook, etc.
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Google);
// SIWE
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Siwe, siweSigner: anyExternalWallet);
// Custom Auth - JWT
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.JWT);
// Custom Auth - AuthEndpoint
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.AuthEndpoint);
// Guest Login
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Guest);
// Session resuming supported for all methods
var isConnected = await wallet.IsConnected();
// If not connected, initiate login flow based on the auth provider you are using
// Email & Phone (OTP)
await wallet.SendOTP(); // and fetch the otp
var address = await wallet.LoginWithOtp("userEnteredOTP"); // try catch and retry if needed
// Socials (OAuth)
var address = await wallet.LoginWithOauth(
// Windows console app example, adaptable to any runtime
isMobile: false,
browserOpenAction: (url) =>
{
var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
_ = Process.Start(psi);
},
mobileRedirectScheme: "myBundleId://"
);
// SIWE (Wallet)
var address = await siweWallet.LoginWithSiwe(chainId: 1);
// Custom Auth (JWT)
var address = await wallet.LoginWithCustomAuth(jwt: "myjwt");
// Custom Auth (AuthEndpoint)
var address = await wallet.LoginWithAuthEndpoint(payload: "mypayload");
// Guest Login (Easy onboarding)
var address = await wallet.LoginWithGuest();

OTP Authentication Flow

The OTP authentication flow involves sending an OTP to the user's email or phone and then verifying the OTP to complete authentication:

Send OTP: Initiate the login process by calling SendOTP on the EcosystemWallet instance. This sends an OTP to the user's email or phone number.

await wallet.SendOTP();

Submit OTP: Once the user receives the OTP, they submit it back to the application, which then calls LoginWithOtp on the EcosystemWallet instance to verify the OTP and complete the login process.

var address = await wallet.LoginWithOtp("userEnteredOTP");
// If this fails, feel free to catch and take in another OTP and retry the login process

Example

Here's an example of creating an EcosystemWallet with a user's email and completing the OTP authentication flow:

// Create EcosystemWallet wallet as signer to unlock web2 auth
var ecosystemWallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", email: "[email protected]"); // or email: null, phoneNumber: "+1234567890"
// Resume session (if `EcosystemWallet` wallet was not logged in)
if (!await ecosystemWallet.IsConnected())
{
await ecosystemWallet.SendOTP();
Console.WriteLine("Please submit the OTP.");
var otp = Console.ReadLine();
var ecosystemWalletAddress = await ecosystemWallet.LoginWithOtp(otp); // try catch and retry if needed
}
Console.WriteLine($"EcosystemWallet address: {await ecosystemWallet.GetAddress()}");
// Sign a message
var message = "Hello, Thirdweb!";
var signature = await wallet.PersonalSign(message);
Console.WriteLine($"Signature: {signature}");

Note: EcosystemWallet leverages the security of OTP-based authentication to ensure a secure and user-friendly experience in blockchain applications.

OAuth Authentication Flow

LoginWithOauth: Initiate the login process by calling LoginWithOauth on the EcosystemWallet instance. This redirects the user to the OAuth provider's login page.

// Windows console app example
var address = await ecosystemWallet.LoginWithOauth(
isMobile: false,
browserOpenAction: (url) =>
{
var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
_ = Process.Start(psi);
},
);
// Godot standalone example
var address = await ThirdwebManager.Instance.EcosystemWallet.LoginWithOauth(
isMobile: OS.GetName() == "Android" || OS.GetName() == "iOS",
browserOpenAction: (url) => OS.ShellOpen(url),
mobileRedirectScheme: "thirdweb://"
);

Example

Here's an example of creating an EcosystemWallet using OAuth.

// Create EcosystemWallet wallet as signer to unlock web2 auth
var ecosystemWallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Google);
// Resume session (if `EcosystemWallet` wallet was not logged in)
if (!await ecosystemWallet.IsConnected())
{
try {
var address = await ecosystemWallet.LoginWithOauth(
isMobile: false,
browserOpenAction: (url) =>
{
var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
_ = Process.Start(psi);
},
);
Console.WriteLine($"OAuth login successful. EcosystemWallet address: {address}");
} catch (Exception ex) {
Console.WriteLine($"OAuth login failed: {ex.Message}");
return;
}
}

Note: The LoginWithOauth API allows for custom browser handling, making it suitable for various application types and platforms.

Unified Identity - Account Linking

EcosystemWallet supports linking multiple authentication methods to a single user account. This feature enables users to access their account using different authentication methods, such as email, phone, or OAuth, without creating separate accounts for each method.

Linking Accounts

var ecosystemWalletMain = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Google);
if (!await ecosystemWalletMain.IsConnected())
{
_ = await ecosystemWalletMain.LoginWithOauth(
isMobile: false,
(url) =>
{
var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
_ = Process.Start(psi);
},
"thirdweb://",
new EcosystemWalletBrowser()
);
}
Console.WriteLine($"Main EcosystemWallet address: {await ecosystemWalletMain.GetAddress()}");
// Prepare Telegram
var socialWallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Telegram);
// Link Telegram
_ = await ecosystemWalletMain.LinkAccount(walletToLink: socialWallet,);
// Prepare Phone
var phoneWallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", phoneNumber: "+1234567890");
_ = await phoneWallet.SendOTP();
var otp = Console.ReadLine();
// Link Phone
_ = await ecosystemWalletMain.LinkAccount(walletToLink: phoneWallet, otp: otp);

Getting Linked Accounts

List<LinkedAccount> linkedAccounts = await ecosystemWalletMain.GetLinkedAccounts();