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

> Understand a wallet's entity, how it differs from ownership, and how it is assigned

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.

<View title="NodeJS" icon="node-js">
  Pass `entity` to `create` to assign at creation, or use `assignEntity` on an existing wallet.

  ```ts theme={"system"}
  import {PrivyClient} from '@privy-io/node';

  const privy = new PrivyClient({
    appId: process.env.PRIVY_APP_ID!,
    appSecret: process.env.PRIVY_APP_SECRET!
  });

  // At creation
  const wallet = await privy.wallets().create({
    chain_type: 'ethereum',
    entity: {id: 'did:privy:xxxxx', type: 'user'}
  });

  // After creation
  await privy.wallets().assignEntity(wallet.id, {
    id: 'did:privy:xxxxx',
    type: 'user'
  });
  ```
</View>

<View title="REST API" icon="terminal">
  <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
      ```

      See the [API reference](/api-reference/wallets/entity) for the full request and response schema.

      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>
</View>

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