简介

面向开发者的 OneKey 硬件钱包集成文档，适用于 Web 和原生应用。

Hardware SDK 1.2.x 支持两种协议。Protocol V1 和 Protocol V2 走同一套 JavaScript API。第一次接入请先看 快速开始。

本页是入门层 —— 帮你选对 SDK 包并装上。端到端流程（搜设备 → 事件 → PIN/passphrase → 首次签名）和参数、事件、错误处理的完整说明，请看 Core API Guide。

选择传输协议

USB 场景一律推荐 @onekeyfe/hd-common-connect-sdk。@onekeyfe/hd-web-sdk 仅用于插件端（iframe 嵌入形式）。

连接方式

平台指南

低层协议与自定义通道参考：底层传输插件与协议

安装 SDK

按运行时选择一个入口安装：

# Web / 桌面 WebUSB（推荐）
npm i @onekeyfe/hd-common-connect-sdk
 
# React Native BLE
npm i @onekeyfe/hd-ble-sdk
 
# 原生宿主 + 底层插件（Android/iOS/Flutter 桥接）
npm i @onekeyfe/hd-common-connect-sdk
 
# 插件端 iframe（仅插件端）
npm i @onekeyfe/hd-web-sdk

传输细节：

• WebUSB：WebUSB 指南
• React Native BLE：BLE 指南
• 原生 Android / iOS / Flutter：通过底层传输插件桥接 JS，见各平台页面。
• 自定义通道与协议：底层传输插件与协议

初始化 SDK

按照运行时选择对应的初始化方式，避免混用。

Web / 桌面 WebUSB

使用 @onekeyfe/hd-common-connect-sdk：

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

React Native BLE

使用 @onekeyfe/hd-ble-sdk：

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

原生桥接 / 低层协议

使用 @onekeyfe/hd-common-connect-sdk。下例展示环境选项；实际接入还需按底层传输插件提供并传入原生 BLE 插件：

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
import type { LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
 
// Provide an implemented native BLE bridge; this is a preparation fragment.
declare const plugin: LowlevelTransportSharedPlugin;
const initialized = await HardwareSDK.init({
  env: 'lowlevel',
  debug: false,
  fetchConfig: true,
}, undefined, plugin);
if (!initialized) throw new Error('SDK initialization failed');

插件端 Iframe

使用 @onekeyfe/hd-web-sdk（仅插件端）。SDK 默认 iframe 地址是 https://jssdk.onekey.so/<安装包版本>/，来自 getSDKVersion()。除非自建 iframe，否则不要传 connectSrc。

当前文档构建跟踪的 SDK 包版本是 1.2.8-alpha.12. 插件 iframe 默认地址是 https://jssdk.onekey.so/1.2.8-alpha.12/. 请省略 connectSrc，让 SDK 使用安装包版本。只有自建 iframe 时才覆盖，且必须与安装的 @onekeyfe/hd-web-sdk 版本一致。

import HdWebSdk from '@onekeyfe/hd-web-sdk';
 
const HardwareSDK = HdWebSdk.HardwareWebSdk;
 
const initialized = await HardwareSDK.init({
  debug: false,
  // omit connectSrc — SDK fills https://jssdk.onekey.so/<installed-version>/
});
if (!initialized) throw new Error('SDK initialization failed');

下一步

HardwareSDK.init(...) 完成之后，先用 快速开始 读出第一个地址，其余流程在 Core API Guide 里端到端讲清楚：

• 1.2.0 机型矩阵：设备
• Pro 2 / Neo 支持哪些链：链支持
• Protocol V1 / V2（自动识别）：协议
• 打开 / 恢复钱包：钱包会话
• 传输选择和重连：传输 · 重连
• 固件 V2 / V3 / V4：固件升级
• 标准生命周期（init → search → getDeviceState → subscribe → call + uiResponse → cleanup）：Core API Guide → 标准生命周期
• 地址、签名与设备方法共享的参数：通用参数
• 标识符参考（connectId / deviceId / passphraseState / …）：Identifiers
• PIN 输入流程：PIN 码
• Passphrase / 隐藏钱包流程：Passphrase

设备与传输兼容性

蓝牙、USB、Air-Gap 与协议族支持状态

设备	协议	蓝牙	USB	Air-Gap
OneKey Classic 1s 经典款 Classic 1s	V1	支持	支持	不支持
OneKey Classic 1s Pure Classic 1s Pure 无电池版本	V1	支持	支持	不支持
OneKey Mini 紧凑型 USB 钱包	V1	不支持	支持	不支持
OneKey Touch 全触屏体验	V1	支持	支持	不支持
OneKey Pro 旗舰版，支持指纹识别	V1	支持	支持	支持
OneKey Pro 2 Protocol V2 专业版	V2	支持	支持	支持
OneKey Neo Protocol V2 轻量版，无摄像头	V2	支持	支持	不支持

Air-Gap 模式： OneKey Pro 和 Pro 2 支持通过二维码离线签名（Air-Gap），无需 USB 或蓝牙连接，签名前由用户在设备上核对详情。详见 Air-Gap 集成。

核心包

包名	用途	NPM	版本
@onekeyfe/hd-common-connect-sdk	统一的 Web/原生 SDK 接口；推荐作为传输层入口	npm
@onekeyfe/hd-ble-sdk	纯 React Native 蓝牙协议栈（推荐用于 RN 项目）	npm
@onekeyfe/hd-transport-react-native	React Native 传输层副作用/桥接	npm
@onekeyfe/hd-transport-web-device	Web 环境设备访问传输层	npm
@onekeyfe/hd-transport-emulator	模拟器传输层（无需物理设备即可开发和测试）	npm
@onekeyfe/hd-transport-http	HTTP 桥接传输层	npm
@onekeyfe/hd-transport-lowlevel	底层主机适配器协议（用于原生集成）	npm
@onekeyfe/hd-core	核心事件、常量、消息处理	npm
@onekeyfe/hd-shared	共享工具和类型	npm
@onekeyfe/hd-web-sdk	Web SDK 封装（不推荐；建议使用 hd-common-connect-sdk）	npm

• 更新日志：releases 

延伸阅读

• 底层传输与消息协议（调试 / 自定义适配器场景）：底层传输插件
• 从老的 hd-web-sdk 方案迁移：迁移指引

支持

致用户：本文档主要面向开发者。如果您在使用我们的产品时遇到问题，请查阅帮助中心或提交工单。

• 帮助中心 
• 问题反馈 

相关仓库

• OneKey App (app-monorepo) 
• OneKey 固件 
• OneKey 硬件 JS SDK 

立即体验