SocketFi Sign-Up Flow: Passkey Registration & Wallet

When a new user arrives at your application and authenticates for the first time, SocketFi does far more than create an account record. It simultaneously creates a passkey credential, deploys a smart wallet on-chain, binds the credential to that wallet, and returns a ready-to-use session — all from a single SDK call. The user never sees a seed phrase, a wallet address, or a blockchain configuration screen. From their perspective, they simply tapped Face ID and got in.

The Registration Flow

The complete sign-up process moves through five stages from the moment the user taps your sign-up button to the moment your application receives a session.

User Initiates Sign-Up

The user clicks your sign-up or “Get Started” button. Your application calls socketfi.authenticate(). SocketFi detects that no existing account is associated with the current device and begins the registration flow rather than the sign-in flow.

const session = await socketfi.authenticate();

That’s the only line of code your application needs. Everything else happens inside the SDK and SocketFi’s backend.

Passkey Created

SocketFi generates a cryptographic registration challenge and passes it to the browser’s WebAuthn API. The user’s authenticator (Face ID, Touch ID, Windows Hello, etc.) prompts the user for biometric or PIN confirmation, then generates a new public-private key pair.The private key is stored inside secure hardware and never transmitted. The public key and a signed registration response are returned to SocketFi for verification.

SocketFi Challenge
  ↓
Platform Authenticator (Face ID / Touch ID / Windows Hello / etc.)
  ↓
User Confirms (biometric or PIN)
  ↓
Key Pair Generated
  ├── Private Key → Secure Enclave / TPM / TEE (never leaves device)
  └── Public Key  → Returned to SocketFi

Credential Verified

SocketFi validates the registration response:

The challenge matches the one issued for this request
The attestation signature is cryptographically valid
The credential ID is unique and not already registered
The registration metadata passes integrity checks

Only credentials that pass all verification checks may proceed to wallet deployment. Any tampered or replayed registration response is rejected.

Wallet Deployed

With a verified credential in hand, SocketFi automatically deploys a smart wallet for the new user. This step is completely invisible to the user — no gas fee prompt, no wallet address to copy, no network selection.

Verified Credential
  ↓
Deploy Smart Wallet
  ↓
Generate Wallet Address
  ↓
Bind Passkey Credential to Wallet
  ↓
Wallet Active

The newly deployed wallet can immediately receive assets, interact with contracts, and authorize transactions. The passkey credential is stored as the wallet’s primary authorized signer.

Session Created

SocketFi issues a signed session and returns it to your application. The user is now authenticated and their wallet is immediately accessible.

// session is the return value of socketfi.authenticate()
{
  userProfile: {
    id: "usr_01HXYZ",
    username: "alice"
  },
  socketfiAccessToken: "eyJhbGciOiJFUzI1NiJ9..."
}

The Authentication Response

After a successful sign-up, socketfi.authenticate() resolves with a Session object:

const session = await socketfi.authenticate();

console.log(session.userProfile.id);          // "usr_01HXYZ"
console.log(session.socketfiAccessToken);     // "eyJhbGciOi..."

// Full Session type
interface Session {
  userProfile: {
    id: string;         // Stable user identifier — use this as your foreign key
    username?: string;  // Display name, if set during registration
  };
  socketfiAccessToken: string; // Signed JWT — include in Authorization: Bearer headers
}

Store the socketfiAccessToken and attach it to every request you make to your backend. Verify it server-side before granting access to any protected resource.

What the User Experiences

From the user’s perspective, the entire flow takes a few seconds:

Tap "Get Started"
  ↓
Face ID / Touch ID / Windows Hello prompt
  ↓
Biometric confirmation
  ↓
Inside the application

They never encounter:

A password field or confirmation box
A seed phrase or recovery key to copy down
A wallet address to save
A network or chain selection screen
A gas fee or transaction confirmation

The embedded wallet exists from this moment forward. Users can access it again later by simply re-authenticating — no import, no migration, no setup.

Wallet Ownership

The wallet created during sign-up belongs entirely to the user. SocketFi deploys and indexes it, but does not hold custody:

SocketFi does not own the wallet
SocketFi does not hold the user’s private keys
SocketFi does not control the assets inside the wallet

The passkey credential — stored on the user’s device — is the proof of ownership. Wallet access is only possible by producing a valid signature from that credential.

Error Handling

Not every sign-up attempt completes successfully. Handle these scenarios gracefully in your application:

try {
  const session = await socketfi.authenticate();
} catch (err) {
  if (err.code === "USER_CANCELLED") {
    // User dismissed the biometric prompt — allow retry
    showRetryButton();
  }
}

try {
  const session = await socketfi.authenticate();
} catch (err) {
  if (err.code === "AUTHENTICATION_FAILED") {
    // The registration response failed server-side validation
    showErrorMessage("Registration failed. Please try again.");
  }
}

Wallet deployment is idempotent. If a deployment fails partway through, retrying socketfi.authenticate() will not create a duplicate wallet.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

SocketFi Sign-Up Flow: Passkey Registration & Wallet

The Registration Flow

The Authentication Response

What the User Experiences

Wallet Ownership

Error Handling

​The Registration Flow

​The Authentication Response

​What the User Experiences

​Wallet Ownership

​Error Handling

The Registration Flow

The Authentication Response

What the User Experiences

Wallet Ownership

Error Handling