Skip to main content

​
Overview

Purchase permits are signed messages that authorize specific wallet addresses to purchase tokens for verified entities. They serve as the bridge between Sonar’s compliance verification and your onchain sale contract. Each permit proves that an entity has completed the required verification and is authorized to make a specific purchase with given funding bounds.

​
Permit Architecture

Permits are short-lived (10 minutes) to ensure fresh compliance status. Participants can use multiple permits during a sale (e.g., to update bids in an auction), but each permit expires quickly to maintain security.

​
Permit Structure

Sonar sets different fields in the permit based on your sale configuration: 
{
    saleSpecificEntityID: "0x1234567890abcdef1234567890abcdef",
    saleUUID: "0xabcdef1234567890abcdef1234567890",
    wallet: "0x742d35Cc6364C0532d0ef6b1234567890abcdef",
    expiresAt: 1704067200,
    minAmount: 1000000000,
    maxAmount: 10000000000,
    minPrice: 1000000000,
    maxPrice: 10000000000,
    opensAt: 1704060000,
    closesAt: 1704153600,
    payload: "0x"
}

​
Field Reference

FieldDescription
saleSpecificEntityIDSale-specific entity identifier. The same entity has different IDs across different sales for privacy.
saleUUIDYour sale’s unique identifier. The contract should verify this matches a hardcoded value.
walletThe authorized wallet address. The contract should verify this matches the transaction sender.
expiresAtUnix timestamp when the permit expires (10 minutes from issuance). The contract should verify this is in the future.
minAmountMinimum total commitment required from this entity. Set based on your sale’s commitment limits.
maxAmountMaximum total commitment allowed for this entity. Used to enforce whale caps and per-entity limits.
minPriceMinimum bid price allowed (for auctions). For fixed-price sales, this equals the sale price.
maxPriceMaximum bid price allowed (for auctions). For fixed-price sales, this equals the sale price.
opensAtUnix timestamp when the permit becomes valid (inclusive). Enables time-gated access windows.
closesAtUnix timestamp when the permit stops being valid (exclusive). The contract should verify the current time is within [opensAt, closesAt).
payloadAdditional data for custom logic (e.g., forced lockup preferences).
Limits are enforced at the entity level, not the wallet level. A participant using multiple wallets still has a single limit across all of them. Your contract should track commitments by saleSpecificEntityID and validate that the entity’s total stays within the min/max bounds.

​
Common Issues

Signature Verification Failures Most permit issues stem from signature verification problems:
  1. Wrong signer address: Ensure your contract has the correct Sonar signer address
  2. Struct encoding: Permit structure must exactly match Solidity definition
  3. Sale UUID mismatch: Verify your sale UUID matches exactly
Debug by logging the recovered signer address in your contract. Expiration Handling Permits expire in 10 minutes:
  1. Generate permits just-in-time: Don’t fetch permits during page load
  2. Implement retry logic: Regenerate expired permits automatically
  3. Handle expired permit errors gracefully: Provide clear retry options

​
See Also

Custom Contracts

Learn how to validate permits in your custom sale contract

Frontend Integration

Generate and use permits in your application

Entities

Understanding entities and why limits are per-entity