Skip to main content

​
Overview

An entity represents the compliance identity that participates in token sales. Entities can be individuals or organizations that complete verification and maintain eligibility status for different sales. All purchase permits (and associated purchase limits) are tied to entities an entity and wallet.

​
User vs Entity vs Wallet

Sonar uses three distinct concepts that form a hierarchy: 
User → Entity → Wallet

User

Person with a Sonar account
  • Authenticates via OAuth
  • Can manage one or more entities

Entity

Compliance identity that participates in sales
  • Individual or organization
  • Completes KYC/KYB verification
  • Has eligibility status per sale

Wallet

Blockchain address linked to an entity
  • Used for actual purchases
  • Multiple wallets per entity allowed

​
How They Relate

A user is the person who logs in. After authentication, they can manage one or more entities. Each entity is a separate compliance identity with its own KYC/KYB verification. An entity can have multiple wallets linked to it for making purchases. Example: Alice has a personal entity for her own investments and also manages her company’s entity. Her personal entity has two wallets linked (one on Ethereum mainnet, one on Arbitrum). When participating in a sale, she selects which entity to use, then can purchase from any wallet linked to that entity.

See Entity Identifiers for details on the different ID types returned by the API.

​
Entity Lifecycle

Entities progress through verification to determine their ability to participate in token sales. All modifications to the entity are done through the Sonar platform, and the user should be redirected there if they need to make changes.

​
Setup States

Entities move through several setup states as they progress through verification on the Sonar platform. Each state represents a specific stage in the KYC/KYB journey. These are the possible setup states an entity may have:
StateValueDescription
Not Startednot-startedThe user has not started the setup process for the entity yet.
In Progressin-progressThe setup is in progress; the user should complete verification steps in the identity portal.
Ready For Reviewready-for-reviewThe user has submitted all required information; the entity is awaiting compliance review.
In Reviewin-reviewThe compliance team is currently reviewing submitted information.
CompletecompleteAll required compliance steps are finished and setup is complete.
FailurefailureThe setup failed due to issues the user can fix (for example, missing or invalid information).
Failure (Final)failure-finalThe setup failed due to issues the user cannot fix (for example, a compliance roadblock).
Technical Issuetechnical-issueThe setup process encountered a technical issue; users should contact support.
Note: Some setup states may require users to take specific actions, such as providing additional information or contacting support.

​
Sale-Specific Eligibility

Once verification is complete, entities are evaluated against each sale’s specific requirements, and is one of the following states:
StateValueDescription
EligibleeligibleThe entity meets all sale requirements, has verified jurisdiction compliance, possesses an adequate accreditation level, and is allowed to generate purchase permits.
Not Eligiblenot-eligibleThe entity does not meet sale requirements, such as having the wrong jurisdiction or accreditation, compliance issues have been identified, and purchase permits are blocked.
Unknownunknown-setup-incompleteSetup is incomplete or required information is missing, so eligibility cannot be determined. The entity must complete verification first.

​
Entity Identifiers

Sonar uses two different entity identifiers to provide privacy isolation at different levels.
IdentifierScopeStabilityUse Case
EntityIDPer OAuth clientStable across all sales for your projectAPI calls to Sonar backend
SaleSpecificEntityIDPer saleStable across all clients for a given saleOnchain operations and purchase permits

​
EntityID (Client-Scoped)

When a user authenticates with your project via OAuth, Sonar returns an EntityID that is unique to your OAuth client. This ID:
  • Remains the same regardless of which sale the entity participates in through your project
  • Is different from the EntityID that another project would see for the same entity
  • Should be used for all Sonar API calls (e.g., generatePurchasePermit, prePurchaseCheck)
This isolation means users cannot be correlated across different clients.

​
SaleSpecificEntityID (Sale-Scoped)

For onchain operations, Sonar provides a SaleSpecificEntityID that is unique to each sale. This ID:
  • Is included in purchase permits and recorded onchain by the sale contract
  • Remains the same for a given entity across all projects participating in the same sale
  • Is different for the same entity across different sales
This design prevents cross-sale tracking. An observer cannot determine that the same entity participated in multiple sales by comparing onchain data.

​
Which ID to use

OperationID to Use
Calling Sonar API endpointsEntityID
Reading commitment data from the contractSaleSpecificEntityID
Looking up allocations onchainSaleSpecificEntityID
Included in purchase permitsSaleSpecificEntityID

​
Testing Entity States

During development, you can use your test sales to simulate different entity states without completing actual verification. Test sales allow you to override setup state, eligibility status, and failure reasons to test how your integration handles various scenarios.