Create a wallet - Privy docs

Privy enables you to programmatically create wallets embedded within your application. When you create a wallet, you can specify its owner, which defines who controls the wallet.

To create a user wallet, specify a user ID as an owner of the wallet. This ensures only the authenticated user has access to their wallet. All client-side SDKs create user wallets by default and automatically set the wallet owner as the authenticated user.
Or, you can specify an authorization key as an owner on a wallet. The holder of the authorization key, typically your application backend, controls the wallet. You must use a server-side SDK to create wallets owned by an authorization key.

The React SDK supports automatically creating embedded wallets for your users when they log in to your app. View this guide to learn more and configure automatic wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useCreateWallet hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useCreateWallet} from '@privy-io/react-auth';
const {createWallet} = useCreateWallet();

Parameters

opts.createAdditional

boolean

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false. Learn more

Returns

wallet

Promise<Wallet>

A Promise for the linked account object for the created wallet.

Callbacks

You can optionally register an onSuccess or onError callback on the useCreateWallet hook.

const {createWallet} = useCreateWallet({
    onSuccess: ({wallet}) => {
        console.log('Created wallet ', wallet);
    },
    onError: (error) => {
        console.error('Failed to create wallet with error ', e)
    }
})

onSuccess

({wallet: Wallet}) => void

Optional callback to run after a user successfully creates a wallet.

onError

(error: string) => void

Optional callback to run after there is an error during wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useCreateWallet hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useCreateWallet} from '@privy-io/react-auth';
const {createWallet} = useCreateWallet();

Parameters

opts.createAdditional

boolean

Returns

wallet

Promise<Wallet>

A Promise for the linked account object for the created wallet.

Callbacks

You can optionally register an onSuccess or onError callback on the useCreateWallet hook.

const {createWallet} = useCreateWallet({
    onSuccess: ({wallet}) => {
        console.log('Created wallet ', wallet);
    },
    onError: (error) => {
        console.error('Failed to create wallet with error ', e)
    }
})

onSuccess

({wallet: Wallet}) => void

Optional callback to run after a user successfully creates a wallet.

onError

(error: string) => void

Optional callback to run after there is an error during wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useSolanaWallets hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useSolanaWallets} from '@privy-io/react-auth/solana';
const {createWallet} = useSolanaWallets();

Parameters

The createWallet method optionally accepts as a parameter an opts object with the following fields:

opts.createAdditional

boolean

Whether or not to create an additional Solana wallet for the user if they already have an existing Solana embedded wallet. Must be set to true to create additional wallets. Defaults to false. Learn more

Returns

wallet

Wallet

The linked account object for the created wallet.

To create a wallet in any of the chains supported at the Tier 2 level with the React SDK, use the createWallet method from the useCreateWallet hook, imported from @privy-io/react-auth/extended-chains:

createWallet: async ({chainType: CurveSigningChainType}) => Promise<{user: User; wallet: Wallet}>

Usage

import {useCreateWallet} from '@privy-io/react-auth/extended-chains';
const {createWallet} = useCreateWallet();

const {user, wallet} = await createWallet({chainType: 'cosmos'}); // or 'stellar', 'sui', etc.

Parameters

opts.chainType

CurveSigningChainType

The chain type of the wallet to create. This could be any of the chains supported at the Tier 2 level.

Returns

user

User

The updated user object with the new wallet added to the user’s linkedAccounts array.

wallet

Wallet

The newly created wallet.

The React SDK supports automatically creating embedded wallets for your users when they log in to your app. View this guide to learn more and configure automatic wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useCreateWallet hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useCreateWallet} from '@privy-io/react-auth';
const {createWallet} = useCreateWallet();

Parameters

opts.createAdditional

boolean

Returns

wallet

Promise<Wallet>

A Promise for the linked account object for the created wallet.

Callbacks

You can optionally register an onSuccess or onError callback on the useCreateWallet hook.

const {createWallet} = useCreateWallet({
    onSuccess: ({wallet}) => {
        console.log('Created wallet ', wallet);
    },
    onError: (error) => {
        console.error('Failed to create wallet with error ', e)
    }
})

onSuccess

({wallet: Wallet}) => void

Optional callback to run after a user successfully creates a wallet.

onError

(error: string) => void

Optional callback to run after there is an error during wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useCreateWallet hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useCreateWallet} from '@privy-io/react-auth';
const {createWallet} = useCreateWallet();

Parameters

opts.createAdditional

boolean

Returns

wallet

Promise<Wallet>

A Promise for the linked account object for the created wallet.

Callbacks

You can optionally register an onSuccess or onError callback on the useCreateWallet hook.

