On this page
Identifiers
Use connectId to route a request, deviceId to bind it to the device’s current seed, and passphraseState to bind it to a hidden wallet. These values are not interchangeable.
Identifier reference
| Field | Purpose | Where to read it | How to use it |
|---|---|---|---|
connectId | Transport routing key | Successful searchDevices().payload entry | First argument to device and wallet methods. Re-enumerate after reconnect. |
serialNo | Physical hardware identity when available | Discovery after initialization; getDeviceState().payload.identity.serialNo | Display or correlate the unit independently of USB/BLE. Do not use as a routing key. |
deviceId | Current seed-lifetime identity | getDeviceState().payload.identity.deviceId; successful openWalletSession | Second argument to wallet methods. Detect reset, recovery, or a different wallet. |
passphraseState | Hidden-wallet fingerprint | Successful hidden openWalletSession result | Pass in every address/signing request for that hidden wallet. Persist with deviceId. |
uuid | Deprecated compatibility identifier | Some device/search results | Prefer serialNo for hardware identity and connectId for routing. May be empty before initialization. |
firmware session_id | Internal unlock handle | Managed inside SDK Core | Do not read, log, persist, or send it on public calls. |
name, label, deviceType | Display and capability information | Discovery/device state | Not unique identifiers and not proof of protocol or wallet identity. |
connectId — the routing key
USB and BLE connections to the same physical unit have different connectId values. Keep connection records separate by transport. A connection ID is not guaranteed to be the physical serial number: a USB descriptor can provide a routing path before hardware identity is available.
Treat the value as opaque. BLE formats depend on the host platform (for example an Android address or iOS peripheral UUID). Never convert it into another transport’s format or use it as evidence of device authenticity.
searchDevices may return connectId: null. Select a candidate with a usable connection ID before making a device call.
deviceId — the wallet identity check
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');
const address = await HardwareSDK.evmGetAddress(connectId, deviceId, {
path: "m/44'/60'/0'/0/0",
useEmptyPassphrase: true,
showOnOneKey: true,
});
if (!address.success) throw new Error(address.payload.error);The standard wallet and hidden wallets on the same seed share the seed-lifetime deviceId. A hidden wallet additionally needs its passphraseState.
On DeviceCheckDeviceIdError, stop the operation and refresh device state. Ask the user to confirm the intended wallet before updating an existing binding; silently replacing the cached ID could direct a later request to another wallet.
device_id versus deviceId
device_id is the legacy field in Protocol V1 getFeatures() results. New code reads the normalized identity.deviceId from getDeviceState(), which supports both protocol families. Discovery can return deviceId: null before initialization.
Hidden-wallet binding
const opened = await HardwareSDK.openWalletSession(connectId, {
mode: 'select-hidden',
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden' || !opened.payload.passphraseState) {
throw new Error('A hidden wallet was not opened');
}
const address = await HardwareSDK.evmGetAddress(connectId, opened.payload.deviceId, {
path: "m/44'/60'/0'/0/0",
passphraseState: opened.payload.passphraseState,
showOnOneKey: true,
});
if (!address.success) throw new Error(address.payload.error);Persist the binding only after a successful response. Protect it as wallet-related application data; never persist the passphrase itself or firmware session handles.
Omitting passphraseState does not bind a call to the intended hidden wallet. Use either a verified hidden-wallet fingerprint or useEmptyPassphrase: true for the standard wallet, never both.
If a binding mismatch occurs, stop and let the user select the intended wallet again. Do not overwrite the binding and automatically replay a signing request.
Method signatures
| Pattern | Examples |
|---|---|
| SDK lifecycle, no connection argument | init, searchDevices, on/off, dispose |
Device or wallet selection, connectId | getDeviceState, openWalletSession, deviceSettings, deviceVerify |
Wallet operation, connectId + deviceId | evmGetAddress, btcSignTransaction, solSignTransaction |
| Hidden-wallet operation | The wallet operation plus passphraseState in its params |
Some methods allow omitted identifiers for compatibility. Follow each method’s public signature, and select a specific device in multi-device applications. UI-response correlation uses a separate request identity; copy responseCorrelation from the event as described in UI Events.