Hooks

useEcho

Primary hook for accessing authentication state, user information, and core functionality.

import { useEcho } from '@merit-systems/echo-react-sdk';

function AuthComponent() {
  const {
    user,
    isAuthenticated,
    isLoading,
    error,
    signIn,
    signOut,
    token,
    getToken,
  } = useEcho();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error}</div>;
  }

  if (!isAuthenticated) {
    return <button onClick={signIn}>Sign In</button>;
  }

  return (
    <div>
      <p>Welcome {user?.name || user?.email}!</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

EchoContextValue

The context value provided by EchoProvider, accessible via useEcho().

import type { EchoContextValue } from '@merit-systems/echo-react-sdk';

EchoContextValue

Prop

Type

EchoUser

User information from OAuth2 authentication.

import type { EchoUser } from '@merit-systems/echo-react-sdk';

const { user } = useEcho();

EchoUser

Prop

Type

useEchoClient

Provides access to the Echo TypeScript SDK client for platform operations.

import { useEchoClient } from '@merit-systems/echo-react-sdk';

const echoClient = useEchoClient({
  apiUrl: 'https://echo.merit.systems',
});

// Access all TypeScript SDK functionality
const apps = await echoClient.apps.listEchoApps();
const balance = await echoClient.balance.getBalance();

useEchoClient provides a full Echo TypeScript SDK client instance, automatically authenticated using the current user's token.

Common operations:

echoClient.apps.* - App management
echoClient.balance.* - Balance operations
echoClient.payments.* - Payment links
echoClient.models.* - Model information
echoClient.users.* - User operations

useEchoModelProviders

Access LLM model providers for direct AI integration.

import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
import { generateText } from 'ai';

function AIComponent() {
  const { openai, anthropic } = useEchoModelProviders();

  const handleGenerate = async () => {
    const { text } = await generateText({
      model: openai('gpt-5'),
      prompt: 'Hello world',
    });

    return text;
  };

  return <button onClick={handleGenerate}>Generate</button>;
}

Balance Management

The useEcho hook provides balance management functionality:

const { balance, freeTierBalance, refreshBalance, createPaymentLink } =
  useEcho();

balance - Current account balance

<p>Balance: ${balance?.balance || 0}</p>
<p>Total Spent: ${balance?.totalSpent || 0}</p>

freeTierBalance - Free tier usage information

<p>Free Credits Remaining: ${freeTierBalance?.userSpendInfo.amountLeft || 0}</p>

refreshBalance() - Manually refresh balance data

<button onClick={refreshBalance}>Refresh Balance</button>

createPaymentLink() - Create Stripe payment links

const paymentUrl = await createPaymentLink(25, 'Credits', '/success');
window.location.href = paymentUrl;

Hooks

On this page