> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# SocketFi SDK Setup: Install, Configure, and Verify

> Install @socketfi/react, @socketfi/react-native, or @socketfi/server, configure your Client ID, and verify your setup with a working auth button.

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.

<Steps>
  <Step title="Create an account">
    Sign up at [portal.socketfi.com](https://portal.socketfi.com) and confirm your email address.
  </Step>

  <Step title="Create an application">
    Click **New Application**, give it a name, and select your target network (TESTNET for development, MAINNET for production).
  </Step>

  <Step title="Copy your Client ID">
    Your Client ID looks like `sf_live_xxxxxxxxxxxxxxxxx`. Store it in an environment variable — never hardcode it in source.
  </Step>

  <Step title="Add allowed origins">
    Under **Allowed Origins**, add every domain your application runs on. Requests from any other origin will be rejected.

    ```text theme={null}
    https://yourapp.com
    https://www.yourapp.com
    https://staging.yourapp.com
    ```
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @socketfi/react
  ```

  ```bash yarn theme={null}
  yarn add @socketfi/react
  ```

  ```bash pnpm theme={null}
  pnpm add @socketfi/react
  ```
</CodeGroup>

### React Native

<CodeGroup>
  ```bash npm theme={null}
  npm install @socketfi/react-native
  ```

  ```bash yarn theme={null}
  yarn add @socketfi/react-native
  ```

  ```bash pnpm theme={null}
  pnpm add @socketfi/react-native
  ```
</CodeGroup>

#### 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.

```bash theme={null}
npx expo install expo-web-browser expo-linking
```

### Server SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @socketfi/server
  ```

  ```bash yarn theme={null}
  yarn add @socketfi/server
  ```

  ```bash pnpm theme={null}
  pnpm add @socketfi/server
  ```
</CodeGroup>

## Configure environment variables

Store your Client ID in an environment variable. The correct variable name depends on your build tool.

**Vite / Remix / most bundlers**

```env theme={null}
VITE_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx
```

**Next.js**

```env theme={null}
NEXT_PUBLIC_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx
```

**Expo / React Native**

```env theme={null}
EXPO_PUBLIC_SOCKETFI_CLIENT_ID=sf_live_xxxxxxxxxxxxxxxxx
```

<Note>
  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.
</Note>

## Initialise the SDK

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

### React

```ts theme={null}
// 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

```ts theme={null}
// 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.

```ts theme={null}
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.

```tsx theme={null}
// 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**:

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

If the popup appears, your installation is complete.

## Troubleshooting

### Invalid Client ID

```text theme={null}
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

```text theme={null}
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.

### Popup Blocked

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.

```tsx theme={null}
// ✅ 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](/getting-started/quickstart) to build a complete authentication and transaction flow.