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.

Ecosystem Wallets support a variety of login methods:

• Email (OTP Login)
• Phone (OTP Login)
• Socials (Google, Apple, Facebook, Telegram, Farcaster, Line, Github, Twitch, Steam etc.)
• Custom Auth (OIDC Compatible)
• Custom Auth (Generic Auth Endpoint)
• Guest (Onboard easily, link other accounts later)
• Backend (Server Wallets)
• Siwe (Login with a seperate wallet supported by the SDK)
• SiweExternal (Login with an external wallet that only supports web using a browser loading a static thirdweb React page temporarily)

// 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);
// 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);
// Server Login
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Backend, walletSecret: "very-secret");
// Siwe
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.Siwe, siweSigner: anyExternalWallet);
// SiweExternal
var wallet = await EcosystemWallet.Create(client: client, ecosystemId: "ecosystem.my-ecosystem", authProvider: AuthProvider.SiweExternal);
 
// 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://"
);
 
// 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();
 
// Backend (Server Wallets)
var address = await wallet.LoginWithBackend();
 
// SIWE (Wallet)
var address = await siweWallet.LoginWithSiwe(chainId: 1);
 
// SiweExternal (React-only wallet)
var address = await wallet.LoginWithSiweExternal(
    // Windows console app example, adaptable to any runtime
    isMobile: false,
    browserOpenAction: (url) =>
    {
        var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
         _ = Process.Start(psi);
    },
    forceWalletIds: new List<string> { "io.metamask", "com.coinbase.wallet", "xyz.abs" }
);

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

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@email.com"); // 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.

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://"
);

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.

LoginWithSiwe: Initiate the login process by calling LoginWithSiwe on the EcosystemWallet instance. This will prompt the external wallet to sign a message instantly.

var address = await siweWallet.LoginWithSiwe(chainId: 1);

LoginWithSiweExternal: Initiate the login process by calling LoginWithSiweExternal on the EcosystemWallet instance. This will initiate a browser-based login flow for external wallets that only support web platforms.

var address = await wallet.LoginWithSiweExternal(
    // Windows console app example, adaptable to any runtime
    isMobile: false,
    browserOpenAction: (url) =>
    {
        var psi = new ProcessStartInfo { FileName = url, UseShellExecute = true };
        _ = Process.Start(psi);
    },
    forceWalletIds: new List<string> { "io.metamask", "com.coinbase.wallet", "xyz.abs" }
);

Note: The parameters are similar to the OAuth flow, with the addition of forceWalletIds to specify the wallet IDs to force the user to use. Using a single wallet id will skip the wallet selection screen and directly open the wallet.

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.

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);

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

List<LinkedAccount> linkedAccounts = await ecosystemWallet.GetLinkedAccounts();
List<LinkedAccount> linkedAccountsAfterUnlinking = await ecosystemWallet.UnlinkAccount(linkedAccounts[0]);