const {createWallet} = useCreateWallet({
    onSuccess: ({wallet}) => {
        console.log('Created wallet ', wallet);
    },
    onError: (error) => {
        console.error('Failed to create wallet with error ', e)
    }
})

onSuccess

({wallet: Wallet}) => void

Optional callback to run after a user successfully creates a wallet.

onError

(error: string) => void

Optional callback to run after there is an error during wallet creation.

To create a wallet with the React SDK, use the createWallet method from the useSolanaWallets hook:

createWallet: async ({createAdditional?: boolean}) => Promise<Wallet>

Usage

import {useSolanaWallets} from '@privy-io/react-auth/solana';
const {createWallet} = useSolanaWallets();

Parameters

The createWallet method optionally accepts as a parameter an opts object with the following fields:

opts.createAdditional

boolean

Returns

wallet

Wallet

The linked account object for the created wallet.

createWallet: async ({chainType: CurveSigningChainType}) => Promise<{user: User; wallet: Wallet}>

Usage

import {useCreateWallet} from '@privy-io/react-auth/extended-chains';
const {createWallet} = useCreateWallet();

const {user, wallet} = await createWallet({chainType: 'cosmos'}); // or 'stellar', 'sui', etc.

Parameters

opts.chainType

CurveSigningChainType

The chain type of the wallet to create. This could be any of the chains supported at the Tier 2 level.

Returns

user

User

The updated user object with the new wallet added to the user’s linkedAccounts array.

wallet

Wallet

The newly created wallet.

The React Native SDK supports automatically creating embedded wallets for your users when they log in to your app. View this guide to learn more and configure automatic wallet creation.

To create a wallet with the React Native SDK, use the create method from the useEmbeddedEthereumWallet hook:

create: async ({createAdditional?: boolean}) => Promise<{user: User}>

Usage

import {useEmbeddedEthereumWallet} from '@privy-io/expo';
const {create} = useEmbeddedEthereumWallet();

Parameters

The create method optionally accepts as a parameter an opts object with the following fields:

opts.createAdditional

boolean

Returns

user

Promise<{user: User}>

A Promise for an object containing the updated user object for the user.

To create a wallet with the React Native SDK, use the create method from the useEmbeddedEthereumWallet hook:

create: async ({createAdditional?: boolean}) => Promise<{user: User}>

Usage

import {useEmbeddedEthereumWallet} from '@privy-io/expo';
const {create} = useEmbeddedEthereumWallet();

Parameters

The create method optionally accepts as a parameter an opts object with the following fields:

opts.createAdditional

boolean

Returns

user

Promise<{user: User}>

A Promise for an object containing the updated user object for the user.

To create a wallet with the React Native SDK, use the create method from the useEmbeddedSolanaWallet hook:

create: async ({createAdditional?: boolean}) => Promise<{user: User}>

Usage

import {useEmbeddedSolanaWallet} from '@privy-io/expo';
const {create} = useEmbeddedSolanaWallet();

Parameters

The create method optionally accepts as a parameter an opts object with the following fields:

opts.createAdditional

boolean

Returns

user

Promise<{user: User}>

A Promise for an object containing the updated user object.

To create a wallet with the React Native SDK, use the create method from the useEmbeddedBitcoinWallet hook:

create: async ({chainType: 'bitcoin-taproot' | 'bitcoin-segtwit', createAdditional?: boolean}) => Promise<{user: User}>

Usage

import {useEmbeddedBitcoinWallet} from '@privy-io/expo';

const {create} = useEmbeddedBitcoinWallet();

Parameters

The create method optionally accepts as a parameter an opts object with the following fields:

opts.chainType

'bitcoin-taproot' | 'bitcoin-segtwit'

required

The type of Bitcoin wallet to create.

opts.createAdditional

boolean

Whether or not to create an additional Bitcoin wallet for the user if they already have an existing Bitcoin embedded wallet. Must be set to true to create additional wallets. Defaults to false. Learn more

Returns

user

Promise<{user: User}>

A Promise for an object containing the updated user object.

To create a wallet in any of the chains supported at the Tier 2 level with the React Native SDK, use the createWallet method from the useCreateWallet hook, imported from @privy-io/expo/extended-chains:

createWallet: async ({chainType: CurveSigningChainType}) => Promise<{user: PrivyUser; wallet: Wallet}>

Usage

import {useCreateWallet} from '@privy-io/expo/extended-chains';
const {createWallet} = useCreateWallet();

const {user, wallet} = await createWallet({chainType: 'cosmos'}); // or 'stellar', 'sui', etc.

Parameters

opts.chainType

CurveSigningChainType

The chain type of the wallet to create. This could be any of the chains supported at the Tier 2 level.

Returns

user

PrivyUser

