How to integrate Clear Signing into your wallet
Integrate Clear Signing into your wallet to provide human-readable transaction information for your users.
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 starting the steps below.
How it works
Wallet providers implement Clear Signing through Ledger’s Device Management Kit (DMK) and Device Signer Kit (DSK). When a user signs a transaction, the DSK fetches metadata for the target contract from the Clear Signing Registry and sends the human-readable field data to the Ledger signer. The signer then displays the formatted transaction details rather than the raw calldata.
Why DMK? The DMK was built with Clear Signing in mind. It provides observable-based patterns, TypeScript-first design, and automatic metadata fetching for all EVM-compatible chains.
Prerequisites
- A browser environment that supports WebHID
- An
originTokenfrom Ledger’s partner program
Integrate Clear Signing
Install the required packages
# Core DMK and transport
npm install @ledgerhq/device-management-kit \
@ledgerhq/device-transport-kit-web-hid \
# Ethereum signer for Clear Signing
@ledgerhq/device-signer-kit-ethereumInitialize the DMK
import {
DeviceManagementKitBuilder,
ConsoleLogger
} from "@ledgerhq/device-management-kit";
import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";
const dmk = new DeviceManagementKitBuilder()
.addLogger(new ConsoleLogger())
.addTransport(webHidTransportFactory)
.build();Connect to the device
This step must be triggered by a user gesture (such as a button click) because browsers require user interaction to open a WebHID device picker.
// startDiscovering() opens the browser's device picker
const discoveredDevices = await dmk.startDiscovering();
// In practice, present a UI so the user selects their device
const device = discoveredDevices[0];
const sessionId = await dmk.connect({
deviceId: device.id,
});Initialize the Ethereum signer with Clear Signing
import { SignerEthBuilder } from "@ledgerhq/device-signer-kit-ethereum";
const signerEth = new SignerEthBuilder({
dmk,
sessionId,
originToken: "your-origin-token", // Obtained through Ledger's partner program
}).build();The originToken identifies your wallet to the Clear Signing Registry and enables metadata fetching. Store it securely and do not expose it in client-side code. To obtain your token, complete the partner program enrollment at the partner intake form.
Sign a transaction
// Build your transaction object
const transaction = {
to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract on Ethereum mainnet
value: "0x0",
data: "0xa9059cbb000000000000000000000000...", // ERC-20 transfer calldata
chainId: 1,
nonce: 0,
gasLimit: "0x5208",
maxFeePerGas: "0x...",
maxPriorityFeePerGas: "0x...",
};
// Clear Signing is applied automatically when metadata exists for the contract
const signature = await signerEth.signTransaction(transaction);
// The user's signer displays human-readable fields (Recipient, Amount)
// rather than raw hex calldataFor complete documentation including device discovery patterns, connection lifecycle management, and advanced configuration options, see the Device Interaction documentation.
Implementation checklist
originTokensignTransaction, signMessage, and signTypedData flowsBest practices
originToken in client-side code. Load it from an environment variable or server-side configuration.Troubleshooting
Clear Signing is not appearing on the signer
Verify that all of the following are true:
- • Your
originTokenis correctly configured and not expired - • A metadata file exists for the target contract in the registry
- • You are using the latest published versions of the DMK and DSK packages
- • The transaction targets a supported EVM chain
Device connection fails or the picker does not appear
Common causes and solutions:
- • Confirm the browser supports WebHID/WebUSB
- • Ensure
startDiscovering()is called from within a user gesture handler (click or keypress event) - • Verify the signer is unlocked and the Ethereum app is open on the device
- • Check that transport permissions have been granted in the browser
- • Try disconnecting and reconnecting the USB cable
signMessage or signTypedData does not trigger Clear Signing
Clear Signing for EIP-712 messages requires a matching eip712 context in the registry metadata file for the target domain. If no matching file exists, the signer falls back to blind signing.
Ask the protocol team to add EIP-712 metadata to the registry.
Your wallet is now ready to display Clear Signing information for all contracts that have registered metadata. Users will see human-readable transaction details on their signer for thousands of protocols automatically.
Resources
With Clear Signing integrated, your wallet automatically displays human-readable information for thousands of protocols, protecting users from blind signing attacks.
