SocketFi Quick Start: Auth, Wallets & Transactions

This guide walks through a complete SocketFi integration from scratch. By the time you reach the end, you will have a working React application that authenticates a user with their passkey, loads their embedded smart wallet, reads data from a Soroban contract, and requests a signed transaction — all without your user ever touching a seed phrase or external wallet.

This guide uses @socketfi/react. If you’re building for React Native, swap the import for @socketfi/react-native — the API is identical.

Install @socketfi/react

Add the React SDK to your project. If you haven’t already set up your Client ID and environment variables, complete the Installation guide first.

npm install @socketfi/react

yarn add @socketfi/react

pnpm add @socketfi/react

Add your Client ID to your environment file:

VITE_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx

Initialise the SocketFi client

Create a single shared SocketFi instance. Export it from a dedicated module so every part of your application uses the same client without re-initialising.

// lib/socketfi.ts
import { SocketFi } from "@socketfi/react";

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET", // switch to "MAINNET" before going live
});

You can optionally pass a brand object to customise the authentication popup with your app’s name and primary colour:

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
  brand: {
    appName: "Your App",
    primaryColor: "#2563eb",
  },
});

Authenticate a user

Call socketfi.authenticate() from a user interaction (a button click). SocketFi opens a secure hosted authentication flow where the user can sign in with an existing passkey or register a new one using Face ID, Touch ID, or Windows Hello.

// components/LoginButton.tsx
import { useState } from "react";
import { socketfi } from "../lib/socketfi";

export function LoginButton() {
  const [session, setSession] = useState(null);

  const handleLogin = async () => {
    try {
      const session = await socketfi.authenticate();
      setSession(session);
      console.log("Authenticated:", session.userProfile);
    } catch (error) {
      console.error("Authentication failed:", error);
    }
  };

  if (session) {
    return <p>Welcome, {session.userProfile.username}!</p>;
  }

  return <button onClick={handleLogin}>Continue</button>;
}

A successful call returns a session object:

{
  userProfile: {
    id: "usr_123",
    username: "alice"
  },
  socketfiAccessToken: "eyJhbGciOi..."
}

The socketfiAccessToken identifies the authenticated user. Store it (for example in React Context or localStorage) to use in subsequent API calls.

Always trigger authenticate() from a button click or equivalent user interaction. Calling it programmatically on page load will be blocked by browser popup policies.

Request a transaction

Once the user is authenticated, call requestTransaction() to propose an on-chain operation. SocketFi presents a hosted approval UI showing exactly what the transaction does before the user confirms and signs.

// After successful authentication
const result = await socketfi.requestTransaction({
  contractId: "CBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  method: "transfer",
  args: [recipientAddress, amount],
});

console.log("Transaction hash:", result.transactionHash);

A confirmed transaction returns:

{
  success: true,
  transactionHash: "abc123..."
}

Wrap every requestTransaction() call in a try/catch — users can decline the approval, and network errors can occur.

try {
  const result = await socketfi.requestTransaction({
    contractId,
    method: "transfer",
    args: [recipient, amount],
  });
  console.log("Success:", result.transactionHash);
} catch (error) {
  console.error("Transaction failed or declined:", error);
}

Read contract state

Read-only contract calls do not require user approval and execute immediately. Use readContract() to query any Soroban contract — for example to fetch a wallet balance before proposing a transfer.

const balance = await socketfi.readContract({
  contractId: "CBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  method: "balance",
  args: [walletAddress],
});

console.log("Balance:", balance);

Because readContract() doesn’t write to the chain, it’s safe to call at any point after initialisation — you don’t need a fully authenticated session for read-only data.

Verify authentication on your backend

Never rely on client-side state alone to gate access to protected resources. Always send the socketfiAccessToken to your API and verify it with the Server SDK. Frontend — attach the token to your request

const response = await fetch("/api/profile", {
  headers: {
    Authorization: `Bearer ${session.socketfiAccessToken}`,
  },
});

Backend — verify the token with verifyAuth()

import { verifyAuth } from "@socketfi/server";

app.get("/api/profile", async (req, res) => {
  const token = req.headers.authorization?.replace("Bearer ", "");

  const auth = await verifyAuth(token);

  if (!auth.valid) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  return res.json({
    user: auth.user,
    wallet: auth.wallet,
  });
});

verifyAuth() returns both the verified user identity and their associated wallet address, giving you a trustworthy, server-side source of truth for the current user.

Complete working example

Here’s a minimal but complete React component that ties every step together — login, transaction, and contract read.

// App.tsx
import { useState } from "react";
import { SocketFi } from "@socketfi/react";

const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
});

const CONTRACT_ID = "CBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

export default function App() {
  const [session, setSession] = useState(null);
  const [balance, setBalance] = useState(null);
  const [txHash, setTxHash] = useState(null);

  async function handleLogin() {
    try {
      const s = await socketfi.authenticate();
      setSession(s);

      // Read balance immediately after login
      const bal = await socketfi.readContract({
        contractId: CONTRACT_ID,
        method: "balance",
        args: [s.userProfile.id],
      });
      setBalance(bal);
    } catch (err) {
      console.error("Login failed:", err);
    }
  }

  async function handleTransfer() {
    try {
      const result = await socketfi.requestTransaction({
        contractId: CONTRACT_ID,
        method: "transfer",
        args: ["GDESTINATION_ADDRESS", "10"],
      });
      setTxHash(result.transactionHash);
    } catch (err) {
      console.error("Transaction failed:", err);
    }
  }

  if (!session) {
    return <button onClick={handleLogin}>Continue with Passkey</button>;
  }

  return (
    <div>
      <p>Welcome, {session.userProfile.username}</p>
      {balance !== null && <p>Balance: {balance}</p>}
      <button onClick={handleTransfer}>Send 10 Tokens</button>
      {txHash && <p>Sent! Tx: {txHash}</p>}
    </div>
  );
}

What to do next

You’ve now covered the full integration surface: installation, authentication, contract reads, transactions, and backend verification. From here:

Review the Production Checklist before switching to MAINNET
Explore the React SDK reference for the full API surface
Follow the integration guide for patterns like persistent sessions, loading states, and error boundaries

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

SocketFi Quick Start: Auth, Wallets & Transactions

Read contract state

Verify authentication on your backend

Complete working example

What to do next

​Read contract state

​Verify authentication on your backend

​Complete working example

​What to do next

Read contract state

Verify authentication on your backend

Complete working example

What to do next