Private keys

Privy enables you to import wallet private keys for use via the Privy API. This allows you to migrate wallets from external sources to Privy, including from a different wallet provider. Or, your app can enable users to bring an existing external wallet into your application in order to access and manage their assets within your app seamlessly.

Importing a wallet

React
NodeJS
NodeJS (server-auth)
REST API
Rust

To import a private key wallet with the React SDK, use the importWallet method from the useImportWallet hook:

importWallet: (input: {privateKey: string}) => Promise<Wallet>;

EVM
Solana

Usage

import {useImportWallet} from '@privy-io/react-auth';

const {importWallet} = useImportWallet();

const wallet = await importWallet({
  privateKey: 'your-wallet-private-key'
});

Parameters

privateKey

string

The hex-encoded private key of the ethereum wallet to import, with or without a 0x prefix.

Returns

wallet

Promise<Wallet>

A Promise for the imported wallet object.

Usage

import {useImportWallet} from '@privy-io/react-auth/solana';

const {importWallet} = useImportWallet();

const wallet = await importWallet({
  privateKey: 'your-wallet-private-key'
});

Parameters

privateKey

string

The base58-encoded private key of the solana wallet to import.

Returns

wallet

Promise<Wallet>

A Promise for the imported wallet object.

To import a private key wallet with the NodeJS SDK, use the import method from the Privy client’s wallets() interface. The Privy client will encrypt your private key for secure transmission to the TEE. See architecture for more details.

EVM
Solana

For EVM wallets, the Privy client accepts a hex-encoded private key, with or without a 0x prefix.

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: 'your-app-id',
  appSecret: 'your-app-secret'
});

try {
  const wallet = await privy.wallets().import({
    wallet: {
      entropy_type: 'private-key',
      chain_type: 'ethereum',
      address: '<your-wallet-address>',
      private_key: '<your-hex-encoded-wallet-private-key>'
    }
  });
} catch (error) {
  console.error('Failed to import wallet:', error);
}

Alternatively, you can also pass the private key directly as binary (Uint8Array).

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: 'your-app-id',
  appSecret: 'your-app-secret'
});

const wallet = await privy.wallets().import({
  wallet: {
    entropy_type: 'private-key',
    chain_type: 'ethereum',
    address: '<your-wallet-address>',
    private_key: '<your-uint8array-wallet-private-key>'
  }
});

For Solana wallets, the Privy client accepts a base58-encoded private key.

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: 'your-app-id',
  appSecret: 'your-app-secret'
});

try {
  const wallet = await privy.wallets().import({
    wallet: {
      entropy_type: 'private-key',
      chain_type: 'solana',
      address: '<your-wallet-address>',
      private_key: '<your-base58-encoded-wallet-private-key>'
    }
  });
} catch (error) {
  console.error('Failed to import wallet:', error);
}

Alternatively, you can also pass the private key directly as binary (Uint8Array).

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: 'your-app-id',
  appSecret: 'your-app-secret'
});

const wallet = await privy.wallets().import({
  wallet: {
    entropy_type: 'private-key',
    chain_type: 'solana',
    address: '<your-wallet-address>',
    private_key: '<your-uint8array-wallet-private-key>'
  }
});

The returned wallet is type Wallet. See get wallet by ID for type definition.

The @privy-io/server-auth library is deprecated. We recommend integrating @privy-io/node for the latest features and support.

To import a private key wallet with the NodeJS SDK, use the importWallet method from the Privy client’s walletApi class. The Privy client will encrypt your private key for secure transmission to the TEE. See architecture for more details.

EVM
Solana

For EVM wallets, the Privy client accepts a hex-encoded private key, with or without a 0x prefix.

import {PrivyClient, WalletApiWalletResponseType} from '@privy-io/server-auth';

const privy = new PrivyClient('your-app-id', 'your-app-secret');

const wallet: WalletApiWalletResponseType = await privy.walletApi.importWallet({
  address: '<your-wallet-address>',
  chainType: 'ethereum',
  entropy: '<your-hex-encoded-wallet-private-key>',
  entropyType: 'private-key'
});

For Solana wallets, the Privy client accepts a base58-encoded private key.

import {PrivyClient, WalletApiWalletResponseType} from '@privy-io/server-auth';

const privy = new PrivyClient('your-app-id', 'your-app-secret');

const wallet: WalletApiWalletResponseType = await privy.walletApi.importWallet({
  address: '<your-wallet-address>',
  chainType: 'solana',
  entropy: '<your-base58-encoded-wallet-private-key>',
  entropyType: 'private-key'
});

The returned wallet is type WalletApiWalletResponseType. See get wallet by ID for type definition.

1. Initialization

Initialize a key import flow by calling the /v1/wallets/import/init endpoint with your wallet address and chain type. See authentication for how to encode your app credentials.

EVM
Solana

curl --request POST \
  --url https://api.privy.io/v1/wallets/import/init \
  --header 'Authorization: Basic <encoded-app-credentials>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
    "address": "<your-wallet-address>",
    "chain_type": "ethereum",
    "entropy_type": "private-key",
    "encryption_type": "HPKE"
  }'

