@sqds/grid-react

React hooks and components for Grid SDK - Build wallet applications with authentication, balance queries, and transactions.

Features

• Authentication Hooks: useEmailAuth, usePasskeyAuth with built-in OTP and session management
• Account Management: useAccount for real-time account state
• Balance Queries: useBalance (single token) and useBalances (all tokens with pagination)
• Transfers: useTransfer (send funds) and useTransfers (fetch history with filtering)
• React Context: GridProvider for SDK client management
• TypeScript: Full type safety with TypeScript support
• Browser Storage: Automatic session persistence with secure storage utilities

Installation

npm install @sqds/grid-react @sqds/grid

Peer Dependencies:

• react >= 16.8.0
• @solana/web3.js ^1.95.0

Quick Start

1. Setup Provider

Wrap your app in GridProvider with your API key:

import { GridProvider } from "@sqds/grid-react";

export default function App({ children }) {
  return (
    <GridProvider>
      {children}
    </GridProvider>
  );
}

Provider Options:

• apiKey - Your Grid API key
• environment - "sandbox" or "production" (default: "sandbox")
• baseUrl - Optional custom API URL
• solanaRpcUrl - Optional custom Solana RPC URL
• client - Or pass a pre-configured GridClient instance

2. Use Authentication

import { useEmailAuth } from "@sqds/grid-react";

function Auth() {
  const {
    requestOtp,
    verifyOtp,
    logout,
    user,
    account,
    isAuthenticated,
    isLoading,
    error
  } = useEmailAuth();

  const handleLogin = async () => {
    try {
      await requestOtp("[email protected]");
      const code = prompt("Enter OTP code:");
      await verifyOtp(code);
    } catch (err) {
      console.error("Login failed:", err);
    }
  };

  if (isAuthenticated) {
    return (
      <div>
        <p>Signed in as {user?.data.email}</p>
        <p>Account: {account?.address}</p>
        <button onClick={logout}>Logout</button>
      </div>
    );
  }

  return (
    <button onClick={handleLogin} disabled={isLoading}>
      {isLoading ? "Loading..." : "Sign In"}
    </button>
  );
}

3. Query Balances and Send Transfers

import { useBalance, useTransfer } from "@sqds/grid-react";

function Wallet() {
  const { balance, isLoading, refetch } = useBalance({ symbol: "USDC" });
  const { transfer, isTransferring, signature, error } = useTransfer();

  const handleSend = async () => {
    await transfer({
      to: "recipient_address",
      amount: "1000000",
      currency: "usdc"
    });
    refetch();
  };

  return (
    <div>
      <p>{balance?.amount_decimal || "0"} USDC</p>
      <button onClick={handleSend} disabled={isTransferring}>
        {isTransferring ? "Sending..." : "Send 1 USDC"}
      </button>
      {signature && <p>Transaction: {signature}</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

API Reference

Authentication

useEmailAuth()

Email + OTP authentication with automatic session management.

const {
  requestOtp,
  verifyOtp,
  logout,
  user,
  account,
  isAuthenticated,
  isLoading,
  error
} = useEmailAuth();

Methods:

• requestOtp(email: string) - Send OTP code to email
• verifyOtp(code: string) - Verify OTP and create session
• logout() - Clear session and sign out

State:

• user - User account data
• account - Smart account address and details
• isAuthenticated - Boolean authentication status
• isLoading - Loading state for async operations
• error - Error object if operation failed

usePasskeyAuth()

WebAuthn passkey authentication for passwordless login.

const {
  createAccount,
  authenticate,
  logout,
  passkeyAccount,
  isAuthenticated,
  hasPasskeySupport,
  sessionStatus,
  isLoading,
  error
} = usePasskeyAuth();

Methods:

• createAccount(params) - Create new passkey account
• authenticate(params) - Sign in with existing passkey
• refreshSession() - Refresh expired session
• logout() - Clear passkey session

State:

• passkeyAccount - Passkey account data with smart account
• sessionKey - Session key for signing transactions
• hasPasskeySupport - Browser passkey support detection
• sessionStatus - "active" | "needs_refresh" | "expired" | "unauthenticated"

Account Management

useAccount()

Real-time account state management.

const { account, isLoading, error } = useAccount();

Returns the current authenticated account with automatic updates.

Balance Queries

useBalance(options)

Fetch a single token balance.

const { balance, isLoading, error, refetch } = useBalance({
  symbol: "USDC",
  accountAddress: "optional_address"
});

Options:

• symbol - Token symbol (e.g., "USDC", "SOL")
• accountAddress - Optional account address (defaults to authenticated account)

useBalances(options)

Fetch all token balances with pagination.

const {
  balances,
  isLoading,
  error,
  refetch,
  pagination
} = useBalances({
  queryParams: { limit: 10, page: 1 },
  refetchOnWindowFocus: true,
  staleTime: 10000
});

Options:

• accountAddress - Optional account address
• queryParams - Pagination params (limit, page)
• enabled - Enable/disable auto-fetching (default: true)
• refetchOnWindowFocus - Refetch on window focus (default: false)
• staleTime - Cache duration in ms (default: 10000)

Transfers

useTransfer()

Send funds via Solana blockchain.

const {
  transfer,
  isTransferring,
  signature,
  error
} = useTransfer();

await transfer({
  to: "recipient_address",
  amount: "1000000",
  currency: "usdc"
});

Transfer Options:

• to - Recipient address
• amount - Amount in smallest unit (e.g., lamports for SOL)
• currency - Token symbol ("usdc", "sol", etc.)

useTransfers(options)

Fetch transfer history with filtering and pagination.

const {
  transfers,
  isLoading,
  error,
  refetch,
  hasMore,
  fetchMore
} = useTransfers({
  payment_rail: "solana",
  state: "completed",
  limit: 25,
  staleTime: 30000
});

Options:

• accountAddress - Optional account address
• payment_rail - Filter by rail: "ach" | "wire" | "sepa" | "swift" | "solana"
• state - Filter by state: "pending" | "completed" | "failed" | "cancelled"
• limit - Results per page (default: 25)
• enabled - Enable auto-fetching (default: true)
• refetchOnWindowFocus - Refetch on focus (default: false)
• staleTime - Cache duration in ms (default: 30000)

Context

useGrid()

Access the Grid SDK client directly.

import { useGrid } from "@sqds/grid-react";

function Component() {
  const { client } = useGrid();

  const result = await client.someMethod();
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  EmailAuthState,
  PasskeyAuthState,
  UseBalanceResult,
  UseTransfersOptions,
  TransferOptions
} from "@sqds/grid-react";

Links

• Documentation: docs.sqds.io
• Core SDK: @sqds/grid

License

MIT