The updated user object with the new wallet added to the user’s linked_accounts array.

wallet

Wallet

The newly created wallet.

To create a wallet with the Swift SDK, use the createEthereumWallet method from the PrivyUser instance:

func createEthereumWallet(allowAdditional: Bool) async throws -> EmbeddedEthereumWallet

Parameters

The createEthereumWallet method optionally accepts the following parameters:

allowAdditional

Boolean

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

EmbeddedEthereumWallet

The newly created EmbeddedEthereumWallet.

To create a wallet with the Swift SDK, use the createEthereumWallet method from the PrivyUser instance:

func createEthereumWallet(allowAdditional: Bool) async throws -> EmbeddedEthereumWallet

Parameters

The createEthereumWallet method optionally accepts the following parameters:

allowAdditional

Boolean

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

EmbeddedEthereumWallet

The newly created EmbeddedEthereumWallet.

To create a wallet with the Swift SDK, use the createSolanaWallet method from the PrivyUser instance:

func createSolanaWallet() async throws -> EmbeddedSolanaWallet

Returns

wallet

EmbeddedSolanaWallet

The newly created EmbeddedSolanaWallet.

To create a wallet with the Android SDK, use the createEthereumWallet method from the PrivyUser instance:

public suspend fun createEthereumWallet: (allowAdditional?: Boolean) => Result<EmbeddedEthereumWallet>

Parameters

The createEthereumWallet method optionally accepts the following parameters:

allowAdditional

Boolean

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Result<EmbeddedEthereumWallet>

A Result containing the EmbeddedEthereumWallet for the user.

To create a wallet with the Android SDK, use the createEthereumWallet method from the PrivyUser instance:

public suspend fun createEthereumWallet: (allowAdditional?: Boolean) => Result<EmbeddedEthereumWallet>

Parameters

The createEthereumWallet method optionally accepts the following parameters:

allowAdditional

Boolean

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Result<EmbeddedEthereumWallet>

A Result containing the EmbeddedEthereumWallet for the user.

To create a wallet with the Android SDK, use the createSolanaWallet method from the PrivyUser instance:

public suspend fun createEthereumWallet: (allowAdditional?: Boolean) => Result<EmbeddedSolanaWallet>

Returns

wallet

Result<EmbeddedSolanaWallet>

A Result containing the EmbeddedSolanaWallet for the user.

To create a wallet with the Unity SDK, use the CreateWallet method on your PrivyUser instance:

Task<IEmbeddedEthereumWallet> CreateWallet(bool allowAdditional)

Parameters

The CreateWallet method accepts the following parameter:

allowAdditional

Boolean

Whether or not to create an additional wallet for the user if they already have an existing ethereum wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Task<IEmbeddedEthereumWallet>

A Task for the created ethereum wallet object.

To create a wallet with the Unity SDK, use the CreateWallet method on your PrivyUser instance:

Task<IEmbeddedEthereumWallet> CreateWallet(bool allowAdditional)

Parameters

The CreateWallet method accepts the following parameter:

allowAdditional

Boolean

Whether or not to create an additional wallet for the user if they already have an existing ethereum wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Task<IEmbeddedEthereumWallet>

A Task for the created ethereum wallet object.

To create a wallet with the Unity SDK, use the CreateSolanaWallet method on your PrivyUser instance:

Task<IEmbeddedSolanaWallet> CreateSolanaWallet(bool allowAdditional)

Parameters

The CreateSolanaWallet method accepts the following parameter:

allowAdditional

Boolean

Whether or not to create an additional wallet for the user if they already have an existing solana wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Task<IEmbeddedSolanaWallet>

A Task for the created solana wallet object.

To create a wallet with the Flutter SDK, use the createEthereumWallet method from the PrivyUser instance:

Future<Result<EmbeddedEthereumWallet>> createEthereumWallet({bool allowAdditional = false});

Parameters

The createEthereumWallet method optionally accepts as a parameter an opts object with the following fields:

allowAdditional

bool

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Future<Result<EmbeddedEthereumWallet>>

A Result containing the EmbeddedEthereumWallet for the user.

To create a wallet with the Flutter SDK, use the createEthereumWallet method from the PrivyUser instance:

Future<Result<EmbeddedEthereumWallet>> createEthereumWallet({bool allowAdditional = false});

Parameters

The createEthereumWallet method optionally accepts as a parameter an opts object with the following fields:

allowAdditional

bool

Whether or not to create an additional Ethereum wallet for the user if they already have an existing Ethereum embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Future<Result<EmbeddedEthereumWallet>>

A Result containing the EmbeddedEthereumWallet for the user.

To create a wallet with the Android SDK, use the createSolanaWallet method from the PrivyUser instance:

