Wallet Locators

Identifiers to reference and manage your wallets across chains, environments, and users

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:[e-mail]:evm:smart identifies the EVM smart wallet owned by [e-mail].

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:[e-mail]
userId	Your app’s internal user ID or a DID	userId:507f1f77bcf86cd799439011
phoneNumber	Phone number in E.164 format	phoneNumber:[phone]
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:[e-mail]: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:[e-mail]:evm:smart:alias:treasury
me:solana:smart:alias:savings
evm:alias:treasury

# Other identifier types
phoneNumber:[phone]: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:[e-mail]: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:[e-mail]: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:[e-mail], server:0xabc..., device:<publicKeyBase64>). Signer types include: passkey, api-key, external-wallet, server, email, phone, and device.

See Signers for details.

See Also

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