> ## Documentation Index
> Fetch the complete documentation index at: https://bkey.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PIN management

> Set, rotate, verify, and remove the signing PIN.

The PIN gates `signMessage`, `signTransactionHash`, and `deleteWallet` when `requirePin` is `true`. It is stored only as a **salted PBKDF2-HMAC-SHA256 digest** (100 000 iterations) in platform secure storage — the raw PIN never touches disk.

The derivation runs in native code, so the 100 000 iterations never block the JavaScript thread.

***

## Set a PIN

Call `setPin` once after wallet provisioning. The PIN must be exactly `BmoniEmbeddedSdk.pinLength` characters (default `6`).

```ts theme={null}
await BmoniEmbeddedSdk.setPin('123456');
```

Throws `pinAlreadySet` if a PIN already exists. Check first:

```ts theme={null}
if (!(await BmoniEmbeddedSdk.hasPin())) {
  await BmoniEmbeddedSdk.setPin('123456');
}
```

***

## Check whether a PIN is set

```ts theme={null}
const hasPin = await BmoniEmbeddedSdk.hasPin();
```

***

## Verify a PIN without throwing

Use `matchPin` to check a PIN without raising an error. This is useful for validating a user's entry before attempting a gated operation.

```ts theme={null}
const matches = await BmoniEmbeddedSdk.matchPin('123456');
if (!matches) {
  // Show "Incorrect PIN" to the user.
}
```

`matchPin` returns `false` when no PIN is set, so use `hasPin` when you need to tell "no PIN" apart from "wrong PIN".

***

## Change a PIN

Requires the current PIN. Both values must be `pinLength` characters.

```ts theme={null}
await BmoniEmbeddedSdk.changePin({
  currentPin: '123456',
  newPin: '654321',
});
```

<Info>
  `changePin` takes an object rather than two positional strings, so you cannot accidentally swap the current and new PIN.
</Info>

***

## Remove a PIN

Removes the stored digest entirely. After removal, `hasPin()` returns `false` and PIN-gated operations are unavailable until a new PIN is set.

```ts theme={null}
await BmoniEmbeddedSdk.removePin('123456');
```

***

## PIN length enforcement

All PIN operations enforce the `pinLength` set in `BmoniEmbeddedSdk.initialize`. Passing a PIN of the wrong length throws `BmoniSignerError` with `errorCode: pinInvalid`.

Read the required length at runtime to drive your UI:

```tsx theme={null}
const requiredLength = BmoniEmbeddedSdk.pinLength; // 6 by default

<TextInput
  maxLength={requiredLength}
  keyboardType="number-pad"
  secureTextEntry
/>;
```

***

## Full example

```ts theme={null}
// 1. One-time setup.
await BmoniEmbeddedSdk.setPin('123456');

// 2. Rotate the PIN.
await BmoniEmbeddedSdk.changePin({
  currentPin: '123456',
  newPin: '654321',
});

// 3. Verify without throwing — useful for a PIN confirmation step.
const ok = await BmoniEmbeddedSdk.matchPin('654321');
console.log('PIN matches:', ok); // true

// 4. Tear down (e.g. on logout).
await BmoniEmbeddedSdk.removePin('654321');
```