Identifiers

OneKey hardware APIs return several identifier-looking fields across searchDevices, getFeatures, getPassphraseState, and chain method responses. This page is the single reference for what each one means, when it changes, and how its shape varies by transport.

Looking for call parameters (passphraseState, initSession, useEmptyPassphrase, …)? See Common Params.

Four layers of identifiers

Each identifier belongs to one of four lifetime tiers. Knowing the tier tells you when to refresh or persist a value.

Which IDs do you pass in?

Only three of the identifiers here are inputs to SDK calls — the rest are fields you read out of responses.

Call-signature patterns

// Device-level — just connectId
HardwareSDK.getFeatures(connectId);
HardwareSDK.deviceLock(connectId, {});
HardwareSDK.getPassphraseState(connectId, { initSession: true });
 
// Wallet-level (standard wallet) — connectId + deviceId
HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
});
 
// Wallet-level (hidden wallet) — connectId + deviceId + passphraseState
HardwareSDK.evmSignTransaction(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  transaction: { /* ... */ },
  passphraseState, // obtained once from getPassphraseState
});

Which methods need which IDs

What happens if you skip or mistype an ID?

⚠️ The silent-standard-wallet case is the sneakiest. If you forget passphraseState when querying a hidden wallet, you’ll get the standard wallet’s address back without any error. Always obtain passphraseState via getPassphraseState once and attach it to every subsequent wallet-level call — or pass useEmptyPassphrase: true explicitly if you intend the standard wallet.

Physical hardware identifiers

Immutable values that identify the physical unit. Survive resets, seed changes, and firmware updates.

Transport connection identifiers

Identify a specific connection. The same physical device has different connectId values on USB vs BLE — these are not interchangeable.

connectId — the routing key

Every call to an SDK method takes connectId as the first argument. It tells the SDK which device/connection to route the request to. Stable across searchDevices() calls on the same transport.

⚠️ If your app supports both USB and BLE for the same physical device, cache connectId separately per transport and never cross-use them.

Other transport-level fields

Seed / wallet state identifier

deviceId (in searchDevices payload) and device_id (in getFeatures payload) are the same value — they identify the currently-loaded seed on the device.

Usage

const { payload: features } = await HardwareSDK.getFeatures(connectId);
const deviceId = features.device_id;
 
// Pass deviceId on every signing call — the SDK uses it to detect that
// the seed didn't change mid-flow and aborts with `DeviceCheckDeviceIdError`
// if it did.
await HardwareSDK.evmSignTransaction(connectId, deviceId, { ... });

If you see DeviceCheckDeviceIdError, re-run getFeatures(connectId) and update your cached deviceId.

Session identifiers

Two session-level identifiers that look similar but serve different purposes.

session_id — ephemeral session token

Short-lived random token the device mints when a passphrase session is initialised. Returned in features.session_id after getPassphraseState or any call that initialises a session.

• Invalidated on lock (auto-lock, manual lock, USB disconnect).
• Used internally by the SDK to keep the device’s cached passphrase alive.
• Rarely surfaced to app code directly — most apps only need passphraseState.

passphraseState — hidden wallet identifier

Deterministic identifier for the hidden wallet bound to a specific passphrase. Returned by getPassphraseState(). The same passphrase on the same seed always produces the same passphraseState, so you can recognise “is this the same hidden wallet I saw last time?” without persisting the passphrase itself.

• Pass as the passphraseState common-param on every SDK call that must stay on the same hidden wallet.
• Cache across processes by persisting (deviceId, passphraseState, session_id) together and calling preloadSessionCache on startup.
• Clearing the cached passphraseState does not invalidate the hidden wallet — the wallet is reproducible by re-entering the same passphrase.

Putting it together — real example

searchDevices() for a Classic 1S connected via USB (node-usb transport) returns:

{
  "connectId":  "CLB21J0013",                      // transport-level (on USB = device serial)
  "uuid":       "CLB21J0013",                      // physical (on USB = connectId)
  "deviceType": "classic1s",                       // transport-level
  "deviceId":   "399A2470958EDB3D9F3826C2",        // seed state; changes on reset
  "path":       "399A2470958EDB3D9F3826C2",        // transport internal; varies by transport
  "name":       "OneKey Classic 1S"                // display label
}

A subsequent getFeatures(connectId) adds:

{
  "device_id":       "399A2470958EDB3D9F3826C2",   // same as deviceId above
  "onekey_serial":   "CLB21J0013",                 // physical; same as connectId on USB
  "session_id":      "80cb8aef933870e4…",          // ephemeral; resets on lock
  "passphrase_protection": true,
  "unlocked":        true,
  "label":           "OneKey Classic 1S"
}

After the user enters their passphrase, getPassphraseState(connectId) returns:

{
  "success": true,
  "payload": "abc123…"                             // passphraseState — pass to subsequent calls
}

Common confusions

connectId vs uuid

On USB transports they happen to be the same string (the device serial). On BLE they may diverge: connectId is the OS-level connection handle (MAC / CoreBluetooth UUID / …) while uuid is whatever stable identifier the SDK surfaces for app use. Always route calls via connectId — treat uuid as a human-readable label only if you need a single stable ID across transports.

deviceId vs uuid / onekey_serial

• deviceId — changes on reset / seed change. Use for “is this the same wallet?”.
• uuid / onekey_serial — never changes. Use for “is this the same physical device?”.

session_id vs passphraseState

• session_id expires when the device locks; passphraseState does not.
• passphraseState identifies which hidden wallet; session_id authenticates this live session.
• Persist (passphraseState, session_id) together to reuse a session across invocations; if the device locked between invocations, discard the cached session_id and force a fresh unlock.

device_id (snake_case) vs deviceId (camelCase)

Same value, different contexts:

• device_id appears in getFeatures().payload (firmware-level, snake_case).
• deviceId appears in searchDevices()[] and as the second positional argument to most SDK methods (JavaScript-level, camelCase).

See also

• Common Params — parameters you pass in to SDK calls
• Passphrase — hidden wallet flow
• PIN Code — PIN entry flow
• Search Devices — returns connectId, uuid, deviceType, deviceId
• Get Features — returns device_id, session_id, onekey_serial, …