curl --request POST \
  --url https://api.privy.io/v1/wallets/import/init \
  --header 'Authorization: Basic <encoded-app-credentials>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
    "address": "<your-wallet-address>",
    "chain_type": "solana",
    "entropy_type": "private-key",
    "encryption_type": "HPKE"
  }'

The endpoint will return a public key to encrypt your private key with:

{
  "encryption_public_key": "<base64-encoded-encryption-public-key>",
  "encryption_type": "HPKE"
}

2. Encryption

Encrypt your private key using Hybrid Public Key Encryption (HPKE) with the following configuration:

KEM: DHKEM_P256_HKDF_SHA256
KDF: HKDF_SHA256
AEAD: CHACHA20_POLY1305
Mode: BASE

There are two outputs from the encryption step that you’ll provide to Privy during submission:

ciphertext: The encrypted private key
encapsulated_key: The encapsulated key

Here’s an example of how to encrypt a private key in TypeScript:

EVM
Solana

import {Chacha20Poly1305} from '@hpke/chacha20poly1305';
import {CipherSuite, DhkemP256HkdfSha256, HkdfSha256} from '@hpke/core';
import {base64} from '@scure/base';

const encryptWithHpke = async ({
  encryptionPublicKey,
  plaintextPrivateKey
}: {
  encryptionPublicKey: Uint8Array;
  plaintextPrivateKey: Uint8Array;
}) => {
  // Deserialize the raw key returned by the `init` request to the Privy API to a public key object
  const suite = new CipherSuite({
    kem: new DhkemP256HkdfSha256(),
    kdf: new HkdfSha256(),
    aead: new Chacha20Poly1305()
  });
  const publicKeyObject = await suite.kem.deserializePublicKey(
    Buffer.from(encryptionPublicKey).buffer
  );

  // Encrypt the plaintext wallet private key
  const sender = await suite.createSenderContext({
    recipientPublicKey: publicKeyObject
  });
  const ciphertext = await sender.seal(Buffer.from(plaintextPrivateKey).buffer);

  // Return the encapsulated key and ciphertext, converting ArrayBuffer to Uint8Array
  return {
    encapsulatedKey: new Uint8Array(sender.enc),
    ciphertext: new Uint8Array(ciphertext)
  };
};

// The encryption public key is returned by the `init` request to the Privy API
// For example: BPoOQ5k9nRk37v+XQWkmFEjpvW6RS0HQsPF3+IbhgMlc2Qwp/vz7lln1h0MJj/l0crLUhyyjdmC9RnAcpAkUNVQ=
const base64EncodedEncryptionPublicKey = '<encryption-public-key>';
// The wallet private key in hex format. This may have a '0x' prefix or may not depending on the
// provider you're importing from, so make sure to remove it before encrypting if present as shown below.
// For example: 0xe42f4dc0c8396e93891f05c3a34228c395f9b02505ffd0e79d7d2098af8b20a3
const hexEncodedPlaintextPrivateKey = '<your-wallet-private-key>';

const {encapsulatedKey, ciphertext} = await encryptWithHpke({
  encryptionPublicKey: base64.decode(base64EncodedEncryptionPublicKey),
  plaintextPrivateKey: new Uint8Array(
    Buffer.from(
      // Be sure to remove the `0x` prefix if present
      hexEncodedPlaintextPrivateKey.replace(/^0x/, ''),
      'hex'
    )
  )
});

import {Chacha20Poly1305} from '@hpke/chacha20poly1305';
import {CipherSuite, DhkemP256HkdfSha256, HkdfSha256} from '@hpke/core';
import {base58, base64} from '@scure/base';

const encryptWithHpke = async ({
  encryptionPublicKey,
  plaintextPrivateKey
}: {
  encryptionPublicKey: Uint8Array;
  plaintextPrivateKey: Uint8Array;
}) => {
  // Deserialize the raw key returned by the `init` request to the Privy API to a public key object
  const suite = new CipherSuite({
    kem: new DhkemP256HkdfSha256(),
    kdf: new HkdfSha256(),
    aead: new Chacha20Poly1305()
  });
  const publicKeyObject = await suite.kem.deserializePublicKey(
    Buffer.from(encryptionPublicKey).buffer
  );

  // Encrypt the plaintext wallet private key
  const sender = await suite.createSenderContext({
    recipientPublicKey: publicKeyObject
  });
  const ciphertext = await sender.seal(Buffer.from(plaintextPrivateKey).buffer);

  // Return the encapsulated key and ciphertext, converting ArrayBuffer to Uint8Array
  return {
    encapsulatedKey: new Uint8Array(sender.enc),
    ciphertext: new Uint8Array(ciphertext)
  };
};

