Skip to main content
This guide covers the breaking changes introduced when migrating from the pre‑1.0 Unity SDK to v1.0.
The v1.0 SDK introduces several public API and ABI changes, including renamed types, renamed methods, and new async patterns. This guide focuses on the most common changes your app will encounter.

​
Initialization and readiness

​
What changed

  • PrivyManager.Initialize(...) now returns an IPrivy instance immediately and begins initialization in the background.
  • v1.0 removes the PrivyManager.AwaitReady() method.
  • The SDK now ensures readiness when your app calls GetAuthState() or GetUser().

​
Migration

Old (pre‑1.0): 
PrivyManager.Initialize(config);
await PrivyManager.AwaitReady();
New (v1.0): 
var privy = PrivyManager.Initialize(config);
// Awaiting GetAuthState/GetUser ensures the SDK is fully initialized.
var authState = await privy.GetAuthState();

​
IPrivy API changes (user and auth access)

​
User access

  • v1.0 removes the User property.
  • Your app should call await privy.GetUser() instead.
Old (pre‑1.0): 
PrivyUser user = PrivyManager.Instance.User;
New (v1.0): 
IPrivyUser user = await PrivyManager.Instance.GetUser();

​
Auth state

  • v1.0 removes the AuthState property.
  • Your app should call await privy.GetAuthState() instead.

​
Auth state change callback

  • v1.0 removes the SetAuthStateChangeCallback(...) method.
  • Your app should subscribe to the AuthStateChanged event instead.
Old: 
PrivyManager.Instance.SetAuthStateChangeCallback(state => {
    // handle state
});
New: 
PrivyManager.Instance.AuthStateChanged += state => {
    // handle state
};

​
Namespace and type relocations

Many public types now live in more specific namespaces to reduce collisions and improve discoverability.
Old namespaceNew namespaceNotes
PrivyPrivy.CoreIPrivy, PrivyManager
PrivyPrivy.ConfigPrivyConfig
PrivyPrivy.Auth / Privy.Auth.ModelsAuth APIs, IPrivyUser, AuthState
PrivyPrivy.WalletsEmbedded wallet APIs
PrivyPrivy.UtilsExceptions, logging, utilities
Update using statements or fully‑qualify types when migrating.

​
Embedded wallet API changes

​
Wallet collection property

  • v1.0 renames EmbeddedWallets to EmbeddedEthereumWallets (the old name is now marked [Obsolete]).

​
Wallet creation methods

OldNew
CreateWallet(...)CreateEthereumWallet(...)
CreateWalletAtHdIndex(...)CreateEthereumWalletAtHdIndex(...)
(new)CreateSolanaWallet(...)

​
RPC provider interface

  • v1.0 removes IRpcProvider.
  • Your app should use IEmbeddedEthereumWalletProvider (in Privy.Wallets) instead.

​
Example (signing a message)

Old: 
IEmbeddedEthereumWallet wallet = await user.CreateWallet();
var response = await wallet.RpcProvider.Request(rpcRequest);
New: 
IEmbeddedEthereumWallet wallet = await user.CreateEthereumWallet();
var response = await wallet.RpcProvider.Request(rpcRequest);

​
Exception type changes

v1.0 refactors the exception hierarchy and moves exceptions to Privy.Utils.
OldNew
PrivyException.AuthenticationExceptionPrivyAuthenticationException
PrivyException.EmbeddedWalletExceptionPrivyWalletException
Example: 
try {
    // ...
} catch (PrivyAuthenticationException ex) {
    // handle auth error
} catch (PrivyWalletException ex) {
    // handle wallet error
}

​
Configuration object changes

PrivyConfig now uses auto-properties and lives in Privy.Config. Old: 
var config = new PrivyConfig {
    AppId = "...",
    ClientId = "...",
    LogLevel = PrivyLogLevel.NONE
};
New: 
using Privy.Config;

var config = new PrivyConfig {
    AppId = "...",
    ClientId = "...",
    LogLevel = PrivyLogLevel.None
};

​
Quick migration checklist

  1. Update using statements to reference the new namespaces (e.g. Privy.Core, Privy.Auth, Privy.Wallets, Privy.Utils).
  2. Replace await PrivyManager.AwaitReady() with await PrivyManager.Instance.GetAuthState() or await PrivyManager.Instance.GetUser().
  3. Replace PrivyManager.Instance.User with await PrivyManager.Instance.GetUser().
  4. Replace SetAuthStateChangeCallback(...) with AuthStateChanged += ....
  5. Replace embedded wallet API calls using CreateWallet / EmbeddedWallets with CreateEthereumWallet / EmbeddedEthereumWallets (and optionally CreateSolanaWallet).
  6. Update exception handling to catch PrivyAuthenticationException and PrivyWalletException.
For compilation errors after upgrading, search for old types in the project (e.g. IPrivyManager, IRpcProvider, PrivyException.AuthenticationException) and update them as described above. See the Unity SDK setup guide and the Unity changelog for additional reference.