Skip to main content

​
Overview

Your frontend application orchestrates the complete purchase flow: user authentication, eligibility verification, and requesting purchase permits to pass to the contract. This section covers how to integrate Sonar’s APIs into your frontend application.

​
Frontend Integration Flow

​
Integration Components

​
Authentication Layer

  • OAuth 2.0 PKCE flow for secure user authentication
  • Token management with refresh handling

​
Entity Management

  • Wallet-to-entity mapping to identify which entity owns a wallet
  • Eligibility checking based on KYC/KYB completion and sale requirements
  • Setup state tracking to guide users through incomplete compliance steps

​
Purchase Orchestration

  • Pre-purchase validation to check readiness and requirements
  • Purchase permit generation with digital signatures
  • Liveness check handling for flagged entities

​
Integration Options

React Integration

Recommended for React projects
  • High-level hooks (useSonarAuth, useSonarEntity, useSonarPurchase)
  • Automatic state management and caching
  • Built-in error handling and loading states
  • TypeScript support with full type definitions
Best for: React, Next.js, Remix applications

Plain JavaScript

For non-React applications
  • Low-level API client with full control
  • Framework-agnostic implementation
  • Manual state management
  • Smaller bundle size
Best for: Vue, Svelte, vanilla JavaScript, or custom frameworks

Example Application

Complete implementation referenceSee a full Next.js application demonstrating:
  • Complete OAuth flow implementation
  • Entity status display with proper error handling
  • Purchase flow with permit generation
  • Contract integration with Wagmi
Best for: Understanding complete integration patterns

​
Implementation Requirements

​
OAuth Configuration

  • Valid OAuth client credentials from Sonar dashboard
  • Redirect URI configuration for your domain
  • Proper scope configuration for required permissions

​
Wallet Integration

  • Wallet connection library (Wagmi, RainbowKit, Web3Modal, etc.)
  • Address normalization for API calls
  • Connection state management

​
Security Considerations

  • Secure token storage (localStorage, secure cookies)
  • Permit expiration handling
  • API error response validation

​
Next Steps

Choose your integration approach based on your frontend framework:

React Applications

Start here if you’re using React, Next.js, or Remix

Other Frameworks

Use the core JavaScript library for Vue, Svelte, or vanilla JS

Smart Contract Integration

Learn how to implement purchase permit validation in your sale contract
⌘I