Skip to main content

​
Frequently Asked Questions

​
Architecture & Responsibilities

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 for token sale logic
  • Frontend user experience and wallet connection
  • Token economics, pricing, and vesting
Allocation Enforcement:Sonar provides allocation data in purchase permits:
  • reservedAmount - Amount specifically reserved for this entity
  • maxAmount - Maximum total this entity can purchase
  • minAmount - Minimum purchase amount required
Your contract enforces these limits:
uint256 newTotal = entityState.amount + purchaseAmount;
require(newTotal <= permit.maxAmount, "Exceeds allocation");
require(newTotal >= permit.minAmount, "Below minimum");
Entity tracking prevents circumvention:
  • Each entity can only use limited wallet addresses (configurable)
  • Permits bind specific wallet addresses to entity UUIDs
  • Contract tracks total purchased amount per entity UUID

​
Technical Implementation

Yes! We provide:JavaScript Libraries:
  • @echoxyz/sonar-core - Low-level API client
  • @echoxyz/sonar-react - React hooks and providers
Example Applications:
  • Complete Next.js example
  • Shows OAuth flow, entity checking, purchase flow
  • Wagmi integration for wallet connection
  • Error handling and edge cases
Integration Guides:Quick Start:
npm install @echoxyz/sonar-core @echoxyz/sonar-react

​
Common Issues & Solutions

​
OAuth Integration

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
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
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

​
Entity & Eligibility Issues

This means the connected wallet isn’t linked to any entity on Sonar.Solutions:
  1. User needs to link wallet on Sonar
  2. User connected wrong wallet (different from one linked on Sonar)
  3. Entity setup is incomplete
Check entity state:
  1. Verify KYC/KYB is fully approved (not just submitted)
  2. Check if entity meets sale requirements (accreditation, jurisdiction, etc.)
  3. Ensure wallet address isn’t flagged for risk
  4. 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
Chainalysis 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

​
Purchase Flow Issues

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

​
Information to when contacting support

When contacting 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

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.
⌘I