SocketFi React SDK

Embedded wallet authentication and transaction approval for React applications.

Installation

npm install @socketfi/react

or

yarn add @socketfi/react

Overview

SocketFi SDK allows applications to integrate seamless embedded wallet authentication and transaction approval flows directly inside their app.

Features include:

• Embedded wallet authentication
• Passkey-based onboarding
• Hosted transaction approval
• React hooks and provider support
• Popup and redirect authentication flows
• Soroban/Stellar transaction support
• Minimal integration setup

Quick Start

1. Wrap Your App

import React from "react";
import ReactDOM from "react-dom/client";
import { SocketFiProvider } from "@socketfi/react";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <SocketFiProvider
    config={{
      clientId: "YOUR_CLIENT_ID",

      network: "TESTNET",

      brand: {
        appName: "My App",
        logo: "https://example.com/logo.png",
        primaryColor: "#2F0FD1",
      },

      onAuthSuccess(session) {
        console.log("Authenticated:", session);
      },

      onError(error) {
        console.error(error);
      },
    }}
  >
    <App />
  </SocketFiProvider>
);

Notes

• clientId is required.
• You can use a test clientId during local development and testing.
• brand configuration is optional.
• appName, logo, and primaryColor are used to customize the hosted authentication and transaction approval UI.
• network defaults to "PUBLIC" if not provided.

Using the SDK

Connect or Authenticate a Wallet

import { useSocketFi } from "@socketfi/react";

function Example() {
  const socketfi = useSocketFi();

  async function handleLogin() {
    const data = await socketfi.authenticate();

    console.log("session:", data.session);
    console.log("access token:", data.session.socketfiAccessToken);
    console.log("wallet:", data.session.address);
  }

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

Notes

• authenticate() opens the hosted SocketFi authentication popup.
• Users can either sign in to an existing wallet or create a new wallet directly through the popup flow.
• Successful authentication resolves with a SocketFiSession.
• The onAuthSuccess callback configured in SocketFiProvider also receives the authenticated session data.
• You can use either the returned promise result or the onAuthSuccess callback depending on your preferred integration flow.

Example using onAuthSuccess:

<SocketFiProvider
  config={{
    clientId: "YOUR_CLIENT_ID",

    onAuthSuccess(data) {
      console.log("Session:", data.session);
      console.log("access token:", data.session.socketfiAccessToken);
      console.log("wallet:", data.session.address);
    },
  }}
>
  <App />
</SocketFiProvider>

Transaction Submission and Approval

const result = await socketfi.requestTransaction({
  accessToken: session.accessToken,

  contractId: "CONTRACT_ID",

  callFunction: {
    name: "transfer",
  },

  argsXdr: [],

  feePreference: {
    asset: "asset-address",
    max: "10000000",
  },
});

console.log(result);

Notes

• requestTransaction() opens the hosted SocketFi transaction approval popup.
• Users review and approve the transaction directly through the hosted approval flow.
• Successful approval resolves with the transaction response data.
• The onTransactionSuccess callback configured in SocketFiProvider also receives the transaction result data.
• accessToken should be the authenticated SocketFi session access token.
• contractId is the target Soroban smart contract address.
• callFunction.name is the contract function to invoke.
• argsXdr should contain serialized Soroban contract arguments in XDR format.
• feePreference is optional.
• feePreference.asset specifies the asset address to use for fee payment.
• feePreference.max specifies the maximum fee the application allows to be charged for the transaction in stroops.
• If feePreference is not provided, the default wallet or application fee behavior is used. Fees may be deferred automatically or the transaction may fail if the maximum allowed deferred fee limit has been reached.
• USDC and XLM are currently guaranteed supported assets for transaction fee payment.
• Additional supported fee assets may be added in future updates.
• If an unsupported fee asset is provided in feePreference.asset, the transaction will fail during validation.

Example using onTransactionSuccess:

<SocketFiProvider
  config={{
    clientId: "YOUR_CLIENT_ID",

    onTransactionSuccess(result) {
      console.log("Transaction result:", result);
    },
  }}
>
  <App />
</SocketFiProvider>

React Hooks

useSocketFi

Returns the active SocketFi SDK instance.

const socketfi = useSocketFi();

useSocketFiState

Subscribe to SDK state updates.

const state = useSocketFiState(socketfi);

Available state:

{
  loading: boolean;
  error: string;
}

Provider Configuration

{
  clientId: string;

  network?: "PUBLIC" | "TESTNET";

  returnTo?: string;

  brand?: {
    appName?: string;
    logo?: string;
    primaryColor?: string;
  };

  onAuthSuccess?: (
    session: SocketFiSession
  ) => void;

  onError?: (
    error: Error
  ) => void;

  onTransactionSuccess?: (
    result: any
  ) => void;
}

Supported Environments

• React 18+
• React 19+
• Vite
• Next.js
• CRA
• TypeScript

Security Notes

SocketFi uses hosted authentication and transaction approval flows to help applications integrate secure embedded wallet onboarding without exposing sensitive signing logic directly inside client applications.

SocketFi validates authenticated sessions and access tokens before protected wallet actions and hosted transaction approvals are processed.

Links

• Website: https://socket.fi
• Documentation: https://docs.socket.fi