Wallet 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 or organization.	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:

If a wallet has no entity, or its entity has not completed KYC or 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.

At creation
After creation

Pass entity when creating the wallet, in a POST request to:

https://api.privy.io/v1/wallets

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"
    }
  }'

Make a POST request to:

https://api.privy.io/v1/wallets/{wallet_id}/entity

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

string

required

ID of the Privy user or organization the wallet is for.

'user' | 'organization'

required

Type of the entity being assigned.

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"
  }'

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.

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.

KYC and KYB

Users

Organizations

Entities

Where entities are required

Automatically assigned entities

Explicitly assign an entity

Read a wallet’s entity

Next steps

KYC

KYB

​Where entities are required

​Automatically assigned entities

​Explicitly assign an entity

​Read a wallet’s entity

​Next steps

KYC

KYB

Where entities are required

Automatically assigned entities

Explicitly assign an entity

Read a wallet’s entity

Next steps