External IDs

Privy allows your app to assign an external_id to any wallet at creation time. External IDs enable your app to reference wallets using your own identifiers, such as order IDs, user references, or other application-specific keys, without maintaining a separate mapping.

Setting an external ID

To assign an external ID, include the external_id field when creating a wallet. External IDs are write-once and cannot be changed after wallet creation.

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",
    "external_id": "order-12345",
    "display_name": "Treasury wallet"
    }'

Constraints

Constraint	Detail
Characters	URL-safe only: `a-z`, `A-Z`, `0-9`, `_`, `-`
Max length	64 characters
Uniqueness	Unique per app. No two wallets in the same app can share an `external_id`.
Mutability	Write-once. Set only at creation and cannot be updated.

Addressing wallets by external ID

Once a wallet has an external_id, your app can use the ext_wal_ prefix in place of the wallet ID on any endpoint that accepts a wallet ID in the URL path. Prefix ext_wal_ to the external ID value to form the identifier. For example, if a wallet has external_id set to order-12345, your app can reference it as ext_wal_order-12345:

# Get a wallet by external ID
curl --request GET https://api.privy.io/v1/wallets/ext_wal_order-12345 \
    -u "<your-privy-app-id>:<your-privy-app-secret>" \
    -H "privy-app-id: <your-privy-app-id>"

# Transfer from a wallet by external ID
curl --request POST https://api.privy.io/v1/wallets/ext_wal_order-12345/rpc \
    -u "<your-privy-app-id>:<your-privy-app-secret>" \
    -H "privy-app-id: <your-privy-app-id>" \
    -H 'Content-Type: application/json' \
    -d '{ ... }'

The ext_wal_ prefix works on all wallet endpoints that include a wallet ID in the path.

When using authorization signatures, sign the request using the URL exactly as sent, including the ext_wal_ prefix.

Display name

Your app can also assign a display_name to a wallet. Unlike external_id, the display name is updatable after creation.

Constraint	Detail
Max length	100 characters
Mutability	Can be set at creation and updated via `PATCH`.

To update a display name after creation, use the update wallet endpoint:

curl --request PATCH https://api.privy.io/v1/wallets/<wallet_id> \
    -u "<your-privy-app-id>:<your-privy-app-secret>" \
    -H "privy-app-id: <your-privy-app-id>" \
    -H 'Content-Type: application/json' \
    -d '{
    "display_name": "Updated treasury wallet"
    }'

Filtering wallets by external ID

The list wallets endpoint supports filtering by external_id as a query parameter:

curl --request GET "https://api.privy.io/v1/wallets?external_id=order-12345" \
    -u "<your-privy-app-id>:<your-privy-app-secret>" \
    -H "privy-app-id: <your-privy-app-id>"

Embedded wallets

Management

Usage

UI components

Custodial wallets

Global wallets

EVM smart wallets

Setting an external ID

Constraints

Addressing wallets by external ID

Display name

Filtering wallets by external ID

​Setting an external ID

​Constraints

​Addressing wallets by external ID

​Display name

​Filtering wallets by external ID

Setting an external ID

Constraints

Addressing wallets by external ID

Display name

Filtering wallets by external ID