Exporting private keys

Privy enables your users to export the private for their embedded wallet. This allows them to use their embedded wallet address with another wallet client, such as MetaMask or Phantom.

Due to the sensitive nature of key export, this feature is only available in web environments (React SDK) where the operation can be secured with strict browser security guarantees. If using mobile or non-web SDKs, direct users to a browser or implement a webview with the React SDK for secure key export.

To have your user export their embedded wallet’s private key, use Privy’s exportWallet method:

import {usePrivy} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();

import {usePrivy} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();

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

When invoked, exportWallet will open a modal where your user can copy the full private key for their embedded wallet. The modal will also link your user to a guide for how to load their embedded wallet into another wallet client, such as MetaMask or Phantom.

If your user is not authenticated or has not yet created an embedded wallet in your app, this method will fail.

As an example, you might attach exportWallet to an export wallet button in your app:

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

function ExportWalletButton() {
  const {ready, authenticated, user, exportWallet} = usePrivy();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account) =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'ethereum'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

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

function ExportWalletButton() {
  const {ready, authenticated, user, exportWallet} = usePrivy();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account) =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'ethereum'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

import {usePrivy, type WalletWithMetadata} from '@privy-io/react-auth';
import {useSolanaWallets} from '@privy-io/react-auth/solana';

function ExportWalletButton() {
  const {ready, authenticated, user} = usePrivy();
  const {exportWallet} = useSolanaWallets();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account): account is WalletWithMetadata =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'solana'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

If your application uses smart wallets on EVM networks, exporting the wallet will export the private key for the smart wallet’s signer, and not the smart wallet itself. Users can control their smart wallet via this private key, but will be required to manually use it to sign calls to the contract for their smart wallet directly to use the smart wallet outside of your app.

Exporting HD wallets

If your user has multiple embedded wallets, you can export the private key for a specific wallet by passing the address of your desired wallet as an address parameter to the exportWallet method:

import {exportWallet} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();
await exportWallet({address: 'insert-your-desired-address'});

import {exportWallet} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();
await exportWallet({address: 'insert-your-desired-address'});

import {useSolanaWallets} from '@privy-io/react-auth/solana';
...
const {exportWallet} = useSolanaWallets();
await exportWallet({address: 'insert-your-desired-address'});

If no address is passed to exportWallet, Privy will default to exporting the wallet at walletIndex: 0.

When your user exports their embedded wallet, their private key is assembled on a different origin than your app’s origin. This means neither you nor Privy can ever access your user’s private key. Your user is the only party that can ever access their full private key.

To have your user export their embedded wallet’s private key, use Privy’s exportWallet method:

import {usePrivy} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();

import {usePrivy} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();

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

If your user is not authenticated or has not yet created an embedded wallet in your app, this method will fail.

As an example, you might attach exportWallet to an export wallet button in your app:

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

function ExportWalletButton() {
  const {ready, authenticated, user, exportWallet} = usePrivy();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account) =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'ethereum'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

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

function ExportWalletButton() {
  const {ready, authenticated, user, exportWallet} = usePrivy();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account) =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'ethereum'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

import {usePrivy, type WalletWithMetadata} from '@privy-io/react-auth';
import {useSolanaWallets} from '@privy-io/react-auth/solana';

function ExportWalletButton() {
  const {ready, authenticated, user} = usePrivy();
  const {exportWallet} = useSolanaWallets();
  // Check that your user is authenticated
  const isAuthenticated = ready && authenticated;
  // Check that your user has an embedded wallet
  const hasEmbeddedWallet = !!user.linkedAccounts.find(
    (account): account is WalletWithMetadata =>
      account.type === 'wallet' &&
      account.walletClient === 'privy' &&
      account.chainType === 'solana'
  );

  return (
    <button onClick={exportWallet} disabled={!isAuthenticated || !hasEmbeddedWallet}>
      Export my wallet
    </button>
  );
}

Exporting HD wallets

If your user has multiple embedded wallets, you can export the private key for a specific wallet by passing the address of your desired wallet as an address parameter to the exportWallet method:

import {exportWallet} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();
await exportWallet({address: 'insert-your-desired-address'});

import {exportWallet} from '@privy-io/react-auth';
...
const {exportWallet} = usePrivy();
await exportWallet({address: 'insert-your-desired-address'});

import {useSolanaWallets} from '@privy-io/react-auth/solana';
...
const {exportWallet} = useSolanaWallets();
await exportWallet({address: 'insert-your-desired-address'});

If no address is passed to exportWallet, Privy will default to exporting the wallet at walletIndex: 0.

To export a wallet’s private key via the REST API, use the /v1/wallets/{wallet_id}/export endpoint. This endpoint uses Hybrid Public Key Encryption (HPKE) to securely transmit the private key.

Server-side export is only enabled for wallets created and managed fully via server-side APIs. User wallets created using client-side SDKs, regardless of provisioned session signers, cannot be exported via REST API.

