# Encrypted backup and restore

AIPAY lives entirely on your device. That is why a backup is not optional — it is the only way to survive a lost phone, a wiped laptop, or "clear browsing data".

## Why you must take a backup

- The wallet, its encrypted recovery phrase, your contacts, merchant settings and order history are stored in your browser's local database (IndexedDB) on **this device only**.
- If that data disappears — new phone, new browser, reinstall, site data cleared, failed OS update — the wallet is gone from that device.
- Nothing is synced to a server. There is no AIPAY account that could put it back.
- Receiving the 12-word recovery phrase is still the ultimate fallback, but a backup also carries your contacts, merchant configuration, products and orders, which the phrase alone cannot restore.

**Take a backup at least once, and again after any significant change** (new wallet, new shop settings, important order history). Store it on a device or drive you control, ideally a second one.

## What a backup contains

One encrypted file, covering both local databases:

| Included | Not included (deliberately) |
|---|---|
| Your wallet(s): encrypted recovery phrase, key material, name, addresses | The **local wallet password (PIN)** — it is never stored anywhere |
| App settings (sanitized copy) | **Biometric** unlock data (`bio_data`, `bio_pin`) and the biometric-enabled flag |
| Contacts | The "install banner dismissed" flag |
| Transaction history | The AI assistant's local password and related local secrets |
| Merchant: shop settings, products, orders | Theme / display preference |

The result: a restored device gets the wallet back, but biometric unlock, the install banner state, the AI local password and the theme must be set up again there. That is intentional — those are per-device conveniences, not wallet data.

## The two passwords (do not confuse them)

There are **two different passwords**, and neither is stored by AIPAY:

| | Local wallet password (PIN) | Backup password |
|---|---|---|
| What it protects | Unlocking the wallet on this device; signing transactions | Encrypting/decrypting the exported backup file |
| Where it is used | Numeric input in the app | The export dialog, or inside CryptoKey.im |
| Length | at least 10 characters | at least 10 characters |
| Set when | Creating / importing a wallet | Taking / restoring a backup |
| Stored anywhere? | No | No — in the CryptoKey flow, AIPAY never even sees it |

**The backup does not contain the wallet password.** So a restored device has the encrypted recovery phrase but still needs the **original wallet password** to unlock it. If you took the backup with one password and have forgotten your wallet password, restoring alone will not help: re-import the 12-word phrase instead.

You may reuse the same string for both, but you lose the benefit of a second, independent secret. A lost backup password means the backup cannot be decrypted — but the recovery phrase can still restore the wallet.

## Export a backup

1. Open **https://aipay.im/en/settings**.
2. Choose **Local Backup** for the plain, offline approach, or **Encrypted Import / Export** for the encrypted file.

### Option A — encrypted JSON file (Local Backup)

1. Enter a **backup password** (at least 10 characters).
2. Tap **Export encrypted backup**.
3. Desktop browsers download the JSON file. On phones and tablets you can use system sharing to save it to Files, a cloud drive, or send it to another device.

The file is encrypted with PBKDF2-SHA256 (310,000 iterations) plus AES-256-GCM. Without the password it is useless — which also means **a lost backup password cannot be recovered**.

### Option B — CryptoKey.im encrypted backup

AIPAY can hand the backup to [CryptoKey.im](https://cryptokey.im) inside an embedded window. The **password is typed inside CryptoKey and never reaches AIPAY**. CryptoKey offers two carriers:

- **`.ckx` file (recommended):** the backup, byte for byte, marked as a CryptoKey file.
- **PNG image:** the encrypted data is hidden in the pixels of a cover image (yours, or one CryptoKey generates). AIPAY checks that the image is big enough before you proceed.

**Keep the carrier as the original file.** Chat apps, social apps, screenshot tools and photo hosting **re-compress images and destroy the hidden data**. If you use the PNG carrier, send/save it only as the original `.png` file (cloud drives and email attachments as files are fine; an image bubble in a chat app is not). When in doubt, use `.ckx`.

## Restore a backup

1. On the new device, open **https://aipay.im/en/import-wallet**.
2. Either:
   - **Restore from backup file / image** — pick the encrypted JSON, `.ckx` file, or original PNG, and decrypt it where prompted; or
   - **Enter the 12-word recovery phrase** directly (no backup file needed).
3. Supply the **local wallet password** you want this device to use. (This is the password for the restored wallet on this device; it does not have to match the backup password.)
4. Reload. The wallet, contacts, settings, products and orders are restored. Then unlock with your wallet password.

If CryptoKey reports a wrong password or a damaged file, AIPAY cannot tell those two cases apart — re-check the file and the password against another copy before assuming the backup is broken.

## Single-device boundaries to remember

- **No automatic sync.** Two devices with the same wallet are independent copies; the same phrase on both is expected.
- **Biometrics, install state, AI password and theme do not travel** with a backup.
- **Never test a restore on your only copy.** Verify the backup opens on a second device (or at least that the file is intact) before you rely on it.
- **The safest backup is the one that is both offline and readable.** An encrypted file you cannot remember the password for is worse than no backup at all.
- **The recovery phrase alone is enough** to rebuild the wallet on a new device, even with no backup file. Write it down as well.

## What is not enabled

The MSG/MSGChain adapter is disabled, so there is nothing MSG-specific to back up today. See [../llms.txt](../llms.txt) for the authoritative feature status.