> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Wallet

> Create a wallet using Crossmint's APIs

## Prerequisites

* **API Key**: Ensure you have an API key with the scopes: `wallets.create`.

## Try it Live

Experience wallet creation in action with this interactive demo. Create a Solana testnet wallet using just your email address:

### Create a Wallet

Select Chain

Create an account

Get USDXM testnet tokens for your wallet.

<details>
  <summary>View API Details</summary>

  POST [https://staging.crossmint.com/api/2025-06-09/wallets](https://staging.crossmint.com/api/2025-06-09/wallets)

  <pre />
</details>

## Creating a Wallet

Wallet creation requires a **recovery method** — used for account recovery and adding new signers. On client-side SDKs, a [device signer](https://docs.crossmint.com/wallets/concepts/signers.md) is automatically added as the default operational signer.

<Snippet file="recovery-prop-deprecated.mdx" />

> [tab] React
>
> ```typescript theme={null}
> import { useWallet } from '@crossmint/client-sdk-react-ui';
>
> const { createWallet } = useWallet();
>
> const wallet = await createWallet({
>     chain: "base-sepolia",
>     recoveryMethods: [
>         {
>             type: "email",
>             email: "user@example.com",
>         },
>     ],
> });
> ```
>
> See the [React SDK reference](https://docs.crossmint.com/sdk-reference/wallets/react/hooks.md#usewallet) for all parameters.

> [tab] Node.js
>
> ```typescript theme={null}
> import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";
>
> const crossmint = createCrossmint({
>     apiKey: "<your-server-api-key>",
> });
>
> const crossmintWallets = CrossmintWallets.from(crossmint);
>
> const wallet = await crossmintWallets.createWallet({
>     chain: "base-sepolia",
>     recoveryMethods: [
>         {
>             type: "server",
>             secret: process.env.RECOVERY_SIGNER_SECRET,
>         },
>     ],
>     signers: [
>         { type: "server", secret: process.env.WALLET_SIGNER_SECRET },
>     ],
> });
>
> ```
>
> See the [SDK reference](https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/CrossmintWallets.md) for all parameters and return types.

> [tab] React Native
>
> ```typescript theme={null}
> import { useWallet } from '@crossmint/client-sdk-react-native-ui';
>
> const { createWallet } = useWallet();
>
> const wallet = await createWallet({
>     chain: "base-sepolia",
>     recoveryMethods: [
>         {
>             type: "email",
>             email: "user@example.com",
>         },
>     ],
> });
> ```
>
> See the [React Native SDK reference](https://docs.crossmint.com/sdk-reference/wallets/react-native/hooks.md#usewallet) for all parameters.

> [tab] Kotlin
>
> ```kotlin theme={null}
> import com.crossmint.kotlin.CrossmintSDK
> import com.crossmint.kotlin.types.EVMChain
> import com.crossmint.kotlin.signers.SignerType
> import com.crossmint.kotlin.types.getOrThrow
>
> CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
> val sdk = CrossmintSDK.shared
> val result = sdk.wallets.createWallet(
>     chain = EVMChain.BaseSepolia,
>     recoveryMethods = listOf(SignerType.Email("user@example.com"))
> )
> val wallet = result.getOrThrow()
> println("Wallet address: ${wallet.address}")
> ```

> [tab] Swift
>
> ```swift theme={null}
> import CrossmintClient
>
> CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
> let sdk = CrossmintSDK.shared
>
> let wallet = try await sdk.crossmintWallets.createWallet(
>     chain: EVMChain.baseSepolia,
>     recoveryMethods: [EVMSigners.email("user@example.com")]
> )
> print("Wallet address:", wallet.address)
> ```

> [tab] Flutter
>
> ```dart theme={null}
> import 'package:crossmint_flutter/crossmint_flutter_ui.dart';
>
> final controller = CrossmintWalletContext.of(context).requireWalletController;
>
> final wallet = await controller.createWallet(
>   const CrossmintWalletCreateRequest(
>     chain: 'base-sepolia',
>     recovery: CrossmintEmailSignerConfig(email: 'user@example.com'),
>   ),
> );
> ```
>
> With `CrossmintWalletProvider` + `createOnLogin`, the wallet is created
> automatically after login. See the
> [Flutter SDK reference](https://docs.crossmint.com/sdk-reference/wallets/flutter/controllers.md#crossmintwalletcontroller)
> for all parameters.

> [tab] REST
>
> ```bash cURL theme={null}
> curl --request POST \
>     --url https://staging.crossmint.com/api/2025-06-09/wallets \
>     --header 'Content-Type: application/json' \
>     --header 'X-API-KEY: <x-api-key>' \
>     --data '{
>         "chainType": "evm",
>         "config": {
>             "recoveryMethods": [
>                 {
>                     "type": "email",
>                     "email": "user@example.com"
>                 }
>             ]
>         },
>         "owner": "email:user@example.com"
>     }'
> ```
>
> ```js Node.js theme={null}
> const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';
>
> const payload = {
>     chainType: "evm",
>     config: {
>         recoveryMethods: [
>             {
>                 type: "email",
>                 email: "user@example.com"
>             }
>         ]
>     },
>     owner: "email:user@example.com"
> };
>
> const options = {
>     method: 'POST',
>     headers: {
>         'X-API-KEY': '<x-api-key>',
>         'Content-Type': 'application/json'
>     },
>     body: JSON.stringify(payload)
> };
>
> try {
>     const response = await fetch(url, options);
>     const data = await response.json();
>     console.log(data);
> } catch (error) {
>     console.error(error);
> }
> ```
>
> ```python Python theme={null}
> import requests
>
> url = "https://staging.crossmint.com/api/2025-06-09/wallets"
>
> payload = {
>     "chainType": "evm",
>     "config": {
>         "recoveryMethods": [
>             {
>                 "type": "email",
>                 "email": "user@example.com"
>             }
>         ]
>     },
>     "owner": "email:user@example.com"
> }
> headers = {
>     "X-API-KEY": "<x-api-key>",
>     "Content-Type": "application/json"
> }
>
> response = requests.post(url, json=payload, headers=headers)
>
> print(response.json())
> ```
>
> See the [API reference](https://docs.crossmint.com/api-reference/wallets/create-wallet.md) for more details.

> [!NOTE]
>
> The REST API uses `config.recoveryMethods` (recovery methods) and `config.delegatedSigners` (operational signers). These map to `recoveryMethods` and `signers` in the TypeScript SDKs. The REST `adminSigner` field is deprecated: it accepts a single recovery method and cannot be combined with `recoveryMethods`.

## Retrieving an Existing Wallet

Use `getWallet()` to retrieve a wallet that was previously created. If the wallet does not exist, it throws a `WalletNotAvailableError`.

> [tab] React
>
> ```typescript theme={null}
> import { useWallet } from '@crossmint/client-sdk-react-ui';
>
> const { getWallet } = useWallet();
>
> const wallet = await getWallet({ chain: "base-sepolia" });
> ```

> [tab] Node.js
>
> ```typescript theme={null}
> import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";
>
> const crossmint = createCrossmint({
>     apiKey: "<your-server-api-key>",
> });
>
> const crossmintWallets = CrossmintWallets.from(crossmint);
>
> const wallet = await crossmintWallets.getWallet(
>     "<wallet-address>",
>     { chain: "base-sepolia" }
> );
>
> await wallet.useSigner({
>     type: "server",
>     secret: process.env.WALLET_SIGNER_SECRET!,
> });
>
> ```

> [tab] React Native
>
> ```typescript theme={null}
> import { useWallet } from '@crossmint/client-sdk-react-native-ui';
>
> const { getWallet } = useWallet();
>
> const wallet = await getWallet({ chain: "base-sepolia" });
> ```

> [tab] Kotlin
>
> ```kotlin theme={null}
> import com.crossmint.kotlin.CrossmintSDK
> import com.crossmint.kotlin.types.EVMChain
> import com.crossmint.kotlin.types.getOrThrow
>
> CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
> val sdk = CrossmintSDK.shared
> val result = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia)
> val wallet = result.getOrThrow()
> println("Wallet address: ${wallet.address}")
> ```

> [tab] Swift
>
> ```swift theme={null}
> import CrossmintClient
>
> CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
> let sdk = CrossmintSDK.shared
>
> let wallet = try await sdk.crossmintWallets.getWallet(
>     chain: EVMChain.baseSepolia
> )
> ```

> [tab] Flutter
>
> ```dart theme={null}
> import 'package:crossmint_flutter/crossmint_flutter_ui.dart';
>
> final controller = CrossmintWalletContext.of(context).requireWalletController;
>
> final wallet = await controller.getWallet(
>   const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
> );
> ```

> [tab] REST
>
> ```bash cURL theme={null}
> curl --request GET \
>     --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator> \
>     --header 'X-API-KEY: <x-api-key>'
> ```
>
> ```js Node.js theme={null}
> const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>';
>
> const options = {
>     method: 'GET',
>     headers: {
>         'X-API-KEY': '<x-api-key>'
>     }
> };
>
> try {
>     const response = await fetch(url, options);
>     const data = await response.json();
>     console.log(data);
> } catch (error) {
>     console.error(error);
> }
> ```
>
> ```python Python theme={null}
> import requests
>
> url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>"
>
> headers = {"X-API-KEY": "<x-api-key>"}
>
> response = requests.get(url, headers=headers)
>
> print(response.json())
> ```
>
> See the [API reference](https://docs.crossmint.com/api-reference/wallets/get-wallet-by-locator.md) for more details.

## Get-or-Create Pattern

If you want to retrieve an existing wallet or create one if it does not exist, use `WalletNotAvailableError` to implement the pattern:

> [tab] React
>
> ```typescript theme={null}
> import { useWallet, WalletNotAvailableError } from '@crossmint/client-sdk-react-ui';
>
> const { getWallet, createWallet } = useWallet();
>
> let wallet;
> try {
>     wallet = await getWallet({ chain: "base-sepolia" });
> } catch (error) {
>     if (error instanceof WalletNotAvailableError) {
>         wallet = await createWallet({
>             chain: "base-sepolia",
>             recoveryMethods: [
>                 {
>                     type: "email",
>                     email: "user@example.com",
>                 },
>             ],
>         });
>     } else {
>         throw error;
>     }
> }
> ```

> [tab] Node.js
>
> ```typescript theme={null}
> import {
>     CrossmintWallets,
>     WalletNotAvailableError,
>     createCrossmint,
> } from "@crossmint/wallets-sdk";
>
> const crossmint = createCrossmint({
>     apiKey: "<your-server-api-key>",
> });
>
> const crossmintWallets = CrossmintWallets.from(crossmint);
>
> let wallet;
> try {
>     wallet = await crossmintWallets.getWallet(
>         "<wallet-address>",
>         { chain: "base-sepolia" }
>     );
>     await wallet.useSigner({
>         type: "server",
>         secret: process.env.WALLET_SIGNER_SECRET!,
>     });
> } catch (error) {
>     if (error instanceof WalletNotAvailableError) {
>         wallet = await crossmintWallets.createWallet({
>             chain: "base-sepolia",
>             recoveryMethods: [
>                 {
>                     type: "server",
>                     secret: process.env.RECOVERY_SIGNER_SECRET,
>                 },
>             ],
>             signers: [
>                 {
>                     type: "server",
>                     secret: process.env.WALLET_SIGNER_SECRET,
>                 },
>             ],
>         });
>     } else {
>         throw error;
>     }
> }
>
> ```

> [tab] React Native
>
> ```typescript theme={null}
> import { useWallet, WalletNotAvailableError } from '@crossmint/client-sdk-react-native-ui';
>
> const { getWallet, createWallet } = useWallet();
>
> let wallet;
> try {
>     wallet = await getWallet({ chain: "base-sepolia" });
> } catch (error) {
>     if (error instanceof WalletNotAvailableError) {
>         wallet = await createWallet({
>             chain: "base-sepolia",
>             recoveryMethods: [
>                 {
>                     type: "email",
>                     email: "user@example.com",
>                 },
>             ],
>         });
>     } else {
>         throw error;
>     }
> }
> ```

> [tab] Kotlin
>
> ```kotlin theme={null}
> import com.crossmint.kotlin.CrossmintSDK
> import com.crossmint.kotlin.types.EVMChain
> import com.crossmint.kotlin.signers.SignerType
> import com.crossmint.kotlin.types.Result
> import com.crossmint.kotlin.types.WalletError
> import com.crossmint.kotlin.types.getOrThrow
>
> CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
> val sdk = CrossmintSDK.shared
> val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia)) {
>     is Result.Success -> result.value
>     is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
>         sdk.wallets.createWallet(
>             chain = EVMChain.BaseSepolia,
>             recoveryMethods = listOf(SignerType.Email("user@example.com"))
>         ).getOrThrow()
>     } else {
>         throw Exception(result.error.toString())
>     }
> }
> ```

> [tab] Swift
>
> ```swift theme={null}
> import CrossmintClient
>
> CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
> let sdk = CrossmintSDK.shared
>
> let wallet: EVMWallet
> if let existing = try await sdk.crossmintWallets.getWallet(
>     chain: EVMChain.baseSepolia
> ) {
>     wallet = existing
> } else {
>     wallet = try await sdk.crossmintWallets.createWallet(
>         chain: EVMChain.baseSepolia,
>         recoveryMethods: [EVMSigners.email("user@example.com")]
>     )
> }
> ```

> [tab] Flutter
>
> ```dart theme={null}
> import 'package:crossmint_flutter/crossmint_flutter_ui.dart';
>
> final controller = CrossmintWalletContext.of(context).requireWalletController;
>
> // Controller.getWallet returns null when the wallet does not exist.
> var wallet = await controller.getWallet(
>   const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
> );
> wallet ??= await controller.createWallet(
>   const CrossmintWalletCreateRequest(
>     chain: 'base-sepolia',
>     recovery: CrossmintEmailSignerConfig(email: 'user@example.com'),
>   ),
> );
> ```

> [!NOTE]
>
> On client-side SDKs (React, React Native), if you use `CrossmintWalletProvider` with the `createOnLogin` prop, the wallet is created automatically when the user logs in — no manual `createWallet` call is needed.

## Next Steps

> [card] [Transfer tokens](https://docs.crossmint.com/wallets/guides/transfer-tokens.md)
>
> Send tokens between wallets

> [card] [Add signers](https://docs.crossmint.com/wallets/guides/signers/add-signers.md)
>
> Register operational signers on your wallet

> [card] [Fund your wallet](https://docs.crossmint.com/wallets/guides/fund-staging-wallet.md)
>
> Get testnet tokens to start testing
