Skip to main content

Serialize & export wallets

Serialization converts your wallet into a structured object that you can safely store or transfer. All signing wallet types — phrase-based, seed-based, xpriv-based, and private key-based — can be serialized.

Serialization is the simplest, most universal way to back up and restore your wallet. Use the serialized data later with deserializeWallet() to re-import the wallet exactly as it was.

Encrypted vs. unencrypted

Wallets can be serialized with or without encryption. If the wallet is encrypted, the serialized output contains ciphertext that can only be decrypted with the password. If serializing without encryption, a console warning is shown — pass { acknowledge: true } to suppress it.

How to serialize​

import { importWallet } from 'chaingate'

const wallet = importWallet({ phrase: 'some bip39 phrase...' })

// Encrypt the wallet first
await wallet.encrypt('strong-password-here', async () => {
  return prompt('Enter password:')
})

// Serialize — output is encrypted
const serialized = await wallet.serialize()
console.log(JSON.stringify(serialized))
// Store serialized safely for future use

Unencrypted wallet​

const wallet = importWallet({ phrase: 'some bip39 phrase...' })

// Serialize without encryption (warning printed to console)
const serialized = await wallet.serialize()

// Suppress the warning
const serialized = await wallet.serialize({ acknowledge: true })
Store securely

Even when encrypted, store serialized wallet data in a private location accessible only to the user. If someone obtains it, they may attempt to brute-force your password. Use a strong, unique password.

Restoring a serialized wallet​

To restore a wallet, pass the serialized data to deserializeWallet():

import { deserializeWallet } from 'chaingate'

// For encrypted wallets, provide an askForPassword callback
const wallet = deserializeWallet(serializedData, async () => {
  return prompt('Enter password:')
})

// For unencrypted wallets
const wallet = deserializeWallet(serializedData)

Check out Deserialize for more details.

Key points​

  • Encryption optional: Encrypted wallets serialize to ciphertext. Unencrypted wallets serialize plaintext (with a warning).
  • Universal: Phrase, seed, xpriv, and private key wallets can all be serialized.
  • View-only wallets: XpubWallet and PublicKeyWallet do not have secret material and are not serialized through this mechanism — simply store the xpub or public key string directly.
  • Brute force risk: If leaked, attackers may try to guess your password. Strong passwords are essential.
  • Compatibility: Restore with deserializeWallet() at any time, on any device.