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

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.

​
Wallet linking

Wallets are linked to an entity implicitly. There is no separate “link wallet” step: a wallet becomes linked to the authenticated entity the first time you call generatePurchasePermit for it. The linking boundary works as follows:
  • New wallet, verified entity. When a verified entity generates a permit for a wallet that has never been associated with any entity, that wallet is auto-associated to the entity (as long as the entity is under its wallet allowance). It is not rejected.
  • Wallet already linked to another entity. A wallet that is already linked to a different entity is rejected. The offchain permit check acts as the first filter, and the SettlementSale contract enforces it onchain by reverting with WalletTiedToAnotherEntity.
  • Wallet allowance. Each entity can link up to maxWalletsPerEntity wallets — the default is 20. The limit is configurable on request. See maxWalletsPerEntity for details.

Eligibility and commitment limits are enforced per entity (tracked by SaleSpecificEntityID), never per wallet. A participant using multiple wallets shares a single entity-level limit, so extra wallets cannot be used to exceed it.

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

​
Entity Identifiers

Sonar uses two different entity identifiers to provide privacy isolation at different levels.

​
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

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