SocketFi React Integration Reference

A production-ready reference application demonstrating how to integrate the SocketFi Embedded Smart Account into a React application.

This repository showcases the complete end-to-end integration of the SocketFi React SDK and SocketFi Server SDK, including hosted authentication, hosted transaction approval, backend transaction preparation, Paymaster fee sponsorship, and Soroban transaction execution.

Whether you're building a DeFi application, marketplace, game, NFT platform, AI agent, fintech product, or consumer application, this project provides a production-ready foundation for integrating embedded smart wallets into your React applications.

✨ Features

🔐 Passkey-based authentication
👛 Embedded Soroban smart wallet
💸 Native XLM transfers
🪙 Stellar Asset Contract token transfers
✅ Hosted transaction approval
⚡ Automatic transaction submission
🧩 Backend transaction preparation using the SocketFi Server SDK
💰 Server-side Paymaster fee sponsorship
🔒 Backend-controlled transaction validation
⚛️ React + TypeScript
🚀 Soroban Testnet ready

Demo

The following demo showcases the complete authentication and token transfer experience using the SocketFi Embedded Wallet.

Application Preview

What You'll Learn

This reference application demonstrates how to:

Authenticate users using SocketFi Passkeys
Create embedded smart wallets
Transfer native XLM
Transfer Stellar Asset Contract tokens
Submit transactions directly using SocketFi
Submit transactions through your own backend Paymaster
Prepare Soroban transactions using the SocketFi Server SDK

Transaction Workflows

This example supports two different transaction workflows depending on your application's architecture.

1. `signAndSubmitTx()`

Recommended for most applications

The frontend requests transaction approval and SocketFi handles everything else.

Flow

User
   │
   ▼
React App
   │
   ▼
SocketFi SDK
   │
   ▼
Hosted Approval
   │
   ▼
User signs authorization
   │
   ▼
SocketFi submits transaction
   │
   ▼
Stellar Network

Responsibilities

SocketFi handles:

Wallet authorization
Transaction approval UI
Transaction submission
Fee sponsorship

Your application only needs to request approval.

This is the simplest integration and is recommended for applications that do not require custom backend transaction processing.

2. `signTx() + Backend Submission`

Recommended for production applications with backend infrastructure

The frontend requests wallet authorization only.

Your backend assembles the transaction, signs it with your Paymaster, and submits it to the network.

Flow

User
   │
   ▼
React App
   │
   ▼
SocketFi React SDK
   │
   ▼
Hosted Approval
   │
   ▼
Signed Authorization
   │
   ▼
Application Backend
   │
   ▼
SocketFi Server SDK
   │
   ▼
Prepare Transaction
   │
   ▼
Paymaster Signature
   │
   ▼
Submit Transaction
   │
   ▼
Stellar Network

Responsibilities

Frontend

Authenticate user
Request transaction approval
Receive signed authorization entries

Backend

Validate transaction parameters
Prepare the transaction using socketfi.prepareTransaction()
Sign the prepared transaction using the Paymaster
Submit the transaction to Stellar RPC

This approach keeps your Paymaster secret securely on your backend while allowing your backend to prepare and validate the transaction before sponsoring and submitting it.

Architecture

                    React Application
                           │
                           ▼
                  SocketFi React SDK
                           │
          ┌────────────────┴────────────────┐
          │                                 │
          ▼                                 ▼
 Hosted Authentication          Hosted Transaction Approval
          │                                 │
          └────────────────┬────────────────┘
                           ▼
                 Embedded Smart Wallet
                           │
                           ▼
                  Stellar Soroban Network

Getting Started

Clone the repository

git clone git@github.com:Socket-Fi/socketfi-react-integration-reference.git

cd socketfi-react-integration-reference

Install dependencies

npm install

npm run install:all

Configure Environment Variables

A preconfigured .env file is included for convenience and is ready to use with the demo.

If you need to customize the configuration (for example, to use your own SocketFi application or backend), update the following values:

# React Application

VITE_CLIENT_ID=YOUR_SOCKETFI_CLIENT_ID
VITE_NETWORK=TESTNET
VITE_SERVER_URL=http://localhost:4000

# Backend

APP_CLIENT_ID=YOUR_SOCKETFI_CLIENT_ID
APP_SECRET_KEY=YOUR_SOCKETFI_SECRET_KEY

PAYMASTER_SECRET_KEY=YOUR_PAYMASTER_SECRET_KEY

STELLAR_NETWORK=TESTNET
STELLAR_RPC_URL=https://soroban-testnet.stellar.org

To create your own Client ID and Secret Key, create a new application in the SocketFi Developer Console:

https://console.socket.fi

Start the whole application (frontend and server)

npm run dev

Project Structure

.
├── client
│   ├── src
│   │   ├── components
│   │   ├── hooks
│   │   ├── utils
│   │   └── App.tsx
│   └── package.json
│
├── server
│   ├── routes
│   ├── services
│   ├── index.ts
│   └── package.json
│
├── .env.example
└── README.md

Environment Variables

Variable	Description
`clientId`	SocketFi Client ID
`VITE_NETWORK`	`TESTNET` or `PUBLIC`
`VITE_SERVER_URL`	Backend server URL