Future<Result<EmbeddedSolanaWallet>> createSolanaWallet()

Parameters

The createSolanaWallet method optionally accepts the following parameters:

allowAdditional

Boolean

Whether or not to create an additional Solana wallet for the user if they already have an existing Solana embedded wallet. Must be set to true to create additional wallets. Defaults to false.

Returns

wallet

Future<Result<EmbeddedSolanaWallet>>

A Result containing the EmbeddedSolanaWallet for the user.

To create a new wallet with the NodeJS SDK, use the create method from the Privy client’s walletApi class:

createWallet: (input: WalletApiCreateRequestType) => Promise<WalletApiCreateResponseType>

If you are creating a user wallet, you must specify the user ID as the owner of the wallet. You can obtain a user ID by first creating a user before creating the wallet.

Or, you can create a user and wallet at the same time.

Usage

const {id, address, chainType} = await privy.walletApi.create({chainType: 'ethereum', owner: {userId: 'privy:did:xxxxx'}});

Parameters

The create method accepts as a parameter an input object with the following fields:

chainType

required

Chain type of the wallet to create.

owner

{'userId': string} | {'publicKey': string}

The user ID to set as the owner of the wallet, or the P-256 public key to set as the owner of the wallet.

If you provide this, do not specify an ownerId as it will be generated automatically.

ownerId

string

The key quorum ID of the owner of the wallet. If you provide this, do not specify an owner.

policyIds

string[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

idempotencyKey

string

Idempotency key to identify a unique request.

additionalSigners

{'signerId': string}[]

List of key quorum IDs that should be allowed to approve transactions for the wallet.

Returns

string

Unique ID of the created wallet. This will be the primary identifier when using the wallet in the future.

address

string

Address of the created wallet.

chainType

Chain type of the created wallet.

policyIds

string[]

List of policy IDs for policies that are enforced on the wallet.

ownerId

string | null

The key quorum ID of the owner of the wallet. If an ownerId was passed in, this response is the input ownerId. If a user ID or authorization key was passed in as the owner, this response is a newly created key quorum containing the input user ID or authorization key.

additionalSigners

{signerId: string}[]

The key quorum IDs of the additional signers for the wallet.

Your app can provision a smart account with the wallet as a signer by following this guide.

To create a new wallet for a user, make a POST request to

https://api.privy.io/v1/wallets

If you are creating a user wallet, you must specify the user ID as the owner of the wallet. You can obtain a user ID by first creating a user before creating the wallet.

Or, you can create a user and wallet at the same time.

Body

In the request body, include the following fields.

chain_type

required

Chain type of the wallet to create.

owner

{user_id: string} | {public_key: string} | null

The user ID to set as the owner of the wallet, or the P-256 public key to set as the owner of the wallet.

If you provide this, do not specify an owner_id as it will be generated automatically.

owner_id

string | null

The key quorum ID of the owner of the wallet. If you provide this, do not specify an owner.

policy_ids

string[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

idempotency_key

string

Idempotency key to identify a unique request.

additional_signers

{signer_id: string}[]

The key quorum IDs to add as additional signers for the wallet.

Response

In the response, Privy will send back the following if successful:

string

Unique ID of the created wallet. This will be the primary identifier when using the wallet in the future.

address

string

Address of the created wallet.

chain_type

Chain type of the created wallet.

policy_ids

string[]

List of policy IDs for policies that are enforced on the wallet.

owner_id

string | null

additional_signers

{signer_id: string}[]

The key quorum IDs of the additional signers for the wallet.

created_at

number

The creation date of the wallet, in milliseconds since midnight, January 1, 1970 UTC.

Example

A sample request might look like the following:

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 '{
    "owner": {
        "user_id": "did:privy:xxxxxx"
    },
    "chain_type": "ethereum"
    }'

A successful response will look like the following:

{
    "id": "fmfdj6yqly31huorjqzq38zc",
    "address": "0xf9f284C7Eaf97b0f9B5542d83Af7F785D12E803a",
    "chain_type": "ethereum",
    "policy_ids": [],
    "owner_id": null,
    "additional_signers": [],
    "created_at": 1733923425155
}

Embedded wallets

Using wallets

Funding

Gas and asset management

Session signers

Global wallets

Advanced Topics

​Usage

​Parameters

​Returns

​Callbacks

​Usage

​Parameters

​Returns

​Callbacks

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Callbacks

​Usage

​Parameters

​Returns

​Callbacks

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Body

​Response

​Example

Usage

Parameters

Returns

Callbacks

Usage

Parameters

Returns

Callbacks

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Callbacks

Usage

Parameters

Returns

Callbacks

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Usage

Parameters

Returns

Body

Response

Example