> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ & Troubleshooting

> Common questions and solutions for Sonar integration.

## Frequently Asked Questions

### Architecture & Responsibilities

<AccordionGroup>
  <Accordion title="Does Sonar handle auth/eligibility and my project provides the onchain sale contract?">
    **Yes, exactly.** Sonar handles:

    * KYC/KYB verification and accreditation checks
    * OAuth authentication and entity management
    * Eligibility determination and allowlist management
    * Signing purchase permits

    Your project handles:

    * Smart contract implementation (only if using a [custom contract](/sonar/integration-guides/custom-contracts))
    * Frontend user experience and wallet connection
    * Token economics, pricing, and vesting
  </Accordion>

  <Accordion title="How do purchase permits work and what's the recommended flow?">
    **Purchase Permit Flow:**

    1. **User authenticates** with Sonar via OAuth
    2. **Entity eligibility check**: your frontend calls Sonar API to verify the entity and wallet are eligible for the sale
    3. **Pre-purchase validation**: check if entity is ready to purchase (no liveness check needed, etc.)
    4. **Generate permit**: Sonar creates a signed permit
    5. **Contract call**: your frontend passes the permit to your contract's purchase function
    6. **Signature verification**: your contract verifies the permit was signed by Sonar's authorized signer

    **Key points:**

    * Permits are short-lived (10 minutes) for security
    * Include purchase limits (min/max purchase amounts)
    * Include price limits (min/max price - can beuseful when there is a dynamic pricing model, e.g. auctions)
    * Include payload (additional data from the Sonar backend - contact us if you need to use this)
    * Contain entity ID and wallet address binding
    * Prevent replay attacks with expiration and sale UUID
  </Accordion>

  <Accordion title="How should per-user caps/quotas be enforced?">
    **Purchase Limit Enforcement:**

    Sonar provides purchase limit data in purchase permits:

    * `maxAmount` - Maximum total this entity can purchase
    * `minAmount` - Minimum purchase amount required
    * `maxPrice` - Maximum price allowed (for auctions)
    * `minPrice` - Minimum price allowed (for auctions)

    **Your contract enforces these limits:**

    ```solidity theme={null}
    uint256 newTotal = entityState.amount + purchaseAmount;
    require(newTotal <= permit.maxAmount, "Exceeds purchase limit");
    require(newTotal >= permit.minAmount, "Below minimum");
    require(price <= permit.maxPrice, "Exceeds max price");
    require(price >= permit.minPrice, "Below min price");
    ```
  </Accordion>
</AccordionGroup>

### Technical Implementation

<AccordionGroup>
  <Accordion title="Do you have a frontend SDK or template?">
    **Yes!** We provide:

    **JavaScript Libraries:**

    * `@echoxyz/sonar-core` - Low-level API client
    * `@echoxyz/sonar-react` - React hooks and providers

    **Example Applications:**

    * [Next.js EVM example](https://github.com/sunrisedotdev/sonar-example-nextjs)
    * [React EVM example](https://github.com/sunrisedotdev/sonar-example-react)
    * [Next.js SVM example](https://github.com/sunrisedotdev/sonar-example-nextjs-svm)
    * [React SVM example](https://github.com/sunrisedotdev/sonar-example-react-svm)
    * Shows OAuth flow, entity checking, purchase flow
    * Wagmi integration for wallet connection
    * Error handling and edge cases

    **Integration Guides:**

    * [Frontend-Only Integration](/sonar/integration-guides/frontend-only) - Using our React hooks
    * [Frontend Integration Overview](/sonar/integration-guides/frontend-overview) - Complete purchase flow

    **Quick Start:**

    ```bash theme={null}
    npm install @echoxyz/sonar-core @echoxyz/sonar-react
    ```
  </Accordion>
</AccordionGroup>

## Common Issues & Solutions

### OAuth Integration

<AccordionGroup>
  <Accordion title="OAuth callback fails with 'invalid redirect URI'">
    **Solution:**

    1. Ensure redirect URI in your code exactly matches the one configured in Sonar dashboard
    2. Check for trailing slashes, http vs https, port numbers
    3. For localhost development, use exact port - `http://localhost:3000/oauth/callback`

    **Common mistakes:**

    * `http://localhost:3000/oauth/callback/` (trailing slash)
    * `https://localhost:3000/oauth/callback` (https instead of http)
    * Using `127.0.0.1` instead of `localhost`
  </Accordion>

  <Accordion title="Getting 'client not authorized' errors">
    **Check:**

    1. OAuth Client UUID is correct for your environment (staging vs production)
    2. Sale is approved and active in Sonar dashboard
    3. OAuth client has correct scopes configured
    4. Using correct API endpoints (staging vs production)

    **Scopes are configured in the dashboard based on your sale requirements:**

    * `read_entities` - Read entity information
    * `sale_eligibility_check` - Check purchase eligibility and generate permits
    * `contact_email` - Access user's contact email
  </Accordion>

  <Accordion title="OAuth tokens expire immediately">
    **Likely causes:**

    1. System clock drift - ensure your server/client has correct time
    2. Token storage issues - check localStorage/sessionStorage
    3. CORS issues preventing token storage
    4. Browser privacy settings blocking storage

    **Debug steps:**

    1. Check browser dev tools → Application → Local Storage
    2. Verify timestamps in JWT payload
    3. Test in incognito mode to rule out extensions
  </Accordion>
</AccordionGroup>

### Entity & Eligibility Issues

<AccordionGroup>
  <Accordion title="Entity shows as ineligible despite completing setup">
    **Check entity state:**

    1. Verify KYC/KYB is fully approved (not just submitted)
    2. Check if entity meets sale requirements (accreditation, jurisdiction, etc.)
    3. Verify sale configuration allows this entity type

    **Debug in Sonar dashboard:**

    1. Check entity compliance status
    2. Review sale configuration requirements
    3. Test with different entity types
  </Accordion>
</AccordionGroup>

### Purchase Flow Issues

<AccordionGroup>
  <Accordion title="Purchase permits expire before contract call">
    **Permits expire in 10 minutes for security.**

    **Solutions:**

    1. Generate permit immediately before contract call, not during page load
    2. Implement retry logic that regenerates permits on expiration
  </Accordion>

  <Accordion title="Wallet risk errors for legitimate addresses">
    **Wallet screening can flag addresses with minimal exposure to risky entities.**

    **Solutions:**

    1. Add specific addresses to `walletRiskAllowlist` in sale configuration
    2. Adjust `eligibilityMaxAllowedWalletRiskLevel` to `medium` or `high`
    3. User can try a different wallet address
    4. Contact support to review specific address flags

    **Prevention:**

    * Use fresh wallet addresses for token sales
    * Avoid addresses that received funds from exchanges or DeFi protocols
  </Accordion>
</AccordionGroup>

### Information to when contacting support

When contacting [support@echo.xyz](mailto:support@echo.xyz), include:

**Required:**

* Your Sale UUID
* Wallet addresses being tested
* Exact error messages from browser console

**Helpful:**

* Screenshots of error states
* Network tab showing API request/response
* Smart contract address (if deployed)
* Expected vs actual behavior

### Community Resources

* **Example Application** - [sonar-example-nextjs](https://github.com/sunrisedotdev/sonar-example-nextjs)
* **Integration Guides** - Start with [Getting Started](/sonar/getting-started)
* **API Reference** - [Sonar Core Documentation](/sonar/reference/sonar-core)

<Info>
  **Response Time** - We typically respond to integration questions within 24 hours during business days. For urgent production issues, mark your email as "URGENT" in the subject line.
</Info>