Wallet Creation: From Sign-Up to Active Smart Wallet

When a new user signs up through your application, SocketFi does not ask them to create a wallet. The wallet is created for them automatically as part of the authentication flow. A single SDK call — await socketfi.authenticate() — handles passkey registration, deploys a Soroban smart contract wallet, binds the credential to that wallet, and returns a session. By the time control returns to your application, the user already owns a fully functional non-custodial smart wallet with a stable CDXXXXX... address.

Creation Flow

Passkey Registration

The user’s device creates a WebAuthn credential during sign-up. Supported authenticators include Face ID, Touch ID, Windows Hello, Android Passkeys, and hardware security keys. Private key material never leaves the device — only the public credential is transmitted.

User device
  ↓
Create WebAuthn credential
  ↓
Return: Credential ID + Public Key + Attestation

Credential Verification

SocketFi verifies the WebAuthn registration response: challenge integrity, authenticator signature, and attestation data. Only verified credentials proceed to wallet deployment.

Verify challenge response
  ↓
Verify authenticator signature
  ↓
Accept registration

Smart Wallet Deployment

Once the credential is verified, SocketFi deploys a new Soroban smart contract wallet on the Stellar network. Each wallet is independent — users never share contracts.

Verified credential
  ↓
Deploy Soroban smart contract
  ↓
Generate stable wallet address: CDXXXXXXXXXX...

The wallet address is globally unique, permanent, and starts with CD. It never changes — not after credential rotation, not after account recovery.

Credential Binding

The verified passkey is bound to the deployed wallet as its primary authorization credential. Future wallet operations require a signature from this bound credential.

Wallet contract
  ↓
Bind primary passkey credential

Wallet Activation

The wallet is initialized with its default on-chain state and becomes active. The wallet can now receive assets, execute transactions, interact with Soroban contracts, and enforce policies.

Session Created

With the wallet active, SocketFi creates a session and returns it to your application. The user is authenticated and their wallet is immediately ready for use.

const session = await socketfi.authenticate();
// session.userProfile.id       → your user's identifier
// session.socketfiAccessToken  → session token for backend verification

The SDK Call That Does It All

From your application’s perspective, the entire six-step flow above is a single awaited call:

import { socketfi } from "./socketfi";

async function handleSignUp() {
  const session = await socketfi.authenticate();

  // For new users: passkey created, wallet deployed, session returned.
  // For returning users: passkey verified, existing wallet resolved, session returned.
  // Your code never needs to distinguish between the two.

  console.log("User ID:", session.userProfile.id);
  return session;
}

The same authenticate() call handles both new and returning users. For returning users it resolves the existing wallet rather than deploying a new one — your integration code is identical in both cases.

Default Wallet State

Every newly created wallet is initialized with the following on-chain state:

State Component	Purpose
Auth Credential	The bound passkey public key that authorizes wallet operations
Recovery Config	Pre-configured recovery state so account recovery is available from day one
Nonce State	Sequential nonce counter initialized at `0` to prevent replay attacks
Policy Config	Default policy set; can be extended with spending limits, contract restrictions, and more

Recovery is configured during wallet creation — not retroactively. This means every wallet supports account recovery from the moment it is activated, without requiring migration.

Wallet Address Properties

The wallet address assigned during deployment has four important properties:

Globally unique — no two wallets share an address
Persistent — the address never changes over the wallet’s lifetime
Chain-verifiable — anyone can inspect the wallet contract at that address on Stellar
Stable across updates — credential rotation and account recovery leave the address unchanged

You can safely treat the wallet address as the canonical identity for a user in your backend systems.

What Can Fail

Wallet creation can fail at several stages. Your application should handle these cases gracefully:

Failed passkey registration

The user declined the passkey prompt, the authenticator timed out, or the device does not support WebAuthn. Prompt the user to retry or check device compatibility.

Credential verification failure

The registration response did not pass server-side verification. This is rare and typically indicates a tampered response or network issue. Restart the registration flow.

Wallet deployment failure

The Soroban deployment transaction failed — usually due to a transient network condition. Retry after a brief delay; the deployment is idempotent if the credential was not already bound.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Wallet Creation: From Sign-Up to Active Smart Wallet

Creation Flow

The SDK Call That Does It All

Default Wallet State

Wallet Address Properties

What Can Fail

​Creation Flow

​The SDK Call That Does It All

​Default Wallet State

​Wallet Address Properties

​What Can Fail

Creation Flow

The SDK Call That Does It All

Default Wallet State

Wallet Address Properties

What Can Fail