SDK Overview

This reference application uses both SocketFi's React and Server SDKs.

React SDK

Authentication:

const session = await socketfi.authenticate();

Sign transaction authorization:

await socketfi.signTx(...);

Sign and submit:

await socketfi.signAndSubmitTx(...);

Server SDK

Validate and prepare a transaction for Paymaster signing:

const prepared = await socketfi.prepareTransaction({
  contractId,
  functionName,
  argsXdr,
  signedAuthEntriesXdr,
  paymasterPublicKey,
});

Authentication

Authentication uses SocketFi's hosted authentication experience.

Features include:

Passkey authentication
Embedded wallet creation
Secure session management
No browser extensions required
No seed phrases

After authentication, the SDK returns:

{
  address, socketfiAccessToken;
}

The access token is required for all protected wallet operations.

Token Transfers

This demo supports transferring:

Native XLM
Stellar Asset Contract Tokens

The application automatically builds the appropriate Soroban contract invocation before requesting user approval.

Fee Sponsorship

When using signAndSubmitTx(), transaction fees are sponsored automatically using the Paymaster configured for your SocketFi project.

When using signTx(), your backend is responsible for:

Receiving the transaction parameters and signed authorization entries
Preparing the transaction using socketfi.prepareTransaction()
Signing the prepared transaction with the Paymaster
Submitting the transaction to Stellar RPC

This keeps your Paymaster secret securely on your backend while allowing your application to validate and control every sponsored transaction.

Backend Transaction Preparation

The backend uses the SocketFi Server SDK to validate and prepare the transaction before signing it with the Paymaster.

By reconstructing the transaction from the original contract invocation parameters and the user-signed authorization entries, the SDK ensures the authorization is applied to the intended transaction before it is sponsored and submitted.

const prepared = await socketfi.prepareTransaction({
  contractId,
  functionName,
  argsXdr,
  signedAuthEntriesXdr,
  paymasterPublicKey: paymaster.publicKey(),
});

const tx = new StellarSdk.Transaction(
  prepared.transactionXdr,
  prepared.networkPassphrase
);

tx.sign(paymaster);

const server = new rpc.Server(RPC_URL);

await server.sendTransaction(tx);

The Server SDK automatically:

Builds the Soroban contract invocation
Injects the user-signed authorization entries
Simulates the transaction
Assembles the transaction
Returns a ready-to-sign transaction XDR

Why Two Transaction Flows?

SocketFi supports two workflows to accommodate different application architectures.

Workflow	Backend Required	Recommended For
`signAndSubmitTx()`	No	Most applications
`signTx()`	Yes	Production applications that require backend-controlled transaction preparation, validation, Paymaster sponsorship, and submission.

Customizing This Demo

You can easily extend this project to:

Call custom Soroban contracts
Read contract state
Add swaps
Build NFT applications
Integrate DeFi protocols
Add wallet guardians
Customize branding
Connect to Mainnet

Supported Stack

React 18+
React 19+
TypeScript
Vite
SocketFi React SDK v2
Soroban
Stellar Testnet

Resources

Developer Console
Create and manage your SocketFi applications, obtain Client IDs, configure branding, and manage your project settings.
https://console.socket.fi
Documentation
Integration guides, SDK documentation, API references, and tutorials.
https://docs.socket.fi
React SDK
https://www.npmjs.com/package/@socketfi/react
Server SDK
https://www.npmjs.com/package/@socketfi/server
Website
https://socket.fi

Who Is This For?

This reference project is ideal for developers building:

DeFi applications
NFT platforms
Wallets
Marketplaces
Consumer applications
AI agents
Fintech applications
Games
Soroban smart contract integrations

Next Steps

After exploring this example, consider:

Integrating your own backend Paymaster
Calling custom Soroban contracts
Reading contract state
Adding wallet guardians
Customizing the hosted authentication experience
Deploying to Stellar Mainnet

Contributing

Contributions, issues, and feature requests are welcome.

If you discover an issue or have suggestions for improving this reference implementation, feel free to open an issue or submit a pull request.

License

MIT

Learn More

🌐 Website: https://socket.fi
📚 Documentation: https://docs.socket.fi
📦 SDK: https://www.npmjs.com/package/@socketfi/react

Built with ❤️ using SocketFi, React, and Stellar Soroban.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
client		client
docs		docs
server		server
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

SocketFi React Integration Reference

✨ Features

Demo

Application Preview

What You'll Learn

Transaction Workflows

1. signAndSubmitTx()

Flow

Responsibilities

2. signTx() + Backend Submission

Flow

Responsibilities

Architecture

Getting Started

Clone the repository

Install dependencies

Configure Environment Variables

Start the whole application (frontend and server)

Project Structure

Environment Variables

SDK Overview

React SDK

Server SDK

Authentication

Token Transfers

Fee Sponsorship

Backend Transaction Preparation

Why Two Transaction Flows?

Customizing This Demo

Supported Stack

Resources

Who Is This For?

Next Steps

Contributing

License

Learn More

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. `signAndSubmitTx()`

2. `signTx() + Backend Submission`