> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

Identity verification and compliance is scoped to a wallet's **entity**: the user or organization the wallet is for. Products that require KYC or KYB read a wallet's entity to determine whether the person or business behind it is verified. A wallet's entity is immutable once set.

The `entity` field is distinct from the `owner` field:

| Field      | What it means                                                                                                       | Permanence                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| **Owner**  | Who can configure and authorize actions from the wallet. May be a user, authorization key, or key quorum.           | Mutable with an authorization signature |
| **Entity** | Who the wallet is for. May be a [user](/user-management/users/overview) or [organization](/organizations/overview). | Immutable once set                      |

A wallet owned by an authorization key still needs an entity to participate in a regulated flow, because the authorization key is not a verified person or business.

## Where entities are required

To participate in a regulated flow, a wallet must have an `entity` set:

* [Fiat deposits](/wallets/funding/fiat-deposits/overview)
* [Fiat payouts](/financial-flows/transfers/fiat-payouts/overview)

If a wallet has no entity, or its entity has not completed [KYC](/kyc-kyb/kyc) or [KYB](/kyc-kyb/kyb), these requests fail.

## Automatically assigned entities

Wallets created for a user are assigned to that user automatically:

* Wallets created alongside the user, through `POST /v1/users`
* Wallets created for an existing user, through `POST /v1/users/{user_id}/wallets`, including wallets created at login
* Wallets created through Privy's client-side SDKs, which are always created for the authenticated user
* Wallets created through `POST /v1/wallets` using that user's access token, when `entity` is omitted

Wallets created through `POST /v1/wallets` with an app secret are **not** assigned automatically, even when `owner` is a user. Ownership and entity assignment are independent, so the entity must be set explicitly in these cases.

## Explicitly assign an entity

An entity can be assigned when the wallet is created, or afterwards.

<Tabs>
  <Tab title="At creation">
    Pass `entity` when creating the wallet, in a `POST` request to:

    ```bash theme={"system"}
    https://api.privy.io/v1/wallets
    ```

    ```bash theme={"system"}
    curl --request POST https://api.privy.io/v1/wallets \
      -u "<your-privy-app-id>:<your-privy-app-secret>" \
      -H "privy-app-id: <your-privy-app-id>" \
      -H 'Content-Type: application/json' \
      -d '{
        "chain_type": "ethereum",
        "entity": {
          "id": "did:privy:xxxxx",
          "type": "user"
        }
      }'
    ```
  </Tab>

  <Tab title="After creation">
    Make a `POST` request to:

    ```bash theme={"system"}
    https://api.privy.io/v1/wallets/{wallet_id}/entity
    ```

    In the body of the request, include the following fields:

    <ParamField body="id" type="string" required>
      ID of the Privy user or organization the wallet is for.
    </ParamField>

    <ParamField body="type" type="'user' | 'organization'" required>
      Type of the entity being assigned.
    </ParamField>

    ```bash theme={"system"}
    curl --request POST https://api.privy.io/v1/wallets/{wallet_id}/entity \
      -u "<your-privy-app-id>:<your-privy-app-secret>" \
      -H "privy-app-id: <your-privy-app-id>" \
      -H 'Content-Type: application/json' \
      -d '{
        "id": "did:privy:xxxxx",
        "type": "user"
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  A wallet's entity is immutable. Once set, it cannot be changed or reassigned — a second assignment
  fails with a `wallet_entity_already_set` error. Create a new wallet if the entity needs to change.
</Warning>

## Read a wallet's entity

Wallets return their entity as an `entity` object containing the entity `id` and `type` (`'user'` or `'organization'`), or `null` if none is assigned. Wallets can also be filtered by `entity_id` when listing them.

## Next steps

<CardGroup cols={2}>
  <Card title="KYC" icon="user-check" href="/kyc-kyb/kyc">
    Verify an individual user
  </Card>

  <Card title="KYB" icon="building" href="/kyc-kyb/kyb">
    Verify an organization
  </Card>
</CardGroup>