Skip to main content
This library provides higher level React hooks to abstract some of the state management for you. You will still need to use the @echoxyz/sonar-core library for some parts of the integration, and to import types.

​
Hooks

​
useSonarAuth

A hook to handle the OAuth flow for the user. Returns
FieldTypeDescription
authenticatedbooleanWhether the user is authenticated.
login() => voidRedirect the user to Sonar to login and authorize your application.
tokenstring | undefinedThe OAuth token for the user.
completeOAuth(args: { code: string; state: string }) => Promise<void>Call this in your OAuth callback handler to complete the OAuth flow and exchange the code for an access token.
logout() => voidCall this to logout the user.

​
useSonarClient

A hook to get a reference to the underlying SonarClient from the @echoxyz/sonar-core library. Returns
FieldTypeDescription
clientSonarClientThe underlying SonarClient.

​
useSonarEntity

A hook to fetch the state of a user’s Sonar entity based on their connected wallet address. Arguments
NameTypeDescription
saleUUIDstringThe UUID of the sale to get entity details for.
walletAddressstring | undefinedThe wallet address of the entity to get details for. It will only start loading once this is defined.
Returns
FieldTypeDescription
authenticatedbooleanWhether the user is authenticated.
loadingbooleanWhether the hook is loading.
entityEntityDetails | undefinedThe state of the user’s Sonar entity. This can be undefined even if the user is not authenticated - see note about 404 errors in readentity docs.
errorError | undefinedPopulated if the entity failed to load.

​
useSonarEntities

A hook to list all available entities for the authenticated user. Arguments
NameTypeDescription
saleUUIDstringThe UUID of the sale to list entities for.
Returns
FieldTypeDescription
authenticatedbooleanWhether the user is authenticated.
loadingbooleanWhether the hook is loading.
entitiesEntityDetails[] | undefinedThe state of the user’s Sonar entities.
errorError | undefinedPopulated if the entity failed to load.

​
useSonarPurchase

A hook to run pre-purchase checks and return functions required to complete the purchase flow. Arguments
NameTypeDescription
saleUUIDstringThe UUID of the sale to run pre-purchase checks against the entity for.
entityIDstringThe UUID of the entity to run pre-purchase checks for.
walletAddressstringThe wallet address of the entity to run pre-purchase checks for.
Returns
NameTypeDescription
loadingbooleanWhether the pre-purchase checks are loading.
readyToPurchasebooleanWhether the entity is ready to purchase.
errorError | undefinedPopulated if the pre-purchase checks failed to run.
failureReasonPrePurchaseFailureReason | undefinedPopulated if the entity is not ready to purchase.
livenessCheckURLstring | undefinedURL to link the user to so that they can complete a liveness check on the Sonar site. Populated if the failureReason is requires-liveness.
generatePurchasePermit() => Promise<GeneratePurchasePermitResponse> | undefinedFunction to generate a purchase permit to pass to the sale contract when purchasing tokens. Populated if the readyToPurchase is true.

​
useSonarProfile

A hook to fetch the authenticated user’s profile information. Returns
FieldTypeDescription
authenticatedbooleanWhether the user is authenticated.
loadingbooleanWhether the profile is loading.
profileMyProfileResponse | undefinedThe authenticated user’s profile containing their entity ID and email address.
errorError | undefinedPopulated if the profile failed to load.

​
useEntityInvestmentHistory

A hook to fetch the authenticated user’s investment history, showing all Echo private group investments they have participated in. This automatically fetches when the user is authenticated and resets when they log out. Returns
FieldTypeDescription
authenticatedbooleanWhether the user is authenticated.
loadingbooleanWhether the investment history is loading.
investmentHistoryEntityInvestmentHistoryResponse | undefinedThe user’s investment history containing an array of investments.
errorError | undefinedPopulated if the investment history failed to load.
Example 
import { useEntityInvestmentHistory } from '@echoxyz/sonar-react';

function InvestmentHistoryList() {
  const { loading, investmentHistory, error } = useEntityInvestmentHistory();

  if (loading) {
    return <div>Loading your investment history...</div>;
  }

  if (error) {
    return <div>Error loading investments: {error.message}</div>;
  }

  if (!investmentHistory?.Investments.length) {
    return <div>No investments yet</div>;
  }

  return (
    <div>
      <h2>Your Investment History</h2>
      <ul>
        {investmentHistory.Investments.map((investment, index) => (
          <li key={index}>
            <strong>{investment.CompanyName}</strong> - {investment.Round}
            <br />
            <small>
              Invested on: {new Date(investment.InvestedOn).toLocaleDateString()}
            </small>
          </li>
        ))}
      </ul>
    </div>
  );
}