PIN - OneKey Developers

On this page

How to handle PIN entry on OneKey devices with recommended UX.

Essentials

Protected calls trigger UI_REQUEST.REQUEST_PIN when the device is locked.
Pro/Touch/Pro 2/Neo require on-device PIN entry. For other models, inspect inputPinOnSoftware.support; host blind-PIN support depends on firmware. Prefer on-device entry when it is available.
Close the prompt on UI_REQUEST.CLOSE_UI_PIN_WINDOW / CLOSE_UI_WINDOW or when the originating operation settles. Invalidate its pending submission callback.

Support matrix (software blind PIN)

Device	Software Blind PIN	Device-only Input
OneKey Classic / 1s / 1s Pure / Mini	Firmware-dependent; check `inputPinOnSoftware.support`	On-device entry may be offered by the host-input flow
OneKey Touch	Not supported	Yes
OneKey Pro	Not supported	Yes
OneKey Pro 2 / Neo	Not supported	Yes

UI design notes

Offer only the input methods supported by the current device, firmware, and UI request. When both are available, use one dialog with Enter on device as the default and Enter here (blind PIN) as an alternative.
Blind PIN keypad is a fixed 3x3 layout; never echo real digits.

Blind PIN mapping example


import { UI_RESPONSE } from "@onekeyfe/hd-core";
 
// Completed sequence of host keypad positions, numbered 1..9.
declare const selectedPositions: number[];
// Copy this from the current REQUEST_PIN event.
declare const responseCorrelation: { interactionId: string; deviceId: string } | undefined;
const BLIND_KEYBOARD_MAP = ['7','8','9','4','5','6','1','2','3'];
if (!selectedPositions.length || selectedPositions.some(position =>
  !Number.isInteger(position) || position < 1 || position > 9
)) throw new Error('Invalid PIN keypad sequence');
 
HardwareSDK.uiResponse({
  ...responseCorrelation,
  type: UI_RESPONSE.RECEIVE_PIN,
  payload: selectedPositions.map(position => BLIND_KEYBOARD_MAP[position - 1]).join(''),
});

Events to responses


import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 
HardwareSDK.on(UI_EVENT, (msg) => {
  if (msg.type === UI_REQUEST.REQUEST_PIN) {
    if (msg.payload.deviceOnly || msg.payload.type === 'ButtonRequest_PinEntry' || msg.payload.type === 'ButtonRequest_AttachPin') {
      // Show the device prompt and wait; this notification does not need a reply.
      return;
    }
    HardwareSDK.uiResponse({
      ...msg.payload.responseCorrelation,
      type: UI_RESPONSE.RECEIVE_PIN,
      payload: '@@ONEKEY_INPUT_PIN_IN_DEVICE',
    });
  }
});