Skip to main content

Wallet serialization (exporting)

Serialization converts your entire wallet into a single, encrypted string that you can safely store or transfer.
All wallet types—phrase-based, seed-based, private key–based, or keystore-based—can be serialized.

Serialization is the simplest, most universal way to back up and restore your wallet.
Use this string later with initializeWallet.deserialize({...}) to re-import the wallet exactly as it was.

Encryption required

Wallets must be encrypted before they can be serialized. If you try to serialize a wallet that is not encrypted, the library will throw a WalletIsNotEncrypted error.

Learn how to encrypt your wallet

Refer to the Wallet in-memory encryption guide in the documentation for instructions on how to secure your wallet with a password before serialization.

How to serialize​

After initializing or creating a encrypted wallet, call its .serialize() method:

import { initializeWallet } from 'chaingate'

async function example() {
  const wallet = await initializeWallet.fromPhrase({
    apiKey: 'your-api-key-from-dashboard',
    phrase: 'some bip39 phrase...',
    encrypt: {
        password: 'g5#fdi6fyJuym...',
        askForPassword: askForPasswordFunction
    }  
  })

  // Now serialize the wallet
  const serialized = await wallet.serialize()
  console.log(serialized)

  // You can store `serialized` safely for future use
}
Store securely

A serialized wallet file doesn’t require the same level of protection as a raw private key or seed phrase, but it must still be stored securely in a private location accessible only to the user.

If someone obtains your serialized string but doesn’t know your encryption password, they can only see limited information like public keys or derivation paths — but they may still attempt to brute-force your password. To protect your wallet from such attacks, use a strong, unique password.

Restoring a serialized wallet​

To restore a wallet, pass the serialized string back to initializeWallet.deserialize():

import { initializeWallet } from 'chaingate'

const wallet = await initializeWallet.deserialize({
  serialized: 'previously-obtained-serialized-string'
})

Check out Import from serialized wallet for more details on deserialization.

Key points​

  • Encryption required: Attempting to serialize an unencrypted wallet throws WalletIsNotEncrypted.
  • Universal: Any wallet type (phrase, seed, private key, keystore) can be serialized.
  • Brute force risk: If leaked, attackers may try to guess your password. Strong passwords are essential.
  • Private storage: Store the serialized string in a location only the user can access.
  • Compatibility: Restore with initializeWallet.deserialize() at any time, on any device.