Skip to main content
This page answers the questions developers and product teams ask most often when evaluating or integrating SocketFi. If you’re looking for step-by-step code, check the Examples section. If something isn’t working, see Troubleshooting.

​
General

SocketFi is an embedded smart wallet platform that lets you add passkey-powered blockchain functionality to any application. Users authenticate with their device biometrics (Face ID, Touch ID, Windows Hello) and immediately get access to a smart wallet on Stellar/Soroban — no seed phrases, no wallet app to install, no blockchain knowledge required.You integrate SocketFi by calling three SDK methods: authenticate(), requestTransaction(), and readContract(). Your users never see a public key or a gas fee selector.
No. SocketFi is non-custodial. Users retain ownership and control of their wallets and assets. SocketFi provides the infrastructure and wallet technology, but it never holds or controls user funds. Wallet ownership is tied to the user’s passkey credential, not to SocketFi’s servers.
SocketFi is built on Stellar and Soroban (Stellar’s smart contract platform). Smart wallets are deployed as Soroban contracts, and all on-chain activity — transfers, contract reads, governance votes, staking — happens on the Stellar network.
SocketFi is a good fit for any application that wants to add wallet functionality without exposing blockchain complexity to users. Common use cases include fintech apps, consumer marketplaces, games with in-game economies, social platforms, rewards programs, DeFi front-ends, and enterprise platforms.It is specifically designed to help Web2 products enter Web3 without forcing users through a traditional crypto wallet onboarding flow.
No. SocketFi handles wallet and authentication infrastructure. Your backend continues to manage business logic, user preferences, application data, and anything else specific to your product. The two systems integrate through the @socketfi/server SDK, which your backend uses to verify SocketFi access tokens.

​
Authentication

Calling socketfi.authenticate() opens a SocketFi-hosted authentication flow. The user is prompted to authenticate with a passkey (Face ID, Touch ID, Windows Hello, or a hardware security key). SocketFi then:
  • Verifies the credential
  • Creates or loads the user’s smart wallet
  • Returns an AuthSession containing a socketfiAccessToken and userProfile with the wallet address
New users are automatically registered on their first call. Existing users are signed in. Your application doesn’t need separate sign-up and sign-in buttons.
Passkeys are a modern authentication standard (built on WebAuthn/FIDO2) that replaces passwords with device-native biometrics or security keys. Instead of typing a password, users authenticate the same way they unlock their phone or laptop.Common passkey mechanisms include Face ID, Touch ID, Windows Hello, and hardware security keys. Passkeys are phishing-resistant and tied to a specific domain, which makes them significantly more secure than passwords.
Yes. When a new user authenticates for the first time, SocketFi creates a Soroban smart wallet for them as part of the onboarding flow. When an existing user authenticates, SocketFi loads their existing wallet. The wallet address never changes between sessions.
Sessions expire according to the access token’s policy. When a token expires, subsequent API calls to your backend will return 401 Unauthorized. Your application should detect this and prompt the user to re-authenticate with socketfi.authenticate(). The user will get a new session without losing any wallet data or assets.
Yes. Store the AuthSession object (which includes the socketfiAccessToken) in localStorage (web) or secure device storage (React Native / Expo). Restore it on app startup so users don’t have to re-authenticate on every visit. See the React Authentication example for the recommended AuthProvider implementation.
No. Logging out only clears the local session state. The user’s smart wallet, address, and all assets remain completely intact on-chain. When the user logs back in with the same passkey, they get the same wallet with the same balance.

​
Smart Wallets

A smart wallet is a blockchain account implemented as a Soroban smart contract rather than a simple key pair. Unlike traditional wallets, smart wallets support programmable features including custom authorization logic, spending policies, account recovery without seed phrases, and credential rotation (migrating to a new passkey without changing your wallet address).
No. Each user gets a stable wallet address that never changes. Authentication, credential rotation, and account recovery all preserve the same wallet address. Assets you send to a user’s wallet address today will still be in the same place after they rotate their credential or recover their account.
Smart wallets on Stellar/Soroban can hold XLM (Stellar’s native asset), Soroban tokens (including USDC and other stablecoins), NFTs, DeFi positions, and other assets deployed on the Stellar network.
Yes. Use requestTransaction() to initiate token transfers. The user sees a hosted approval screen showing the recipient, amount, and fees before signing with their passkey. Your application can also display a wallet address so other users or services can send assets to it directly.

​
Transactions

Yes — all state-changing blockchain operations require explicit user approval. When you call requestTransaction(), SocketFi opens a hosted approval screen where the user reviews the contract address, method, arguments, and fees before signing with their passkey. Read-only operations via readContract() do not require any approval.
The SDK throws an error with code TRANSACTION_REJECTED or USER_CANCELLED. Your application should catch this error and treat it as a normal user action — show a neutral message and allow the user to retry. Do not log it as an application error.
Fee handling depends on your application and wallet configuration. SocketFi smart wallets support fee abstraction, meaning your application can sponsor fees so users never need to hold XLM just to pay for gas. Consult your SocketFi project configuration and the Soroban documentation for specifics.
A POLICY_VIOLATION error means the requested transaction was blocked by a spending policy configured on the smart wallet — for example, a per-transaction spending limit was exceeded. Check the policy configuration for your application and explain the restriction to the user.

​
Recovery

Users can initiate account recovery to restore access to their wallet. The recovery flow verifies the user’s identity through a configurable process and then updates the smart wallet’s authentication credentials to a new passkey — all without changing the wallet address or affecting any assets.
No. Assets are stored on-chain in the smart wallet contract, not on the device. If a user loses their device, their wallet address and all assets are preserved. Once they complete account recovery, they regain full access to their wallet with a new passkey.
No. Recovery updates the authentication credential while preserving the existing wallet address, assets, and ownership. After recovery, the user authenticates with their new passkey and accesses the same wallet they had before.
Credential rotation lets a user replace their current passkey with a new one while they still have access to the old one — for example, when getting a new device or upgrading to a hardware security key. Unlike recovery, rotation doesn’t require identity re-verification because the user can prove ownership with their existing credential. The wallet address and assets remain unchanged.

​
Security

Yes. SocketFi is designed for production applications. Authentication is built on the WebAuthn/FIDO2 standard, which is phishing-resistant and backed by device hardware. Smart wallets support programmable policies and on-chain authorization rules. Backend verification through verifyAuth() ensures your server never trusts unverified client-provided identity.Follow the security practices described throughout this documentation — especially server-side token verification and HTTPS — and SocketFi provides a strong security foundation.
WebAuthn (the standard underlying passkeys) will only operate in a secure context — meaning the page must be served over HTTPS (or localhost for development). If your application is served over plain HTTP in production, passkey authentication will fail entirely.Always deploy your frontend behind TLS. This also protects the Authorization: Bearer tokens your frontend sends to your backend from being intercepted in transit.
Always. The socketfiAccessToken your frontend receives must be verified server-side with verifyAuth() before you trust any identity claim. Never accept wallet addresses, user IDs, or any other identity information sent directly from the client — always derive them from the verified token result.
clearKeyCache() is a utility exported by @socketfi/server that flushes the internal public key cache. The server SDK caches keys to avoid repeated network lookups on every verifyAuth() call — in normal production use you never need to touch this cache.The function is useful when writing automated tests: call it in a beforeEach or afterAll hook to ensure each test starts with a fresh key fetch rather than cached state.