Wallet Locators

A wallet locator is a string that identifies a specific wallet across all Crossmint APIs and SDKs. Instead of tracking raw blockchain addresses, you reference wallets by a user identity (email, user ID, phone number, or social handle) combined with chain and wallet type information. The general format is:

<userType>:<userIdentifier>:<chainType>:<walletType>

For example, email:alice@example.com:evm:smart identifies the EVM smart wallet owned by alice@example.com.

Components

User Type

The user type specifies how the wallet owner is identified. You can use an email, your app’s internal user ID, a phone number, a social handle, or the me shorthand for client-side contexts. You can also pass a raw wallet address directly.

User type	Description	Example
`email`	Email address	`email:alice@example.com`
`userId`	Your app’s internal user ID or a DID	`userId:507f1f77bcf86cd799439011`
`phoneNumber`	Phone number in E.164 format	`phoneNumber:+12125551234`
`twitter`	Twitter/X handle	`twitter:johndoe`
`x`	Alias for `twitter`	`x:johndoe`
`me`	Authenticated user (client-side only)	`me`
(none)	Direct wallet address	`0x1234...abcd`

The userId type accepts any string, including Decentralized Identifiers (DIDs) with colons (e.g., userId:did:key:z6Mk...abc:evm:smart). The API parses the chain and wallet type from the end of the locator correctly.

Chain Type

The chain type specifies which blockchain ecosystem the wallet belongs to. It is required for all user-based locators. For direct wallet addresses, the chain is inferred from the address format.

Chain type	Blockchains
`evm`	Ethereum, Base, Polygon, Arbitrum, and other EVM-compatible chains
`solana`	Solana
`stellar`	Stellar
`aptos`	Aptos
`sui`	Sui

Wallet Type

The wallet type specifies the wallet’s underlying architecture. It is optional and defaults to smart when omitted. For most integrations, smart is the recommended type.

Wallet type	Description
`smart`	Smart contract wallet (ERC-4337 on EVM, Swig on Solana, Soroban on Stellar)
`mpc`	MPC (multi-party computation) wallet

Alias

An alias is an optional label that lets you create multiple wallets for the same user on the same chain. Aliases are appended with the :alias:<name> suffix. Alias constraints:

Alphanumeric characters, hyphens, and underscores only
Maximum 36 characters
Only supported with the smart wallet type

Formats

Optional segments are shown in square brackets.

Format	Description
`<address>`	Direct wallet address (EVM, Solana, or Stellar)
`email:<email>:<chainType>[:<walletType>][:alias:<alias>]`	Wallet by email
`userId:<userId>:<chainType>[:<walletType>][:alias:<alias>]`	Wallet by user ID
`phoneNumber:<phone>:<chainType>[:<walletType>][:alias:<alias>]`	Wallet by phone number
`twitter:<handle>:<chainType>[:<walletType>][:alias:<alias>]`	Wallet by Twitter handle
`x:<handle>:<chainType>[:<walletType>][:alias:<alias>]`	Wallet by X handle
`me:<chainType>[:<walletType>][:alias:<alias>]`	Authenticated user’s wallet (client-side)
`<chainType>[:<walletType>]:alias:<alias>`	Wallet by alias only

Examples

# Basic — walletType defaults to smart
email:alice@example.com:evm
userId:user-abc-123:solana:smart
me:evm:smart

# Direct addresses — no user identifier needed
0x1234567890123456789012345678901234567890
7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV

# With aliases — multiple wallets per user on the same chain
email:alice@example.com:evm:smart:alias:treasury
me:solana:smart:alias:savings
evm:alias:treasury

# Other identifier types
phoneNumber:+44207946123:evm:smart
twitter:satoshi:solana
userId:my-app-user-456:evm

Client-Side vs. Server-Side

Client-Side (Client API Key + JWT)

The authenticated user’s identity is derived from the JSON Web Token (JWT). On the client side, me is the recommended prefix to reference the current user’s wallet:

me:evm:smart
me:solana

You cannot reference other users’ wallets from the client side. When using the SDK’s getWallet() on the client side, you don’t build the locator manually. The SDK constructs it automatically from the chain you provide — it builds a locator in the format me:<chainType>:smart, always using smart as the wallet type. If you need a wallet with an alias, pass the alias option in your wallet args and the SDK appends :alias:<name> for you.

// Client-side: just pass the chain — the SDK builds the locator for you
const wallet = await wallets.getWallet({ chain: "evm", /* signer config */ });

// With an alias
const treasury = await wallets.getWallet({ chain: "evm", alias: "treasury", /* signer config */ });

Server-Side (Server API Key)

You must specify the full user identifier since there is no authenticated session:

email:alice@example.com:evm:smart
userId:user-abc-123:solana:smart

The me prefix is not available server-side. When using the SDK’s getWallet(), pass the wallet locator string as the first argument:

// Server-side: pass the full locator string
const wallet = await wallets.getWallet("email:alice@example.com:evm:smart", { chain: "evm", /* signer config */ });

Where Wallet Locators Are Used

Wallet locators appear in REST API paths, SDK methods, and transfer operations:

REST API — GET /api/2025-06-09/wallets/{walletLocator}, .../transactions, .../balances, .../signers
Token transfers — both the source wallet and the recipient field accept locators
SDK methods — getWallet(), createWallet(), and other wallet operations

When calling the REST API directly, standard URL encoding rules apply for characters like @ or +. The SDK handles encoding automatically.

Wallet Locators vs. Signer Locators

Wallet locators identify a wallet — they combine a user identity, chain, and wallet type. Signer locators identify a signer attached to a wallet — they follow the format <signerType>:<identifier> (e.g., email:alice@example.com, server:0xabc..., device:<publicKeyBase64>). Signer types include: passkey, api-key, external-wallet, server, email, phone, and device. See Signers for details.

Create a Wallet

Step-by-step guide to creating wallets using the SDK and REST API

Architecture

How the dual-layer architecture separates wallet logic from signer control

Introduction

Quickstarts ⚡️

Concepts

Guides

API Reference

Components

User Type

Chain Type

Wallet Type

Alias

Formats

Examples

Client-Side vs. Server-Side

Client-Side (Client API Key + JWT)

Server-Side (Server API Key)

Where Wallet Locators Are Used

Wallet Locators vs. Signer Locators

See Also

Create a Wallet

Architecture

​Components

​User Type

​Chain Type

​Wallet Type

​Alias

​Formats

​Examples

​Client-Side vs. Server-Side

​Client-Side (Client API Key + JWT)

​Server-Side (Server API Key)

​Where Wallet Locators Are Used

​Wallet Locators vs. Signer Locators

​See Also

Create a Wallet

Architecture

Components

User Type

Chain Type

Wallet Type

Alias

Formats

Examples

Client-Side vs. Server-Side

Client-Side (Client API Key + JWT)

Server-Side (Server API Key)

Where Wallet Locators Are Used

Wallet Locators vs. Signer Locators

See Also