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

# Entities

> Understanding compliance entities and verification requirements.

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

<CardGroup cols={3}>
  <Card title="User" icon="user">
    **Person** with a Sonar account

    * Authenticates via OAuth
    * Can manage one or more entities
  </Card>

  <Card title="Entity" icon="id-card">
    **Compliance identity** that participates in sales

    * Individual or organization
    * Completes KYC/KYB verification
    * Has eligibility status per sale
  </Card>

  <Card title="Wallet" icon="wallet">
    **Blockchain address** linked to an entity

    * Used for actual purchases
    * Multiple wallets per entity allowed
  </Card>
</CardGroup>

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

<Info>
  <p>See [Entity Identifiers](#entity-identifiers) for details on the different ID types returned by the API.</p>
</Info>

## 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`](/sonar/core-features/purchase-permits) 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`](/sonar/reference/contracts/settlement-sale#deployment-defaults) for details.

<Info>
  <p>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.</p>
</Info>

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

| State            | Value              | Description                                                                                    |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| Not Started      | `not-started`      | The user has not started the setup process for the entity yet.                                 |
| In Progress      | `in-progress`      | The setup is in progress; the user should complete verification steps in the identity portal.  |
| Ready For Review | `ready-for-review` | The user has submitted all required information; the entity is awaiting compliance review.     |
| In Review        | `in-review`        | The compliance team is currently reviewing submitted information.                              |
| Complete         | `complete`         | All required compliance steps are finished and setup is complete.                              |
| Failure          | `failure`          | The setup failed due to issues the user can fix (for example, missing or invalid information). |
| Failure (Final)  | `failure-final`    | The setup failed due to issues the user cannot fix (for example, a compliance roadblock).      |
| Technical Issue  | `technical-issue`  | The 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:

| State        | Value                      | Description                                                                                                                                                                   |
| ------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Eligible     | `eligible`                 | The entity meets all sale requirements, has verified jurisdiction compliance, possesses an adequate accreditation level, and is allowed to generate purchase permits.         |
| Not Eligible | `not-eligible`             | The entity does not meet sale requirements, such as having the wrong jurisdiction or accreditation, compliance issues have been identified, and purchase permits are blocked. |
| Unknown      | `unknown-setup-incomplete` | Setup 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.

| Identifier               | Scope            | Stability                                  | Use Case                                |
| ------------------------ | ---------------- | ------------------------------------------ | --------------------------------------- |
| **EntityID**             | Per OAuth client | Stable across all sales for your project   | API calls to Sonar backend              |
| **SaleSpecificEntityID** | Per sale         | Stable across all clients for a given sale | Onchain 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

| Operation                                 | ID to Use              |
| ----------------------------------------- | ---------------------- |
| Calling Sonar API endpoints               | `EntityID`             |
| Reading commitment data from the contract | `SaleSpecificEntityID` |
| Looking up allocations onchain            | `SaleSpecificEntityID` |
| Included in purchase permits              | `SaleSpecificEntityID` |

## Testing Entity States

During development, you can use your [test sales](/sonar/core-features/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.