// The encryption public key is returned by the `init` request to the Privy API
// For example: BPoOQ5k9nRk37v+XQWkmFEjpvW6RS0HQsPF3+IbhgMlc2Qwp/vz7lln1h0MJj/l0crLUhyyjdmC9RnAcpAkUNVQ=
const base64EncodedEncryptionPublicKey = '<encryption-public-key>';
// The wallet private key in base58 format. This is commonly the format used when exporting a Solana wallet from another provider.
// For example: 4ANrq8ysACrNqmjWnekSPpud8GEdPN9YB7isMBbCxKWYrzcyAWnttYe8dPxfkhkR9mwLh4SfyZx4cUXnJAmZvbQ2
const base58EncodedPlaintextPrivateKey = '<your-wallet-private-key>';

const {encapsulatedKey, ciphertext} = await encryptWithHpke({
  encryptionPublicKey: base64.decode(base64EncodedEncryptionPublicKey),
  plaintextPrivateKey: base58.decode(base58EncodedPlaintextPrivateKey)
});

3. Submission

Submit your encrypted private key to the Privy API by calling the /v1/wallets/import/submit endpoint with the rest of your wallet configuration (e.g. an owner, policies, or signers). See creating a wallet for more information on configuration options.

EVM
Solana

curl --request POST \
  --url https://api.privy.io/v1/wallets/import/submit \
  --header 'Authorization: Basic <encoded-app-credentials>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
    "wallet": {
      "address": "<your-wallet-address>",
      "chain_type": "ethereum",
      "entropy_type": "private-key",
      "encryption_type": "HPKE",
      "ciphertext": "<base64-encoded-encrypted-private-key>",
      "encapsulated_key": "<base64-encoded-encapsulated-key>"
    },
    // Optional additional configuration
    "owner": {...},
    "policy_ids": [...],
    "additional_singers": [...]
  }'

curl --request POST \
  --url https://api.privy.io/v1/wallets/import/submit \
  --header 'Authorization: Basic <encoded-app-credentials>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
    "wallet": {
      "address": "<your-wallet-address>",
      "chain_type": "solana",
      "entropy_type": "private-key",
      "encryption_type": "HPKE",
      "ciphertext": "<base64-encoded-encrypted-private-key>",
      "encapsulated_key": "<base64-encoded-encapsulated-key>"
    },
    // Optional additional configuration
    "owner": {...},
    "policy_ids": [...],
    "additional_singers": [...]
  }'

The endpoint will return the wallet object of your imported wallet:

EVM
Solana

{
  "id": "<privy-wallet-id>",
  "address": "<your-wallet-address>",
  "chain_type": "ethereum",
  "policy_ids": [],
  "additional_signers": [],
  "exported_at": null,
  "imported_at": 1753300563195,
  "created_at": 1753300563197,
  "owner_id": null
}

{
  "id": "<privy-wallet-id>",
  "address": "<your-wallet-address>",
  "chain_type": "solana",
  "policy_ids": [],
  "additional_signers": [],
  "exported_at": null,
  "imported_at": 1753300563195,
  "created_at": 1753300563197,
  "owner_id": null
}

To import a private key wallet with the Rust SDK, use the import() method. The Rust SDK automatically handles the HPKE encryption for secure transmission to the TEE. See architecture for more details.

Usage

use privy_rs::{PrivyClient, generated::types::*};

let client = PrivyClient::new(app_id, app_secret)?;

// Import an Ethereum wallet from private key
let imported_wallet = client
    .wallets()
    .import(
        "0x742d35Cc6635C0532925a3b8D2dB4C5e64b1C0dB", // wallet address
        "your-hex-encoded-private-key", // private key (with or without 0x prefix)
        WalletImportSupportedChains::Ethereum,
        None,   // owner
        vec![], // policy_ids
        vec![], // additional_signers
    )
    .await?
    .into_inner();

println!("Imported wallet {} with address {}", imported_wallet.id, imported_wallet.address);

Parameters and Returns

See the Rust SDK documentation for detailed parameter and return types, including embedded examples:

For REST API details, see the API reference.

The Rust SDK automatically handles the HPKE encryption process internally when importing wallets. You don’t need to manually encrypt the private key - simply provide the raw private key string and the SDK will handle secure transmission to Privy’s infrastructure.

Using imported wallets

Imported wallets function the same way as Privy-generated wallets. See the API reference for Ethereum or Solana for information about how to send transactions and execute other wallet operations.

Embedded wallets

Using wallets

Funding

Webhooks

Gas management

Global wallets

Importing a wallet

Usage

Parameters

Returns

Usage

Parameters

Returns

1. Initialization

2. Encryption

3. Submission

Usage

Parameters and Returns

Using imported wallets

Embedded wallets

Using wallets

Funding

Webhooks

Gas management

Global wallets

​Importing a wallet

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​1. Initialization

​2. Encryption

​3. Submission

​Usage

​Parameters and Returns

​Using imported wallets

Importing a wallet

Usage

Parameters

Returns

Usage

Parameters

Returns

1. Initialization

2. Encryption

3. Submission

Usage

Parameters and Returns

Using imported wallets