Wallet export is restricted to wallet owners and enabled by default, unless explicitly disabled by a DENY policy. For wallets that are NOT assigned an owner, they can only be exported if they are assigned a DENY policy.

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/export \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --header 'privy-authorization-signature: <privy-authorization-signature>'
  --data '{
    "encryption_type": "HPKE",
    "recipient_public_key": "<base64-encoded-recipient-public-key>"
  }'

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/export \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --header 'privy-authorization-signature: <privy-authorization-signature>'
  --data '{
    "encryption_type": "HPKE",
    "recipient_public_key": "<base64-encoded-recipient-public-key>"
  }'

import {generateAuthorizationSignature} from "@privy-io/server-auth/wallet-api"

// Generate a base64-encoded key pair for the recipient
const keypair = await crypto.subtle.generateKey(
  {
    name: "ECDH",
    namedCurve: "P-256"
  },
  true,
  ["deriveKey", "deriveBits"]
)
const [publicKey, privateKey] = await Promise.all([
  crypto.subtle.exportKey("spki", keypair.value.publicKey),
  crypto.subtle.exportKey("pkcs8", keypair.value.privateKey)
])
const [publicKeyBase64, privateKeyBase64] = [
  Buffer.from(publicKey).toString("base64"),
  Buffer.from(privateKey).toString("base64")
]

// Create the signature for the request
const input = {
  headers: {
    "privy-app-id": "your-privy-app-id",
  },
  method: "POST",
  url: `https://api.privy.io/v1/wallets/${walletId}/export`,
  version: 1,
  body: {
    encryption_type: "HPKE",
    recipient_public_key: publicKeyBase64,
  },
};
const signature = generateAuthorizationSignature(
  input: input,
  authorizationPrivateKey: "your-privy-authorization-private-key" // This should be the private key of your authorization key
)

// Make the request to export the wallet
const res = await fetch(
  `https://api.privy.io/v1/wallets/${walletId}/export`,
  {
    method: input.method,
    headers: {
      ...input.headers,
      "Content-Type": "application/json",
      "privy-authorization-signature": signature as string,
      Authorization: generateBasicAuthHeader(
        "your-privy-app-id",
        "your-privy-app-secret"
      ),
    },
    body: JSON.stringify(input.body),
  }
);

import requests
import base64
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives import serialization

# Generate a key pair for the recipient
private_key = ec.generate_private_key(ec.SECP256R1())
public_key = private_key.public_key()

# Export keys to base64
public_key_base64 = base64.b64encode(
    public_key.public_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PublicFormat.SubjectPublicKeyInfo
    )
).decode('utf-8')

# Prepare the request data
data = {
    "encryption_type": "HPKE",
    "recipient_public_key": public_key_base64,
}

# Make the request to export the wallet
response = requests.post(
    f'https://api.privy.io/v1/wallets/{wallet_id}/export',
    headers={
        'Authorization': 'Basic <encoded-value>',
        'Content-Type': 'application/json',
        'privy-app-id': '<privy-app-id>',
        'privy-authorization-signature': '<privy-authorization-signature>'
    },
    json=data
)

The endpoint will return the encrypted private key along with the encapsulation information needed for decryption:

{
  "encryption_type": "HPKE",
  "ciphertext": "Zb2XqqIpPlQKJhkb9GRoXa8N6pKLAlozYnXg713g7mCu5vvn6tGIRbeJj4XOUQkFeB9DRxKg",
  "encapsulated_key": "BLplgxEpMz+WMxDSOzGZe+Oa5kkt9FTxUudRRyO5zRj/OaDbUaddlE18uNv8UKxpecnrSy+UByG2C3oJTgTnGNk="
}

Decrypting the Private Key

The exported private key is encrypted using Hybrid Public Key Encryption (HPKE) with the following configuration:

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

To decrypt the private key, you’ll need to use these same parameters along with your recipient private key. Here’s how to implement the decryption in several languages:

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

/**
 * Decrypts a message using HPKE (Hybrid Public Key Encryption).
 *
 * Uses P-256 keys with HPKE to decrypt an encrypted message. The function expects base64-encoded
 * inputs and handles all necessary key imports and context creation for HPKE decryption.
 *
 * @param privateKeyBase64 Base64-encoded private key in PKCS8 format used for decryption.
 * @param encapsulatedKeyBase64 Base64-encoded raw public key bytes representing the
 *     encapsulated key.
 * @param ciphertextBase64 Base64-encoded encrypted message using base64url encoding that
 *     will be decrypted.
 * @returns A Promise that resolves to the decrypted message as a UTF-8 string.
 * @throws {Error} If decryption fails or if any of the inputs are incorrectly formatted.
 */
