hak-ledger-plugin

The first Ledger hardware-wallet plugin for the Hedera Agent Kit.

Gives a Hedera agent a human-in-the-loop signer: a high-risk EVM transaction is Clear-Signed on a physical Ledger before it executes. The device is the final confirmation gate — nothing high-value leaves the agent without an explicit on-device approval.

Part of the Aivy ecosystem.

Why

Autonomous agents are great until they move real value. This plugin adds device-backed security to a HAK agent: keep small actions autonomous, and gate high-risk ones behind a hardware Clear-Sign. It pairs directly with hak-uniswap-plugin, which returns { status: 'requires_ledger_approval', unsignedTx } above a threshold — hand that unsignedTx straight to ledger_clear_sign.

Install

npm i hak-ledger-plugin
# USB transport (Node) is an optional dep; install if you sign over USB:
npm i @ledgerhq/hw-transport-node-hid

Use

import { HederaLangchainToolkit } from 'hedera-agent-kit';
import { ledgerPlugin } from 'hak-ledger-plugin';

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: { plugins: [ledgerPlugin] },
});

Tools

ledger_clear_sign — human-in-the-loop signer

Clear-Signs an unsigned EVM transaction on the device and (optionally) broadcasts it.

| param | type | notes | |---|---|---| | unsignedTx | string | object | RLP-serialized unsigned tx (hex), or { to, value, data, … } | | chainId | number | e.g. 296 Hedera testnet, 11155111 Sepolia | | rpcUrl | string? | RPC for nonce/gas fill + broadcast (defaults by chainId) | | derivationPath | string | default 44'/60'/0'/0/0 | | broadcast | boolean | default true; false returns the signed raw tx |

Returns { status: 'executed', txHash }, or { status: 'signed', rawSigned }, or { status: 'rejected' } if the human declines on the device.

ledger_get_address — hardware-backed identity

| param | type | notes | |---|---|---| | derivationPath | string | default 44'/60'/0'/0/0 | | verify | boolean | true shows the address on the device to confirm |

Pairing with hak-uniswap-plugin (HITL settlement)

const quote = await tools.uniswap_swap({ /* … large swap … */ });
if (quote.status === 'requires_ledger_approval') {
  // the agent proposes; the human Clear-Signs on the Ledger; then it executes
  const res = await tools.ledger_clear_sign({ unsignedTx: quote.unsignedTx, chainId: quote.chainId });
  // res.status === 'executed' (or 'rejected' if the human declined)
}

A runnable example is in examples/sample-agent.js.

Transport

USB over @ledgerhq/hw-transport-node-hid by default (Node + a plugged-in Ledger). Browser WebHID or Speculos consumers can inject their own transport via context.ledgerTransport — the plugin uses it instead of opening USB.

Security

The Ledger device is the final confirmation gate. Keep on-device confirmation intact: do not auto-approve or bypass it. Clear Signing shows human-readable details (recipient, amount, contract action) so the approver sees what they sign.

License

MIT