Importing a Private Key: Where the Wallet Breaks
Importing a private key is an operation that looks trivial in a demo and falls apart on real devices.
The user pastes a string from a backup, the app shows "wallet restored," and the balance is empty: the address was derived along a different derivation path, and the funds sit on a branch the interface doesn't display.
This isn't a cosmetic defect — it's a loss of access, and the person who comes to sort it out already has assets on the line.
The first class of failures is key formats. Mnemonics, WIF, hex without a prefix, a key with a checksum and without one — these are all different inputs, and a parser written for one variant either silently accepts the rest or crashes with an unclear import error.
It's worse when the string passes validation but is interpreted as a key of a different type: the wallet gets created, an address gets generated, and there's no access to the previous funds.
The second class is an interrupted write to secure storage. Import isn't a single operation but a sequence: decrypt, verify, write to the keychain, update state.
If the app is minimized or the system unloads the process between steps, a half-finished state remains: the record exists, but the link to the account was never created. On the next launch, the user sees an empty list and repeats the import, spawning duplicates.
The third class is derivation. The same key yields different addresses depending on the chosen scheme and index.
If the app doesn't let you choose the scheme explicitly and doesn't show which address will result before confirmation, the user only learns about the discrepancy from a zero balance.
Let's break down how this is solved at the architecture level rather than with patches in the interface.
What a correct key import delivers
A correct import is not "an input field and a button." It is format parsing (WIF, JSON keystore, BIP39 mnemonic, raw hex), checksum validation, address derivation, and comparison against the expected one.
If even a single step is skipped, the user gets a "successful import" of the wrong key — and only finds out when the funds are no longer visible in the balance.
The metric by which we judge quality: the share of successful imports on the first attempt. On a raw parser it stays at 70–80% — the rest are typos, extra spaces, keys from a different format.
When checksum validation and input normalization are built into the flow, the share reaches 95%+. The difference is the people who did not go to support and did not abandon the wallet.
Access recovery time is the second metric. If the import requires manually entering the address and network, the user spends minutes and makes a mistake in choosing the network.
When the app determines the network itself from the key format and shows the address before confirmation, recovery takes seconds. This directly affects retention: a person who has lost access to their wallet only comes back if they got it back quickly.
The class of failures that a correct import closes is "the key was accepted, but it is the wrong one." It is more dangerous than an obvious error: the user is sure everything is fine, while the assets go to an address they have no access to.
Verifying key integrity and comparing the derived address with the original eliminates this class entirely — the import either passes with a confirmed address or honestly reports that the key does not fit.
Format compatibility is the third metric. Support for WIF, JSON keystore, and mnemonic with automatic format detection removes the question "will my key work?". The user pastes a string, the app figures out what it is on its own, and offers the right path. This lowers the share of support requests and makes the import predictable for any key source.
Key formats and how they are accepted
Importing a private key is always a choice between convenience of input and control over where the key ends up after import. Below are four real options that people choose between at the start, and their engineering constraints.
| Option | When it fits | Constraints |
|---|---|---|
| Mnemonic phrase | Restoring a wallet on a new device, moving between applications | Requires checksum verification and whitespace normalization; sensitive to keyboard layout and autocorrect; remains on screen and in the clipboard |
| Hex string | Importing a single key, service and test scenarios | No checksum — a typo yields a valid but foreign key; length and alphabet must be validated manually |
| Keystore file | Bulk transfer, export from another wallet | Many formats, some are encrypted with a password; requires parsing the structure and an explicit rejection on an unknown version |
| Hardware device | Keys that must not leave the device | The key is not extractable — only the public part is imported; a communication channel with the device is required |
A mnemonic phrase and a hex string pass through an input field, and therefore through the clipboard and logs. We mitigate this at the application level: blocking screenshots on the input screen, clearing the clipboard after pasting, disabling autocorrect and keyboard suggestions.
For a keystore file, we add schema validation before writing to the device's secure storage, so that a corrupted file does not settle in persistent memory.
A hardware device changes the model itself: the private key never enters the application at all, and signing is performed on the device side.
This removes a whole class of risks related to storage, but adds a dependency on the exchange protocol and the behavior of a specific model.
The format's constraints determine what we can actually verify before import: the checksum, length, alphabet, schema version. Anything that fails validation is rejected before writing — otherwise the wallet will accept a key that cannot sign a single transaction.
How we embed key import into an application
Private key import is an operation where a single mistake nullifies the entire security model of a wallet.
That is why we run it as a separate engineering project with fixed stages, rather than as "add a screen with an input field." Below is how the process is structured from audit to handing the solution over to your team.
-
Audit of the current storage scheme. We analyze where secrets currently reside: in the operating system's keychain, in the device's secure module, or in ordinary files and settings.
We examine who has access to this data, what ends up in backups and logs, and how encryption at rest is implemented. The output is a map of secret flows and a list of places where the key could leak.
-
Designing the import flow. We define the input formats — mnemonic phrase, hexadecimal string, keystore file — and their validation rules. We design how the key enters the application, where it is decrypted, and at what point the intermediate copy is destroyed. We separately work through error behavior: invalid checksum, foreign format, interrupted input.
-
Configuring secure storage. We place the key only in the device's hardware-isolated storage, and restrict access to it via biometrics or a system passcode. We prevent the secret from ending up in screenshots, the clipboard, system journals, and backups. The private key never leaves the secure perimeter, even at the moment of transaction signing.
-
Testing on test sets. We run the import on prepared sets: valid keys of various formats, corrupted data, edge cases, access attempts without authentication. We verify recovery after a failure and the correctness of the addresses that the application outputs after import.
-
Handing over the solution. We deliver to your team the storage configuration, flow diagrams, secret handling policies, and maintenance documentation. We conduct a code walkthrough with the developers so that import support remains within the team without our ongoing support.
Each stage ends with a verifiable artifact — a diagram, a configuration, or a test report. Describe your task: we will come back with a timeline estimate and a stage-by-stage work plan.
Access policies and key protection on the device
Once a key lands on a device, it lives by the rules we describe before the first line of code.
Access policies define who can initiate an operation and under what conditions: confirmation via biometrics or a system code, session time limits, a ban on exporting the material beyond the secure perimeter.
The storage configuration determines where the key resides — in the device's hardware module or in an isolated encrypted area — and what happens when access to it is attempted from outside the application.
A separate layer is key protection at the moment of import: the material must not end up in logs, temporary files, or the clipboard.
We design the flow so that the key is unpacked only in memory and wiped immediately after being written to storage, while all intermediate states are inaccessible to other processes on the device.
As a result, the client receives a package that allows the system to be operated and handed over between teams:
- storage configurations describing protection levels and the conditions that trigger them;
- import and signing flow diagrams — from input to writing and confirmation;
- access policies: roles, confirmation triggers, session lifetime;
- a recovery procedure — what to do in case of device loss, media change, or rollback;
- a failure matrix: which scenarios are blocked, which require manual confirmation;
- documentation for the support service with an analysis of typical requests;
- instructions for auditing — which events are logged and in what form they are stored.
Such a set removes the main risk: when the key is already in the user's hands, but the team does not understand by what rules it is protected and what to do in an emergency. Describe your task — we will come back with an estimate and a plan for each layer.
Case: key import without losing funds
A client came to us with a classic pain point: users complained that after reinstalling the app, the wallet did not see their funds, even though the recovery phrase had been saved.
The investigation showed that the problem was not in the blockchain, but in the import itself — different key formats, mismatched derivation paths, and the lack of clear validation on input.
Out of ten import attempts, roughly six completed successfully, while the rest hung in an undefined state: zero balance, transactions failing, and the user not knowing what to do next.
What it was before
Every failed import turned into a support request: the person sent screenshots, we asked for logs, figured out the key format, and manually suggested the derivation path.
Resolving a single case took an average of 40 minutes, and some users managed to delete the app and lose access to their funds forever. The successful import rate stayed at 62% — even though the wallet itself worked correctly.
What was changed
Our engineers rewrote the import flow: they added automatic key format detection, checksum verification, and explicit network selection with an address preview before confirmation.
If a key did not match any supported format, the user received a clear error with a hint instead of a blank screen. They also separately closed the recovery-after-failure scenario — the import state is saved, and the process can be resumed from the same step.
What it became
The successful import rate grew from 62% to 99.4%. The time to restore access dropped from 40 minutes to 2 minutes — now it is just a few screens with address verification.
Support requests on the topic of import fell by 8 times: typical cases are resolved with hints right in the interface, and only truly non-standard situations are left for the engineers.
The solution is built on Trust Wallet Core — a proven library for working with keys on mobile platforms.
How is key import different from recovery by phrase?
Importing a private key and recovering by phrase solve the same problem — restoring the user's access to funds on a new device — but they approach it from different directions.
With import, you transfer an already existing key: the app accepts it as is, checks the format and checksum, places it in secure storage, and uses it to sign transactions.
With recovery by phrase, the key is not transferred — it is re-derived from the mnemonic using a standard algorithm, and the output is the same address, because deterministic generation produces the same result on any device.
Hence the first difference in risks. An imported key is a ready-made secret: if it leaks from the clipboard, a screenshot, or a chat, the funds are gone irrevocably, with no rollback.
A mnemonic is also a secret, but it is usually stored offline on paper or metal, and it does not pass through messengers as often as key strings do.
However, recovery has its own cost of error: one mixed-up word position or an incorrect checksum — and you will get a valid but someone else's empty address, where nothing will arrive.
The second difference is in the checks we build in. For key import, it is critical to confirm that the format and network prefix match, otherwise a key from one network will silently create an address in another.
For the phrase, we check each word against the dictionary, the order, and the checksum, and after deriving the key we compare the resulting address with the expected one — this catches typos before the user sends funds.
In both scenarios, the key never leaves the device's secure perimeter, and buffers are cleared after use.
The difference in approaches also affects support: import requires an explicit warning about irreversibility and confirmation that the user understands the consequences, while recovery requires input hints and protection against word substitution.
We cover both paths separately, because mixing up their checks is a direct way to lose funds for no good reason.
Common technical concerns
Importing a private key is an operation where the cost of a mistake is maximal: an incorrect format, insecure storage, or a failure when reading from a hardware device results in loss of funds rather than an error message.
Below are the technical concerns that clients most often raise during the design phase, and how we address them in the architecture.
Which key formats should the application accept?
Compatibility is determined not by the "popularity" of a format, but by which wallets and devices the user already has.
We support import from common text and QR representations, including formats with and without a mnemonic phrase, with checksum verification before writing to storage. An unsupported format is rejected at the input with a clear message rather than a "silent" error.
How is the key stored on the device?
The private key does not end up in the application's regular storage and is not written to logs. It is placed in a protected area of the operating system — a hardware-backed key store accessible only after biometric authentication.
This prevents the key from being extracted during backup, debugging, or compromise of the application itself.
Does import work with hardware devices?
Yes, for scenarios with elevated security requirements we implement support for hardware wallets: the key never leaves the device, and the application receives only signed transactions. This removes the need to store the key on the phone and moves verification to a separate device.
What happens if an import fails?
Error handling is designed as part of the user journey: an invalid format, a corrupted checksum, denied access to the protected storage, and an interrupted operation are all distinguished.
Each scenario produces a separate message and does not leave partially written data — the import is atomic, and on failure the state is rolled back.
If you have your own requirements for compatibility or devices — describe the task, and we will come back with an estimate and an implementation plan.
Let's discuss your key import task
To come back with an estimate and a work plan rather than generalities, we need a minimum of input about your product. Private key import touches several layers at once: cryptography, secret storage, the interface, and compatibility with existing wallets.
The more precisely you describe the current state, the fewer assumptions we'll build into the plan and the more predictable the result will be.
- Which key and mnemonic formats need to be supported: hex, WIF, BIP-39, keystore files, hardware storage — and in what form the user receives them.
- Which networks and account types are a priority: one network or several, whether addresses of different standards are needed from a single key.
- Where secrets are currently stored: a system secure container, password encryption, biometrics — and what protection requirements you are setting.
- How input is structured: manual entry, QR scanning, paste from clipboard, file import — and what happens on an error or duplicate.
- Whether there is already a working wallet from which users will transfer keys, and whether backward compatibility is needed.
- The platforms and minimum OS versions you are targeting, as well as app store requirements for handling keys.
- What is critical for you in terms of timelines: launch by a date, phased rollout, or first testing on a limited audience.
As a result, you will receive an estimate of effort by stage, a work plan with the order of implementation and checkpoints, a scheme for storing and processing the key, as well as a list of risks with options for closing them.
Separately, we will discuss how the rollback will be structured and what will go into the first version versus what can be moved to the second.
Describe the task in free form — what already exists, what needs to be added, and what result you are aiming for. We'll come back with an estimate and a work plan, and we'll agree on the next step after we've verified the details.