async function decryptHPKEMessage(
  privateKeyBase64: string,
  encapsulatedKeyBase64: string,
  ciphertextBase64: string
): Promise<string> {
  // Initialize the cipher suite
  const suite = new CipherSuite({
    kem: new DhkemP256HkdfSha256(),
    kdf: new HkdfSha256(),
    aead: new Chacha20Poly1305()
  });

  // Convert base64 to ArrayBuffer using browser APIs
  const base64ToBuffer = (base64: string) =>
    Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)).buffer;

  // Import private key using WebCrypto
  const privateKey = await crypto.subtle.importKey(
    'pkcs8',
    base64ToBuffer(privateKeyBase64),
    {
      name: 'ECDH',
      namedCurve: 'P-256'
    },
    true,
    ['deriveKey', 'deriveBits']
  );

  // Create recipient context and decrypt
  const recipient = await suite.createRecipientContext({
    recipientKey: privateKey,
    enc: base64ToBuffer(encapsulatedKeyBase64)
  });

  return new TextDecoder().decode(await recipient.open(base64ToBuffer(ciphertextBase64)));
}

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

/**
 * Decrypts a message using HPKE (Hybrid Public Key Encryption).
 *
 * Uses P-256 keys with HPKE to decrypt an encrypted message. The function expects base64-encoded
 * inputs and handles all necessary key imports and context creation for HPKE decryption.
 *
 * @param privateKeyBase64 Base64-encoded private key in PKCS8 format used for decryption.
 * @param encapsulatedKeyBase64 Base64-encoded raw public key bytes representing the
 *     encapsulated key.
 * @param ciphertextBase64 Base64-encoded encrypted message using base64url encoding that
 *     will be decrypted.
 * @returns A Promise that resolves to the decrypted message as a UTF-8 string.
 * @throws {Error} If decryption fails or if any of the inputs are incorrectly formatted.
 */
async function decryptHPKEMessage(
  privateKeyBase64: string,
  encapsulatedKeyBase64: string,
  ciphertextBase64: string
): Promise<string> {
  // Initialize the cipher suite
  const suite = new CipherSuite({
    kem: new DhkemP256HkdfSha256(),
    kdf: new HkdfSha256(),
    aead: new Chacha20Poly1305()
  });

  // Convert base64 to ArrayBuffer using browser APIs
  const base64ToBuffer = (base64: string) =>
    Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)).buffer;

  // Import private key using WebCrypto
  const privateKey = await crypto.subtle.importKey(
    'pkcs8',
    base64ToBuffer(privateKeyBase64),
    {
      name: 'ECDH',
      namedCurve: 'P-256'
    },
    true,
    ['deriveKey', 'deriveBits']
  );

  // Create recipient context and decrypt
  const recipient = await suite.createRecipientContext({
    recipientKey: privateKey,
    enc: base64ToBuffer(encapsulatedKeyBase64)
  });

  return new TextDecoder().decode(await recipient.open(base64ToBuffer(ciphertextBase64)));
}

from cryptography.hazmat.primitives import serialization
from hpke import CipherSuite, KEMId, KDFId, AEADId
import base64

async def decrypt_hpke_message(
    private_key_base64: str,
    encapsulated_key_base64: str,
    ciphertext_base64: str
) -> str:
    """
    Decrypts a message using HPKE (Hybrid Public Key Encryption) with P-256 keys

    Args:
        private_key_base64: Base64-encoded private key in PKCS8 format used for decryption.
        encapsulated_key_base64: Base64-encoded raw public key bytes representing the
                                encapsulated key.
        ciphertext_base64: Base64-encoded encrypted message using base64url encoding that
                          will be decrypted.

    Returns:
        str: The decrypted message as a UTF-8 string

    Raises:
        ValueError: If decryption fails or if inputs are incorrectly formatted
    """
    # Initialize the cipher suite
    suite = CipherSuite.new(
        KEMId.DHKEM_P256_HKDF_SHA256,
        KDFId.HKDF_SHA256,
        AEADId.CHACHA20_POLY1305
    )

    # Convert base64 to bytes
    raw_public_key = base64.b64decode(encapsulated_key_base64)
    private_key_bytes = base64.b64decode(private_key_base64)
    ciphertext = base64.b64decode(ciphertext_base64)

    # Import private key
    loaded_private_key = serialization.load_der_private_key(
        private_key_bytes,
        password=None
    )
    private_number = loaded_private_key.private_numbers().private_value
    private_bytes = private_number.to_bytes(32, byteorder="big")  # P-256 uses 32 bytes
    private_kem_key = suite.kem.deserialize_private_key(private_bytes)

    # Create recipient context and decrypt
    encapsulated_kem_key = suite.kem.deserialize_public_key(raw_public_key)
    recipient_context = suite.create_recipient_context(
        encapsulated_kem_key.to_public_bytes(),
        private_kem_key
    )

    # Decrypt and return as UTF-8 string
    return recipient_context.open(ciphertext).decode("utf-8")

Embedded wallets

Using wallets

Funding

Gas and asset management

Session signers

Global wallets

Advanced Topics

Exporting private keys

Exporting HD wallets

Exporting HD wallets

Decrypting the Private Key

Embedded wallets

Using wallets

Funding

Gas and asset management

Session signers

Global wallets

Advanced Topics

​Exporting HD wallets

​Exporting HD wallets

​Decrypting the Private Key

Exporting HD wallets

Exporting HD wallets

Decrypting the Private Key