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: Wallet integration requires enrollment in Ledger’s partner program to obtain an originToken. Contact the team to discuss integration and receive your token before you start.

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 originToken from Ledger’s partner program
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 with your origin token

The default context module requires an originToken. It identifies your application to Ledger’s security services and enables Clear Signing along with the other transaction security features — Transaction Check and Web3 checks, and trusted names. Without a valid token, those features are unavailable.

signer-setup.ts


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

Keep your 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 a descriptor exists for the target contract — there is nothing extra to call.

transaction-signing.ts


const signature = await signerEth.signTransaction(transaction);
// The signer displays human-readable fields (Recipient, Amount) when a
// descriptor exists; otherwise it falls back to blind signing.

For the full Ethereum signer API — signTransaction, signMessage, signTypedData, and more — see the Ethereum Signer Kit reference.

Implementation checklist

Set up the DMK with the WebHID transport and connect to the signer
Configure the signer with your partner program originToken
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. 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:

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 a matching eip712 descriptor in the registry for the target domain. If none exists, the signer falls back to blind signing. Ask the protocol team to add EIP-712 metadata.

Resources

Ethereum Signer Kit reference Device Management Kit Clear Signing Registry

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.