How to integrate Clear Signing into your wallet

This guide shows you how to display human-readable transaction details in your wallet by integrating Clear Signing through Ledger’s Device Management Kit (DMK) and Ethereum signer.

Partner program: A valid originToken issued by Ledger identifies your application to Ledger services and enables Transaction Checks and the full supported Clear Signing experience. Contact the team to discuss an integration.

How it works

When a user signs a transaction, the Ethereum signer resolves the ERC-7730 descriptor for the target contract through its context module and displays the human-readable fields — recipient, amount, approval type, requesting dApp — on the signer’s Secure Screen instead of raw calldata.

The context module is the component that fetches descriptors and security context on your behalf. Ledger provides a default implementation, so you do not have to resolve registry entries or decide which ones to trust yourself. If you need control over that resolution, you can supply your own with withContextModule — see the Ethereum Signer Kit reference.

Both the wallet and the dApp must support ERC-7730 for the details to display. If no descriptor exists for the target contract, the signer falls back to blind signing.

Prerequisites

A browser environment that supports WebHID
An optional originToken issued by Ledger for Transaction Checks and the full supported Clear Signing experience
A working Device Management Kit setup — see Device interaction: getting started for device discovery and connection

Integrate Clear Signing

Install the packages

npm


npm install @ledgerhq/device-management-kit \
  @ledgerhq/device-transport-kit-web-hid \
  @ledgerhq/device-signer-kit-ethereum

yarn


yarn add @ledgerhq/device-management-kit \
  @ledgerhq/device-transport-kit-web-hid \
  @ledgerhq/device-signer-kit-ethereum

pnpm


pnpm add @ledgerhq/device-management-kit \
  @ledgerhq/device-transport-kit-web-hid \
  @ledgerhq/device-signer-kit-ethereum

Set up the DMK and connect to a signer

Build the Device Management Kit with a transport, discover devices, and open a session. This is standard DMK setup — follow Device interaction: getting started and the Device Management Kit guide for the full connection lifecycle. You end up with a dmk instance and a sessionId.

Initialize the Ethereum signer

originToken is optional to initialize SignerEthBuilder and its default context module. Pass a valid token issued by Ledger to identify your application to Ledger services and enable Transaction Checks and the full supported Clear Signing experience. Without a token, signing remains available and basic Clear Signing may still be supported, but advanced contract context may be unavailable and some transactions may fall back to blind signing.

signer-setup.ts


import { SignerEthBuilder } from "@ledgerhq/device-signer-kit-ethereum";
 
const signerEth = new SignerEthBuilder({
  dmk,
  sessionId,
  originToken: "your-origin-token", // Optional; issued by Ledger
}).build();

Keep an originToken out of version control. Inject it at build time from an environment variable or your configuration service rather than committing it to your repository.

Sign a transaction

Clear Signing applies automatically when matching metadata is available — there is nothing extra to call. The signing API requires a derivation path and returns a cancellable action with an observable; use the Ethereum Signer Kit signTransaction reference for the current call and result handling.

For the full Ethereum signer API — including the current signTransaction, signMessage, and signTypedData call patterns — see the Ethereum Signer Kit reference.

Implementation checklist

Set up the DMK with the WebHID transport and connect to the signer
Configure an originToken when your integration needs Ledger services and the full supported Clear Signing experience
Implement the signTransaction, signMessage, and signTypedData flows
Show users whether Clear Signing is active, or whether the transaction will use blind signing
Add error handling for connection failures and signing rejections
Test the Clear Signing display on a physical Ledger signer

Best practices

Secure the origin token. If you use one, keep it out of version control and inject it from build or runtime configuration.
Show signing status. Tell users whether Clear Signing is active for a given transaction. When no descriptor is available, display a clear blind-signing warning.
Handle errors gracefully. Device disconnections and user rejections are expected — implement retry logic and meaningful error messages rather than silent failures.

Troubleshooting

Clear Signing is not appearing on the signer

Verify that all of the following are true:

If used, your originToken is correctly configured and not expired
A descriptor exists for the target contract in the registry
You are using the latest published versions of the DMK and Ethereum signer packages
The transaction targets a supported EVM chain

Device connection fails or the picker does not appear

Confirm the browser supports WebHID
Ensure device discovery is called from within a user gesture handler (a click or keypress event)
Verify the signer is unlocked and the Ethereum app is open
Check that transport permissions are granted in the browser

See Device interaction: getting started for the full connection flow.

signMessage or signTypedData does not trigger Clear Signing

Clear Signing for EIP-712 messages requires matching metadata in the registry for the target domain. If none exists, the signer falls back to blind signing. Ask the protocol team to author and publish metadata through ClearSigning.org Build .

Resources

Ethereum Signer Kit reference Device Management Kit Registry submission process

Your wallet now displays human-readable transaction details for every contract that has a descriptor in the registry. On Ledger touchscreen signers, Clear Signing works alongside Transaction Check for an additional layer of threat detection.