SocketFi SDK Setup: Install, Configure, and Verify

Before your users can authenticate or transact, you need a Client ID from the SocketFi Developer Portal and the right SDK package installed for your platform. This page walks through every step — from creating your application to confirming that authentication opens successfully in your browser.

Prerequisites

Make sure your environment meets these requirements before installing. Frontend applications

Requirement	Minimum version
React	18+
Next.js	14+ (if using Next.js)
React Native	0.76+
TypeScript	5+ (recommended)

Backend applications

Requirement	Minimum version
Node.js	20+
Package manager	npm, yarn, or pnpm

Supported backend frameworks include Express, Fastify, and NestJS. ESM modules are recommended for TypeScript projects.

Get a Client ID

Every SocketFi SDK call is authenticated against your application using a Client ID. You must create an application in the Developer Portal before initialising the SDK.

Create an account

Create an application

Click New Application, give it a name, and select your target network (TESTNET for development, MAINNET for production).

Copy your Client ID

Your Client ID looks like sf_live_xxxxxxxxxxxxxxxxx. Store it in an environment variable — never hardcode it in source.

Add allowed origins

Under Allowed Origins, add every domain your application runs on. Requests from any other origin will be rejected.

https://yourapp.com
https://www.yourapp.com
https://staging.yourapp.com

Your Client ID is not a secret, but it is tied to your allowed origins list. Any domain not on that list will receive an “Origin not allowed” error at runtime.

Install the SDKs

Install only the packages your project needs. Most applications use the React or React Native SDK on the frontend and the Server SDK on the backend.

React

npm install @socketfi/react

yarn add @socketfi/react

pnpm add @socketfi/react

React Native

npm install @socketfi/react-native

yarn add @socketfi/react-native

pnpm add @socketfi/react-native

Expo additional dependencies

If you’re using Expo, install these two packages as well. They provide the browser and deep-linking primitives that SocketFi uses for authentication and transaction approval flows.

npx expo install expo-web-browser expo-linking

Server SDK

npm install @socketfi/server

yarn add @socketfi/server

pnpm add @socketfi/server

Configure environment variables

Store your Client ID in an environment variable. The correct variable name depends on your build tool. Vite / Remix / most bundlers

VITE_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx

Next.js

NEXT_PUBLIC_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx

Expo / React Native

EXPO_PUBLIC_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx

Never store secrets (API keys, signing keys, or server-side tokens) in a VITE_, NEXT_PUBLIC_, or EXPO_PUBLIC_ variable. These values are bundled into your client code and are visible to anyone who inspects your JavaScript. Your Client ID is the only SocketFi value that belongs in a frontend environment variable.

Initialise the SDK

Create a single SocketFi instance and export it so every component in your application shares the same client.

React

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

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET", // use "MAINNET" for production
});

React Native

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

export const socketfi = new SocketFi({
  clientId: process.env.EXPO_PUBLIC_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
});

Server SDK

The Server SDK does not require initialisation. Import verifyAuth wherever you need to validate a SocketFi access token.

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

// In your route handler:
const auth = await verifyAuth(token);

Verify your installation

The quickest way to confirm everything is wired up correctly is to render a sign-in button and click it. A successful installation opens the SocketFi authentication popup.

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

export default function LoginButton() {
  return (
    <button onClick={() => socketfi.authenticate()}>
      Sign In
    </button>
  );
}

When you click Sign In:

The SocketFi hosted authentication popup opens.
The user completes registration or login with their passkey.
SocketFi resolves their wallet.
A session object is returned to your callback.

If the popup appears, your installation is complete.

Troubleshooting

Invalid Client ID

Error: Invalid Client ID

Double-check the value of your environment variable matches what the Developer Portal shows.
Confirm the application still exists and hasn’t been deleted or suspended.
Confirm the network value in your SDK config (TESTNET or MAINNET) matches the network your application was created on.

Origin Not Allowed

Error: Origin not allowed

Open the Developer Portal, navigate to your application, and check the Allowed Origins list.
Add the exact origin your app is running on (including protocol and port for local development, e.g. http://localhost:5173).
Save and retry — changes take effect immediately.

Browsers block popups that are not triggered by a direct user interaction. Never call authenticate() automatically on page load or inside a useEffect. Always invoke it from a click handler.

// ✅ Correct — triggered by user click
<button onClick={() => socketfi.authenticate()}>Sign In</button>

// ❌ Wrong — triggered on mount, will be blocked
useEffect(() => { socketfi.authenticate(); }, []);

Next steps

With the SDK installed and your first auth button working, continue to the Quick Start guide to build a complete authentication and transaction flow.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

SocketFi SDK Setup: Install, Configure, and Verify

Prerequisites

Get a Client ID

Install the SDKs

React

React Native

Expo additional dependencies

Server SDK

Configure environment variables

Initialise the SDK

React

React Native

Server SDK

Verify your installation

Troubleshooting

Invalid Client ID

Origin Not Allowed

Next steps

​Prerequisites

​Get a Client ID

​Install the SDKs

​React

​React Native

​Expo additional dependencies

​Server SDK

​Configure environment variables

​Initialise the SDK

​React

​React Native

​Server SDK

​Verify your installation

​Troubleshooting

​Invalid Client ID

​Origin Not Allowed

​Popup Blocked

​Next steps

Prerequisites

Get a Client ID

Install the SDKs

React

React Native

Expo additional dependencies

Server SDK

Configure environment variables

Initialise the SDK

React

React Native

Server SDK

Verify your installation

Troubleshooting

Invalid Client ID

Origin Not Allowed

Popup Blocked

Next steps