Introduction

Developer-focused documentation for integrating OneKey hardware in Web and Native apps.

This page is the orientation layer — pick the right SDK package for your platform and install it. For the end-to-end walkthrough (search → events → PIN/passphrase → first signing call) plus parameters, events, and error handling, see the Core API Guide.

Choose Your Transport

USB integrations should use @onekeyfe/hd-common-connect-sdk; use @onekeyfe/hd-web-sdk only when the host mandates an iframe/plugin setup.

Connection Methods

Platform Guide

Low-level protocol and custom channels: Low-Level Transport Plugin & Protocol

Install SDK

Pick one entry by runtime:

# Web / desktop WebUSB (recommended)
npm i @onekeyfe/hd-common-connect-sdk
 
# React Native BLE
npm i @onekeyfe/hd-ble-sdk
 
# Native host with low-level plugin (Android/iOS/Flutter bridge)
npm i @onekeyfe/hd-common-connect-sdk
 
# Plugin iframe host only (plugin-only)
npm i @onekeyfe/hd-web-sdk

Transport details:

• WebUSB: WebUSB guide
• React Native BLE: BLE guide
• Native Android / iOS / Flutter: bridge JS calls through low-level transport plugins (see pages for examples).
• Custom channel & protocol: Low-Level Transport Plugin & Protocol

Initialize the SDK

Use the initialization method that matches your runtime—avoid mixing SDK entries.

Web / Desktop WebUSB

Use @onekeyfe/hd-common-connect-sdk:

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
await HardwareSDK.init({
  env: 'webusb',
  debug: process.env.NODE_ENV !== 'production',
  fetchConfig: true,
});

React Native BLE

Use @onekeyfe/hd-ble-sdk:

import HardwareSDK from '@onekeyfe/hd-ble-sdk';
 
await HardwareSDK.init({
  debug: __DEV__,
});

Native Bridge / Low-level

Use @onekeyfe/hd-common-connect-sdk:

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
await HardwareSDK.init({
  env: 'lowlevel',
  debug: process.env.NODE_ENV !== 'production',
  fetchConfig: true,
});

Plugin Iframe Host

Use @onekeyfe/hd-web-sdk (plugin-only):

import { HardwareSDK } from '@onekeyfe/hd-web-sdk';
 
await HardwareSDK.init({
  debug: process.env.NODE_ENV !== 'production',
  connectSrc: 'https://jssdk.onekey.so/1.1.19/', // iframe host
});

Next steps

After HardwareSDK.init(...) returns, the rest of the flow — device discovery, event wiring, PIN/passphrase handling, signing — is documented end-to-end in the Core API Guide:

• Standard lifecycle (init → search → getFeatures → subscribe → call + uiResponse → cleanup): Core API Guide → Standard lifecycle
• Call parameters accepted by every method: Common params
• Identifier reference (connectId / deviceId / passphraseState / …): Identifiers
• PIN entry flow: PIN Code
• Passphrase / hidden-wallet flow: Passphrase

Device and Transport Compatibility

Support status for Bluetooth, USB, and Air-Gap connections

Device	Bluetooth	USB	Air-Gap
OneKey Classic 1s OneKey Classic 1s	Supported	Supported	N/A
OneKey Classic 1s Pure Battery-free edition	Supported	Supported	N/A
OneKey Mini Compact USB-only wallet	N/A	Supported	N/A
OneKey Touch Full touchscreen experience	Supported	Supported	N/A
OneKey Pro Premium with fingerprint security	Supported	Supported	Supported

Air-Gap Mode: OneKey Pro supports air-gapped signing via QR codes — no USB or Bluetooth connection required, providing the highest level of security. See Air-Gap Integration for details.

Core Packages

Package	Purpose	NPM	Version
@onekeyfe/hd-common-connect-sdk	Unified SDK surface for Web/Native; recommended entry for transports	npm
@onekeyfe/hd-ble-sdk	Pure React Native BLE stack (recommended for RN projects)	npm
@onekeyfe/hd-transport-react-native	React Native transport side-effects/bridge	npm
@onekeyfe/hd-transport-web-device	Web transport for device access in web contexts	npm
@onekeyfe/hd-transport-emulator	Emulator transport (develop and test without a physical device)	npm
@onekeyfe/hd-transport-http	HTTP bridge transport	npm
@onekeyfe/hd-transport-lowlevel	Low-level host adapter contract (for native integrations)	npm
@onekeyfe/hd-core	Core events, constants, message wiring	npm
@onekeyfe/hd-shared	Shared utilities and types	npm
@onekeyfe/hd-web-sdk	Web SDK wrapper (not recommended; prefer hd-common-connect-sdk)	npm

• Changelog: releases 

Further reading

• Low-level transport & message protocol (for debugging or custom adapters): Low-Level Transport Plugin
• Migration from the legacy hd-web-sdk flow: Migration Guide

Support

For users: This documentation is primarily for developers. If you encounter issues while using our products, please consult our Help Center or submit a support ticket.

• Help Center 
• Discussions 
• Issues 

Related Repositories

• OneKey App (app-monorepo) 
• OneKey Firmware 
• OneKey Hardware JS SDK 

Try It Out