Connect your first device

Install Hardware SDK 1.2.x, connect a device, and confirm your first address.

This page is the first-run path. After it works, pick a transport guide and read the Core API Guide for PIN, passphrase, events, and signing.

Hardware SDK 1.2.0 speaks Protocol V1 (Classic / Mini / Touch / Pro) and Protocol V2 (Pro 2 / Neo) through the same JavaScript API. You do not choose the protocol in init().

1. Pick a package

npm i --save-exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

pnpm add --save-exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

yarn add --exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

The command selects published 1.2.x packages and saves exact versions. Keep the SDK, core, and shared packages on the same release and commit your lockfile. If you embed @onekeyfe/hd-web-sdk, omit connectSrc so it matches the installed package.

2. Initialize once

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
const initialized = await HardwareSDK.init({
  env: 'webusb',
  debug: false,
  fetchConfig: true,
});
if (!initialized) throw new Error('SDK initialization failed');

Call init() once at app entry. Do not mix @onekeyfe/hd-web-sdk and @onekeyfe/hd-common-connect-sdk in the same runtime.

3. Search, identify, read an address

Register the UI event handler before protected calls so locked devices can complete PIN input. For WebUSB, authorize the device from the user’s Connect button before discovery:

import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
// Run directly in the Connect button handler.
if (!navigator.usb) throw new Error('WebUSB is unavailable in this browser');
await navigator.usb.requestDevice({ filters: ONEKEY_WEBUSB_FILTER });

Then discover devices. This example requires exactly one candidate; if several devices are available, let the user select one before continuing.

const devices = await HardwareSDK.searchDevices();
if (!devices.success || !devices.payload.length) {
  throw new Error('No OneKey device found');
}
 
// Select explicitly in the application when more than one device is available.
if (devices.payload.length !== 1) throw new Error('Select exactly one device before continuing');
const { connectId } = devices.payload[0];
if (!connectId) throw new Error("Missing connectId");
 
const state = await HardwareSDK.getDeviceState(connectId);
if (state.success === false) 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 === false) throw new Error(address.payload.error);
console.log(address.payload.address);

Always check success before reading payload. useEmptyPassphrase: true keeps this first call on the standard wallet so a leftover hidden-wallet session cannot silently change the address.

getDeviceState() is the V1/V2 read. getFeatures() is Protocol V1 only; Pro 2 and Neo must use getDeviceState().

WebUSB requires HTTPS and a user gesture. BLE requires OS Bluetooth permission.

Device and wallet support

• The SDK detects Protocol V1 vs V2 from the live device. Do not branch on USB PID, BLE name, or product string. See Protocol V1 and V2.
• Pro 2 and Neo use the same methods as Classic / Pro. Device differences are listed in Devices.
• Open or switch a wallet with openWalletSession. getPassphraseState is deprecated. See Wallet Sessions.

Next

1. Already on 1.1.x: Upgrade to Hardware SDK 1.2
2. Wire PIN / passphrase UI events: Core API Guide
3. Connect for real on your platform: Transport
4. Handle drops: Disconnects and reconnection
5. Which chains on which device: Chain Support
6. Sign a transaction: Signer Guides
7. Firmware: Firmware Update
8. Try without hardware: Playground