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

# External IDs

> Assign custom external IDs to wallets for referencing with your own identifiers

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](/wallets/wallets/create/create-a-wallet). External IDs are **write-once** and cannot be changed after wallet creation.

```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",
    "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`:

```bash theme={"system"}
# 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>"
```

```bash theme={"system"}
# 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.

<Info>
  When using [authorization signatures](/api-reference/authorization-signatures), sign the request
  using the URL exactly as sent, including the `ext_wal_` prefix.
</Info>

## 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](/wallets/wallets/update-a-wallet) endpoint:

```bash theme={"system"}
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](/wallets/wallets/get-a-wallet/get-all-wallets) endpoint supports filtering by `external_id` as a query parameter:

```bash theme={"system"}
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>"
```