Skip to main content
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

ConstraintDetail
CharactersURL-safe only: a-z, A-Z, 0-9, _, -
Max length64 characters
UniquenessUnique per app. No two wallets in the same app can share an external_id.
MutabilityWrite-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.
ConstraintDetail
Max length100 characters
MutabilityCan 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>"