On this page

Search Devices

Discover connection candidates. searchDevices() returns a result object; the device list is in payload only when success is true.

Discovery is not proof that a device is initialized or that its wallet is unlocked. BLE discovery can return an advertised name and connection ID before a connection exists. USB discovery may also return a descriptor without initialized identity fields.

Method


const result = await HardwareSDK.searchDevices();
if (!result.success) throw new Error(result.payload.error);
if (!result.payload.length) throw new Error('No OneKey device found');
 
// For this example, select the only connected device.
// In an app, ask the user to choose when multiple devices are present.
if (result.payload.length !== 1) throw new Error('Select a device before continuing');
const { connectId } = result.payload[0];
if (!connectId) throw new Error('Device connection is unavailable');
 
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');

WebUSB authorization belongs in a user-initiated flow. BLE scanning requires the platform’s Bluetooth permissions. See WebUSB or React Native BLE.

Parameters

The parameter object is optional. See the searchDevices type and Common Params for the installed SDK version.

Result fields

Field	Type	Meaning
`connectId`	`string \| null`	Transport routing key. Pass a non-null value to later device calls.
`connectProtocol`	`'V1' \| 'V2' \| undefined`	Available after an active protocol probe; do not infer it from the advertised name.
`serialNo`	`string \| null \| undefined`	Physical serial when available after initialization.
`deviceId`	`string \| null`	Seed-lifetime identity when available; refresh using `getDeviceState`.
`uuid`	`string`	Deprecated compatibility field. It can be empty before initialization; prefer `serialNo` for physical identity.
`deviceType`	`IDeviceType`	Detected model, or unknown before initialization.
`name`	`string`	Display name; not a unique identifier.
`commType`	`OneKeyDeviceCommType`	Communication type reported by the transport.

The exact public shape is SearchDevice. Do not depend on additional internal fields such as path.

USB and BLE use different connectId values for the same physical device. Re-enumerate after reconnect and refresh state before reusing a wallet binding. See Identifiers.

Failure handling

On failure, payload contains error and an optional code. Handle the code rather than matching error text. An empty successful list means no candidates were found; it is not an SDK failure.

Do not log the complete device list or device objects. Keep diagnostics to the operation status and non-sensitive counts.