On this page
Wallet Sessions
This page is the hardware wallet session: which seed / passphrase context is unlocked on the device.
It is not Agent Wallet Session. Agent Wallet is a product on top of OneKey GUI. Hardware sessions exist on Classic / Pro / Pro 2 / Neo whether or not Agent Wallet is involved.
Public identity
Persist only this pair as a wallet binding:
| Field | Meaning | Persist? |
|---|---|---|
deviceId | Current seed lifetime (device_id from Features / DeviceState) | Yes |
passphraseState | Hidden-wallet fingerprint. null on the standard wallet | Yes, if hidden |
firmware session_id | Device-side unlock handle | No. Core keeps it internally |
If you skip passphraseState on a hidden wallet, address and signing APIs may succeed on the standard wallet with no error. Always pass useEmptyPassphrase: true or a real passphraseState.
Preferred API (1.2.0)
New integrations should open a wallet with openWalletSession:
import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
// Standard wallet
const standard = await HardwareSDK.openWalletSession(connectId, {
mode: OpenWalletSessionMode.Standard,
});
if (!standard.success) throw new Error(standard.payload.error);Or let the user select a hidden wallet:
// Choose this flow instead of the standard-wallet example.
const hidden = await HardwareSDK.openWalletSession(connectId, {
mode: OpenWalletSessionMode.SelectHidden,
});
if (!hidden.success) throw new Error(hidden.payload.error);
if (hidden.payload.walletType !== 'hidden' || !hidden.payload.passphraseState) {
throw new Error('A hidden wallet was not opened');
}Store payload.deviceId, payload.walletType, and payload.passphraseState. Then pass those values on address / signing calls. Core resumes the required wallet context inside that method. Do not call openWalletSession before every signer.
openWalletSession has no resume-hidden mode. Passing mode: 'resume-hidden' returns CallMethodInvalidParameter. Load the stored binding and pass passphraseState on the next address / sign call.
Deprecated compatibility API
getPassphraseState is deprecated. Existing apps may keep it plus initSession / useEmptyPassphrase / passphraseState on each call. Core still maps that path onto Protocol V1 and V2. New code should use openWalletSession.
Do not mix openWalletSession({ mode }) with useEmptyPassphrase / initSession on the same call.
Attach-to-PIN
Some Pro / Pro 2 units can bind a hidden wallet to a dedicated PIN. The public API still returns walletType: 'hidden' and a passphraseState. You do not implement a second session protocol for Attach-to-PIN.
If the SDK returns DeviceCheckUnlockTypeError, the current unlock type cannot reach the wallet you asked for. Lock the device and let the user unlock with the intended PIN; do not retry the same binding in a loop.