WebUSB Connection

Connect a browser app directly to OneKey with @onekeyfe/hd-common-connect-sdk. This path does not require an iframe or OneKey Bridge.

Requirements

• A WebUSB-capable browser and a secure context. Feature-detect navigator.usb; show a supported-browser message when it is unavailable.
• A user gesture to open the USB chooser.
• An initialized OneKey device and a data-capable USB cable.
• UI event handling for PIN, passphrase, and device confirmation.

1. Install and initialize

npm i @onekeyfe/hd-common-connect-sdk @onekeyfe/hd-core @onekeyfe/hd-shared

Keep the SDK packages on the same version. Initialize once near app startup:

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');

2. Register UI events

Use the complete Core API UI handler before reading an address or signing. It distinguishes input requests from device notifications and preserves response correlation.

Your application supplies the dialogs. Host PIN entry needs a blind keypad; device-only PIN and button requests need an instruction screen, not a host approval button. Cancel the selected SDK operation when the user cancels, and remove listeners when your integration is torn down.

3. Authorize from a user action

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

Handle chooser cancellation in your button handler. Opening the chooser does not prove that the device is initialized. Previously authorized devices may be enumerated without reopening it.

4. Select the connection and read identity

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');
 
// This example requires one device. Use a device selector for multiple candidates.
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');

Do not assume discovery includes deviceId, and do not infer the protocol from USB descriptors. See Search Devices.

5. Confirm a receiving address

const address = await HardwareSDK.btcGetAddress(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
if (!address.success) throw new Error(address.payload.error);
 
// Display address.payload.address in your application after device confirmation.

This example explicitly selects the standard wallet. For a hidden wallet, open it with openWalletSession and pass its passphraseState on both address and signing calls. Keep the wallet context and derivation path consistent.

Disconnect and cleanup

• Subscribe to DEVICE.DISCONNECT and invalidate the current connection in the UI.
• Re-enumerate and read device state after reconnecting.
• Serialize calls per device. Do not automatically repeat a signing or firmware-update request after a timeout.
• Call dispose() when tearing down the SDK or switching transports, then initialize before further use.

See Disconnects and reconnection.

Troubleshooting

Continue with Signer Guides or Error Codes.