# Ledger Developer Portal — full markdown

> All documentation pages concatenated into a single file.
> Updated automatically from MDX sources.

---

<!-- https://developers.ledger.com/docs/ai-tools/hardware-security/open-pgp -->

---
title: OpenPGP encryption
category: explanation
description: How your Ledger acts as an OpenPGP key to protect secrets used by your agents and tools.
---

# OpenPGP encryption

> **Note:** **For advanced users.** This app is intended for developers already proficient with OpenPGP and GnuPG.

> **Warning:** **Back up your keys.** Keys do not automatically persist across devices, OS updates, or app reinstalls. Follow the backup and restore instructions in the [app-openpgp repository](https://github.com/LedgerHQ/app-openpgp) — losing your keys means losing access to anything encrypted against them.

Your Ledger can hold an OpenPGP private key that controls access to encrypted secrets—files, environment variables, API tokens, and any sensitive material your agents or tools consume. Because the private key never leaves the device, anything encrypted against your Ledger is unreadable without it physically present.

## How it works

When you set up OpenPGP on your Ledger, a key pair is generated and stored on the device. You encrypt sensitive material against that public key. From that point, decryption requires the Ledger to be connected. Unplug the device and the secrets are opaque ciphertext to any process on the machine—including agents.

A stricter mode requires a manual tap on the device for each decryption event. In that mode, your Ledger becomes an active approval gate: even a process already running on your machine cannot read a secret without your explicit, on-device confirmation. This is the hardware-level expression of the principle running through all of Ledger's AI tools—agents propose, humans verify.

## In the context of AI tools

This matters most in agent workflows where automation handles sensitive material. An agent that needs API keys or credentials to do its work can only access those secrets when your signer is present. In tap-required mode, it needs your confirmation for every individual access.

## Further reading

- [OpenPGP on Ledger](https://support.ledger.com/fr/article/115005200649-zd): setup and usage in the Ledger Help Center
- [Ledger Wallet CLI](../ledger-cli): manage accounts and run agent workflows from the terminal

---

<!-- https://developers.ledger.com/docs/ai-tools/hardware-security/security-key -->

---
title: Security Key
category: explanation
description: How your Ledger acts as a FIDO2 hardware security key to gate access to services like GitHub, npm, and 1Password.
---

# Security Key

Your Ledger can act as a FIDO2 hardware security key, adding a physical gate to sign-in flows for services such as GitHub, npm, 1Password, and Discord.

## How it works

FIDO2 replaces or supplements passwords with a cryptographic challenge that only the registered physical device can answer. When you register your Ledger as a security key for a service, that service requires the device at sign-in. If credentials are leaked or stolen, the account remains locked without the physical hardware. The private key used to answer the challenge is generated on-device and never exposed.

This creates a meaningful constraint for agent-assisted workflows. Agents operating in your environment can use a session you have already opened, but they cannot independently start a new authenticated session to a hardware-gated service. The human had to be present to open the session—that is the guarantee.

## In the context of AI tools

Hardware-gated sign-in means agents always operate within sessions that required human presence to establish. For developers building processes where agents call external services, gating those services behind hardware authentication is one of the most direct ways to enforce a human-in-the-loop requirement without building a custom approval layer.

> **Note:** The Security Key app on Ledger supports FIDO2 and U2F. Service-specific setup varies; check the service's documentation alongside the Ledger Help Center article linked below.

## Further reading

- [Security Key setup guide](https://support.ledger.com/fr/article/12350325732893-zd): step-by-step setup in the Ledger Help Center
- [Ledger Wallet CLI](../ledger-cli): manage accounts and run agent workflows from the terminal

---

<!-- https://developers.ledger.com/docs/ai-tools/ledger-cli -->

---
title: Ledger Wallet CLI
category: how-to
description: Install the Ledger Wallet CLI, optional agent skill, and use accounts, send, receive, swap, earn, and key ring encryption from the terminal with device confirmation.
agent_skills:
  - label: Wallet CLI Usage
    url: https://raw.githubusercontent.com/LedgerHQ/agent-skills/main/skills/wallet-cli/wallet-cli-usage/SKILL.md
    role: primary
    refs:
      - label: Business Logic
        url: https://raw.githubusercontent.com/LedgerHQ/agent-skills/main/skills/wallet-cli/wallet-cli-usage/references/business-logic.md
---

## Agent Skills

- [Wallet CLI Usage](https://raw.githubusercontent.com/LedgerHQ/agent-skills/main/skills/wallet-cli/wallet-cli-usage/SKILL.md) (primary)
  - [Business Logic](https://raw.githubusercontent.com/LedgerHQ/agent-skills/main/skills/wallet-cli/wallet-cli-usage/references/business-logic.md)

# Ledger Wallet CLI

This guide shows you how to install the Ledger Wallet CLI and run common workflows from the terminal: account discovery, transfers, swaps, staking, and key ring encryption. You confirm every fund-touching command on the Ledger device before it runs.

> **Note:** This CLI manages **personal accounts**. Looking for something else? The [Ledger Enterprise CLI](https://help.enterprise.ledger.com/api-documentation-v2/guides/develop-with-ai) covers institutional, policy-enforced workflows. The [Ledger Enterprise Multisig CLI](https://help.multisig.ledger.com/guides/cli-guides) covers Safe multisig wallets.

## Verify your signer

Before running any workflow, you can confirm that your Ledger is genuine. `genuine-check` verifies the device's authenticity against Ledger's attestation service and exits with a non-zero code if it fails. Run it once after setup, or include it as a guard in automated workflows.

```bash
wallet-cli genuine-check
✔ Device is genuine
```

## Conventions

- Every command supports `--output json` for piping into other tools (`--output human` is the default).
- Signing commands follow the same pattern: the terminal announces what is about to happen, you confirm on the Ledger screen, the terminal reports the outcome.
- Read-only commands (balances, operations, `earn yields`, `earn positions`) never touch the device and are safe to run in CI or from an untrusted agent.

## Supported networks

The CLI supports **Bitcoin**, **Ethereum** (and EVM-compatible chains), and **Solana**.

| Network        | Balances & ops | Send / receive | Swap | Token lookup |         Earn        |
| -------------- | :------------: | :------------: | :--: | :----------: | :-----------------: |
| Bitcoin        |        ✓       |        ✓       |   ✓  |       —      |          —          |
| Ethereum / EVM |        ✓       |        ✓       |   ✓  |    ERC-20    | ✓ (ERC-4626 vaults) |
| Solana         |        ✓       |        ✓       |   ✓  |      SPL     |  ✓ (native staking) |

## Prerequisites

- **Supported platforms:** macOS, Linux, Windows (WSL recommended)
- **Ledger device connected over USB**, with the relevant app installed (for example, the Ethereum app for ETH accounts)

## Install

### Install the CLI

### pnpm

```bash
pnpm add -g @ledgerhq/wallet-cli
```

### npm

```bash
npm i -g @ledgerhq/wallet-cli
```

### yarn

```bash
yarn global add @ledgerhq/wallet-cli
```

### bun

```bash
bun add -g @ledgerhq/wallet-cli
```

```bash
wallet-cli --version
wallet-cli v2.1.0

wallet-cli --help # list all available commands

Commands:
  account        Account management commands
  assets         Crypto-assets store queries (resolve tokens by address or id)
  balances       Fetch native and token balances for an account (no device required)
  earn           Earn-related commands (yields, positions, deposit, withdraw)
  genuine-check  Check whether the connected Ledger device is genuine
  operations     List operations for an account (no device required)
  receive        Get receive address for an account (optionally verify on device)
  ring           Ledger Key Ring (LKRP) encryption commands
  send           Sign and broadcast a transaction
  session        Session management commands
  skill          Agent skill commands (list, retrieve, install, doctor)
  swap           Swap-related commands

```

### Install the agent skill

The agent skill teaches Claude Code, Cursor, and similar tools to drive the CLI from natural language. Since wallet-cli 2.1.0 the skill ships embedded in the binary, so the CLI installs it for you:

```bash
# Install the embedded skill into your agent's skills directory
wallet-cli skill install --agent cursor   # also: claude, codex, or generic "agents"

# Detect drift between an installed skill and the one in your binary
wallet-cli skill doctor
```

If you have not installed the CLI yet, pull the skill from the repository instead:

```bash
npx skills add LedgerHQ/agent-skills -s wallet-cli-usage
```

## Manage accounts

Run `account discover` once per network to derive every account on the device. After that, balances and operations work without the device plugged in. Pass `bitcoin`, `ethereum`, or `solana` as the network argument.

```bash
# Discover accounts — device required once per network
wallet-cli account discover bitcoin
bitcoin:main account #0 (utxo) bc1q…4f2s
bitcoin:main account #1 (utxo) bc1q…9xj7

wallet-cli account discover ethereum
ethereum:main account #0 0x71C7…976F
ethereum:main account #1 0x9A44…47F3

wallet-cli account discover solana
solana:main account #0 7EcD…BkPm
solana:main account #1 3fVw…Qa9r


# Read balances — no device needed
wallet-cli balances <label>
✔ Balances fetched
  1.5 ETH
  100 USDT

# List operations — paginated
wallet-cli operations <label> --limit 20
```

`account discover` saves the account label to a local session so subsequent commands do not need the device.
Use `session view` to inspect what is stored and `session reset` to clear it.

```bash
# Inspect the current session
wallet-cli session view
ethereum-1 account:1:address:ethereum:main:0x71C7…976F:m/44h/60h/0h/0/0
ethereum-2 account:1:address:ethereum:main:0xsDd7…3LJb:m/44h/60h/1h/0/0

# Clear all stored accounts
wallet-cli session reset
Removed 2 accounts from session.
```

## Send and receive

`receive` shows a fresh address and asks you to verify it on the device screen. `send` prompts you to review the transaction on-device before signing. Amounts must include a ticker; it drives token resolution. Use `--dry-run` to estimate fees without touching the device.

All three networks are supported. Some flags are network-specific:

| Flag             | Network                        |
| ---------------- | ------------------------------ |
| `--fee-per-byte` | Bitcoin only                   |
| `--rbf`          | Bitcoin only                   |
| `--data`         | Ethereum / EVM only (calldata) |
| `--memo`         | Solana only                    |

Solana staking (delegate, undelegate, withdraw) goes through `earn deposit` and `earn withdraw`, not through `send`. See [Earn](#earn).

```bash
# Receive — verify address on-device
wallet-cli receive <label>
0x1a2B...9a0b
Compare the address above with what's shown on your Ledger...
[⧖] Review address on device. Approve or reject

# Once it's approved 
0x1a2B…9a0b
Compare the address above with what\'s shown on your Ledger...
✔ Address verified
0x1a2B…9a0b


# Send — native, token, dry-run
wallet-cli send <label> --to 0xDEF… --amount '0.1 ETH'
To:  0xDEF…
Amount: 0.1 ETH
Fees: 0.0004961 ETH
⧖  Review on device. Approve or reject.

# Once it's approved 
✔ Signed → broadcast → 0x8f4a2b…91d3e6
```

## Resolve tokens

`assets token` and `assets token-by-id` let agents and scripts look up the canonical Ledger token id from a contract address or from an id they already hold. The resolved id is what `swap quote --from` / `--to` expects, so you can build swap workflows without hard-coding tickers.

```bash
# Resolve by contract address
wallet-cli assets token ethereum 0xdac17f958d2ee523a2206206994597c13d831ec7
ethereum/erc20/usd_tether__erc20_

# Resolve by token id (validation / round-trip check)
wallet-cli assets token-by-id ethereum/erc20/usd_tether__erc20_
```

Both commands are read-only and require no device.

## Swap

Get a quote, execute the swap, then track its status. For most providers the Exchange app on your device clear-signs the transaction so you can verify the exact amounts and provider before approving. The DEX providers (`uniswap`, `oneinch`, `velora`, `okx`) instead execute in the partner's embedded coin app via the Device Intent Executor: these are EVM-only, and a quote that resolves to an RFQ order falls back to the Exchange-app pipeline.

```bash
wallet-cli swap quote --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --amount 0.1
from:     0.01 BTC ($950.00)
to:       0.2439 ETH ($942.27)
quote_id: q_abc123 (valid 30s)

wallet-cli swap execute --from ethereum --to bitcoin --account ethereum-1 --to-account bitcoin-native-1 --provider changelly --amount 0.1  
⧖  Review the swap on your Ledger. Confirm or reject.
✔ Swap initiated — swp_xyz789

wallet-cli swap status --swap-id <swapId> --provider changelly
Status: ● FINISHED  ·  Received 0.2439 ETH
```

### Choose a provider

`swap quote` takes no `--provider` flag. It queries the available providers and returns the quotes that came back, so the quote output is the source of truth for what you can use right now. Pass the provider id from the quote line you picked to `swap execute`.

`swap execute --provider` accepts `changelly`, `changelly_v2`, `cic`, `cic_v2`, `exodus`, `lifi`, `nearintents`, `okx`, `oneinch`, `swapsxyz`, `uniswap`, and `velora`. It also accepts two aliases: `changelly` resolves to `changelly_v2`, and `1inch` resolves to `oneinch`.

Not every provider quotes every pair, and coverage changes over time. Rates also differ between providers and change from one quote to the next, so compare the quotes for your pair rather than hard-coding a provider.

## Earn

Browse yield opportunities, check your active positions, then deposit into or withdraw from a vault. `earn yields` and `earn positions` are read-only and require no device. `earn deposit` and `earn withdraw` sign on the device. Ethereum ERC-4626 vaults and Solana native staking are supported. Use `--dry-run` on a deposit or withdrawal to validate it without signing.

```bash
# List yield opportunities for a network — no device needed
wallet-cli earn yields -n ethereum
  Lido         Liquid   3.21%   0.01 ETH    none
  Rocket Pool  Liquid   3.05%   0.01 ETH    none

# Check your active positions — no device needed
wallet-cli earn positions <label>
  Lido         1.5000 stETH   +0.0031 ETH    active

# Deposit or withdraw — device required
wallet-cli earn deposit <label> --amount '0.5 ETH'
⧖  Review the deposit on your Ledger. Approve or reject.
✔ Signed → broadcast → 0x8f4a2b…91d3e6

wallet-cli earn withdraw <label> --amount '0.5 stETH'
⧖  Review the withdrawal on your Ledger. Approve or reject.
✔ Signed → broadcast → 0x2c91da…4e7f10
```

Run `wallet-cli earn deposit --help` and `wallet-cli earn withdraw --help` for the full set of vault and validator selection flags.

## Key ring

The Ledger Key Ring (LKRP) encrypts and decrypts data under keys tied to your Ledger device. Run `ring init` once to provision the key ring via the device, and always protect it with a password. After that, `ring encrypt` and `ring decrypt` need network access to restore the trustchain, but no device.

```bash
# One-time provisioning — device required, password read from WALLET_PASS
wallet-cli ring init
✔ Key ring provisioned

# Encrypt a file under a named key (AES-256-GCM)
wallet-cli ring encrypt -i secrets.txt -o secrets.enc --key my-key

# Decrypt it back
wallet-cli ring decrypt -i secrets.enc -o secrets.txt --key my-key

# List the keys this machine has used
wallet-cli ring keys

# Tear down the ring — removes local credentials and the remote LKRP application
wallet-cli ring destroy
```

`ring encrypt` and `ring decrypt` also accept text via stdin/stdout instead of `-i`/`-o` files.

### Provide the ring password

The `ring` commands read the password from the `WALLET_PASS` environment variable whenever there is no interactive terminal, which is the case in CI and when an agent runs the command.

Never write the password literally into a command. A literal value leaks into your shell history, `ps` output, CI logs, and, when an agent runs the command, the agent transcript. Store the password once in your OS keychain, then inject it with command substitution so the secret never appears in the command text:

```bash
# macOS — store the password once
security add-generic-password -a default -s ledger-wallet-cli -w

# macOS — inject it at call time
WALLET_PASS=$(security find-generic-password -a default -s ledger-wallet-cli -w) wallet-cli ring init

# Linux — inject from the Secret Service keyring
WALLET_PASS=$(secret-tool lookup service ledger-wallet-cli account default) wallet-cli ring encrypt --key my-key -i secrets.txt -o secrets.enc
```

Apply this to throwaway and test passwords too, because you reuse the same command shape with a real secret later. Command substitution still leaves the password in the child process environment, where another process running as your user can read it, so prefer a keychain lookup over exporting the password into your shell.

> **Warning:** When an agent drives the CLI, it must never choose, type, or otherwise handle the password value. Provision the password yourself and let the agent reference only the `$(…)` substitution. `ring init` also accepts `--unsecure-no-password`, which leaves the ring unprotected: do not use it for anything holding real data.

## Important Legal notice

The Ledger Wallet CLI is a technology feature that supports AI agents and terminal-based workflows to prepare and present transactions for hardware confirmation on a Ledger device. It is not a financial service, brokerage, investment adviser, or custodian.

Transactions proposed or initiated through this feature require affirmative physical confirmation by the user on their Ledger device before they are signed or executed. Ledger does not hold, manage, or have access to user assets at any time. Ledger exercises no control over, and bears no responsibility for, the logic, prompts, financial parameters, or economic outcomes of any AI agent nor for the accuracy, profitability, suitability, or intent of any AI agent. The user is solely responsible for the logic, instructions, financial parameters, and outcomes of any transaction proposed or initiated by an AI agent operating through this CLI. Ledger does not select, recommend, or endorse specific swap providers, rates, validators, or staking positions. These are presented for user review and confirmation only.

Details regarding transactions that are displayed by the CLI are provided for informational purposes only and are sourced from third-party providers. They do not constitute investment advice or a recommendation to transact. Staking yields displayed by the earn commands are indicative only and not guaranteed. Ledger is not party to any swap or staking transaction. The contractual relationship is between the user and the relevant third-party provider.

Due to the non-deterministic nature of AI models, instructions generated by AI agents may contain errors, inaccuracies, or unintended parameters. Users must independently verify all transaction details on the Ledger device screen before confirming.

Use of this feature does not establish any contractual, advisory, or fiduciary relationship between the user and Ledger SAS or its affiliates. This tool is provided "as is," in early experimental development, without warranty of any kind. To the maximum extent permitted by law, Ledger SAS and its affiliates shall not be liable for any direct, indirect, incidental, special, punitive, or consequential damages arising from use of this feature, including but not limited to loss of digital assets, unauthorised access, smart contract exploits, or transaction malfunction.

---

<!-- https://developers.ledger.com/docs/ai-tools/ledger-dmk-skills -->

---
title: Ledger DMK Skills
category: how-to
description: Install and use Markdown DMK skills so agents integrate the Device Management Kit with intent mapping, implementation steps, and concept references.
---

# Ledger DMK Skills

This guide shows you how to install and use the DMK agent skills so your agent can integrate the [Device Management Kit (DMK)](/docs/device-interaction/getting-started) into your application, with a Ledger device acting as the human-in-the-loop signer. Skills are Markdown instruction sets your agent loads on demand.

> **Warning:** DMK skills are in early development. Breaking changes may happen between releases.

## Available skills

- **[DMK · Intent](https://github.com/LedgerHQ/agent-skills/tree/main/skills/dmk/dmk-intent-vocabulary)** — Maps natural language ("sign a tx", "find my Ledger", "is this device real?") to the right DMK API. Load when the request is ambiguous. Skill ID: `dmk-intent-vocabulary`.
- **[DMK · Implementation](https://github.com/LedgerHQ/agent-skills/tree/main/skills/dmk/ledger-dmk-implementation)** — The main implementation skill. 5-step execution process (Init → Session → Device State → App Management → Operation) with HITL gates, error classification, and timeout bounds. Bundles SDK reference, code patterns, and platform patterns loaded on demand. Skill ID: `ledger-dmk-implementation`.
- **[DMK · Concepts](https://github.com/LedgerHQ/agent-skills/tree/main/skills/dmk/dmk-business-logic)** — Clear Signing, Secure Channel, sessions, transports. Load for conceptual questions, not for implementation work. Skill ID: `dmk-business-logic`.

## Prompting your agent

The implementation skill loads its reference files on demand based on what your prompt mentions. You will get sharper output if you name the **platform** (web, Node.js CLI, mobile), the **transport** (WebHID, Bluetooth, USB Speculos), the **chain** (Ethereum, Bitcoin, Solana, Cosmos), and the **operation** (derive address, sign transaction, install app).

**Minimal WebHID demo:**

> Build a Vite + React app that connects to a Ledger signer over WebHID, derives an Ethereum address, and verifies it on the device. Trigger discovery from a button click and surface user-rejection errors.

> **Note:** WebHID only runs in Chromium-based browsers, on `localhost` or HTTPS, and requires a user gesture to start discovery. The skill follows these constraints, but your dev environment must respect them.

## Install

Use Skills to install the three skills related to the Ledger DMK:

```bash
# Use Skills to install the three skills related to the Ledger DMK
npx skills add ledgerhq/agent-skills -s ledger-dmk-implementation dmk-intent-vocabulary dmk-business-logic

# If Skills is not installed, you will be prompted an install message. Type y to proceed.
Need to install the following packages:
skills@1.5.21
Ok to proceed? (y) 
```

Licenses and repository-specific notes live on GitHub: [agent-skills](https://github.com/LedgerHQ/agent-skills).

## Next steps

Your agent can now integrate DMK with the right level of guidance for each phase of the build. For DMK behavior and APIs in this portal, see the [Device Management Kit how-to](/docs/device-interaction/integration/how_to/dmk) and [Device Interaction getting started](/docs/device-interaction/getting-started).

## Important Legal notice

These DMK Skills are provided by Ledger SAS as developer resources to accelerate integration with the Ledger Device Management Kit. They are provided "as is," without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement.

Skills encode implementation patterns derived from official Ledger documentation and publicly available source code. They do not constitute a security audit, certification, or endorsement of code, smart contract, or application built using them.

Ledger does not guarantee that outputs generated by these Skills are secure, correct, or free from vulnerabilities. Due to the non-deterministic nature of AI models, you acknowledge outputs may contain errors, inaccuracies, or outdated information. The developer is solely responsible for the security, correctness, and compliance of their code, smart contracts and applications.

The DMK architecture these skills describe is designed to maintain the Ledger device as a final confirmation gate for user operations. Developers building on these skills are responsible for preserving the human-in-the-loop confirmation requirement in their implementations. Removing or circumventing on-device confirmation may expose users to risk.

Use of these skills does not establish any contractual, advisory, partnership, or fiduciary relationship between the developer and Ledger SAS or its affiliates. To the maximum extent permitted by law, Ledger SAS and its affiliates shall not be liable for any direct, indirect, incidental, special, punitive, or consequential damages arising from use of or reliance on these skills, including but not limited to loss of digital assets, unauthorised access, smart contract exploits, or transaction malfunction.

---

<!-- https://developers.ledger.com/docs/ai-tools/overview -->

---
title: Agent capabilities with Ledger signers and services
category: explanation
description: Hardware-grade signing for AI agents via DMK skills and the Ledger Wallet CLI, with human-in-the-loop confirmation on critical actions.
---

# Agent capabilities with Ledger signers and services

Ledger offers two AI tools, addressed to two different readers and two different jobs. The **Ledger Wallet CLI** is a terminal binary that you (or your agent) drive at runtime to manage your own accounts: balances, transfers, swaps, and staking, with on-device confirmation on every signing step. **DMK skills** are Markdown instruction sets that your coding agent loads at build time so it can help you integrate the Device Management Kit into an application you are building. In both cases, the Ledger device stays the final gate. On top of either tool, **hardware security features** let you protect the credentials and service access your agents rely on, using your signer as the hardware gate for encryption and authentication.

## Pick the tool for your job

The two tools answer different questions. Pick the row that matches what you want to do; you do not need both.

- **[Manage your own Ledger accounts from a terminal or agent](./ledger-cli)** — For end users and power users running an agent against their own wallet. Install the CLI, plug in your Ledger, and run discover, balances, send, receive, swap, and staking. Drive these commands directly from a terminal or through any agent that can run shell commands (Claude Code, Cursor, or your own).
- **[Add Ledger support to an app you are building](./ledger-dmk-skills)** — For application developers integrating hardware signing into their own product. Markdown skill files teach your coding agent intent mapping, a 5-step execution process with HITL gates, and the concepts behind Clear Signing and secure sessions, so the agent helps you write clean DMK integration code.

## Works with

- The CLI runs anywhere a shell does: at the terminal directly, or under any agent that can run shell commands (Claude Code, Cursor, Claude Desktop, or your own).
- The DMK skills work with any coding agent that loads Markdown skill files (Claude Code, Cursor, Cline, and similar).

## Get started

Install Ledger agent skills with:

```bash
npx skills add ledgerhq/agent-skills
```

Then go to [Ledger Wallet CLI](./ledger-cli) or [DMK skills](./ledger-dmk-skills) for the full setup. To protect the credentials and service access your agents rely on, see [Hardware security](./hardware-security/open-pgp).

## CLI use cases

Things you (or your agent) can do once the Ledger Wallet CLI is installed and your device is plugged in. Hardware confirmation is required for every signing step.

- **Portfolio snapshot** — `"Show my ETH balance and last 10 transactions."` \
  The agent calls balances and operations without touching the device. Useful for dashboards, briefings, and health checks.
- **Agent-assisted send** — `"Send 100 USDT to 0xDEF… — confirm on my Ledger."` \
  The agent plans the transaction, calls `send --dry-run` to preview fees, then triggers hardware signing after your approval.
- **Natural-language swap** — `"Swap 0.1 ETH to BTC at best rate."` \
  The agent fetches a quote, surfaces rate and fees in plain English, then Clear Signs the swap on your device with one confirm.

## DMK skills use cases

Things your coding agent can help you build once the DMK skills are installed in your skills directory.

- **Add Ledger to a wallet app** — `"Add WebHID-based Ethereum signing to my Vite + React wallet."` \
  The agent uses the implementation skill to wire transports, sessions, and clear-sign payloads, and surfaces user-rejection errors correctly.
- **Add HITL approval to an agent workflow** — `"Pause my trading bot and require Ledger confirmation before any send."` \
  The agent uses the 5-step execution process to insert a hardware approval gate at sensitive steps in your own application.

---

> **Note:** Both surfaces are in early development. Breaking changes may happen between releases. Feedback welcome on the [Ledger Discord server](https://developers.ledger.com/discord/).

## Important Legal notice

The tools described on this page are technology features. They support cryptographic signing capabilities and developer resources. They are not financial services, investment advice, or execution services of any kind. Every transaction proposed or initiated through these tools requires affirmative physical confirmation by the user on their Ledger device before it is signed or executed. Ledger does not hold, manage, or have access to user assets at any time. Ledger exercises no control over, and bears no responsibility for, the logic, prompts, financial parameters, or economic outcomes of any AI agent nor for the accuracy, profitability, suitability, or intent of any AI agent.

These tools are in early development. Features, APIs, and behaviours may change. They are provided "as is" without warranty of any kind. Use of these tools does not establish any contractual, advisory, or fiduciary relationship between the user or developer and Ledger SAS or its affiliates. To the maximum extent permitted by law, Ledger SAS and its affiliates shall not be liable for any direct, indirect, incidental, special, or consequential damages arising from use of these tools, including but not limited to loss of digital assets, unauthorised access, smart contract exploits, or transaction malfunction.

---

<!-- https://developers.ledger.com/docs/clear-signing/for-dapps/get-started -->

---
title: Get started
category: how-to
---

# How to add Clear Signing to your dApp

This guide shows you how to make your protocol's transactions readable on Ledger signers, using Ledger's tools to create and submit an ERC-7730 descriptor.

Clear Signing is defined by the open [ERC-7730](https://eips.ethereum.org/EIPS/eip-7730) standard, whose canonical home is [clearsigning.org](https://clearsigning.org). This guide covers the Ledger path: the tools Ledger provides to generate the descriptor and get it into the registry.

## Prerequisites

Before you start, make sure you have the following:

- Your smart contract **deployed** on an EVM-compatible chain
- Your contract **address** and **ABI** (from Etherscan or your deployment artifacts)
- Basic familiarity with JSON

> **Note:** ERC-7730 metadata currently describes EVM-compatible chains.

## What you will produce

A Clear Signing _descriptor_ is a JSON metadata file that tells compatible wallets how to display your contract's transactions. It describes:

- **Smart contract functions** — the intent and human-readable label for each function users sign (for example, "Send", "Swap tokens", "Approve spending")
- **EIP-712 messages** — structured data your users sign off-chain (permits, orders, votes)
- **Parameter formatting** — how to render amounts, addresses, timestamps, and other values

The heart of a descriptor is the `display.formats` block, which maps each function to an intent and labelled fields:

```json
"display": {
  "formats": {
    "transfer(address,uint256)": {
      "intent": "Send",
      "fields": [
        { "path": "_to",    "label": "Recipient", "format": "addressOrName" },
        { "path": "_value", "label": "Amount",    "format": "tokenAmount", "params": { "tokenPath": "@.to" } }
      ],
      "required": ["_to", "_value"],
      "excluded": []
    }
  }
}
```

See a complete descriptor in the [JSON Builder guide](/docs/clear-signing/for-dapps/json-builder) or [manual implementation](/docs/clear-signing/for-dapps/manual-implementation).

## The process

### Create your descriptor

Build your descriptor with the JSON Builder or write it manually. Choose the approach below.

### Validate

Run the ERC-7730 validator to confirm the descriptor meets the schema requirements.

### Submit

Open a pull request to the [Clear Signing Registry](https://github.com/ethereum/clear-signing-erc7730-registry).

### Deploy

Once your pull request is approved and merged, compatible wallets automatically fetch your descriptor and display human-readable transaction details.

## Choose your approach

- **[JSON Builder (recommended)](/docs/clear-signing/for-dapps/json-builder)**
- **[Manual implementation](/docs/clear-signing/for-dapps/manual-implementation)**

Use the **JSON Builder** for single-contract deployments with standard function signatures — it generates the descriptor in under 10 minutes. Use **manual implementation** for EIP-712 messages, multi-chain deployments, nested tuples, or reusable includes.

## Common questions

Do I need a plugin for my smart contract?

Most contracts work with a descriptor alone. You only need a [dedicated plugin](/docs/device-app/integration/how-to/plugin) if your contract has highly dynamic execution patterns that change with on-chain state, complex nested data that needs custom parsing, non-standard encoding, or security requirements beyond standard validation. Start with a descriptor — you can upgrade to a plugin later. [Contact support](https://support.ledger.com/contact-us) if you are unsure.

My dApp includes a built-in signing interface. What do I need to do?

Complete the descriptor process above, and also integrate the SDK so your dApp can display Clear Signing directly, without relying on an intermediary wallet extension. See the [wallet integration guide](/docs/clear-signing/for-wallets) for the additional steps.

How long does the review process take?

Review times depend on the registry maintainers and on how complex your submission is — submissions covering multiple deployments or EIP-712 schemas take longer. The registry is stewarded by the Ethereum Foundation; see [clearsigning.org/build](https://clearsigning.org/build) for the review process, and [Validate and submit](/docs/clear-signing/for-dapps/validate-submit) for what reviewers check.

## Next steps

You now know the path from contract to Clear Signed transaction. Choose your approach and create your descriptor:

- **[Create your descriptor with the JSON Builder](/docs/clear-signing/for-dapps/json-builder)**
- **[Write your descriptor manually](/docs/clear-signing/for-dapps/manual-implementation)**

---

<!-- https://developers.ledger.com/docs/clear-signing/for-dapps/json-builder -->

---
title: JSON Builder
category: how-to
---

# How to create metadata with the JSON Builder

This guide shows you how to generate a Clear Signing descriptor — the ERC-7730 metadata file — for your smart contract in under 10 minutes, using Ledger's ERC-7730 JSON Builder.

## Prerequisites

Before you start, have the following ready:

- Your smart contract **address** on a supported EVM chain
- Your contract's **ABI** (available on Etherscan or from your deployment artifacts)
- Your **dApp name** and public URL

> **Note:** The JSON Builder works best for single-contract deployments with standard function signatures. If your contract uses EIP-712 messages, nested tuples, proxy patterns, or custom encoding, use the [manual implementation](/docs/clear-signing/for-dapps/manual-implementation) guide instead.

## Create your descriptor

### Open the JSON Builder

Go to the [ERC-7730 JSON Builder](https://get-clear-signed.ledger.com/).

![The ERC-7730 JSON Builder interface showing the contract address input field and chain selector](/clear-signing/json-builder-tool.png)

The JSON Builder fetches your ABI automatically when you enter a verified contract address

### Enter your contract details

Paste your checksummed contract address into the **Contract address** field and select the chain it is deployed on. The tool fetches your ABI automatically from Etherscan.

If automatic ABI fetching fails — for example because the contract is not verified — paste your ABI JSON directly into the **ABI** field. You can copy it from your deployment artifacts, Hardhat build output, or your block explorer.

### Add your dApp information

Enter your **dApp name** (shown to users during signing) and your **dApp URL**. These values populate the `owner` and `info.url` fields in the generated metadata.

### Select the functions to describe

The tool lists every public and external function from your ABI. Select the functions users call directly when interacting with your dApp — for example `transfer`, `swap`, or `approve`. You do not need to include internal, pure, or owner-only functions that users never sign.

### Configure the display for each function

For each selected function, define the following:

- **Intent** — a short verb phrase shown to the user on their signer (for example, "Send" or "Swap tokens")
- **Field labels** — human-readable names for each parameter (for example, rename `_to` to "Recipient")
- **Field formats** — how each value is displayed (for example, `tokenAmount` for ERC-20 values, `addressOrName` for Ethereum addresses, `date` for timestamps)

To choose the right format for each field, refer to the [format types reference](/docs/clear-signing/reference/erc7730-reference#format-types).

> **Warning:** Every parameter in the function signature must either be assigned a display format or explicitly excluded. The validator rejects the file if any parameter is left unaccounted for.

### Preview the result

Click **Preview** to see how your metadata appears on a Ledger signer. Verify that each field shows the correct label and value. If a field displays raw hex data instead of a readable value, check that the format and its required parameters are correctly configured.

### Export the JSON file

Click **Export** to download your descriptor. The file is now ready for validation and submission to the registry.

## What the exported file looks like

The JSON Builder produces a file in the ERC-7730 format. Here is an example for an ERC-20 `transfer` function:

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "contract": {
      "abi": "https://api.etherscan.io/api?module=contract&action=getabi&address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "deployments": [
        { "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
      ]
    }
  },
  "metadata": {
    "owner": "Circle",
    "info": { "url": "https://www.circle.com/" }
  },
  "display": {
    "formats": {
      "transfer(address,uint256)": {
        "intent": "Send",
        "fields": [
          { "path": "_to", "label": "Recipient", "format": "addressOrName" },
          {
            "path": "_value",
            "label": "Amount",
            "format": "tokenAmount",
            "params": { "tokenPath": "@.to" }
          }
        ],
        "required": ["_to", "_value"],
        "excluded": []
      }
    }
  }
}
```

## Troubleshooting

ABI fetch fails or returns an empty result

This happens when the contract is not verified on Etherscan, or when the contract is deployed on a chain where automatic ABI fetching is not supported.

- Verify the contract on Etherscan if it is not already verified
- Paste your ABI JSON directly into the ABI field
- Confirm you selected the correct chain

A function does not appear in the function list

The tool lists only `external` and `public` functions. Internal, private, and view functions are not shown.

- Confirm the function visibility in your contract source
- If the function uses a non-standard signature, nested tuples, or calldata slicing, use [manual implementation](/docs/clear-signing/for-dapps/manual-implementation) instead

The preview shows raw values instead of formatted labels

A field format may be missing a required parameter. For example, `tokenAmount` requires either `tokenPath` or a direct `token` address.

- Review the format configuration for each field
- Check the [format types reference](/docs/clear-signing/reference/erc7730-reference#format-types) for required parameters per format

## Next steps

Your descriptor is ready. Validate it and submit it to the registry:

- **[Validate and submit](/docs/clear-signing/for-dapps/validate-submit)**
- **[Write metadata manually](/docs/clear-signing/for-dapps/manual-implementation)**

---

<!-- https://developers.ledger.com/docs/clear-signing/for-dapps/manual-implementation -->

---
title: Manual Implementation
category: how-to
---

# How to write metadata manually

This guide shows you how to write an ERC-7730 descriptor by hand, for the contracts and EIP-712 messages the [JSON Builder](/docs/clear-signing/for-dapps/json-builder) cannot cover.

Write the file manually when you need any of the following:

- One file that covers multiple deployments or contract variants
- EIP-712 or other structured messages
- Display logic that relies on nested paths, byte slices, or conditional rules
- Reusable enums, constants, or shared definitions across contracts
- The `addressMatcher` or `factory` context options for proxy patterns

If instead you target a single contract with clean function signatures and minimal formatting, use the [JSON Builder](/docs/clear-signing/for-dapps/json-builder) — it is faster.

## Prerequisites

- Contract ABI or EIP-712 schema for every interaction you plan to support
- Chain IDs and contract addresses
- A list of the user-facing fields each signer must display

## Write the descriptor

The goal is a JSON file that turns raw calldata (for example `0x23b872dd…`) into a readable display such as **Send — Recipient: alice.eth, Amount: 500 USDT**. This walkthrough uses Tether (USDT) deployed on three chains.

### Define the context

The `context` section binds the metadata to one or more contract deployments.

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "$id": "Tether USD",
    "contract": {
      "abi": "https://api.etherscan.io/api?module=contract&action=getabi&address=0xdac17f958d2ee523a2206206994597c13d831ec7",
      "deployments": [
        { "chainId": 1,     "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
        { "chainId": 137,   "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F" },
        { "chainId": 42161, "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9" }
      ]
    }
  }
}
```

> **Note:** Working with EIP-712? Replace the `contract` block with an `eip712` definition. See the [context reference](/docs/clear-signing/reference/erc7730-reference#context-section) for the full schema, including the `addressMatcher` and `factory` options for proxy patterns.

### Add protocol metadata

The `metadata` section introduces the protocol to users and stores reusable values such as token definitions and enums.

```json
"metadata": {
  "owner": "Tether",
  "info": {
    "legalName": "Tether Limited",
    "url": "https://tether.to/",
    "deploymentDate": "2017-11-28T12:41:21Z"
  },
  "token": {
    "ticker": "USDT",
    "name": "Tether USD",
    "decimals": 6
  }
}
```

> **Note:** The `metadata` section also supports `enums` (value-to-label mappings) and `constants` (reusable values). See the [metadata reference](/docs/clear-signing/reference/erc7730-reference#metadata-section).

### Define the display rules

The `display.formats` section maps contract function parameters to the labels and formats shown on the signer.

```json
"display": {
  "formats": {
    "transfer(address,uint256)": {
      "intent": "Send",
      "fields": [
        { "path": "_to",    "label": "Recipient", "format": "addressOrName" },
        {
          "path": "_value",
          "label": "Amount",
          "format": "tokenAmount",
          "params": { "tokenPath": "@.to" }
        }
      ],
      "required": ["_to", "_value"],
      "excluded": []
    }
  }
}
```

You can key each entry in `display.formats` by Solidity declaration, canonical signature, or raw selector — use whichever form your tooling already produces:

```json
"transfer(address _to,uint256 _value)": { },   // Solidity declaration
"transfer(address,uint256)": { },              // Canonical signature
"0xa9059cbb": { }                              // 4-byte selector
```

> **Warning:** Every function parameter must appear in either `fields` or `excluded`. Validation fails if any parameter is left unaccounted for.

> **Note:** For the full list of format types, path syntax, array helpers, and advanced patterns, see the [format types reference](/docs/clear-signing/reference/erc7730-reference#format-types) and [path system guide](/docs/clear-signing/reference/erc7730-reference#path-system).

### Reuse definitions with includes (optional)

To share display logic across multiple files, extract common snippets into a helper file and reference it with `includes`:

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "includes": "common-swap.json",
  "context": {
    "contract": {
      "deployments": [{ "chainId": 324, "address": "0x6fd4383cB451173D5f9304F041C7BCBf27d561fF" }]
    }
  }
}
```

Shared definitions live under `display.definitions` in the included file:

```json
{
  "display": {
    "definitions": {
      "sendAmount": {
        "label": "Amount to Send",
        "format": "tokenAmount",
        "params": { "tokenPath": "desc.srcToken" }
      }
    },
    "formats": {
      "swap(...)": {
        "intent": "Swap",
        "fields": [
          { "path": "desc.amount", "$ref": "$.display.definitions.sendAmount" }
        ]
      }
    }
  }
}
```

When the including file redeclares the same key, its version takes precedence. Use this to override only the fields that differ per chain while keeping shared logic in one place.

### Validate and submit

Run the ERC-7730 validator on your completed file, then follow [Validate and submit](/docs/clear-signing/for-dapps/validate-submit) to open a pull request to the registry.

## The complete file

Combining the sections above produces the full descriptor:

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "$id": "Tether USD",
    "contract": {
      "abi": "https://api.etherscan.io/api?module=contract&action=getabi&address=0xdac17f958d2ee523a2206206994597c13d831ec7",
      "deployments": [
        { "chainId": 1,     "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
        { "chainId": 137,   "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F" },
        { "chainId": 42161, "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9" }
      ]
    }
  },
  "metadata": {
    "owner": "Tether",
    "info": {
      "legalName": "Tether Limited",
      "url": "https://tether.to/",
      "deploymentDate": "2017-11-28T12:41:21Z"
    },
    "token": {
      "ticker": "USDT",
      "name": "Tether USD",
      "decimals": 6
    }
  },
  "display": {
    "formats": {
      "transfer(address,uint256)": {
        "intent": "Send",
        "fields": [
          { "path": "_to",    "label": "Recipient", "format": "addressOrName" },
          {
            "path": "_value",
            "label": "Amount",
            "format": "tokenAmount",
            "params": { "tokenPath": "@.to" }
          }
        ],
        "required": ["_to", "_value"],
        "excluded": []
      }
    }
  }
}
```

## More examples

### 1inch Order (EIP-712)

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "eip712": {
      "deployments": [
        { "chainId": 1,   "address": "0x119c71d3bbac22029622cbaec24854d3d32d2828" },
        { "chainId": 10,  "address": "0x11431a89893025d2a48dca4eddc396f8c8117187" },
        { "chainId": 56,  "address": "0x1e38eff998df9d3669e32f4ff400031385bf6362" },
        { "chainId": 137, "address": "0x94bc2a1c732bcad7343b25af48385fe76e08734f" },
        { "chainId": 42161, "address": "0x7f069df72b7a39bce9806e3afaf579e54d8cf2b9" }
      ],
      "domain": { "name": "Permit2" },
      "schemas": [{
        "primaryType": "OrderStructure",
        "types": {
          "EIP712Domain": [
            { "name": "name",              "type": "string" },
            { "name": "version",           "type": "string" },
            { "name": "chainId",           "type": "uint256" },
            { "name": "verifyingContract", "type": "address" }
          ],
          "OrderStructure": [
            { "name": "salt",         "type": "uint256" },
            { "name": "maker",        "type": "address" },
            { "name": "receiver",     "type": "address" },
            { "name": "makerAsset",   "type": "address" },
            { "name": "takerAsset",   "type": "address" },
            { "name": "makingAmount", "type": "uint256" },
            { "name": "takingAmount", "type": "uint256" },
            { "name": "makerTraits",  "type": "uint256" }
          ]
        }
      }]
    }
  },
  "metadata": {
    "owner": "1inch Limit Order Protocol"
  },
  "display": {
    "formats": {
      "OrderStructure": {
        "intent": "1inch Order",
        "fields": [
          { "path": "maker",         "label": "From",             "format": "raw" },
          { "path": "makingAmount",  "label": "Send",             "format": "tokenAmount", "params": { "tokenPath": "makerAsset" } },
          { "path": "takingAmount",  "label": "Receive minimum",  "format": "tokenAmount", "params": { "tokenPath": "takerAsset" } },
          { "path": "receiver",      "label": "To",               "format": "raw" }
        ],
        "excluded": ["salt", "makerTraits"],
        "required": ["maker", "makingAmount", "takingAmount", "receiver"]
      }
    }
  }
}
```

### Uniswap V3 Router

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "contract": {
      "abi": [...],
      "deployments": [
        { "chainId": 1, "address": "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45" }
      ]
    }
  },
  "display": {
    "formats": {
      "exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))": {
        "intent": "Swap tokens",
        "fields": [
          { "path": "params.tokenIn",           "label": "From",         "format": "token" },
          { "path": "params.amountIn",          "label": "Amount",       "format": "tokenAmount" },
          { "path": "params.tokenOut",          "label": "To",           "format": "token" },
          { "path": "params.amountOutMinimum",  "label": "Min received", "format": "tokenAmount" }
        ]
      }
    }
  }
}
```

### Permit2

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context": {
    "eip712": {
      "deployments": [
        { "chainId": 1, "address": "0x000000000022D473030F116dDEE9F6B43aC78BA3" }
      ],
      "domain": { "name": "Permit2", "version": "1" },
      "schemas": [{
        "primaryType": "PermitSingle",
        "types": {
          "PermitSingle": [
            { "name": "details",     "type": "PermitDetails" },
            { "name": "spender",     "type": "address" },
            { "name": "sigDeadline", "type": "uint256" }
          ]
        }
      }]
    }
  },
  "display": {
    "formats": {
      "PermitSingle": {
        "intent": "Approve spending",
        "fields": [
          { "path": "details.token",  "label": "Token",   "format": "token" },
          { "path": "details.amount", "label": "Amount",  "format": "tokenAmount" },
          { "path": "spender",        "label": "Spender", "format": "addressOrName" }
        ]
      }
    }
  }
}
```

## Troubleshooting

Validation fails with "unaccounted parameter"

Every parameter in the function signature must appear in either `fields` or `excluded`. Check the error message for the parameter name, then either add it to `fields` with an appropriate format or add it to the `excluded` array.

The function signature in my display key does not match

The key in `display.formats` must exactly match the function's canonical signature, Solidity declaration, or 4-byte selector. Common mistakes:

- Parameter names included when the canonical form is expected: use `transfer(address,uint256)`, not `transfer(address to,uint256 value)`
- Tuple syntax differs from the ABI: use the full tuple expansion, for example `(address,uint256)`, not `SwapParams`
- Extra whitespace around commas or parentheses

Path expression returns nothing or fails validation

Check the path root: `#` for the decoded data being signed (bare paths are relative to it), `$` for values in the file, `@` for the transaction envelope. See the [path system reference](/docs/clear-signing/reference/erc7730-reference#path-system) for the full syntax.

ABI URL returns an error during validation

If the ABI URL is not reachable or returns an error during validation, embed the ABI directly in the file as a JSON array instead of a URL string. You can copy the ABI from Etherscan's contract page under the **Contract** tab.

## Next steps

Your descriptor is complete. Validate it and submit it to the registry:

- **[Validate and submit](/docs/clear-signing/for-dapps/validate-submit)**
- **[Browse the public registry](https://github.com/ethereum/clear-signing-erc7730-registry/tree/master/registry)**

For the full specification — factories, matchers, typed-data options, enums, constants, and includes — see the [ERC-7730 reference](/docs/clear-signing/reference/erc7730-reference) and the [ERC-7730 EIP](https://eips.ethereum.org/EIPS/eip-7730).

---

<!-- https://developers.ledger.com/docs/clear-signing/for-dapps/token-support -->

---
title: Token Support
category: how-to
---

# How to add token support

This guide shows you how to make your token display with its name, symbol, and formatted amounts on Ledger signers, instead of a raw contract address and wei values.

## How token support works

Without token support, users see contract addresses instead of token names, raw wei values instead of formatted amounts, and hexadecimal data instead of readable information. With it, they see token symbols (USDT, UNI, AAVE), formatted amounts (`1,000 USDT` instead of `1000000000`), and collection names for NFTs.

> **Note:** Token support is automatic once your token is in the Ledger database. You do not need to create a descriptor just to add basic token display.

Support covers the common token standards:

- **ERC-20** — formatted amounts with correct decimals and the token symbol
- **ERC-721** — collection name and token ID from on-chain metadata
- **ERC-1155** — both fungible and non-fungible token information

## Check whether your token is already supported

Before submitting a request, verify that your token is not already in the database:

- **Search the supported assets list** — look up your token by name, symbol, or contract address in [Ledger's supported assets list](https://www.ledger.com/supported-crypto-assets).
- **Test a transaction** — send a small test transaction involving your token. If it is supported, your signer shows the token symbol; if not, it shows the raw contract address.

> **Note:** Each chain requires a separate support entry. A token supported on Ethereum is not automatically supported on Polygon or Arbitrum.

## Request token support

If your token is not in the database, submit a request with this information:

- **Contract address** — checksummed address from your block explorer
- **Token symbol** — official symbol (for example, UNI, AAVE)
- **Token name** — full display name
- **Decimals** — number of decimal places (18 for most ERC-20 tokens; 6 for USDC and USDT)
- **Chain or network** — Ethereum, Polygon, Arbitrum, and so on; submit a separate request for each chain

### Submit a support request

[Contact Ledger Support](https://support.ledger.com/contact-us) with your token information.

### Wait for review

Tokens are reviewed and added in weekly batches. Expect one to two weeks from submission to availability.

### Verify the addition

Check the [supported assets list](https://www.ledger.com/supported-crypto-assets) or send a small test transaction once you receive confirmation.

> **Note:** Token support is subject to review. Tokens must have a legitimate use case, sufficient liquidity, and regulatory compliance.

## Add a token icon (optional)

To display your token's icon in Ledger Wallet, submit a PNG or SVG that is 64×64 px (or a scalable vector), on a transparent background, under 50 KB. Then:

- Fork the [ledger-live repository](https://github.com/LedgerHQ/ledger-live)
- Add your icon to the `assets/icons/` directory, following the existing naming convention
- Open a pull request

## Reference tokens in your metadata

When your contract interacts with tokens, reference them in your descriptor so amounts display correctly during signing.

Use a static token address when your contract always interacts with the same token:

```json
{
  "path": "amount",
  "label": "Amount",
  "format": "tokenAmount",
  "params": {
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  }
}
```

Use `tokenPath` when the token address is passed as a parameter in the transaction. Its value is a path expression pointing to the parameter that holds the token contract address:

```json
{
  "path": "amount",
  "label": "Amount",
  "format": "tokenAmount",
  "params": {
    "tokenPath": "tokenAddress"
  }
}
```

For NFT collections, use `nftName` to display the collection name and token ID. Reference the collection with `collection` (fixed address) or `collectionPath` (address from transaction data):

```json
{
  "path": "tokenId",
  "label": "NFT",
  "format": "nftName",
  "params": {
    "collection": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"
  }
}
```

For the full list of format types and their parameters, see the [format types reference](/docs/clear-signing/reference/erc7730-reference#format-types).

## Troubleshooting

Token shows as "Unknown Token"

The token is not yet in the Ledger database. Follow the request process above to add it.

Amounts show with incorrect decimal places

The decimal value in the database is incorrect. Contact support with the correct decimal count. You can find the authoritative value from the token contract's `decimals()` function on Etherscan.

NFT metadata is not loading

Ensure the NFT contract implements the standard metadata methods: `tokenURI(uint256)` for ERC-721 and `uri(uint256)` for ERC-1155.

Token is supported on Ethereum but not on another chain

Each chain deployment requires a separate support entry. Submit a new request specifying the chain and contract address for each additional network.

## Next steps

Your token is ready to display correctly in Clear Signing transactions. Reference it in your protocol's descriptor:

- **[Write metadata manually](/docs/clear-signing/for-dapps/manual-implementation)**
- **[Format types reference](/docs/clear-signing/reference/erc7730-reference#format-types)**

---

<!-- https://developers.ledger.com/docs/clear-signing/for-dapps/validate-submit -->

---
title: Validate & Submit
category: how-to
---

# How to validate and submit your descriptor

This guide shows you how to validate your descriptor, preview it on a Ledger signer, and submit it to the registry so your protocol's transactions become Clear Signed.

Before you start, make sure you have created your descriptor with the [JSON Builder](/docs/clear-signing/for-dapps/json-builder) or [written it manually](/docs/clear-signing/for-dapps/manual-implementation).

## Validate your descriptor

Validate your file against the ERC-7730 schema before submitting, to catch errors early.

### CLI tool

### Install the validator

```bash
pip install erc7730
```

> **Note:** Requires Python 3.12 or higher.

### Validate your file

```bash
# Validate a single file
erc7730 lint your-descriptor.json

# Validate multiple files
erc7730 lint registry/**/eip712-*.json registry/**/calldata-*.json
```

### Auto-format your file

```bash
erc7730 format your-descriptor.json
```

### Node.js (CI)

To validate in CI, run the same `erc7730` CLI, or check your descriptor against the ERC-7730 JSON schema with any JSON Schema validator. Download the schema from the registry's [`specs/` directory](https://github.com/ethereum/clear-signing-erc7730-registry/tree/master/specs), then validate with [Ajv](https://ajv.js.org/):

```javascript
import Ajv from 'ajv';
import { readFileSync } from 'node:fs';

const schema = JSON.parse(readFileSync('./erc7730-v1.schema.json', 'utf8'));
const descriptor = JSON.parse(readFileSync('./your-descriptor.json', 'utf8'));

const validate = new Ajv({ allErrors: true }).compile(schema);

if (!validate(descriptor)) {
  console.error(validate.errors);
  process.exit(1);
}
console.log('Descriptor is valid');
```

> **Note:** Install Ajv with `npm install ajv`.

### Common validation errors

- **Missing required fields** — the file must include the `context`, `metadata`, and `display` sections, plus the top-level `$schema` field.
- **Unaccounted parameters** — every function parameter must appear in either `fields` or `excluded`.
- **Incorrect format structure** — format types must match the field's data type. For example, `tokenAmount` requires either `tokenPath` or `token` in `params`. See the [format types reference](/docs/clear-signing/reference/erc7730-reference#format-types).
- **Incorrect chain ID** — verify each deployment's `chainId` against the actual deployment. Use [ChainList](https://chainlist.org) to look up IDs (1 for Ethereum mainnet, 137 for Polygon, 42161 for Arbitrum).
- **Invalid path expression** — check the `#`, `$`, and `@` roots against the [path system reference](/docs/clear-signing/reference/erc7730-reference#path-system).

## Test the display on a signer

Before submitting, preview how your descriptor renders on a real device. The [ERC-7730 Tester](https://app.devicesdk.ledger.com/clear-signing-tools) injects your descriptor and displays the resulting fields against a live Ledger signer or the Speculos emulator, so you can confirm each label and value before opening a pull request.

## Submit to the registry

Once your descriptor passes validation, submit it as a pull request to the registry.

### Fork and clone the registry

Fork [github.com/ethereum/clear-signing-erc7730-registry](https://github.com/ethereum/clear-signing-erc7730-registry), then clone your fork:

```bash
git clone https://github.com/YOUR_USERNAME/clear-signing-erc7730-registry.git
cd clear-signing-erc7730-registry
```

### Add your descriptor

Place your file in a directory named after your dApp, using lowercase and hyphens (`uniswap-v3/swap-router.json`, not `UniswapV3/file1.json`):

```bash
mkdir -p registry/your-dapp-name
cp /path/to/your-descriptor.json registry/your-dapp-name/descriptive-name.json
```

### Open a pull request

Commit, push to your fork, and open a pull request describing your protocol, the contracts covered, and any notable configuration choices.

> **Note:** The registry runs automated checks (schema, linting, ABI and deployment consistency) before a maintainer review. For the full, ecosystem-wide submission and review process — including auditor signals and attestations — see [clearsigning.org/build](https://clearsigning.org/build).

If a reviewer requests changes, push to the same branch and the pull request updates automatically. Submissions are most often rejected for:

- Contract addresses that do not match the claimed protocol
- Display labels that are misleading or incomplete
- Schema violations not caught by local validation

## After your pull request merges

Once merged, your descriptor becomes available in  (after the next scheduled update), in all wallets that support the Clear Signing standard, and through the public registry API. Users signing transactions through your protocol then see human-readable details instead of raw hex.

## Get help

- **[Registry issues (GitHub)](https://github.com/ethereum/clear-signing-erc7730-registry/issues)**
- **[Discord community](https://discord.ledger.com)**

---

<!-- https://developers.ledger.com/docs/clear-signing/for-wallets -->

---
title: For Wallets
category: how-to
---

# 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.

> **Note:** **Partner program:** Wallet integration requires enrollment in Ledger's partner program to obtain an `originToken`. [Contact the team](https://docs.google.com/forms/d/e/1FAIpQLSe4xsr-KzPhQdaYMlNe9r9hY7XPZvbwFPutYOx6p3GOW4ALsg/viewform?usp=sharing\&ouid=107637591620972246516) 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](/docs/device-interaction/references/signers/eth).

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](/docs/device-interaction/getting-started) for device discovery and connection

## Integrate Clear Signing

### Install the packages

### npm

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

### yarn

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

### pnpm

```bash
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](/docs/device-interaction/getting-started) and the [Device Management Kit guide](/docs/device-interaction/integration/how_to/dmk) 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.

```typescript filename="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();
```

> **Warning:** 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.

```typescript filename="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.
```

> **Note:** For the full Ethereum signer API — `signTransaction`, `signMessage`, `signTypedData`, and more — see the [Ethereum Signer Kit reference](/docs/device-interaction/references/signers/eth).

## 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](https://github.com/ethereum/clear-signing-erc7730-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](/docs/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](/docs/clear-signing/for-dapps/get-started).

## Resources

- **[Ethereum Signer Kit reference](/docs/device-interaction/references/signers/eth)**
- **[Device Management Kit](/docs/device-interaction/getting-started)**
- **[Clear Signing Registry](https://github.com/ethereum/clear-signing-erc7730-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.

---

<!-- https://developers.ledger.com/docs/clear-signing/overview -->

---
title: Overview
category: explanation
---

# Clear Signing overview

Clear Signing turns the raw, encoded data of a blockchain transaction into plain language that a person can read and verify before approving it. Instead of an opaque hexadecimal string, the signer's Secure Screen shows the real intent of the transaction: what it does, who receives what, and how much. The guiding principle is simple — what you see is what you sign.

This page explains what Clear Signing is, where it came from, and how it fits into Ledger's products. For the standard itself — its full specification, governance, and the wider ecosystem — see [clearsigning.org](https://clearsigning.org), its canonical home.

## The problem: blind signing

When a wallet cannot decode a transaction, the user faces _blind signing_: they approve a screen full of unreadable calldata with no way to confirm what they are authorizing. This is where phishing and malicious contracts do their damage, because the user cannot tell a legitimate transfer from a hostile one.

![Comparison between blind signing and Clear Signing on Ledger signers](/clear-signing/blind-signing-risk.png)

Two common safeguards fall short on their own. Transaction simulation predicts an outcome but strips away context, so a legitimate cross-chain transfer can look like a total loss. An ABI decodes the function call but cannot establish intent or trust, and a malicious contract can publish a deceptive one. Clear Signing addresses the gap directly by describing, in the protocol's own terms, what a given call means.

## How Clear Signing works

Clear Signing is defined by [ERC-7730](https://eips.ethereum.org/EIPS/eip-7730), an open Ethereum standard. A protocol author writes a JSON _descriptor_ — an ERC-7730 metadata file — that maps each contract function or message to human-readable fields. The descriptor is published to an open registry. At signing time, a compatible wallet fetches the matching descriptor and renders the transaction in plain language on the signer's Secure Screen. Clear Signing never modifies the transaction; it adds a display layer that is verified on the signer itself.

![A Clear Signed transaction displayed on a Ledger signer's Secure Screen](/clear-signing/preview-example-poap.png)

A POAP claim displayed with Clear Signing on Ledger Stax

> **Note:** **The standard lives at [clearsigning.org](https://clearsigning.org).** It is the source of truth for the ERC-7730 specification, the descriptor registry, governance, and the ecosystem of wallets and protocols. This documentation covers Ledger's tools and integrations for putting Clear Signing to work.

## From Ledger to the Ethereum Foundation

Ledger introduced Clear Signing in 2023 as an open-source security initiative and formalized it as the ERC-7730 standard. From the start it was designed to be open and permissionless: any protocol can describe its contracts, and any wallet can render them.

For a standard meant to protect the whole ecosystem, neutrality matters more than authorship. On May 12, 2026, Ledger transferred stewardship of Clear Signing to the Ethereum Foundation, through its Trillion Dollar Security Initiative. The descriptor registry now lives under the Ethereum Foundation, where anyone can mirror it and no single vendor controls it.

Ledger remains an active steward alongside Trezor, MetaMask, WalletConnect, Sourcify, Fireblocks, Cyfrin, and others, and it continues to ship Clear Signing across its products — Ledger Wallet, Ledger Enterprise Multisig, and Ledger Direct Access in dApps. That is the focus of this documentation: the Ledger-specific side of Clear Signing, from the tools that generate descriptors to the kits that bring it into a wallet. For the neutral, ecosystem-wide view, see the Ledger announcement, [Stewardship of Clear Signing passed to the Ethereum Foundation](https://www.ledger.com/blog-ledger-clear-signing-ethereum-foundation), and [clearsigning.org](https://clearsigning.org).

## When users see Clear Signing

Once a protocol has a descriptor in the registry, its transactions display as Clear Signed on  in the following contexts.

When the transaction originates from a Ledger Wallet interface:

- Through the Ledger Wallet application over WalletConnect: always available
- Through the Ledger Wallet application's web3 browser, or the Ledger Wallet Button (direct connectivity between a dApp's front end and the signer): only if the dApp has implemented that integration

When the transaction originates from a third-party wallet, it displays as Clear Signed if that wallet has a Clear Signing agreement in place with Ledger.

On Ledger touchscreen signers, Clear Signing works alongside Transaction Check, which screens transactions for suspicious patterns and warns the user before they confirm. Together they form a layered defense: Clear Signing shows what a transaction does, and Transaction Check flags when it looks dangerous.

## Build with Ledger

- **[Add Clear Signing to your dApp](/docs/clear-signing/for-dapps/get-started)**
- **[Integrate Clear Signing into your wallet](/docs/clear-signing/for-wallets)**
- **[ERC-7730 quick reference](/docs/clear-signing/reference/erc7730-reference)**

## Further reading

- [clearsigning.org](https://clearsigning.org) — the standard, its registry, governance, and ecosystem
- [ERC-7730 specification](https://eips.ethereum.org/EIPS/eip-7730) — the authoritative Ethereum Improvement Proposal
- [Stewardship of Clear Signing passed to the Ethereum Foundation](https://www.ledger.com/blog-ledger-clear-signing-ethereum-foundation) — Ledger's announcement of the move

---

<!-- https://developers.ledger.com/docs/clear-signing/reference/erc7730-reference -->

---
title: ERC-7730 Reference
category: reference
---

# ERC-7730 quick reference

A practical reference for the ERC-7730 fields and formats you use with Ledger's tools. For the authoritative, complete specification, see the [ERC-7730 EIP](https://eips.ethereum.org/EIPS/eip-7730) and [clearsigning.org](https://clearsigning.org).

> **Note:** Ledger's tools and the registry currently target **ERC-7730 v1**. Version 2 is in draft — track it at [clearsigning.org](https://clearsigning.org). This page reflects v1; the EIP is the source of truth.

## File structure

An ERC-7730 descriptor has three sections:

```json
{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
  "context":  { /* what the descriptor binds to: contract + chain, or an EIP-712 schema */ },
  "metadata": { /* owner, plus reusable enums and constants */ },
  "display":  { /* how each function or message is formatted for the signer */ }
}
```

### Context section

Binds the descriptor to what is being signed.

- **Contract calls:** `contract.abi` (URL or inline) and `contract.deployments` (chain ID + address pairs). Optional `contract.addressMatcher` and `contract.factory` for proxy and factory patterns.
- **EIP-712 messages:** `eip712.schemas` (type definitions), with optional `eip712.domain` and `eip712.deployments`.

### Metadata section

- `owner` — protocol name (required)
- `info` — `url`, `legalName`, `deploymentDate` (optional)
- `enums` — value-to-label mappings
- `constants` — reusable values
- `token` — `ticker`, `name`, `decimals` (token contracts only)

### Display section

`display.formats` keys each function or message to an `intent` (a short verb phrase) and a list of `fields`. Each field has a `path`, a `label`, a `format`, and optional `params`. Every parameter must appear in `fields` or `excluded`.

Key each entry by Solidity declaration, canonical signature, or 4-byte selector:

```json
"transfer(address _to,uint256 _value)": { },   // Solidity declaration
"transfer(address,uint256)": { },              // Canonical signature
"0xa9059cbb": { }                              // 4-byte selector
```

## Format types

| Format          | Params                                                 | Use for                              |
| --------------- | ------------------------------------------------------ | ------------------------------------ |
| `raw`           | —                                                      | IDs, counts, generic integers        |
| `amount`        | —                                                      | Native currency (ETH, BNB)           |
| `tokenAmount`   | `tokenPath` or `token`\* (opt. `threshold`, `message`) | ERC-20 amounts and approvals         |
| `nftName`       | `collectionPath` or `collection`\*                     | NFT collection and token ID          |
| `date`          | `encoding` (`timestamp` or `blockheight`)              | Deadlines, expirations               |
| `duration`      | —                                                      | Lock periods, timeouts (HH:MM:SS)    |
| `addressOrName` | `type` (optional)                                      | Recipients, contracts (ENS-resolved) |
| `enum`          | `$ref` to `$.metadata.enums.NAME`                      | Status codes, modes                  |
| `unit`          | `unit`                                                 | Percentages, rates, custom units     |

\*One of the two is required.

```json
{
  "path": "amount",
  "label": "Amount",
  "format": "tokenAmount",
  "params": { "tokenPath": "token", "threshold": "0xFFFFFFFF", "message": "Unlimited" }
}
```

## Path system

Field paths reference data with three roots:

| Root | Refers to                                                                        | Example                             |
| ---- | -------------------------------------------------------------------------------- | ----------------------------------- |
| `#`  | The structured data being signed — decoded calldata parameters or EIP-712 fields | `#.amount`                          |
| `$`  | Values in the merged ERC-7730 file                                               | `$.metadata.enums.interestRateMode` |
| `@`  | Container fields from the transaction envelope                                   | `@.to`, `@.value`                   |

Omitting the root makes a path relative to the structure being described — equivalent to starting with `#.`. This is why most field paths are written bare (`_to`, `amount`) rather than `#._to`.

Arrays and byte slices:

```javascript
"tokens[]"        // all array elements
"tokens[0]"       // first element
"data[4:]"        // skip the first 4 bytes
"data[:32]"       // first 32 bytes
```

## Validation checklist

- Include the `$schema` field
- Define a `contract` or `eip712` context
- Add display formats for every user-facing function
- Use the correct path roots (`#`, `$`, `@`), or bare paths for calldata
- Match format types to the field's data type
- Validate against the schema before submitting

## Resources

- [ERC-7730 EIP](https://eips.ethereum.org/EIPS/eip-7730) — the authoritative specification
- [clearsigning.org](https://clearsigning.org) — the standard, registry, and v2 work
- [JSON schema](https://github.com/ethereum/clear-signing-erc7730-registry/tree/master/specs) — validate programmatically
- [Registry examples](https://github.com/ethereum/clear-signing-erc7730-registry/tree/master/registry) — real descriptors from major protocols

---

<!-- https://developers.ledger.com/docs/clear-signing/reference/external-resources -->

---
title: External Resources
category: reference
---

# External resources

Where to find the standard, tools, and SDKs for Clear Signing. Use this as an index when you need a specific resource while working.

## The standard

[clearsigning.org](https://clearsigning.org) is the canonical home of Clear Signing — the ERC-7730 specification, the registry, governance, and the ecosystem. Start there for anything about the standard itself.

- **[clearsigning.org](https://clearsigning.org)**
- **[ERC-7730 EIP](https://eips.ethereum.org/EIPS/eip-7730)**
- **[Clear Signing Registry](https://github.com/ethereum/clear-signing-erc7730-registry)**

## Ledger tools

Use these to create, preview, and validate your descriptors.

- **[ERC-7730 JSON Builder](https://get-clear-signed.ledger.com/)**
- **[ERC-7730 Tester](https://app.devicesdk.ledger.com/clear-signing-tools)**
- **[Python validator (erc7730)](https://pypi.org/project/erc7730/)**

The JSON Builder generates descriptors visually, the ERC-7730 Tester previews them on a real Ledger signer or the Speculos emulator, and the `erc7730` CLI validates and formats files locally (requires Python 3.12 or higher).

Community tooling maintained by other stewards — Sourcify's preview and TypeScript library, Cyfrin's Clearsig, and a Rust library — is listed on [clearsigning.org/build](https://clearsigning.org/build).

## Ledger SDKs

For integrating Clear Signing into a wallet or signing interface.

- **[Device Management Kit](/docs/device-interaction/getting-started)**
- **[Ethereum Signer Kit](/docs/device-interaction/references/signers/eth)**

## Token support

- **[Supported token list](https://www.ledger.com/supported-crypto-assets)**
- **[ledger-live repository](https://github.com/LedgerHQ/ledger-live)**

Check the supported token list before requesting a new token, and use the ledger-live repository to contribute token icons. See [How to add token support](/docs/clear-signing/for-dapps/token-support).

## Referenced standards

- [EIP-155](https://eips.ethereum.org/EIPS/eip-155) — chain IDs, used to bind descriptors to networks
- [EIP-712](https://eips.ethereum.org/EIPS/eip-712) — typed structured data, used for off-chain messages such as permits and orders
- [ChainList](https://chainlist.org) — look up EVM chain IDs for the `deployments` array
- [Etherscan API](https://docs.etherscan.io/) — fetch verified contract ABIs

## Support and feedback

- **[Registry issues (GitHub)](https://github.com/ethereum/clear-signing-erc7730-registry/issues)**
- **[Ledger Support](https://support.ledger.com)**

---

<!-- https://developers.ledger.com/docs/device-app/beginner/vscode-extension -->

---
title: Quick Start Your Project with the Ledger VS Code Extension
category: tutorial
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Quick Start Your Project with the Ledger VS Code Extension

The Ledger VS Code extension gives you a fast, self-contained environment for building and testing apps for Ledger devices. It uses Ledger's own [Docker image](https://github.com/LedgerHQ/ledger-app-builder/blob/master/dev-tools/Dockerfile) so your environment is ready in minutes.

## What the extension includes

- Build your app for all Ledger devices. Supports Rust apps (recommended for new projects) and C apps.
- Run [functional tests](../../integration/requirements/development#tests) on the device emulator ([Speculos](https://github.com/LedgerHQ/speculos)) or on a real device.
- Load and delete apps on a physical device.
- Run AI-powered code reviews using Ledger's own [agent instructions](https://github.com/LedgerHQ/ledger-app-ai-instructions/).
- Run [development guidelines](../../integration/requirements/development#workflows) checks to verify your app is ready for deployment.
- Stay up to date with the latest SDK.
- Support multiple app folders in the same workspace, each with its own Docker container.
- Inspect what the extension executes directly in the editor's terminal panels.

## Prerequisites

- [Docker](https://www.docker.com/) installed and running
- An X Window System server:
  - **Linux:** running by default
  - **macOS:** install and launch [XQuartz](https://www.xquartz.org/)
  - **Windows:** install and launch [VcXsrv](https://sourceforge.net/projects/vcxsrv/)
  - On macOS and Windows, make sure client connections are allowed in the X server settings.
- [Visual Studio Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/)
- The Ledger VS Code extension: [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools) · [Open VSX](https://open-vsx.org/extension/LedgerHQ/ledger-dev-tools)
- One of: [Rust App Boilerplate](https://github.com/LedgerHQ/app-boilerplate-rust), [C App Boilerplate](https://github.com/LedgerHQ/app-boilerplate), or [Plugin Boilerplate](https://github.com/LedgerHQ/app-plugin-boilerplate)

## Using the extension

All features are accessible through the **sidebar webview**. Use the toolbar inside the webview to pin the actions you use most. You can also trigger build and test tasks directly from the VS Code task menu with `Ctrl+Shift+B` (`Cmd+Shift+B` on macOS), without opening the sidebar.

The **status bar** shows two quick indicators at the bottom of the editor:

- The device you are currently building for.
- The status of the Ledger developer tools Docker image.

## Build and load your app

1. Start Docker and your X server.
2. Open a boilerplate app in your editor.
3. Select your target device in the sidebar.
4. Click **Build app** to compile.
   ![Build App](/device-app/AppBuild.gif)
5. Click **Load app on device** to sideload onto a connected device. Note that sideloading is not available on Nano X.
   ![Load App](/device-app/LoadOnDevice.gif)

## Functional tests

Run functional tests against the [Speculos](https://github.com/LedgerHQ/speculos) emulator or on a real device directly from the sidebar. See the [testing requirements](../../integration/requirements/development#tests) for details.

![Run Tests](/device-app/RunTests.gif)

## Device operations

The extension supports a quick device setup that skips the standard onboarding by assigning a generic seed and PIN defined in the extension settings. This seed is for testing only — use the seed generated by your device for any real-world use, and factory reset your device after testing.

You can also load and delete apps on a connected device from the sidebar.

## AI Review

The extension can run an AI-powered code review of your app using Ledger's [agent instructions](https://github.com/LedgerHQ/ledger-app-ai-instructions/). Trigger the review from the sidebar.

**VS Code:** select the model that matches your GitHub Copilot subscription and review needs.

**Cursor:** the extension's AI review relies on GitHub Copilot, which is not available in Cursor. To use the same instructions with Cursor's built-in AI, add the instructions submodule directly to your app repository — see the [ledger-app-ai-instructions repository](https://github.com/LedgerHQ/ledger-app-ai-instructions) for setup instructions.

![AI Review](https://github.com/LedgerHQ/ledger-vscode-extension/blob/main/resources/aireview.gif?raw=true)

---

You are now set up to build, test, and review a Ledger app. Modify the boilerplate to fit your project's requirements.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/architecture-diagram -->

---
title: Global architecture
category: explanation
---

# Global architecture

A Ledger device application rarely runs in isolation. Understanding the pieces that surround it (the wallet app on the user's computer, the network explorer, and the Ledger Manager) helps you decide what your device app must do, and what you can defer to the host. This page sketches the typical end-to-end architecture for a cryptocurrency app and shows where the device app fits in.

## End-to-end architecture

![End-to-end architecture of a Ledger OS application](/device-app/app_architecture.png)
_End-to-end architecture of a Ledger OS application_

A working setup has up to three pieces of software:

1. **Ledger OS application.** Written in C using the [Ledger Secure SDK](https://github.com/LedgerHQ/ledger-secure-sdk), running on the device under [BOLOS](./ledger-os/introduction). Handles the security-critical work: holding the private key, deriving addresses, displaying the human-readable transaction details, and producing the signature. The SDK targets the active Ledger devices: Nano X, Nano S+, Stax, Flex and Nano Gen5 (see the SDK's `API_LEVEL` table for the exact device/OS pairs).
2. **Wallet (or "companion") app.** Runs on the user's computer or phone, talks to the device over USB or Bluetooth via the [Device Management Kit](../../device-interaction/getting-started). It owns the GUI, builds unsigned transactions, and forwards them to the device for signing. For most projects this is Ledger Live or a third-party wallet, so your team may not need to write one.
3. **Transaction explorer / node.** Speaks to the cryptocurrency's network. Usually a remote light-wallet endpoint, sometimes a full node running locally. The wallet app uses it to fetch balances and broadcast signed transactions.

If your project does not add support for a new cryptocurrency (for example a plugin or a non-financial app), you can ignore the third piece, and the wallet app can be as simple as a CLI without a GUI.

## The Ledger Manager

![The Ledger Manager](/device-app/manager.png)
_The Ledger Manager_

The Ledger Manager is the service that distributes Ledger OS applications onto Ledger devices. It is the only path through which both Ledger's own apps and third-party apps reach end users, and the entry point of the [device-app submission process](../submission-process/process).

## Why this matters

- **Trust boundary.** Anything that needs the user's private key or has to be confirmed on a screen they fully control belongs in the device app. Everything else (UX, network calls, fee estimation, address book…) belongs in the wallet app.
- **Memory and CPU budget.** The device app runs on a constrained secure element. Heavy parsing and formatting are usually offloaded to the wallet app, then verified on-device against signed metadata. See [Architecture good practices](./architecture-good-practices) for concrete patterns.
- **Distribution.** Reaching users requires a Ledger Manager listing, which means going through the [device-app submission process](../submission-process/process).

## Key takeaways

- A Ledger app is one component of a three-part system: device app, wallet/host app, and network explorer.
- The device app is written in C against the Ledger Secure SDK and runs on BOLOS.
- The Ledger Manager is the single distribution channel for device apps.

## See also

- [Ledger OS introduction](./ledger-os/introduction): what BOLOS is and how it isolates apps.
- [Application environment](./ledger-os/application-environment): what an app sees at runtime.
- [Hardware architecture](./ledger-os/hardware-architecture): the secure element and MCU split.
- [Architecture good practices](./architecture-good-practices): what to keep on-device vs. off-device.
- [Device app role](./device-app-role): the device app's responsibilities in more detail.
- [`LedgerHQ/ledger-secure-sdk`](https://github.com/LedgerHQ/ledger-secure-sdk): source for the SDK.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/architecture-good-practices -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

## App architecture good practices

The vast majority of applications are mainly designed to sign a transaction. Although they share a similar goal, their implementation varies greatly.

### Transaction signature flow

The application's structure should follow this pattern:

```mermaid
flowchart LR
A[Receive transaction];
B[Parse tx data ];
C[Select fields];
D[Display fields];
E[Sign transaction];
A --> B --> C --> D --> E
```

In order to produce an easily maintained, readable codebase composed of reusable components, each of these steps should be cleanly cut.
It is sometimes tempting to mix in the parser with the rest of the code, or format data for printing within the parser, but doing so produces code that is hard to test or maintain.

Here is a detailed description of each step:

1. **Receive:** the transaction is sent through one or more APDUs. If this transaction is too large to be sent at once, it is copied chunk by chunk into a global buffer.
2. **Parsing:** the various fields of the transaction are read. This step is devoted to making sure the transacation is correctly formed and extracting its fields. Its logic must be as simple as possible.  We recommend making use of zero-copy mechanisms, for both security and memory footprint reasons. It is more efficient to store only the address of a buffer and its size than copying it entirely somewhere else.
3. **Selection:** when the transaction is deemed valid, its fields must be printed to the user. Those field vary a lot depending on the transaction type and the selection logic is not always apparent.  This is the reason why separating the selection step from the parsing step is important. The output is a table of elements to be printed, each represented by its identifier, its type and its associated data (an integer for the "integer" type, a pointer and a length for a string, or just a pointer for a fixed-size array for example)
4. **Display:** This step iterates over those fields. Each of them must be made human-readable through formatting and then displayed on screen. The formatting should take place only then and not sooner.
5. **Signing:** if the user validates the transaction then it is signed and its signature is sent back to the user by the application.

Rationale: From experience reviewing lots of applications, the above structure allows writing easy-to-follow, maintainable and testable applications.  Easy-to-follow because each step only does one thing.
Maintainable because adding a transaction type only affects steps 2 and 3, minimizing changes. Testable because each step can be tested independently, increasing code coverage.

Last important consequence is the ability to write reusable components. The functions related to receiving, structures used during the selection phase, formatters and parsing building blocks can be reused in another application.

The [Solana app](https://github.com/LedgerHQ/app-solana) is a great example of such architecture.
We recommend developing a portable library implementing all the complex steps of the signature flow (parsing, field selection and field formatting) as he libsol library from Solana does.

### Good Practices for Transaction Handling

Parsing transaction data, extracting important fields from this data, and showing them to the end user is the complex part of cryptocurrency applications for signers. This is where most time of the security review is spent.

A significant part of the work can be automated. We make extensive use of static analysis, using [Clang Static Analyzer](https://clang-analyzer.llvm.org/) and [Coverity Scan](https://scan.coverity.com/), and dynamic analysis tools ([AFL](https://lcamtuf.coredump.cx/afl/), [libFuzzer](https://llvm.org/docs/LibFuzzer.html), [valgrind](https://valgrind.org/)).

To use these tools correctly, the security team adapts, most of the time, the application code. This task is tedious, and is the main reason why security reviews take, sometimes, a longer time than expected. Here are a few recommendations to write robust code, with better security guarantees:

- **Do not rely on the Ledger OS SDK to handle transaction data**

Transaction handlers can be split, as seen above, in 5 parts. Only very specific areas require using the Ledger OS SDK: receiving data from USB or BLE, displaying a formatted field on the screen, and signing the transaction data. These parts should be clearly separated from the rest of the core library responsible to handle transactions.

This library should be portable. This will result in modular and testable code. Hence, a good practice for transaction parsers and printers is to put them in dedicated files. Such files should not include headers from the SDK. Do not include "`os.h`", "`cx.h`" nor "`os_io_seproxyhal.h`" in such files.

- **Document the transaction format**

Transactions are structured data. The structure of this data is sometimes well documented. In other cases, there is no documentation exception the code repository of the project. And, in some cases, even this code is ambiguous and does not define correctly how data has to be encoded.

Using a app that does not read correctly transaction data on a signer makes no sense: one of the advantages of having a signer is to control what you sign, and to make sure that what you see is what you sign. For these reasons, every cryptocurrency app _should_ link to a thorough documentation of the transaction format.

As we do not require app developers to write a full documentation for transactions if it does not exist yet, we ask for minimal test cases for every kind of transaction handled by the application. We also ask to document the kinds of transactions that are not handled by the application.

To ensure test cases cover a major part of the transactions supported by your application, developers can rely on [code coverage](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html), which becomes easy to add if your transaction parsers and printers are portable. We do not enforce a minimal percentage of coverage for unit tests. Nevertheless, we reserve the right to reject an app during the security review if we consider it cannot be tested easily.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/cryptography -->

---
title: Cryptography — why the rules exist
category: explanation
---

# Cryptography — why the rules exist

The Ledger security model gives each application a controlled, auditable window into the device's cryptographic capabilities. The rules in [Cryptography requirements](../integration/requirements/cryptography) are not arbitrary — each one exists to close a specific class of attack. This page explains the reasoning behind them.

## The threat model

A device app operates in an environment where the host computer may be compromised. The attacker controls the data sent to the device, can intercept responses, and can observe timing. The Secure Element isolates the private key material, but only if the application itself does not inadvertently expose it.

The rules below address the most common ways applications have done exactly that.

## Why you must not store secrets derived from the seed

The seed is the root of every private key the device will ever derive. If an application stores a derived key — even encrypted, even on the device's own flash — it creates a persistent copy of a secret that was designed to be ephemeral.

The correct model is **derive on demand, erase immediately**. An application derives a key for a single operation, uses it, and calls `explicit_bzero` before the stack frame is torn down. This limits the window during which an attacker with code-execution capability could extract the key.

## Why blind signing is forbidden

Allowing an application to sign an arbitrary hash is equivalent to allowing it to sign an arbitrary transaction. An attacker who controls the host can present a hash of a transaction the user did not intend to authorise. The user sees a prompt to confirm, but confirming means signing a transaction they never reviewed.

The mitigation is structural: only sign data with a known, validated format. For user-supplied "personal" messages, prepend a fixed prefix that cannot be a valid transaction prefix. This makes it impossible to repurpose a personal-message signature as a transaction signature.

## Why user approval is always required

Without explicit user approval, the device becomes a signing oracle. Any process on the host — including malware — can instruct the device app to sign whatever it sends. Requiring a physical button press means the attacker must have physical access to the device, which is outside the threat model.

> **Note:** Consider whether your application should also require approval before revealing a public key. Some users prefer not to expose account public keys until a transaction actually requires it, since an exposed public key narrows the anonymity set.

## Why you must use the SDK's cryptographic primitives

Side-channel attacks — timing attacks, power-analysis attacks, electromagnetic leakage — are not theoretical on embedded secure hardware. The SDK's cryptographic functions are implemented with constant-time guarantees and hardware acceleration specifically designed to resist these attacks on the Secure Element.

Custom implementations, even correct ones from a pure-cryptography perspective, almost certainly lack these mitigations. If the SDK does not support the primitive you need, contact Ledger to discuss adding it rather than implementing it yourself.

## Why `_no_throw` variants are required

The `cx_ecdsa_sign` family of functions raises an exception on failure using a non-standard C exception mechanism. Exception paths are difficult to reason about and have historically been the source of private-key leaks: the `explicit_bzero` call that was supposed to run after the signing operation is skipped when the exception is thrown, leaving key material on the stack.

The `_no_throw` equivalents return an error code instead of throwing, making it straightforward to clean up in all code paths — a standard `if (err != CX_OK) { goto cleanup; }` pattern with `explicit_bzero` in the `cleanup` label.

## Further reading

- [Cryptography requirements](../integration/requirements/cryptography) — the prescriptive checklist of what your application must do
- [Security specificities](./security-specificities) — APDU-level security patterns: untrusted inputs, host-cached data, and key-pair manipulation
- [Security requirements](../integration/requirements/security) — the full security checklist for app submission

---

<!-- https://developers.ledger.com/docs/device-app/explanation/device-app-role -->

# What is a device app?A device app runs directly on your Ledger signer and gives users a secure way to manage crypto assets and interact with blockchain protocols. There are three types of device apps: classical device apps, dApp plugins, and utility applications.> **Note:** The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.![A Ledger Nano S Plus hardware signer](/device-app/nanosplus.png)\
\
Embedded: [Blockchain Foundation Dev Journey](https://view.genial.ly/6630a9cf5ef56b0014673b98)## Classical device appsA classical device app allows users to manage their crypto assets with their Ledger signer. It is the first step toward integrating your coin or token into the Ledger ecosystem and into . The following sections will help you develop this type of application. For more information about the role of the Ledger device app, read [this Academy article](https://www.ledger.com/academy/hardwarewallet/what-are-ledger-applications-and-why-do-i-need-them).## dApp pluginsdApp plugins are developed to integrate an Ethereum dApp into , which has a dApp browser where your dApp will be visible and usable through an iframe. Ethereum dApps can be developed for example to lend or borrow, swap, trade, pay with crypto assets, or manage your portfolio. The documentation for dApp plugins is in the [Live App section](../../../docs/discover).For a dApp plugin to be able to sign transactions on a Ledger signer, you need to develop a small, specific application relying on the Ethereum application environment. This type of application is called a **plugin**.## Utility applicationsUtility applications leverage Ledger technology but are not involved in managing crypto assets. Examples include a password manager application or a two-factor authentication application.**You are developing a classical device app, a utility application, or a plugin — you are in the right section.**## Next steps* [Getting started](../../getting-started) — overview of the device app development journey.
* [App boilerplate](../integration/how-to/app-boilerplate) — fork the official boilerplate to begin your project.
* [Architecture diagram](./architecture-diagram) — how a device app fits into the Ledger system.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/gen5-porting -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Ledger Nano Gen5 porting

If you need to adapt a device app to be compatible with the Ledger Nano Gen5, follow the guidelines below.
Get in touch with your usual contact at Ledger if you are not sure if you should proceed with the modifications.

## What needs to be updated

- Create two icons for your application: a 48x48px B\&W png and a 32x32px B\&W png
  - Add the 48x48px in the `glyphs` folder, and use this naming template `app_yourcoin_48px.png`
  - Add the 32x32px in the `icons` folder, and use this naming template `app_yourcoin_32px.png`
- For C applications, update the makefile, with the the 32px icon target
  ```bash
  ICON_APEX_P = icons/app_yourcoin_32px.png
  ```
- For Rust applications, update `cargo.toml` with the Nano Gen5 target (apex\_p)
  ```bash
  [package.metadata.ledger.apex_p]
  icon = "icons/app_yourcoin_32px.png"
  # ...
  unexpected_cfgs = { level = "warn", check-cfg = ['cfg(target_os, values("apex_p", "stax", "flex", "nanos", "nanox", "nanosplus"))'] }
  ```
- For both C and Rust applications, update `ledger_app.toml` with the Nano Gen5 target (apex\_p)
  ```bash
  devices = ["nanox", "nanos+", "stax", "flex", "apex_p"]
  ```
- Add tests for Nano Gen5
- Add the Nano Gen5 target (apex\_p) to your App in the [the Ledger App Database ](https://github.com/LedgerHQ/ledger-app-database/blob/main/app-load-params-db.json)

## Examples

You can use our Boilerplates Apps update to understand the required modifications.

- For Device Apps in C, read [this PR](https://github.com/LedgerHQ/app-boilerplate/pull/158).
- For Device Apps in Rust, read [this PR](https://github.com/LedgerHQ/app-boilerplate-rust/pull/154).

## Submission

Use [the submission form](../submission-process/submission-form) to submit your update.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/io -->

---
title: Application structure and I/O
category: explanation
---

# Application structure and I/O

Most Ledger OS applications follow a **host-driven model**: the application on the device does not act autonomously. Instead, it waits for commands from a host process running on a computer or smartphone, performs a secure operation (signing, encryption, derivation), and returns a response. This page explains how that command-and-response cycle works and how the SDK supports it.

## The APDU interpretation loop

The command-and-response scheme is modelled on the [ISO/IEC 7816-4](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit) smartcard protocol. Each packet is called an **APDU** (Application Protocol Data Unit). The device application is driven by a never-ending loop that calls `io_exchange(...)` from the SDK on every iteration:

```c
// Pseudocode for the main APDU loop
while (true) {
    // Send the previous response (if any) and block until the next command arrives.
    uint8_t *rx_buffer = io_exchange(CHANNEL_APDU, tx_len);

    // Dispatch to the appropriate handler based on the command byte.
    handle_apdu(rx_buffer);
}
```

Each call to `io_exchange` does two things in sequence:

1. Sends the response APDU that was prepared in the previous iteration (skipped on the very first call).
2. Blocks until the host sends the next command APDU, then returns a pointer to the received data.

### Asynchronous replies

Some operations require the user to confirm an action on the device before the response is sent — for example, approving a transaction before signing it. In this case the application cannot reply immediately, so it uses the `IO_ASYNCH_REPLY` flag to defer the response:

```c
// In the APDU handler: defer the reply and wait for user input.
io_exchange(CHANNEL_APDU | IO_ASYNCH_REPLY, 0);

// Later, in the button-press handler, after the user approves:
io_exchange(CHANNEL_APDU | IO_RETURN_AFTER_TX, response_len);
```

- `IO_ASYNCH_REPLY` tells the SDK to send no data now and return control to the application.
- `IO_RETURN_AFTER_TX` sends the queued response and immediately returns without waiting for the next command — the main loop will call `io_exchange` again to receive it.

For a worked example, see [blue-app-samplesign](https://github.com/LedgerHQ/blue-sample-apps/blob/2fb0f8f68ef68bbecd601cf476e532177288a0fa/blue-app-samplesign/src/main.c): the sign-message handler sets `IO_ASYNCH_REPLY` (line 510), and the approval/denial button handlers send the deferred response using `IO_RETURN_AFTER_TX` (line 434).

## The Event / Commands / Status model

The APDU loop above is a synchronous request-response model. Ledger OS also exposes an **Event / Commands / Status (ECS)** model that decouples input events (button presses, USB/BLE packets, timer ticks) from the APDU response cycle. ECS is designed to avoid the limitations of the synchronous model and lets developers build custom event-processing loops when the default APDU dispatcher does not fit their use case.

## Transport-layer flexibility

The APDU protocol is **not** implemented by Ledger OS itself — it is entirely the responsibility of the SDK. This means applications can replace or augment it:

- **Alternative protocols**: an application can implement a custom protocol on top of USB HID, USB CCID, or BLE instead of APDU.
- **Custom USB enumeration**: applications can modify how the device is enumerated as a USB device by the host.

The diagram below shows the common protocol stack used across Ledger OS applications:

![Common protocols across Ledger OS applications](/device-app/common_protocols.png)
_Common protocols across Ledger OS applications_

## Summary

| Concept                          | Purpose                                           |
| -------------------------------- | ------------------------------------------------- |
| `io_exchange(CHANNEL_APDU, len)` | Send a response and block for the next command    |
| `IO_ASYNCH_REPLY`                | Defer the response until user confirms on-device  |
| `IO_RETURN_AFTER_TX`             | Send the deferred response and return immediately |
| ECS model                        | Alternative event loop for non-APDU use cases     |

## Further reading

- [Application isolation](./psd/application-isolation) — how Ledger OS restricts memory access between apps and the OS.
- [Security specificities](./security-specificities) — common APDU-level security pitfalls and how to avoid them.
- [App boilerplate](../integration/how-to/app-boilerplate) — a working starting point that includes a full APDU dispatch loop.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/ledger-os/application-environment -->

# Application environment

## Introduction

Because the Secure Element has limited RAM, it supports only one running application at a time. This isolation prevents other applications from interfering with the SE-MCU link. It also allows Ledger OS to give the running application full control of I/O with the device's peripherals.

This model gives applications as much control over the device's features as possible. Each application effectively runs in a virtual device and can reconfigure the hardware. Ledger OS [isolates the application](../psd/application-isolation/) from other applications and restricts its flash memory access to areas allocated exclusively to it.

This control does not limit what the application can do, but it makes each application responsible for managing every layer of the transport protocols used to communicate outside the Secure Element. The SDK implements the I/O handling that typical applications need. Developers can also customize I/O protocols for specialized applications.

![The application-centric view of the Ledger OS environment](/device-app/app_centric_view.png)
_The application-centric view of the Ledger OS environment_

The diagram shows the system from the application's perspective. The application directly accesses multiple peripherals and controls the device while it runs. Each box represents a coprocessor under the application's direct command.

Some peripherals receive commands from the Secure Element and trigger events that the MCU relays back to it. These peripherals include buttons activated by user actions and I/O peripherals that communicate in the background, such as the USB controller. They can also pass requests to the application for processing.

In this model, the application is central and does not rely on other embedded co-applications.

## Delegation model

![An overview of the USB delegation model](/device-app/usb_delegation_overview.png)
_An overview of the USB delegation model_

After Ledger OS boots an application, the application can no longer reach the operating system directly. Ledger OS provides only basic services through system calls while the application runs. As a result, Ledger OS does not process commands that peripherals, such as USB, send to the device and does not participate in I/O handling.

Together, application control and I/O delegation put applications in charge of the device. They can customize the display, user input actions, and how the device is enumerated over USB. Through event handling, an application can emulate Mass Storage or appear as a WinUSB peripheral.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/ledger-os/features -->

# Ledger OS features

## Introduction

This page explains several features built into Ledger OS. These features are available through the [dashboard app](./introduction#the-dashboard), userspace applications, or both.

## Management of cryptographic secrets

Ledger OS stores and manages two important cryptographic secrets:

- The `Device` keypair, which is generated in the factory
- The [BIP 32 master node](../psd/masterseed/), which is derived from the user's BIP 39 mnemonic seed

For security, applications cannot access either secret directly. Applications can use the Device keypair indirectly for [application attestation](./features#endorsement--application-attestation). They can also use a Ledger OS system call to derive secrets from the BIP 32 master node, provided they received the required permissions when loaded onto the device.

### Passphrases in Ledger OS

Since firmware version 1.3, Ledger OS has allowed users to load multiple [BIP 39 passphrases](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki/#from-mnemonic-to-seed) onto the device at once. As described in [the previous chapter](../psd/introduction), a passphrase adds entropy to the BIP 39 master seed and completely changes the [HD tree](../psd/keys/). Users can set a temporary passphrase that remains active until the device disconnects. They can also store a passphrase on the device by attaching it to a PIN. In that case, the passphrase activates only when the user unlocks the device with the corresponding PIN. For more information, see the [Help Center article on the advanced passphrase options](https://support.ledger.com/hc/en-us/articles/115005214529-Advanced-passphrase-security).

Activating a passphrase changes the binary seed derived according to BIP 39 and, therefore, the entire HD tree. Applications that derive information from the HD tree, such as cryptocurrency wallet applications, then derive different information. For example, they generate different cryptocurrency addresses.

## Attestation

Attestation allows Ledger devices to prove that they are genuine. Ledger OS can use attestation when connecting to a host computer to prove that the device has not been tampered with. Applications can also use it to prove that they are running on a genuine Ledger device. For attestation purposes, Ledger OS supports device endorsement by third parties called [Owners](#owner).

### Anti-tampering with attestation

![A Ledger Wallet warning that a connected device is not genuine](/device-app/wallet_not_genuine.png)

Anti-tampering technology built into the firmware protects Ledger devices from interdiction attacks, in which someone tampers with a device while it travels from a Ledger warehouse to a user. Attestation verifies the device's authenticity in software whenever you connect it to a  application.

During factory provisioning, each Ledger device generates a unique `Device` public-private keypair. Ledger's `Issuer` key then signs the Device public key to create an Issuer Certificate, which is stored on the device. This certificate acts as a digital seal of authenticity. By providing its Device public key and Issuer Certificate, the device can prove that it is genuine.

When a Ledger device connects to a  application, it uses the Issuer Certificate to prove its authenticity. This process occurs while establishing the [Secure Channel](#secure-channel), described later on this page. If an attacker created a clone that ran rogue firmware, attestation would fail, and the application would reject the device as non-genuine. An attacker cannot replace the device firmware and pass attestation without a Device private key and the corresponding Issuer Certificate signed by Ledger.

Compromising the Device private key is extremely unlikely because the Secure Element is designed to resist physical attacks. Extracting the private key is theoretically possible, but it requires extensive time and resources.

> **Note:** To learn more about how Ledger uses a Secure Element to verify device authenticity, see [ How to protect signers against tampering ](https://www.ledger.com/how-to-protect-hardware-wallets-against-tampering/). Some information in this article does not apply to Ledger's latest products.

### Endorsement & application attestation

As described in the previous section, the `Device` private key can prove that a Ledger device is genuine. To prevent compromising this key, only Ledger OS can access it directly. Applications can use the Device private key indirectly for attestation by generating attestation keypairs.

Users can generate attestation keypairs on demand for applications. They can set up an attestation key with `endorsementSetup.py` or `endorsementSetupLedger.py`. During generation, the host computer connects to the Dashboard application and initiates a [Secure Channel](#secure-channel). It then instructs the device to create an attestation keypair.

The device generates a new attestation keypair and signs it with the `Device` private key to create a Device Certificate. It returns the attestation public key, Device Certificate, and Issuer Certificate to the host over the Secure Channel. The host, which may be Ledger or a third party, signs the attestation public key with an `Owner` private key. This signature creates an Owner Certificate, which the host sends back over the Secure Channel for storage on the device. In this way, the Owner endorses the device's authenticity.

The device can then use the Device Certificate and Issuer Certificate to prove that the attestation key belongs to a genuine Ledger device. It can use the Owner Certificate to prove that the Owner trusts the attestation key.

Applications cannot access attestation keys directly. Instead, Ledger OS gives userspace applications attestation functionality through cryptographic primitives available as system calls. Applications can use two Endorsement Schemes: **Endorsement Scheme #1** and **Endorsement Scheme #2**. When creating an attestation keypair, the user chooses its scheme. Applications use the keypair through the cryptographic primitives available for that scheme.

**Endorsement Scheme #1 offers two cryptographic primitives:**

- `os_endorsement_key1_get_app_secret(...)` derives a secret from the attestation private key and the hash of the running application.

- `os_endorsement_key1_sign_data(...)` signs a message concatenated with the hash of the running application using the attestation private key. The signature can be verified with `verifyEndorsement1.py`.

**Endorsement Scheme #2 offers a single cryptographic primitive:**

- `os_endorsement_key2_derive_sign_data(...)` signs a message using a private key derived from the attestation private key and the hash of the running application. The signature can be verified with `verifyEndorsement2.py`.

For an example of these features, see [blue-app-otherdime](https://github.com/LedgerHQ/blue-app-otherdime) and [this blog post](https://www.ledger.com/attestation-redux-proving-code-execution-on-the-ledger-platform), which discusses the application in detail.

### Attestation chain of trust

![The chain of trust for Ledger's attestation model](/device-app/chain_of_trust.png)
_The chain of trust for Ledger's attestation model_

The diagram shows the chain of trust in the attestation model. The Device Certificate proves that the attestation keys belong to a device, and the Issuer Certificate proves that the device is genuine. Together, these certificates establish that a genuine Ledger device signed the data. The Owner Certificate proves that an Owner, which may be Ledger or a third party, trusts the attestation keys.

### Secure Channel

A host computer can establish a Secure Channel with a device during its standard lifecycle. This channel lets the host verify the device's authenticity and exchange secrets with it securely.

As described in the anti-tampering section, a host computer can verify a Ledger device by requesting its `Issuer Certificate`, which Ledger signs. This verification occurs when the host establishes a Secure Channel with the device. The Secure Channel also provides encrypted communication between the host and device. Only the [dashboard application](./introduction#the-dashboard) can establish this channel because the process requires access to the `Device` private key.

The Secure Channel protocol builds on the APDU (Application Protocol Data Unit) protocol used to communicate with the device over USB. The host computer sends a series of Command APDUs, and the device returns a corresponding Response APDU for each command.

The Secure Channel connects two parties: the Signer and the Device. Here, the Signer is the remote host that connects to the device. The Signer may be the Issuer (Ledger) connecting through Ledger APIs, a [Custom Certificate Authority](#custom-ca) connecting with a previously [enrolled Custom CA public key](#custom-ca-public-key-enrollment), or another end user using a randomly generated keypair.

To establish the Secure Channel, the Signer and Device each generate an ephemeral keypair. They use these keypairs to calculate a shared secret through ECDH for encrypted communication. Each party provides a certificate chain to prove that it trusts its ephemeral public key. The certificate chains include both a Signer nonce and a Device nonce to prevent an eavesdropper from reusing the certificates.

If a party trusted by the device signed the root certificate in the Signer's certificate chain, the device gives the remote host special permissions after establishing the Secure Channel. For example, the host can add or remove applications without user confirmation if a previously enrolled Custom CA keypair or Ledger's Issuer keypair signed the root certificate.

The following diagram illustrates how the parties establish a Secure Channel.

![The Secure Channel protocol handshake](/device-app/secure_channel_protocol.png)
_The Secure Channel protocol handshake_

In segment (6) of the diagram, the Device provides a Signer serial. This number is stored by the device and identifies the Issuer keypair used to sign the device's Issuer Certificate. Ledger does not use the same Issuer keypair for every device.

From segments (7) to (11), the Signer certificate chain is generated, sent to the device, and verified. From segments (12) to (16), the Device certificate chain is generated, sent to the Signer, and verified. In this example, each chain contains two certificates.

The root certificate in the Signer certificate chain is self-signed. The Signer signs the final certificate, which verifies the Signer's ephemeral public key. In the Device certificate chain, the Issuer Certificate is the root certificate. Verifying it also verifies the device's authenticity. The Device signs the final certificate, which verifies the Device's ephemeral public key.

## Custom CA public key enrollment

A [Custom Certificate Authority](#custom-ca) can generate a keypair with `genCAPair.py` and enroll its public key on the device with `setupCustomCA.py`. Enrollment gives the Custom CA two special privileges:

- The Custom CA can open an authenticated [Secure Channel](#secure-channel) with the device by using the `--rootPrivateKey` option of the Python Loader.
- The Custom CA can sign applications with `signApp.py`. This signature allows the device to load the application without user confirmation.

Ledger OS application developers can use this feature to simplify development. Third-party companies can also use it to give their own application manager permission to manage the device without requiring user confirmation for every action.

## Parties involved in the model

The following parties participate in the public key cryptography model.

### Device

**Device Certificate:** Each Device has a **unique** public-private keypair known **only to that device**. The Device generates this keypair in the factory, and Ledger does not know its private key. The Device keypair can sign certificates.

### Issuer

**Issuer Certificate:** The Issuer is the party that initially provisions the [Device](#device). This party is always Ledger. The Issuer has a public-private keypair that can sign Issuer Certificates. Ledger uses multiple Issuer keypairs.

### Owner

**Owner Certificate:** An Owner is a party that owns a Ledger device, verifies its authenticity, or both. An Owner has a public-private keypair that can sign certificates. A single [Device](#device) can have zero or more Owners, and an Owner does not have to be Ledger. The device uses Owner Certificates only for [application attestation](#endorsement--application-attestation).

### Custom CA

**Custom CA Certificate:** A Custom Certificate Authority has a public-private keypair. Its public key is [enrolled on the device](#custom-ca-public-key-enrollment), and its private key can establish an authenticated [Secure Channel](#secure-channel) with the device and sign applications.

> **Note:** A Custom CA may be a Ledger OS application developer or a third-party company that wants to give its application manager special administrative permissions on a Ledger OS device.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/ledger-os/hardware-architecture -->

# Hardware architecture

## Introduction

Ledger signers use a distinctive architecture that combines the security of the Secure Element with support for several peripherals. These peripherals include the screen, buttons, a host computer connected over USB, and, for the Ledger Blue, Bluetooth and NFC.

The architecture connects an additional STM32 microcontroller (MCU) to the Secure Element (SE). The MCU acts as a simple router between the SE and the peripherals. It does not perform application logic or store any cryptographic secrets used by Ledger OS. Instead, it manages the peripherals and notifies the SE when new data is ready. Ledger OS runs applications entirely on the SE. This section describes the hardware architecture and its constraints before examining their software implications.

## Multiple processors: Secure Element proxy

![A detailed Ledger OS architecture diagram](/device-app/bolos_architecture.png)
_A detailed Ledger OS architecture diagram_

Ledger OS uses two hardware chips. One is secure; the other has JTAG enabled and acts as a proxy.

| Hardware signer    | Microcontroller (MCU) | Secure Element (SE) |
| ------------------ | --------------------- | ------------------- |
| Ledger Nano X      | STM32WB55 / STM32WB35 | ST33J2M0            |
| Ledger Nano S Plus | STM32F042             | ST33K1M5C           |
| Ledger Stax        | STM32WB35             | ST33K1M5C           |
| Ledger Flex        | STM32WB35             | ST33K1M5C           |

The Secure Element also contains two parts: firmware that is under NDA and therefore closed source, and SDK and application-loaded code that is open-source friendly. The Ledger OS firmware handles low-level I/O operations and implements the SE-MCU link. The running app handles the protocol between the SE and the MCU.

Ledger OS relies on both chips to support Secure Element applications. The SE is powerful but lacks inputs and outputs. The MCU provides them and acts as the SE's proxy. In this sense, the MCU serves as a coprocessor for the SE. Through a simple asynchronous protocol, the SE controls the proxy. The security implications of this design are outside the scope of this section.

The SE-MCU link protocol is called SEPROXYHAL, or SEPH, in source code and documentation. "HAL" stands for Hardware Abstraction Layer.

## SEPROXYHAL

The SEPROXYHAL protocol uses a serialized list of three packet types: Events, Commands, and Statuses. It is the SE's only channel for communicating with the outside world. A protocol error, such as an incorrect packet order or format, isolates the SE and prevents communication. This is typically the most common failure scenario during application development. If it occurs, you must reboot the signer to reset the SEPROXYHAL protocol state. Software guards are intended to help prevent these errors.

The protocol begins when the MCU sends an Event, such as a button press, ticker, or USB transfer. The SE responds to the Event with zero or more Commands. It then sends a Status to indicate that it has fully processed the Event and waits for the next one.

![SEPROXYHAL protocol concept](/device-app/seproxyhal.png)
_SEPROXYHAL protocol concept_

Because of the buffer size, the SE uses a Status to send requests to display content on the screen. After processing the Display Status, the MCU issues a Display Processed Event to indicate that it is ready for another Display Status. Building a complete user interface requires the application to display multiple elements asynchronously from its core logic. A UX helper in the SDK supports this process, as discussed in the next chapter.

The SE throws an exception if an application sends more than one Status in a row without fetching a new Event between them.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/ledger-os/introduction -->

# Introduction

These pages explain the core features of Ledger OS and how Ledger OS applications and end users can use them. They cover how Ledger OS manages the master device seed and device private key, including their use in attestation. They also describe the hardware architecture shared by all Ledger OS devices.

Ledger OS is the operating system behind all . It provides a lightweight, open-source framework for developers to build portable applications that run in a secure environment. For more context about their role, see the [introduction to signers](../psd/introduction).

Ledger OS allows users to review and install applications that use their cryptographic secrets. At the same time, it protects the device and other applications from malicious code. Its [application isolation](../psd/application-isolation/) technology supports open-source applications while limiting their access to users' cryptographic secrets.

Ledger OS is organized into the following modules:

- An input/output module that allows applications in a secure environment to communicate with the outside world and third-party peripherals
- A cryptography module that implements low-level cryptographic primitives and provides access to hardware acceleration where available
- A persistent storage module that lets applications store data securely on the device
- A personalization module for interfacing with the device master seed
- An endorsement and application attestation module that allows Ledger OS applications to provide proof of execution
- A user interface module for rendering the GUI and handling user input, such as input from buttons on the device

### The dashboard

All Ledger OS devices include a special application with elevated privileges called the Dashboard application, or the PSD Content Manager. The Dashboard provides the main GUI when no other application is open. Users enter their master seed and launch other applications through it. The host computer also communicates with the Dashboard when it loads applications onto the device or deletes them.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/memory/memory-alignment -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Memory alignment

## Introduction

The Secure Elements on top of which the Ledger Operating System and the associated applications run imply a 32-bit alignment. This article aims at explaining the C associated development constraints.

## Alignment concept

The memory alignment is a concept which applies to memory and pointers:

- A memory address is 'b-bits aligned' when it is a multiple of b/8, b/8 being a power of 2
- A memory address is said to be aligned when the data referenced by said address is b bits long, and said address is b-bits aligned
- A pointer is 'aligned' when it points on aligned memory
- A pointer is 'unaligned' when it points on unaligned memory

## Alignment constraints for basic types and structures

Implementing C source code with types and structures is not functionally impacted by the 32-bit alignment, except for potentially wasting a few bytes without even noticing.

This paragraph is important for writing memory-efficient structures, once the application is compiled and loaded onto a device.

Within any application source code, the alignment of basic types will be considered as follows, at compilation time:

- `char` / `unsigned char` / `int8_t` / `uint8_t` : 8-bit aligned
- `short` / `unsigned short` / `int16_t` / `uint16_t`: 16-bit aligned
- `int` / `unsigned int` / `int32_t` / `uint32_t`: 32-bit aligned
- any pointer: 32-bit aligned

Please note that 8-bit aligned means that there is actually no alignment constraint.

The compiler will add padding in any structure which is not aligned by design, in order to respect:

- The alignment of each field associated to their respective length
- The alignment of the whole structure, which must have a total length, padding included, multiple of the largest field's length

For instance the following structure is 8 bytes long before compilation:

```c copy
// Before compilation
struct Example1
{
    char    field_1;
    short   field_2;
    int     field_3;
    char    field_4;
};
```

However during compilation, the structure is modified to ensure the alignment, and will thus be 12 bytes long:

```c copy
// After compilation
struct Example1
{
    char    field_1;
    // Padding added for field_2 to start on a 16-bit aligned address
    char    padding_1;
    short   field_2;
    // With padding_1 being added, field_3 will start on a 32-bit aligned
    // address and no padding is required here.
    int     field_3;
    char    field_4;
    // The structure is aligned to the number of bits corresponding to the
    // largest field's alignment, in this case, due to field_3, 32-bits.
    // For the structure to be 32-bit aligned, it needs 3 more bytes of padding.
    char    padding_2[3];
};
```

```c copy
 [xxxxxxxx] -------- [xxxxxxxx   xxxxxxxx]
 [xxxxxxxx   xxxxxxxx   xxxxxxxx   xxxxxxxx]
 [xxxxxxxx] --------   --------   --------
```

In this example, it is possible to reorganize the structure's fields to avoid alignment-induced padding, but sometimes padding will not be avoidable.

You can order the structure fields according to their length in decreasing order:

```c copy
// Before compilation
struct Example1_reordered
{
    int     field_3;
    short   field_2;
    char    field_1;
    char    field_4;
};
```

```c copy
// After compilation
struct Example1_reordered
{
    int     field_3;
    // No need for padding since field_2 is already on a 16-bit aligned address.
    short   field_2;
    // No need for padding for char types.
    char    field_1;
    char    field_4;
    // No need for padding since the structure is 8 bytes long and thus, its length
    // is already a multiple of its largest field's length.
};
```

You can also order the structure fields to make sure the minimum amount of padding bytes will be added by the compilation phase:

```c copy
// Before compilation
struct Example1_reordered_other_way
{
    int     field_3;
    char    field_1;
    char    field_4;
    short   field_2;
};
```

```c copy
// After compilation
struct Example1_reordered_other_way
{
    int     field_3;
    // No need for padding for char types.
    char    field_1;
    char    field_4;
    // No need for padding since field_2 is already on a 16-bit aligned address.
    short   field_2;
    // No need for padding since the structure is 8 bytes long and thus, its length
    // is already a multiple of its largest field's length.
};
```

## Alignment constraints for pointers

Using pointers within C source code might be functionally impacted by the 32-bit alignment in a specific case: when the pointer points on a memory area which type differs from the pointer, and is dereferenced.

Dereferencing unaligned pointers within an application makes the application crash.

Usually, pointers are used to store the address of an element which type corresponds to the pointer one, and for simple example:

```c copy
uint16_t *pointer;
uint16_t array[10];

// Pointer positioning is perfectly fine.
pointer = &array[3];

// Dereferencing this pointer is also perfectly fine, since the
// pointed memory is aligned in accordance with the pointer type.
*pointer = 0x0001;
```

However, if we use a pointer with a specific type to store the address of a memory area declared with another type (usually with an alignment-related size less than the pointer one), it can lead to hardware faults and the application crashing:

```c copy
uint16_t *pointer;
uint8_t array[10];

// Case where it will work even if not advised.

// Pointer positioning is fine.
pointer = (uint16_t*)&array[2];

// Dereferencing this pointer is also fine: the pointed memory is aligned
// in accordance with the pointer type (because the offset 2 in the array variable
// is a multiple of 16 bits).
if (*pointer == 0x0001) {
    do_something();
}

// Case where it will make the application crash.

// Pointer positioning is fine, but it is unaligned.
pointer = (uint16_t*)&array[3];

// Dereferencing this pointer will make the application crash: the pointed memory is not aligned
// in accordance with the pointer type (because the offset 3 in the array variable
// is not a multiple of 16 bits).
if (*pointer == 0x0001) { /* This dereferencing makes the application crash. */
    do_something();
}
```

The same reasoning applies when pointing on structures:

```c copy
// Same example as within the previous paragraph, being ordered
// makes it 8 bytes long.
struct Example1_reordered
{
    int     field_3;
    short   field_2;
    char    field_1;
    char    field_4;
};

Example1_reordered *pointer;
uint8_t array[32];

// Case where it will work even if not advised.

// Pointer positioning is fine.
pointer = (Example1_reordered*)&array[8];

// Dereferencing this pointer is also fine: the pointed memory is aligned
// in accordance with the pointer type (because the offset 8 in the array variable
// is a multiple of the structure's size after compilation).
if (pointer->field_2 == 0x0001) {
    do_something();
}

// Case where it will make the application crash.

// Pointer positioning is fine, but it is unaligned.
pointer = (Example1_reordered*)&array[3];

// Dereferencing this pointer will make the application crash: the pointed memory is not aligned
// in accordance with the pointer type (because the offset 3 in the array variable
// is not a multiple of the structure's size after compilation).
if (pointer->field_2 == 0x0001) { /* This dereferencing makes the application crash. */
    do_something();
}
```

Unaligned pointers can thus occur in cases where a pointer:

- is declared as positioning on some data type (or structure),
- is used to point on a memory area actually containing another type of data,
- is dereferenced.

In order to produce robust to alignment constraints C source code, avoid using pointers in this way.

## External links

- [Data structure alignment Wikipedia](https://en.wikipedia.org/wiki/Data_structure_alignment)
- [ARM documentation about Address alignment](https://developer.arm.com/documentation/dui0497/a/the-cortex-m0-instruction-set/about-the-instruction-descriptions/address-alignment)

---

<!-- https://developers.ledger.com/docs/device-app/explanation/memory/persistent-storage -->

---
title: Persistent storage
category: explanation
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Persistent Storage

## Introduction

Ledger OS applications have access to two different types of memory in the Secure Element (SE):

- A small amount of RAM for the call stack and certain global variables
- A considerably larger amount of flash memory for persistent storage

The Memory Protection Unit, configured by Ledger OS, controls access to flash memory and prevents applications from writing to sections they do not own. Applications can read the flash region where their code and constant data are stored. This data includes code and `const` variables, but applications may also allocate extra space in NVRAM to be used at runtime for persistent storage.

## Types of Memory

You decide which data lives in RAM and which persists to flash. To make your decision, know that:

- All global variables that are declared as `const` are stored in read-only flash memory, right next to code. In most Ledger device apps for example, general settings are stored in flash memory.
- All normal global variables that are declared as non-`const` are stored in RAM.

  However, thanks to the link script (`script.ld`) in the SDK, global variables that are declared as non-`const` and are given the prefix `N_` are placed in a special write-permitted location of NVRAM. This data can be read in the same way that regular global variables are read. However, writing to NVRAM variables must be done using the `nvm_write(...)` function defined by the SDK, which performs a syscall. When loading the app, NVRAM variables are initialized with data specified in the app's hex file (this is usually just zero bytes).

> **Warning:** Initializers of global non-const variables (including NVRAM variables) are ignored. As such, this data must be initialized by application code.

## Flash Memory Endurance

Secure elements used in Ledger devices each have a flash memory rated to a certain amount of erase / write cycles. There should be enough cycles to last the expected lifetime of the devices, but only if applications use it properly. Applications should avoid erasures as much as possible.

**Here are some techniques for avoiding wearing out the device's flash memory.**

- If you intend to be changing data in flash memory many times while an application is running, consider caching the data in RAM and then flushing to flash memory when the application has finished its operation. This of course has the downside of possible data loss if the user powers off the device (perhaps by unplugging it, in the case of the Nano S Plus) before the data has been written to persistent storage.
- Developers should be aware that flash memory pages are aligned to 64-byte boundaries. Each page in flash memory is expected to survive the amount of erase / write cycles related to the SE. As such, one can develop an application that writes to as few pages as possible. For example, if you intend to store 32 bytes of data in flash memory, write amplification can be avoided by making sure that 32 bytes of data is contained entirely within a single page (and modified using only a single call to `nvm_write(...)`). If the data crossed a 64-byte page boundary, then writing to it once may require two pages to be erased instead of just one.

## See also

- [Ledger OS hardware architecture](../../explanation/architecture) — how the Secure Element and memory map relate to each other
- [Device app memory layout](../../references/memory-layout) — detailed memory regions for each Ledger device
- [SDK link script (`script.ld`)](https://github.com/LedgerHQ/ledger-secure-sdk/blob/master/script.ld) — defines `N_` variable placement in NVRAM

---

<!-- https://developers.ledger.com/docs/device-app/explanation/memory/position-independent-code -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Position-Independent Code

Position-Independent Code (PIC) is a requirement for all Ledger device apps. Because Ledger OS loads apps into different flash memory slots at runtime, your code must not contain hard-coded addresses that reference compile-time link addresses. This page explains how PIC works in the Ledger OS environment, what limitations it introduces, and how to use the `PIC()` macro to avoid common segmentation faults.

This page is part of the memory management series for Ledger device apps. See also [persistent storage](./persistent-storage) and [memory alignment](./memory-alignment).

## PIC and model implications

PIC stands for Position-Independent Code. The Ledger OS toolchain produces PIC to allow the code **link address** to be different from the code **execution address**. For example, the `main` function is linked in the generated application at address `0xC0D00000`. However, the slot used when loaded into the Secure Element could be `0x10E40400`. Therefore, if the code makes a reference to `0xC0D00000`, even with an offset, it would be denied access as the application is locked by the Memory Protection Unit (not to mention, this is not the correct address of the `main` function at runtime).

The PIC assembly generator makes sure every dereference is relative to the Program Counter, and never to an arbitrary address resolved during the link stage. This behavior is supported by clang versions 4.0.0 and later.

Traditionally, PIC code implies the BSS segment (RAM variables) is at a constant offset of the code. For example, if code is at `0xC0D00000`, then global vars may be at `0xC2D00000`, so if loaded at `0x10E00000` then global vars would be at `0x12E00000`. However, Ledger OS uses a fixed address for global vars. The global variables start address and length are defined in the link script. Only the code is meant to be placed at different addresses (in flash memory, rather than RAM).

The model we choose has limitations, which are related to the way `const` data and code is referenced in other `const` data. Here is a simple example:

```c copy
const char array1[] = {1, 2, 3, 4};
const char array2[] = {1, 2, 3, 4};
const char *array_2d[] = {array1, array2};

void main() {
    int sum, i, j;
    sum = 0;
    for (i = 0; i < 2; i++) {
        for (j = 0; j < 4; j++) {
            sum += array_2d[i][j]; // Segmentation Fault!
        }
    }
}
```

In the example above, when dereferencing `array_2d`, the compiler uses a link-time address (in the `0xC0D00000` space, following the previous examples). This is not where the program is loaded in memory at runtime. Therefore, when the dereference is executed, it causes a segmentation fault that effectively stalls the SE. Luckily, the solution is straightforward, thanks to a small piece of assembly provided with the SDKs which is invoked with the `PIC(...)` macro. `PIC(...)` uses the current load address to adjust the link-time address in order to acquire the correct runtime address of `const` data and code. The above example can be corrected by modifying the line where `array_2d` is dereferenced as follows:

```c copy
sum += ((const char*) PIC(array_2d[i]))[j];
```

The same mechanism must be applied when storing function pointers in `const` data. The PIC call cast is just different. Additionally, if a non-link-time address is passed to `PIC(...)`, it will be preserved. This is possible due to the wisely chosen link-time address which is beyond both real RAM and loadable addresses. For example, `PIC(...)` is used during a call to `io_seproxyhal_display_default(...)`: all display elements can hold a reference to a string to be displayed with the element, and the string could be in RAM or code, and therefore `PIC(...)` is applied to acquire the correct runtime address of the string, even if it is in RAM.

## Summary

The key rules for writing PIC-compliant code:

- Use the `PIC(...)` macro whenever you dereference a pointer stored in `const` data, including function pointers.
- Never assume that a link-time address matches the runtime address.
- `PIC(...)` passes through RAM addresses safely; you can apply it even when you are unsure whether a pointer points to RAM or flash.
- The PIC model only relocates code in flash; global variables (BSS segment) always live at a fixed address defined in the link script.

## Further reading

- [Persistent storage](./persistent-storage) — how flash memory and NVRAM are managed in Ledger OS.
- [Memory alignment](./memory-alignment) — alignment constraints for the Secure Element.
- [Application environment](../ledger-os/application-environment) — how Ledger OS isolates and loads apps into the Secure Element.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/plugin -->

# Ethereum Plugins and Ethereum Clone Apps: What's the Difference?

When dealing with Ethereum-based applications, two important concepts are Ethereum Plugins and Ethereum Clone Apps. These tools serve distinct functions but work towards the same goal of enhancing user experience and security. Let's explore the differences between them.

## Ethereum Plugins

Ethereum Plugins are specialized extensions that focus on improving the interaction with smart contracts. Their primary function is to provide users with detailed information about specific smart contracts, thereby reducing the risk of blind signing. By integrating with the Ethereum App, these plugins ensure that users have access to readable and clear contract details before they proceed with any transaction approval.

Key responsibilities of an Ethereum Plugin include:

1. Extracting necessary details from smart contract data.
2. Formatting this information as a string and sending it back to the Ethereum App for display.

## Ethereum Clone Apps

Ethereum Clone Apps are specifically designed to facilitate the adaptation of the Ledger Ethereum App for other Ethereum-compatible Layer 2 blockchains. This process allows developers to replicate the functionality of the Ethereum App on their custom chain, leveraging the robust infrastructure of the Ethereum App to ensure seamless operation with their L2 solutions.

## Summary

While both Ethereum Plugins and Ethereum Clone Apps are integral to optimizing user interaction with blockchain applications, they cater to different aspects—plugins enhance smart contract transparency, and clone apps expand compatibility across different chains.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/psd/application-isolation -->

---
title: Application isolation
category: explanation
---

# Application isolation

Ledger OS isolates each application from the rest of the device's memory and from other applications. This isolation is the hardware-enforced guarantee that an application — even a malicious one — cannot read your seed, access another application's data, or interfere with the operating system.

## User mode and Supervisor mode

Ledger OS uses two capabilities built into the Secure Element's ARM core to enforce isolation:

- **Memory Protection Unit (MPU)**: maps each application to its own memory region and blocks access to all other regions at the hardware level. ([ARM MPU reference](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dai0179b/CHDFDFIG.html))
- **Operating modes**: applications run in **User mode**, while the operating system runs in **Supervisor mode**. ([ARM operating modes reference](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0210c/Cihhcjia.html)) User-mode code cannot directly execute privileged instructions.

Because only one application runs at a time and each is confined to its own memory region, no application can observe or modify another application's state, even while both are installed on the same device.

## Syscalls

When an application needs the operating system to perform a privileged action — accessing hardware peripherals, running hardware-accelerated cryptographic operations, or deriving keys from the master seed — it issues a **syscall**.

A syscall causes the Secure Element to switch momentarily to Supervisor mode: the OS performs the requested operation, then switches back to User mode and returns control to the application. The SDK exposes wrapper functions for every syscall so applications never call them directly. Common syscall categories include:

- Hardware-accelerated cryptographic primitives (functions defined in `include/cx.h`)
- Low-level I/O with the MCU (USB, BLE)
- Key derivation from the BIP-32 master seed

## Controlled access to cryptographic secrets

Applications cannot access the master seed or derived keys directly. Instead, they call a syscall that asks the OS to derive a node from the seed along a specific BIP-32 path. The OS grants or denies the derivation based on the path allowlist declared in the application's metadata at load time. (See [security requirements](../../integration/requirements/security#derivation-path) for the mandatory derivation-path declaration.)

This means:

- Multiple applications can be installed simultaneously, each restricted to a different subtree of the HD tree.
- An application that is not authorised for a given path cannot derive keys on that path, even if it issues the syscall.
- Deleting and reinstalling an application does not change which paths it is permitted to use — the allowlist is in the metadata, not in the application's flash storage.

## Summary

| Mechanism                 | What it does                                                     |
| ------------------------- | ---------------------------------------------------------------- |
| Memory Protection Unit    | Confines each app to its own memory region at the hardware level |
| User / Supervisor mode    | Prevents apps from executing privileged instructions directly    |
| Syscall interface         | Gives apps controlled access to hardware and OS services         |
| Derivation-path allowlist | Limits which BIP-32 paths an app can use to derive keys          |

## Further reading

- [Ledger OS introduction](../ledger-os/introduction) — overview of the operating system and its components.
- [Security requirements](../../integration/requirements/security) — the derivation-path declaration and other mandatory security metadata.
- [Master seed](./masterseed) — how the device generates and serializes the BIP-39 seed.
- [HD key generation](./keys) — how an infinite number of keys is derived from a single seed.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/psd/applications -->

# Applications for HD trees

## Introduction

The previous section, `hd_keys`, described how a single master seed can generate an infinite number of cryptographic secrets. This article explains how Ledger applies this concept to develop lightweight, easily recoverable applications for [signers](./introduction).

## Coin types

HD trees are useful because developers of different cryptocurrencies [reserved a space on the tree](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#registered-coin-types). The developers for each cryptocurrency specified a location, called the coin's path, where users store their private keys. This path is public information because no one can determine the value of your keys without knowing your master node, or mnemonic seed. [BIP 44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) defines the paths for different cryptocurrencies and the paths used to derive cryptocurrency addresses and private keys. BIP 44, in turn, defers coin type registration to [SLIP 44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md).

Each cryptocurrency has a node on the tree where all keys for that coin begin. This article refers to it as the coin type root node. Because the tree is hierarchical and deterministic, the same rules that apply to the master node also apply to the coin type root node. An infinite tree of keys descends from the master node, and another infinite tree descends from each coin type root node. As a result, a 24-word mnemonic seed gives you a virtually infinite[^1] number of Bitcoin addresses, even if you do not use Bitcoin. It also gives you a virtually infinite number of Ethereum addresses.

> **Warning:** In the Ledger Ethereum Wallet desktop app, addresses are not derived according to BIP 44. Instead of using the derivation path m / 44' / 60' / account' / change / address\_index (as defined by BIP 44 for Ethereum), the Ledger Ethereum Wallet desktop app uses the derivation path m / 44' / 60' / 0' / address\_index.

## How your wallet finds used addresses

Most BIP 44-compliant HD wallet programs, including the Ledger Bitcoin Wallet desktop app, divide your addresses into accounts. You can distribute your coins across these accounts as you might across multiple bank accounts. For example, you can use separate accounts for savings, donations, and common expenses. Each account contains two virtually infinite chains of addresses: an external chain and an internal chain, commonly called the change address chain. Every address in each chain receives a number, called the address index, starting at 0.

When your wallet software starts for the first time, it searches the blockchain for transactions involving address 0 in each chain. If it finds any transactions, it displays the address and searches for transactions involving address 1. The wallet continues until it finds an address that you have not used. It displays that address and stops searching the chain because it assumes that you have not used any later addresses.[^2]

This process keeps the important information about your transaction history on the blockchain rather than on the signer. If you destroy or reset your wallet, you can enter your 24-word mnemonic seed into a new HD wallet. The wallet then searches the public blockchain for the information it needs.

## Summary

![A diagram of a hierarchical deterministic wallet; everything in the box labelled "hierarchical deterministic tree" is recoverable if your wallet is lost, destroyed, or reset because it is all derived from the master seed](/device-app/where_are_my_assets.png)
_A diagram of a hierarchical deterministic wallet; everything in the box labelled "hierarchical deterministic tree" is recoverable if your wallet is lost, destroyed, or reset because it is all derived from the master seed_

An HD wallet has three important properties:

- The 24-word mnemonic seed generates the tree that makes up an HD wallet. This seed is all you need to generate your cryptocurrency addresses and sign transactions.
- You do not need to save individual private keys. Even as you receive Bitcoin at more addresses, the corresponding private keys remain available in the HD tree.
- Ledger uses the industry-standard BIPs 32, 39, and 44 for HD wallets. Your 24-word mnemonic seed works with any HD wallet that supports these standards, not only Ledger wallets.

## Going beyond cryptocurrencies

Hierarchical deterministic wallets can do more than secure assets on blockchains. You can extend the same concept and use your master seed to derive passwords, PGP keys, and SSH keys.

For example, Ledger developed a [Password Manager app](https://github.com/LedgerHQ/blue-app-password-manager). It converts a node on the HD tree into a text password that appears random. When you create a password, you enter a label such as "Google", "Dropbox", or "Twitter". **The password's label encodes the location of its node on the HD tree.** When you request the password, the app uses the label to locate the node and convert it into text. You cannot specify your own passwords; the app generates them for you.

**Footnotes**

[^1]: In this case, virtually infinite = 263 = 9 223 372 036 854 775 808.

[^2]: In this example, we described a wallet that operates with a [gap limit](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#address-gap-limit) of 1. Different wallet software use different values, but BIP 44 currently recommends a gap limit of 20.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/psd/introduction -->

# Introduction

Ledger signers isolate cryptographic secrets, such as PGP or Bitcoin private keys, from a potentially insecure computer. Storing these secrets on a physical medium that a virus cannot infect, such as paper or an encrypted drive, is secure until you need to use your funds.

To transfer funds, you need to sign the transaction. Loading your private keys onto your computer for this purpose exposes them to potential malware. The alternative is to perform the required cryptographic operations by hand, which is impractical.

Signers address this problem. They store your cryptographic secrets and let you use them securely for operations such as signing transactions. Ledger signers also use an AIS-31-compliant true random number generator (TRNG) to generate secrets with a large amount of entropy. Using these internally generated secrets is more secure than importing a secret that may have been compromised before it reached the signer.

Ledger uses Secure Element technology to build signers that connect people with cryptocurrencies and blockchains. The Secure Element protects your private keys from tampering and eavesdropping. The screens on the Ledger Nano X and Nano S Plus also provide a trusted source of information about your assets. The signer controls the screen, rather than potentially vulnerable computer software.

Signers are not intended to store data. Instead, they provide a root of trust. Signer apps tend to be lightweight and work with a host computer. Because the Secure Element limits storage capacity, it is preferable to store encrypted data on the host computer rather than directly on the signer. The signer holds private keys that you can use to unlock your data and assets. If your computer becomes infected with a virus, those keys remain protected.

Applications that process large amounts of data may not be able to store all the data on the signer at once. One approach is to stream data through the signer while the application processes it, for example, by encrypting or decrypting the data. Alternatively, an application can derive a secret on the signer, preferably from the master seed, and use it on the computer to process the data. This is how the [PGP app](https://github.com/LedgerHQ/blue-app-openpgp-card) works.

The key concept is that a signer provides a secure portal to your assets; it is not a bank. If you lose or destroy your signer, your assets remain safe. Your master seed is the key to this portal. The next section explains [The Master Seed](./masterseed/).

---

<!-- https://developers.ledger.com/docs/device-app/explanation/psd/keys -->

# HD Key Generation

## Introduction

In [the previous section](./masterseed/) we discussed how Ledger devices use a master 24-word mnemonic seed to derive a theoretically infinite number of cryptographic secrets. Though it might seem impossible at first glance, this can be done using nothing more than some mathematical sorcery. The process used to do this is called hierarchical deterministic (HD) key generation.

The process for HD key generation used by all Ledger devices (and many other HD wallets) is defined by [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).

Here's how it works.

## The Master Node

Hierarchical deterministic key generation involves creating a theoretically infinite tree of cryptographic secrets. The root of this tree from which everything is generated is called the master node. The master node is derived directly from the master binary seed described in the previous section using HMAC-SHA512. The master node of your wallet is all the information you need to access an infinite hierarchy of private keys. As such, you should take good care to keep your mnemonic seed safe.

### Passphrases

Passphrases are a standard feature of BIP 39 supported by many HD wallets. Passphrases are an optional way of adding additional data to the master seed before deriving the master node of the HD wallet. By specifying a different passphrase (or no passphrase at all), the value of the master node is completely changed. As you will discover as you read the rest of this section, changing the master node of the HD wallet completely changes all of the information derived from it (for example, your Bitcoin addresses). In this way, you can keep the same master seed on a device, but use different passphrases to access completely unique, separated wallets.

## An Infinite Tree

Descending from the master node is a tree of an infinite number of private keys. All you need to determine a particular key is the master node (your mnemonic seed) and the location of the key in the tree (called its "path"). This tree is created using an incredibly powerful algorithm defined by BIP 32 called the CKD function. All you need to know about this magical algorithm is that it can be used to calculate any node on the HD tree given the node's position and the value of the master node. Essentially, the CKD function is applied to the master node a number of times in order to "scramble" its bits and output a brand new node. This algorithm is magical because **it is impossible to reverse**. Given a private key on your tree, it is impossible to go backwards up the tree and determine your master node.[^1]

## Child Key Derivation Function

The HD tree is made up of "nodes". Using the CKD function, many "child" nodes can be derived from a single "parent" node. Each node contains three pieces of information: a private key, a public key, and a chain code. In the case of a cryptocurrency wallet, the private key is the part that is used to sign transactions and the public key is used to generate the corresponding cryptocurrency address. The node's chain code is an extra little bit to prevent someone from determining the children of a node using only the node's public and private keys.

The CKD function has been designed in a way that provides great flexibility in the way child nodes are derived. Specifically, instead of requiring the public key, private key, and chain code to derive a child node, the CKD function can be used to derive child public keys from the parent public key and child private keys from the parent private key. Additionally, BIP 32 defines the concept of "hardened" child nodes. If a child node is "hardened", then its public key cannot be determined from its parent node's public key.

These are the transformations that the CKD function can perform:

- parent private key & chain code ➞ child private key & chain code
- parent public key & chain code ➞ child public key & chain code (unless the child node is hardened)
- parent private key & chain code ➞ child public key & chain code

Note that it is impossible to derive a child private key from a parent public key. This model has some interesting consequences, mainly that the parent public key and chain code can be shared which allows someone to derive all child public keys (unless the child nodes are hardened), but no private keys.

For example, this model can be used to facilitate the process of auditing an HD wallet. By sharing the public key and chain code of all accounts in an HD wallet, one can give an auditor the ability to view all addresses in the wallet (without having the associated private keys). As such, the auditor could determine what money is going where, without having access to any private keys, meaning the auditor couldn't sign any transactions. We'll talk about what "accounts" are in the next section.

For a more detailed list and explanation of some of the use-cases made possible by this model, see [this section](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#use-cases) of the BIP 32 specification.

In the [next section](./applications/), `hd_use_cases`, we'll talk about how all of these features are used by HD wallets and other applications.

> **Note:** If you'd like to play with BIP 39 mnemonics or BIP 32 derivation on a computer, take a look at this tool: [ iancoleman.io/bip39 ](https://iancoleman.io/bip39/)

**Footnotes**

[^1]: Technically it isn't impossible to determine a node given the child node and the corresponding index, but there is no known attack to do this faster than a properly executed brute-force attack. See [this section of BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#security) for details.

---

<!-- https://developers.ledger.com/docs/device-app/explanation/psd/masterseed -->

# The Master Seed

## Introduction

Applications running on Ledger [signers](./introduction) are designed to be lightweight and easily recoverable. Ledger achieves both of these goals by using **hierarchical deterministic key generation**. Hierarchical deterministic key generation is used by applications to derive a theoretically infinite number of cryptographic secrets from a single master seed. This way, your cryptocurrency private keys, passwords, and other cryptographic secrets can all be determined and intrinsically "stored" in a single master seed. Thanks of this, the device's apps don't have to store their own private keys, because they can all be generated on-demand by the device from the master seed. This means that if your device is lost, destroyed, or reset then all you need is your master seed to recover your secrets. In addition, an application that supports this scheme can be deleted and reinstalled without losing any secure data or assets. Your master seed is randomly generated for you when you first set up your Ledger device, and then you just need to write it down to allow you to recover your device in the future.

## Generation and Serialization

The master seed is the key to your cryptographic secrets. As such, the master seed should be something that is long and nearly impossible for anyone to guess. Your master seed isn't like a password or a PIN (Ledger devices already have PINs to protect access to them), instead it's the root of all of your cryptographic secrets. Once your device randomly generates it for the first time and you write it down on paper, you will only need to access it if you have to recover your device.

Ledger uses a standard called [BIP 39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) for the generation and interpretation of the master seed on all of our devices. BIP 39 is an industry standard used by many other hierarchical deterministic wallets. The exact type of BIP 39 seed used by Ledger devices by default is a 24-word mnemonic that consists of only the 2048 words from the [BIP 39 English wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt). Here's how a BIP 39 24-word mnemonic seed is generated:

1. The device generates a sequence of 256 random bits using the true random number generator (TRNG) built into the device's Secure Element
2. The first 8 bits of the SHA-256 hash of the initial 256 bits is appended to the end, giving us 264 bits
3. All 264 bits are split into 24 groups of 11 bits
4. Each group of 11 bits is interpreted as a number in the range 0 - 2047, which serves as an index to the BIP 39 wordlist, giving us 24 words

The result of this process is that your device will generate a single mnemonic seed out of 2256 possible mnemonic seeds (That's one of 115 792 089 237 316 195 423 570 985 008 687 907 853 269 984 665 640 564 039 457 584 007 913 129 639 936 possible mnemonic seeds). Note that while the first 23 words are completely random, the final word is derived from 3 random bits and 8 calculated bits from the SHA-256 hash. This means that the final word can act like a checksum - if you input an incorrect seed into the device while recovering it, it is possible for the device to detect that the inputted seed is invalid.

> **Note:** Can someone guess my seed? There are 2256 different possible 24-word mnemonic seeds. For comparison, the number of atoms on Earth is estimated to be around 2166. Just let that sink in for a second. The chance of someone else being able to guess your seed is astronomically small, to say the least.

**But all we have here is a sequence of 24 words, how can the device use this as a cryptographic secret?**

After the 24-word mnemonic is generated, it has to be converted into a binary seed by the device. This process is called serialization. This is done using the PBKDF2-HMAC-SHA512 key derivation function to convert your mnemonic seed **and an optional passphrase of your choosing** into a 512 bit binary seed. This BIP 39 passphrase can be [set on your device](https://support.ledger.com/hc/en-us/articles/115005214529) through the Settings menu, and it can be changed at will without resetting your device (in fact, you can have multiple passphrases loaded onto the device at once if you wish). By changing the passphrase, the resulting 512 bit binary seed is completely changed.

This 512 bit binary seed is the root of your device's cryptographic secrets. Every cryptographic secret that your device needs (cryptocurrency private keys & addresses, passwords, etc.) can be derived from this 512 bit binary seed. We'll explore how an infinite number of cryptographic secrets can be derived from this one seed in the next section, [HD Key Generation](./keys/).

---

<!-- https://developers.ledger.com/docs/device-app/explanation/security-specificities -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Security specificities

When building a device app, certain implementation patterns can introduce security vulnerabilities. This page describes the most common insecure patterns encountered across cryptocurrency integrations and explains how to mitigate them. Understanding these risks will help you write safer APDU handlers and protect your users' funds.

This page complements the [security requirements](../integration/requirements/security) and the [cryptography guidelines](./cryptography).

## Security concerns

This section describes possibly insecure patterns found in specific cryptocurrencies, and how to handle them.

### Be wary of untrusted input

Some cryptocurrencies do not have _explicit_ fees encoded in the transaction. In such cases, the app cannot rely on the fee value sent from the host. Instead, it should receive previous UTxOs and check their output amounts. Note that this usually needs to be done in a separate step due to memory constraints. Check the BTC app design for this.

### Properly protect data you cache on the host computer

Sometimes your app needs to compute over more data than it can fit inside memory. Taking an example from the previous section, it might not be easy to store all UTxOs in the device memory. As such, you might break computation into multiple steps and, for example, verify each UTxO separately and let the host computer cache a "certified summary". If you do this, be aware that:

1. If the information you want the host to cache is public, you still need to attach a signature to it so that the host cannot send some other value later. This could be done with a standard HMAC digest. We recommend using a temporary (per session) key for this — a per-session HMAC allows you to truncate the digest size (for example, you do not need an HMAC that withstands years of brute-force attack; instead, you can balance the digest size against some reasonable upper bound on how long the session lives, such as one month).

2. If the information is not public, you need to both encrypt it and provide a signature. Notably, it is not enough to "scramble" the data by XORing with a random key, as this would still allow an attacker to tamper with the values (or even break the scrambling if you reuse the same key).

   Instead:

   - Encrypt the information with a sufficiently strong cipher.
   - Provide a digest to prevent tampering with the value.

### Do not allow the host to freely manipulate key pairs

Some cryptocurrencies (notably Monero) need to perform extensive calculations with _(public, private)_ key pairs spread over multiple APDU exchanges. If you need to do the same, **do not** allow the attacker to step out of the protocol. Allowing the attacker to freely perform key manipulation (such as group multiplications or exponentiations) could undermine your app security **even if the private key never leaves the device**. In general, keep an explicit protocol state machine during the computation. Also, consult with cryptography experts to check for implications if you deviate from the protocol.

## Summary

The main security principles for Ledger device apps are:

- Never trust fee or amount values sent from the host; verify them from raw transaction data whenever possible.
- If your app caches sensitive data on the host computer, always sign it and, if the data is private, encrypt it. XOR scrambling is not sufficient.
- Maintain explicit protocol state machines for multi-step APDU exchanges to prevent attackers from injecting unexpected operations.

## Further reading

- [Security requirements](../integration/requirements/security) — the full list of mandatory security checks for app submission.
- [Cryptography guidelines](./cryptography) — how to use cryptographic primitives correctly in your app.
- [Cryptography requirements](../integration/requirements/cryptography) — what cryptographic operations are allowed for submission.

---

<!-- https://developers.ledger.com/docs/device-app/getting-started -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Getting started

In this section of the Developer Portal, you will find the resources to build, test, and submit Rust and C apps, Ethereum plugins, and Cloned coins apps, compatible with all Ledger devices.

> **Note:** **Rust is mandatory for all new device app projects.** C remains supported as a reference for teams maintaining existing C apps.

## Reach an agreement with our team

### 1. Contact us and introduce your project

[Fill in this form](https://docs.google.com/forms/d/e/1FAIpQLScc_luftAe3Y9f7Y89aGjCa-z3XPOf1cVfIEeOZzhgx71MYbQ/viewform?usp=sharing\&ouid=107637591620972246516) to introduce your project. We’ll get back to you to align on your device app development and its integration in . After meeting with our teams, you’ll be directed to one of the following paths.

### 2.a. Ledger Development

You can sign a contract with Ledger for development of your device app and full support of your blockchain in .

This option includes:

- Development of your device app with Clear Signing for transactions
- Integration into , including the features defined in the SOW and the relevant  services
- Ongoing maintenance and updates of the integration
- Mandatory security audits for each device app update, managed within Ledger’s process
- Direct collaboration with Ledger’s engineering team throughout the project

### 2.b. Autonomous Development

If an agreement with Ledger is not feasible, you can still develop a device app on your own.

**What to expect**

- Every device app must pass a security audit before it can appear on the  “My Ledger” app list.
- You will build a device app compatible with third-party wallets; users won’t be able to manage their assets in  unless an agreement is signed later.

**Security audit**

Before publication, your app must go through a functional and security audit. The audit is performed by one of our approved partners, at your expense. Both partners follow Ledger specifications and deliver a full report including potential vulnerabilities.

**Audit partners**

When your device app is ready for audit, contact one of our partners:

- [Kudelski IoT](https://www.kudelski-iot.com/services-and-systems/ledger-security-audit)
- [Quarkslab](https://www.quarkslab.com/) — [contact them here](mailto:qb_ledger@quarkslab.com)

> **Note:** Ensure your device app meets all necessary requirements and is fully tested before initiating a security audit with our partners.

**Agreement details**

When contracting with an auditor, align on:

- **Time** — When the audit can start
- **Cost** — The audit is entirely at your expense
- **Maintenance** — Include a clause for updates or plan to sign a new contract for major updates. Otherwise, Ledger will not update your app and it may be delisted from the My Ledger app list if it becomes incompatible.

> **Note:** Ledger is not a party to the contract between you and the auditor.

## Tools and boilerplates

- To learn how to quickstart a project with the Ledger VS code extension, read [this guide](./beginner/vscode-extension). The extension makes the environment set up, the app building, and the tests very easy.
- To start developing your project with the boilerplates, go to the How-to section in "Integration walkthroughs". You will find [the app boilerplate](./integration/how-to/app-boilerplate) (Rust is mandatory for new projects; C is kept as reference for existing apps), [the Ethereum plugin doc](./integration/how-to/plugin), and [the Cloned coins apps integration process](./integration/how-to/clone).
- To enable AI-assisted development with Ledger's embedded coding rules in your repo (GitHub Copilot, Cursor, and compatible agents), see the [ledger-app-ai-instructions repository](https://github.com/LedgerHQ/ledger-app-ai-instructions).

## Technical information

### Languages

| Component                                         | Developing language                                                |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| [Ledger OS](./explanation/ledger-os/introduction) | `C`                                                                |
| Applications                                      | `Rust` (mandatory for new projects) / `C` (existing projects only) |
| Plugins                                           | `C`                                                                |
| Tools (including tests)                           | `Python` (mostly)                                                  |

### Data formats

| Component                   | Format |
| --------------------------- | ------ |
| CI (GitHub Workflows)       | `YAML` |
| `ledger_app.toml` manifests | `TOML` |
| App database                | `JSON` |

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/address -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Address verification

This guide shows you how to implement address verification in your device app so that users can safely confirm receive addresses on the secure screen of their .

**Prerequisites:** Read the [design guidelines introduction](./intro) before implementing address verification screens.

## Basic address verification

Just like for transactions, address verification starts with an intent that attracts the user's attention and lets them know what action they are going to perform.

Once the user continues, they are shown the full address to compare with its software counterpart.

| ![Address verification flow on Ledger Stax and Flex: verification prompt, full address display, and QR code display](/device-app/stax-flex-address-verification.png) |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                             _Verification prompt, followed by address display, and the QR code display._                                             |

> **Note:** A plain "Confirm" button is used here instead of the "Hold to sign" gesture. The "Hold to sign" gesture is reserved for signing transactions and messages that have an actual impact on blockchain state or user funds.The "Cancel" button dismisses address verification immediately, without requiring another user confirmation.

A button lets users display the address as a QR code, useful when they need to scan it from their mobile. By using the high-level API, your app gets this capability automatically.

> **Note:** API\
> nbgl\_useCaseAddressReview()\
> This high-level API function builds the default template for address verification. It also handles the enriched version presented in the next section. [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#abb0d60831b55936803dd477cfffa226c).

## Enriched address verification

In advanced use cases, you may want to show additional information alongside the address, such as derivation paths. Use a transaction-like flow with pagination, starting with the address on the first page. Here is an example with Cardano address verification:

![Enriched address verification on Ledger Stax and Flex, showing the address on the first page followed by derivation path details](/device-app/stax-flex-enriched-address-verification.png)

The same `nbgl_useCaseAddressReview()` function handles both the basic and enriched templates. Pass additional tag-value pairs to populate the extra pages.

## Key takeaway

> **Key takeaway:** Make address verification simple and fast by conforming to the standard templates. This also lets your users display their address as a QR code for convenient sharing.

## Next steps

- [Transaction screens](./transactions) — how to design the transaction review and signing flow.
- [Info and settings screen](./info-settings) — how to implement the settings and info pages.
- [Advanced interactions](./advanced) — handling special cases such as enriched flows with streaming data.

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/advanced -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Advanced interactions

This guide shows you how to implement advanced UI patterns for situations where the standard templates are insufficient for your app's needs.

**Prerequisites:** Read the [design guidelines introduction](./intro) and the [transaction screens](./transactions) guide before using the patterns described here.

## Streamed transactions

For some operations, your app may not be able to fully load the data into memory before presenting it to users. When streaming transaction data to your device page by page, the navigation must change:

- If the total number of pages is not known, hide the page count.
- If the user cannot go back to previous pages, hide the "back" button.

Here is what an EIP-712 streamed message looks like in the Ethereum app, on Ledger Stax and Ledger Flex:

| ![Streamed transaction UI on Ledger Stax and Flex, showing a footer without a back arrow or page numbers](/device-app/stax-flex-streamed-transactions.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                 _The footer changes: no "back" arrow and no page numbers._                                                 |

> **Note:** API\
> nbgl\_useCaseReviewStreamingStart()\
> nbgl\_useCaseReviewStreamingContinue()\
> nbgl\_useCaseReviewStreamingFinish()\
> These high-level API functions allow your app to stream pages of information, as shown above. [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#a42b9838f8e87318f142b4bfa11cd8e1a).

> **Warning:** Avoid transaction streaming in your app whenever possible. Blocking users in a forward-only progression is not recommended UX.

## Progressive disclosure of long fields

When signing operations with uncontrolled structure and contents, you can encounter data that is too long to fit in one field, even on one page.

In these cases, you can hide the contents of a field behind a "More" interaction to use progressive disclosure. This lets users move faster to signing while still providing a preview of the field contents.

When the user taps the "More" button, a modal containing the full field opens. If the field spans several pages, navigation arrows appear:

![Progressive disclosure UI showing a field with a "More" button that expands into a multi-page modal](/device-app/stax-flex-long-fields.png)

> **Note:** API\
> There is no specific graphical API to display this "More" button. It is handled automatically by the nbgl\_useCaseReview() and nbgl\_useCaseReviewStreamingContinue() functions.

> **Warning:** Use progressive disclosure only for fields that do not affect your user's privacy, security, or funds. Reserve this pattern for non-critical data only.

## Key takeaways

> **Key takeaway:** 

## Next steps

- [Transaction screens](./transactions) — the standard review flow you should use before reaching for these advanced patterns.
- [Address confirmation](./address) — how to implement address verification screens.
- [NBGL use case reference](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html) — full API documentation for all use-case functions.

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/home -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# App home screen

The home screen tells users what your app is about and leads them to their next action. Most often, that action is creating a transaction in  or another software wallet.

This guide shows you how to design and implement the home screen for your device app.

**Prerequisites:** Familiarize yourself with the [design guidelines introduction](./intro) before implementing any screen.

## Anatomy of the home screen

Your app's home screen must show the app icon, name, and description.

The creation and positioning of these elements are handled automatically from your app's assets, so you can focus on providing a helpful, concise description of what your app does.

| ![Bitcoin app home screen showing the app icon, name, and description on Ledger Stax, Ledger Flex, and Nano devices](/device-app/bitcoin-home.png) |
| :------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                   _The Bitcoin app's home screen, on Ledger Stax, Ledger Flex, and Nano devices._                                  |

> **Note:** API\
> nbgl\_useCaseHomeAndSettings()\
> This high-level API takes care of automatically building the app home screen and the settings screen (see the next chapter). [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#a438078d9be71706e0ad6a05f56658255).

The top-right icon is set automatically: a wheel icon if there are user-customizable settings, or an "info" icon otherwise. Read the next chapter for details on settings.

## Troubleshooting

**The home screen layout looks different than expected on a physical device.**
Test your home screen on the Speculos emulator for each target device before loading on hardware. Use the `BOLOS_SDK` variable to target different SDKs when building. See the [app boilerplate setup guide](../how-to/app-boilerplate) for details.

## Key takeaways

> **Key takeaway:** 

## Next steps

- [Info and settings screen](./info-settings) — how to implement the settings and info pages that appear after the home screen.
- [Transaction screens](./transactions) — how to design the transaction review flow.
- [App boilerplate](../how-to/app-boilerplate) — fork the boilerplate to get a working home screen out of the box.

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/info-settings -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# App info and settings

This guide shows you how to implement the info screen and optional settings screen for your device app.

**Prerequisites:** Read the [design guidelines introduction](./intro) and review the [app home screen](./home) guidelines before implementing the info and settings screens.

## App information

Your app must provide at least its version number and the developer name or organization. This information is part of the app's resources and is used to automatically build a default version of the info screen.

| ![Bitcoin app info screen showing version number and developer name, on Flex and Nano devices](/device-app/bitcoin-info.png) |
| :--------------------------------------------------------------------------------------------------------------------------: |
|                                  _The Bitcoin app's info screen, on Flex and Nano devices._                                  |

> **Note:** API\
> nbgl\_useCaseHomeAndSettings()\
> This high-level API contains structures describing the info and settings of your app. [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#a438078d9be71706e0ad6a05f56658255).

If needed, you can add more information using the same format: rows of key-value pairs.

## App settings

> **Warning:** App settings are reset to their default values every time your app is updated or reinstalled after an OS update.Ledger is currently working on solving this limitation by providing a backup-and-restore mechanism for app data. These guidelines will be updated when that mechanism is released.

Your app can have settings that unlock new capabilities or alter its behavior. As soon as your app includes a setting, the icon on the home screen changes from an "info" icon to a wheel icon.

Settings must always appear before the app's info, as shown in the Ethereum app example below. Navigation arrows are introduced automatically to split sections across their respective pages.

| ![Ethereum app settings screen on Flex and Stax, showing the wheel icon on the home screen and the settings page appearing before the info page](/device-app/stax-flex-settings-01.png) |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                        _On Flex and Stax, the wheel icon leads to settings, which appear before the app's info on the next page._                                       |

Settings can use the following interactive elements:

- Toggle switches
- Radio buttons
- Tappable rows for navigation

Tappable rows are used to introduce hierarchy and sub-settings. Do not mix interactive element types on the same page (for example, do not show both toggle switches and radio buttons on the same page):

| ![Monero app settings showing two levels: tappable rows on the first level and radio buttons on the second level](/device-app/stax-flex-settings-02.png) |
| :------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                    _The Monero app settings: a first level with tappable rows, and a second level of sub-settings with radio buttons._                   |

## Key takeaways

> **Key takeaway:** 

## Next steps

- [App home screen](./home) — how to design the home screen that leads users to settings and info.
- [Transaction screens](./transactions) — how to implement the transaction review and signing flow.
- [Advanced interactions](./advanced) — handling edge cases such as settings with sub-pages.

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/intro -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Designing blockchain apps for Ledger devices

These guidelines describe best practices for designing a great experience for users of your app. Follow them to ensure your app passes the Ledger review process and delivers a consistent, trustworthy UX across all supported devices.

If you are developing your app using Ledger's high-level APIs and standard transaction templates, your app will already conform to these design guidelines.

## Which apps are covered?

These guidelines apply to blockchain-related apps that cover the standard use cases of sending crypto and NFTs, verifying addresses, or signing messages. This is the majority of apps available today on Ledger Wallet.

Apps with more specific needs and interfaces are not covered by these guidelines; however, the general principles on usability and wording described here are a great starting point. To access the complete NBGL component library if needed, visit the [NBGL repository](https://github.com/LedgerHQ/ledger-secure-sdk/tree/master/lib_nbgl).

## Ledger Stax, Flex, and Nano devices

Whether you start developing your app on Ledger Stax, Ledger Flex, Nano S Plus, or Nano X, porting it to other Ledger devices requires little to no code change, as all devices use the same APIs and graphical libraries.

| ![Ledger Stax and Ledger Flex showing the same Bitcoin app UI, demonstrating that the same app code scales across both touch-screen devices](/device-app/UI-Guidelines-Intro.png) |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                 _The same app code scales to both Ledger Stax and Ledger Flex, including interaction and navigation differences._                                 |

| ![Bitcoin transaction review screen on Ledger Nano S Plus and Nano X, showing the same transaction split across multiple screens](/device-app/nano-bitcoin-transaction.png) |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                      _On Ledger Nano S Plus and Nano X, the same transaction can result in multiple screens if needed._                                     |

Your app's UI is automatically adapted to the target device model when you build your app, dynamically adjusting size, elements, and number of pages. This works best when you use the high-level API endpoints known as "use cases".

> **Note:** The NBGL library's high-level "use case" functions handle layout, pagination, and navigation automatically. Prefer these over low-level rendering calls to stay in compliance with these guidelines with minimal effort.

## In this section

- [App home screen](./home) — the home screen structure, icon, and description.
- [Transaction screens](./transactions) — the full transaction review and signing flow, including blind signing.
- [Address verification](./address) — how to implement address confirmation screens.
- [Info and settings](./info-settings) — how to expose app metadata and user-configurable settings.
- [Advanced interactions](./advanced) — streaming transactions, progressive disclosure, and other edge cases.

## Next steps

Start with the [app home screen](./home) to implement the entry point of your app, then follow the section order above to cover the full user journey. When you are ready to build and test, see the [app boilerplate guide](../how-to/app-boilerplate) to set up your development environment.

---

<!-- https://developers.ledger.com/docs/device-app/integration/design-guidelines/transactions -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Signing transactions and messages

This guide shows you how to implement the transaction review and signing flow in your device app, including Clear Signing, blind signing, and message signing.

Signing transactions is the core function of Ledger's signers, and probably a core function of your app too.

**Prerequisites:** Read the [design guidelines introduction](./intro) before implementing any transaction screen.

## Definitions

### Transactions, messages, and operations

Throughout the Ledger documentation, you will find references to signing "transactions" and "messages". They are defined as:

- **A transaction** affects the state of a blockchain, such as sending Bitcoin or transferring an NFT on Polygon.
- **A message** is an off-chain payload that is signed and then either broadcasted later, bundled with another operation, or used for off-chain verification. This is typically encountered on EVM chains (for example, EIP-191 or EIP-712 such as permits).
- **An operation** is a generic term that can describe a transaction or a message, and can be used as a generic fallback.

### Clear Signing and blind signing

**Clear Signing** means that users fully understand what they are signing. The transaction parameters must be presented in a complete and easy-to-understand way so that the user's consent is fully informed.

Thanks to the secure display of their Ledger device and Ledger's cryptographic infrastructure, users have the guarantee that what they see is what they sign.

While this does not always guarantee execution (which would require full smart contract audits and more), Clear Signing is a must-have for security because it protects users against malware and man-in-the-middle attacks.

User experience greatly benefits from Clear Signing too: only the fields relevant to the review are presented (conciseness) and they are well-formatted (clarity and protection from mistakes).

Because Clear Signing is crucial for security and user-friendliness, blind-signed transactions and messages must display a standard warning that asks for explicit user acknowledgment. This is presented later in this guide.

## Anatomy of a transaction

All transactions and messages must respect the following structure:

![Diagram of the transaction structure on Ledger Stax and Flex, showing intent page, field review pages, and signing page connected by two-sided navigation arrows](/device-app/stax-flex-transaction-structure.png)

The double-sided arrows represent the ability for users to navigate back and forth within the operation. Navigation edge cases are discussed in the [Advanced interactions](./advanced) chapter.

Here is an illustration of this structure with the Bitcoin app on Ledger Flex:

![Bitcoin transaction review structure on Ledger Flex, showing the intent, amount and address fields, fee field, and signing page](/device-app/stax-flex-bitcoin-structure.png)

And the same structure on Nano devices:

![Bitcoin transaction review structure on Ledger Nano devices, showing the same fields split across multiple button-navigated screens](/device-app/nano-bitcoin-structure.png)

> **Warning:** Users must be able to reject the operation at any time, including at the intent and signing steps. Do not modify the default UI elements that display the "Reject" or "Cancel" buttons at the bottom of each step.

In the following sections, we go step by step over the different parts of a canonical transaction.

> **Note:** API\
> nbgl\_useCaseReview()\
> This high-level API function covers the full standard transaction layout presented in this chapter. [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#a303e3242b26535f74695f94a51d8cb6a).

## Loading transaction data

Most transactions and messages load instantaneously for users.

Sometimes, though, processing or data-fetching durations may be noticeable. In these cases, use the standard loader for Ledger Stax and Ledger Flex. As a rule of thumb, show the loader if the loading duration is 1 second or more. Avoid showing the loader for only a few milliseconds, as the flash may appear as a bug to users.

![Loading indicator on Ledger Stax and Flex, showing a spinner while transaction data is being processed](/device-app/stax-flex-loading.png)

## Intent: giving users context before signing

The transaction intent is the first page displayed to users. It is part of Clear Signing and shows crucial information:

- **The nature of the operation:** transaction or message.
- **The chain(s) or network(s) involved.**
- **The type of operation:** send, swap, delegate, approve, list NFT, and so on.
- **Any other useful information** before the detailed review of fields.

The intent acts both as an informational step and a safety net, because users can reject the operation as soon as the prompt is displayed, without reviewing any fields.

> **Note:** When the intent appears, Ledger Stax and Ledger Flex play a sound to attract the user's attention to the device. Keep this default behavior in your app unless you have a specific reason not to. Users can disable sounds in the device settings.

Here are intent examples for different apps and operations:

| ![Intent screen examples on Ledger Stax and Flex: Bitcoin transfer intent, NFT transfer on Polygon intent, and Ethereum Permit2 message intent](/device-app/stax-flex-intent-example-01.png) |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                        _Intent examples, from left to right: Bitcoin transfer, NFT transfer on Polygon, and Ethereum Permit2 message._                                       |

Here are more intent examples from other chains:

![Additional intent screen examples on Ledger Stax and Flex, showing various blockchain operations](/device-app/stax-flex-intent-example-02.png)

When you lack information about the transaction or message, use a generic intent as a fallback:

| ![Generic fallback intent screens on Ledger Stax and Flex, showing minimal information when the operation cannot be decoded](/device-app/stax-flex-generic-intant.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                                 _Generic, fallback intents (to avoid)._                                                                |

> **Warning:** Avoid generic intents as much as possible. Always provide more context so that users can clear sign with confidence, or reject if anything differs from what they expected.

> **Note:** The prompt sentence must start with "Review". It is built either:

## Presenting transaction fields for review

Transaction fields must allow users to fully understand the operation they are signing, while minimizing information that is not useful for their control or safety.

Transaction and message fields are always structured as rows of key-value pairs. The default layout takes care of page construction and pagination automatically.

| ![Bitcoin transfer fields on Ledger Stax and Ledger Flex, showing key-value pairs for amount, recipient, and fees, with layout differences handled automatically by the API](/device-app/stax-flex-layout-differences.png) |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                  _Fields for a Bitcoin transfer, on Ledger Stax and Ledger Flex. Layout differences are handled automatically by the API._                                                 |

Ensure consistency by presenting common fields in a standard order. For simple transfers, this is:

1. "From" address
2. "Amount" (value and currency)
3. "To" address
4. "Fees" (value and currency)

Here is how the Ethereum app displays a transfer by following this guideline:

![Ethereum transfer review on Ledger Stax and Flex, showing From, Amount, To, and Fees fields in the standard order](/device-app/stax-flex-ethereum-transaction.png)

> **Warning:** 

## Signing a transaction

The signing page is always the last one. It ensures that users reviewed all critical fields before confirming.

The signing page recalls the intent by presenting similar data, restoring context at the moment of signing.

Confirming a transaction always uses the same press-and-hold gesture on the dedicated area of the screen: "Hold to sign". After 2 seconds, the transaction is signed and the user receives a success notification accompanied by a sound.

The notification dismisses automatically after a few seconds, and the user is returned to your app's home screen.

| ![Bitcoin transfer signing page on Ledger Stax, showing the Hold to sign gesture and the success notification](/device-app/stax-flex-bitcoin-transfer.png) |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                              _Signing a Bitcoin transfer with the Bitcoin app on Ledger Stax._                                             |

| ![Ethereum Permit2 message signing page on Ledger Flex, showing the Hold to sign gesture](/device-app/stax-flex-permit2-ethereum.png) |
| :-----------------------------------------------------------------------------------------------------------------------------------: |
|                                   _Signing a Permit2 message with the Ethereum app on Ledger Flex._                                   |

> **Warning:** 

## Rejecting a transaction

Rejecting a transaction is a safety action that must be accessible at all times. It sits at the bottom of every screen, from the transaction prompt to the signing step.

When users tap "Reject transaction", a confirmation modal asks them to confirm. This prevents accidental touches.

![Reject transaction confirmation modal on Ledger Stax and Flex, showing the reject button at the bottom and a confirmation dialog](/device-app/stax-flex-rejecting-transaction.png)

## Page grouping

To help users navigate longer or more complex transactions, you can group several field pages into sections using divider pages that show a section title and number:

| ![Page grouping with divider pages in the Stellar app, showing a section title page before and after grouped fields](/device-app/stax-flex-page-grouping.png) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                             _Divider pages to organize a complex signing flow in the Stellar app._                                            |

## Blind signing

When a transaction cannot be fully decoded, you must present a standard "blind signing warning sequence" to users. It must be accompanied by a dedicated setting that the user enables in order to sign non-decoded transactions or messages.

- The "blind signing" setting must be off by default. When it is off, a specific warning is presented when the user attempts to sign a non-decoded transaction.
- After enabling the setting, users must still be warned for every blind transaction.
- On the transaction intent and signature pages, a warning icon is introduced. When tapped, it opens a modal with the detailed risk review.

The example below shows a blind signing sequence on Ledger Stax, where the Ethereum app presents the approval of an unknown ERC-20 token, after the blind signing setting was enabled:

|                         ![Ledger Stax blind signing sequence step 1: unknown ERC-20 token approval with null amount and missing token info](/device-app/stax-blind-signing-01.png)                        |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                             ![Ledger Stax blind signing sequence step 2: warning modal opened from the warning icon on the intent page](/device-app/stax-blind-signing-02.png)                            |
| _The user cannot understand that they are signing a token approval in this example. The last screen appears when the user taps the warning icon in the top-right corner on the intent and signing pages._ |

If the "blind signing" setting is disabled, a dedicated warning redirects the user when they attempt to sign a transaction that cannot be fully decoded:

| ![Ledger Flex blind signing disabled warning, redirecting the user to enable the blind signing setting before proceeding](/device-app/flex-blind-signing.png) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                    _Replace "transaction" with "message" when signing a message instead of a transaction._                                    |

> **Note:** API\
> nbgl\_useCaseReviewBlindSigning()\
> This high-level API function covers the special case of blind-signed transactions and messages presented in this section. [View API docs](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html#aad9da84942ed4c248b8aa18e52b0c321).

## Signing messages

While this chapter mainly focuses on transactions, the same principles apply to messages. Replace "transaction" with "message" consistently throughout the wording.

When messages lack information about their type, structure, blockchain, or network, the prompt and signature screens must use this "scroll" icon:

![Generic message signing screen on Ledger Stax and Flex, showing the scroll icon used when message type and structure are unknown](/device-app/stax-flex-review-transaction.png)

## Key takeaways

> **Key takeaway:** 

## Next steps

- [Address verification](./address) — how to implement address confirmation screens.
- [Info and settings](./info-settings) — how to expose app info and user-configurable settings.
- [Advanced interactions](./advanced) — streaming transactions, progressive disclosure, and other edge cases.
- [NBGL use case reference](https://ledgerhq.github.io/ledger-secure-sdk/nbgl__use__case_8h.html) — full API documentation.

---

<!-- https://developers.ledger.com/docs/device-app/integration/how-to/app-boilerplate -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# How to use the app boilerplate

This guide shows you how to fork and set up the Ledger app boilerplate to start building a  app.

The boilerplate showcases the Ledger Device SDK and the surrounding development tooling: Docker containers, Speculos emulator, and the Ragger test framework. It includes examples for APDU handling, UI flows, cryptography, and build/test/CI integration.

**Who this is for:**

- Developers beginning  app development.
- Developers who want a concise reference for build, test, and CI logic in a  app.

**Supported devices:** Nano S+, Nano X, Stax, Flex, and Nano Gen5.

## Quick start

> **Note:** Rust is mandatory for new projects. The C boilerplate is kept as reference for existing C apps.

### Rust

### Fork the app boilerplate (Rust)

[Click here](https://github.com/LedgerHQ/app-boilerplate-rust) to fork the repository and start your project.

### Set up the VSCode extension

[Use Ledger's VSCode developer tools](../../beginner/vscode-extension) to build, run on Speculos, run functional tests, and load on a device from the VSCode UI.

### C

### Fork the app boilerplate (C)

[Click here](https://github.com/LedgerHQ/app-boilerplate) to fork the repository and start your project.

### Set up the VSCode extension

[Use Ledger's VSCode developer tools](../../beginner/vscode-extension) to build, run on Speculos, run functional tests, and load on a device from the VSCode UI.

## Continuous Integration (CI)

Two workflows are required for app submission: **Build\_and\_functional\_tests** and **Guidelines\_enforcer**.

> **Warning:** Setting up an efficient CI pipeline is crucial for your project's success. The Guidelines enforcer and Build and run functional tests workflows are mandatory for submitting your device application for review.

### Rust

### Build\_and\_functional\_tests

[Build\_and\_functional\_tests](https://github.com/LedgerHQ/app-boilerplate-rust/blob/main/.github/workflows/build_and_functional_tests.yml) builds the app and runs functional tests using Ragger and Speculos.

### Guidelines\_enforcer

[Guidelines\_enforcer](https://github.com/LedgerHQ/app-boilerplate-rust/blob/main/.github/workflows/guidelines_enforcer.yml) calls a reusable workflow used for submission checks.

### C

### Build\_and\_functional\_tests

[Build\_and\_functional\_tests](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/build_and_functional_tests.yml) builds the app and runs functional tests using Ragger and Speculos.

### Guidelines\_enforcer

[Guidelines\_enforcer](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/guidelines_enforcer.yml) calls a reusable guidelines\_enforcer workflow used for submission checks.

## Troubleshooting

**The `Guidelines_enforcer` workflow fails in CI.**
Review the workflow logs to identify the specific rule that failed. Common causes include missing or incorrectly formatted app metadata (in `ledger_app.toml`) and icon size issues. Refer to the [development requirements](../requirements/development) page for the full list of checks.

**Speculos does not launch on macOS.**
Make sure XQuartz is running and that you have enabled "Allow client connections" under **XQuartz > Preferences > Security**. Then restart the Docker container.

## Next steps

After forking either boilerplate and reviewing the included CI workflows and guidelines, adapt the application to your project by:

- Updating metadata in `ledger_app.toml`.
- Implementing your APDU handlers.
- Designing UI flows that follow the [graphic library usage guidelines](../design-guidelines/intro).

When your app is ready, follow the [submission process](../../submission-process/process) to submit it for review.

---

<!-- https://developers.ledger.com/docs/device-app/integration/how-to/clone -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Clone Applications

Use this guide to create and publish a clone (variant) of an existing Bitcoin or Ethereum device application. It focuses on the minimal steps required to complete the task.

## Prerequisites

- Understanding of the device app development framework (learn more [here](../../references/framework))
- Ledger VS Code extension installed and configured (learn more [here](../../beginner/vscode-extension))
- Icons templates [here](../../submission-process/deliverables/icons)
- Signed commits enabled: `git commit -S -m "message"`

## Bitcoin

If you are building a Layer 2 Bitcoin application :

### Fork \[app-btcext-boilerplate]\(https\://github.com/LedgerHQ/app-btcext-boilerplate)

### Customize it

- Add icons
- Customize Makefile and hooks
- Implement validation logic and UX
- Update the README

### Build and test

- Build with the Ledger VS Code extension
- Add tests and ensure CI passes

## Ethereum clones

### 44/60 path

Adding a 44/60 EVM network is straightforward: you submit icons to the [ledger-network-icons](https://github.com/LedgerHQ/ledger-network-icons) repository, and Ledger takes care of adding your network to the Crypto Asset List (CAL).

Follow the [procedure in the repository README](https://github.com/LedgerHQ/ledger-network-icons/blob/main/README.md#procedure-to-add-a-new-network-icon).

> **Warning:** The repository requires signed commits. Use the `-S` flag: `git commit -S -m "your commit message"`

### Other paths

> **Warning:** If your chain does not use the `44/60` path, you won't be able to use Metamask with your device app.

> **Warning:** Make your changes to the `develop` branch only.

> **Warning:** For security reasons, the repository is set up to accept only pull requests with signed commits. To sign your commits, use the -S flag : $ git commit -S -m your commit message

The following page uses the Walton Chain as an example, please replace every `WaltonChain` occurence with the name of your coin and chain.

### Create a file in app-ethereum/makefile\_conf/chain

Following the next example, add a `.mk` file in `app-ethereum/makefile_conf/chain`

```c copy
APP_LOAD_PARAMS += --path "44'/999999'"
TICKER = "WTC"
CHAIN_ID = 15
APPNAME = "WaltonChain"
```

> **Caution:** It is necessary to choose a Derivation Path and a Chain ID specific to your network to prevent the risk of replay attack (Introduced by EIP155) that can happen when using the same Derivation Path ( m/44'/60'/0') and Chain ID as Ethereum. This could expose your users to loss of funds.\
> You can either use the same Derivation Path but define a new chain ID (make sure this is not used by another network) or use slip44/BIP44 standard to reserve a dedicated coin type that will allow you to define a new derivation path.

### Upload your app's icons

- Add your 16x16px Nanos , 14x14px Nano S Plus / Nano X and 32x32 Stax gif icons in the `icons` folder following these naming conventions: `nanos_app_chain_yourchainid.gif`, `nanox_app_chain_yourchainid.gif`, `stax_app_chain_yourchainid.gif`
- Add your 64x64px gif icon in the `icons` folder following this naming convention: `stax_yourchainid_64px.gif`.
  Use the template provided [here](../../submission-process/deliverables/icons).

### Build the application

To build the clone application, use the Ledger VSCode extension. [Follow the beginners' guide if you need help](../../beginner/vscode-extension).

### Add your Network to SLIP-0044

Open a PR to add your network [in this file](https://github.com/satoshilabs/slips/blob/master/slip-0044.md)

### Open a pull request

When your application is ready, open a pull request on the Ethereum application repository and follow the process in [Publishing an application](../../submission-process/process).

---

<!-- https://developers.ledger.com/docs/device-app/integration/how-to/plugin -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# How to develop an Ethereum plugin

This guide shows you how to start developing an Ethereum plugin for your dApp's smart contract interactions.

The [ERC-7730 process](../../../clear-signing/understand/what-is-clear-signing) replaces plugins for simple cases by providing a standardized way to display transaction information. However, more specific dApps with complex smart contract interactions may still require custom plugin development to provide Clear Signing capabilities for their users.

> **Warning:** Plugin development requires prior approval from Ledger. If your project requires a plugin, you are already in contact with Ledger and have been directed to develop one. Plugin development is only undertaken when Ledger has determined that your use case cannot be adequately handled by the standard ERC-7730 process.

**Prerequisites:**

- You have been approved by Ledger to develop a plugin.
- You are familiar with C development and Ledger device app architecture. See [What is a device app?](../../explanation/device-app-role) for an overview.

## What's included in the Ethereum Plugin SDK

The [Ethereum Plugin SDK documentation](https://ethereum-plugin-sdk.ledger.com/) provides comprehensive guidance for plugin development, including:

### Core components

- **Plugin architecture** — how plugins work alongside the Ethereum application.
- **Handler functions** — the key functions you implement: `handle_init_contract`, `handle_provide_parameter`, `handle_finalize`, and others.
- **Utility functions** — pre-built helpers for common operations.
- **Transaction data parsing** — tools for extracting and formatting smart contract data.

### Development tools

- **Ethereum Plugin SDK** — the main framework that handles integration with the Ethereum app.
- **Plugin boilerplate** — a template repository to get started quickly.
- **Test framework** — functional tests and fuzzing capabilities.
- **CI workflows** — automated testing and quality assurance.

### File structure

A complete plugin includes:

- Source code (in C)
- Plugin specification document
- Icons and glyphs for device display
- Makefile and build configuration
- Test suite and fuzzing setup

## Getting started

To develop your Ethereum plugin:

1. **Read the SDK documentation** — use the comprehensive guide at [ethereum-plugin-sdk.ledger.com](https://ethereum-plugin-sdk.ledger.com/).
2. **Fork the boilerplate** — start with the official Plugin Boilerplate template linked from the SDK docs.
3. **Implement your handlers** — focus on the smart contract parsing logic specific to your dApp, starting with `handle_init_contract` and `handle_provide_parameter`.
4. **Write functional tests** — cover all transaction paths your plugin handles. Tests are mandatory for submission.
5. **Submit for review** — when your plugin and tests are ready, follow the [submission process](../../submission-process/process).

## Troubleshooting

**CI: the `Guidelines_enforcer` workflow fails.**
The enforcer checks against Ledger's published app guidelines. Review the workflow logs for the specific rule that failed, then refer to the [security requirements](../requirements/security) and [development requirements](../requirements/development) pages to address each issue.

**I am not sure whether my use case needs a plugin or can use ERC-7730.**
Start with the [ERC-7730 process](../../../clear-signing/understand/what-is-clear-signing). If your smart contract interactions are too complex for that standard, contact Ledger to discuss plugin development.

## Next steps

Your plugin is ready when it passes all functional tests and the CI workflows. Submit it alongside your deliverables using the [submission form](../../submission-process/submission-form).

- [Ethereum Plugin SDK documentation](https://ethereum-plugin-sdk.ledger.com/) — full technical reference for plugin development.
- [Submission process](../../submission-process/process) — how to submit your plugin for review.
- [Development requirements](../requirements/development) — mandatory CI workflows and tooling requirements.

---

<!-- https://developers.ledger.com/docs/device-app/integration/requirements/cryptography -->

---
title: Cryptography requirements
category: reference
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Cryptography requirements

The rules below are mandatory for all device apps submitted to Ledger. Each rule addresses a specific class of vulnerability. For the reasoning behind each requirement, see [Cryptography — why the rules exist](../../explanation/cryptography).

## Rules

This section presents general concepts about cryptography development, but also guidelines specific to the security model of the Ledger devices. It gives guidelines to:

- Ensure a potential vulnerability in one application will not cause damages to other apps.
- Make sure all the operations that manipulate secrets are approved by the user.
- Restrict the use of these secrets by apps.

### Never store or export secrets derived from seed

The seed allows the user to derive any key from a given path at will. The user can reconstruct this secret from a new device by reentering its seed if he were to lose the original device.

Generating secrets must be done on demand. An application **must not** store a secret derived from the seed, and should regenerate it instead then erased when it is not used anymore.

Even in encrypted form, those secrets **must not** be stored outside of the device. They can be regenerated instead.

### Avoid blindly signing data

**You must never allow signing of any attacker-controlled message unless it has been verified for structural validity. Importantly, you must never sign a message that might be a hash of transaction.**

Rationale: If you allow an attacker to blindly sign a message, it can easily supply a hash of a valid transaction. Your signature could then be used to send an unauthorized transaction.

If you want to sign user-supplied "personal" messages, you **must** prefix them with a fixed string (which shouldn't be a valid transaction prefix). It is also a good practice to include message length in the text to be signed. Ledger-app-eth has a good example in function `handleSignPersonalMessage`. Note that sometimes cryptocurrencies have a standardized way of signing such personal messages and in that case you should use the approved scheme.

Warning: If you allow signing untrusted hashes (while displaying a prompt to the user), be aware that

1. Some users are not familiar with security and could be easily tricked. They can click through your prompt without properly checking unless you give them explicit "Warning: this is a very unusual operation. Do not continue unless you know what you are doing" warning. They might not see the message even then.
2. A compromised host might both change hash on the screen and also data sent to device. This opens the possibility of users signing something they didn't want to.

### Signing/disclosing keys

> **Warning:** You must always require user approval for signing transactions/messages.

Rationale: If you do not require user consent for signing important data, an attacker can use your device as a signing black box and sign whatever they want.

> **Note:** You might also consider approvals for extracting public keys, as some users might want extended privacy.

1. They might not want to reveal their _root/account_ public key, only address keys
2. They might not want to reveal address public key until it is required. (Some cryptocurrencies use addresses that are hash of public keys. It is therefore enough to send the address to the host).

> **Note:** There is a trade-off between privacy and usability here. If you want privacy, it would require a user interaction every time they want to use Ledger device, as opposed to only interaction while signing transactions. The behaviour could also be manually set in the application options.

### Don't roll your own crypto primitives

**You should never roll your own crypto primitives** (including encryption/derivation schemes, hashing functions, HMAC, etc.)

Rationale: It is a purpose of Ledger OS operating system to perform these in a secure manner. Importantly, writing your own crypto primitives is likely to open you to side-channel attacks or other problems. If your primitive is not supported by Ledger OS (e.g., some very new cryptography), consult with Ledger developers the possibility of including it in the OS.

### Avoid Exceptions for Cryptographic Code

From the 2.0 version of the SDK every cryptographic function has a version that returns an error code instead of raising an exception. As an example `cx_ecdsa_sign_no_throw` performs the same computation as `cx_ecdsa_sign` but does not raise any exception and returns CX\_OK if everything went fine.

We enforce using all `_no_throw` equivalents when available, as the ones raising exceptions are deprecated in a future SDK release.

Rationale: the exception mechanism is not standard C, and is difficult to use, particularly for error management. There were errors related to this exception model in every single app we reviewed in 2020.

### Private Key Management

**You should minimize the code that works with private (ECDSA, RSA, etc.) or secret (HMAC, AES, etc.) keys.** Importantly, you **must always clear the memory** after you use these keys. That includes key data and key objects.

Leaving parts of private or secret keys lying around in memory is not a security issue on its own because there is no easy way to extract the RAM content on the chip. If a key is left in RAM by an app, another app will not be able to access it.

However, if the key has not properly been erased, a security issue could lead to the leak of this key, even if it is not used anymore. An attacker able to read arbitrary memory from the app, or execute arbitrary code, will be able to read the content of the stack segment, hence the parts of the key which have not been erased.

Here is an example of a common and **wrong way** of doing this:

```c copy
uint8_t privateKeyData[64];
cx_ecfp_private_key_t privateKey;

os_perso_derive_node_bip32(
    tmpCtx.transactionContext.curve, tmpCtx.transactionContext.bip32Path,
    tmpCtx.transactionContext.pathLength, privateKeyData,
    NULL);
cx_ecfp_init_private_key(tmpCtx.transactionContext.curve, privateKeyData,
                         32, &privateKey);
explicit_bzero(privateKeyData, sizeof(privateKeyData));

// (later, after privateKey is not needed)
explicit_bzero(&privateKey, sizeof(privateKey));
```

In the happy path, the previous code will correctly clean the memory once the private key is initialized. Note, however, that this code **fails to protect private keys in case some system call throws (for example cx\_ecfp\_init\_private\_key)**. Correct code should wrap the clearing in `BEGIN_TRY { TRY { ... } FINALLY { explicit_bzero() } END_TRY;`.

Applications where such issues were fixed include [the ARK app](https://github.com/LedgerHQ/app-ark/commit/e84a4dc0c422f7ade586c831cbab56cb15c64df1) and [the Solana app](https://github.com/LedgerHQ/app-solana/pull/5/files).

---

<!-- https://developers.ledger.com/docs/device-app/integration/requirements/development -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Development

## Workflows

Ledger provides [reusable workflows running on GitHub actions](https://github.com/ledgerhq/ledger-app-workflows), which
builds, analyzes or tests the code, checks the application's metadata and more. Some of these workflows are mandatory.

> **Warning:** * The following workflows are required on every device app repository, and must run without error.
> * Ledger will not deploy an application if these workflows are not integrated and green.

- The [guidelines enforcer workflow](https://github.com/LedgerHQ/ledger-app-workflows/blob/master/.github/workflows/reusable_guidelines_enforcer.yml)
  (example its usage on boilerplate [here](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/guidelines_enforcer.yml))
- The [build workflow](https://github.com/LedgerHQ/ledger-app-workflows/blob/master/.github/workflows/reusable_build.yml)
  (example of its usage on boilerplate [here](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/build_and_functional_tests.yml#L21-L25))

## Manifest

Some high-level application metadata must be declared in a `ledger_app.toml` manifest file, stored at the root of the
application repository.

The format of this manifest is described [here](https://github.com/LedgerHQ/ledgered/blob/master/doc/utils/manifest.md),
along with the tool which can be used to check the validity of the manifest.
You can also use [the manifest in Boilerplate](https://github.com/LedgerHQ/app-boilerplate/blob/master/ledger_app.toml)
as a living example

Most of our workflows (including the mandatory ones) use this manifest to infer environment data (like the SDK language,
or the build directory) so the validity of the manifest can be checked through these.

> **Warning:** Ledger will not deploy an application without a correct `ledger_app.toml` manifest.

## Tests

The application repository must have a `tests` folder that contains at least functional tests using the
[Speculos](../../references/tools#speculos) emulator. These tests must be triggered by the CI and running without error.

> **Warning:** Ledger will not deploy an application without tests or with failing tests.

For Python tests, Ledger provides the [`Ragger` library](https://github.com/ledgerhq/ragger), which can be easily
integrated with `Pytest` in the GitHub action with the [Ragger workflow](https://github.com/LedgerHQ/ledger-app-workflows/blob/master/.github/workflows/reusable_ragger_tests.yml)
(example of its usage on boilerplate [here](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/build_and_functional_tests.yml#L27-L32))

Unit tests are highly recommended, especially for critical functions like parsers - preferably relying on a standard framework like [cmocka](https://cmocka.org/). These tests must be automated using GitHub actions the [unit tests workflow](https://github.com/LedgerHQ/app-boilerplate/blob/master/.github/workflows/unit_tests.yml) of the Boilerplate application can act as a reference.

## Nice to have

On top of that, we also encourage the following practices:

- Linting helps improving code quality and ensuring consistent coding style and resolving basic coding errors.
- Developing a fuzzer (example of its usage on boilerplate [here](https://github.com/LedgerHQ/app-boilerplate/tree/master/fuzzing)).
- Integration with the Coverity static code analysis tool helps finding security issues and software defects.

---

<!-- https://developers.ledger.com/docs/device-app/integration/requirements/security -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Security

## Application parameters: minimal and declared

Refer to [this section](../../references/app-permissions) for further information.

### App permissions

Every app must declare a set of permissions it needs to run properly. These permissions must be minimal, and be declared
not only in each app repository, but also listed  in the
[Ledger app database](https://github.com/LedgerHQ/ledger-app-database).

The coherence between these permissions and the app `Makefile` is verified as part of
[Ledger guidelines enforcer GitHub workflow](https://github.com/ledgerhq/ledger-app-workflows),
[which is also a requirement](./development#workflows).

> **Warning:** Ledger will not deploy an app if its permissions have not been registered in Ledger app database.

### Derivation path

The application derivation paths must be restricted to coin-specific BIP32 prefix, and declared in the
[Ledger app database](https://github.com/LedgerHQ/ledger-app-database).

The coherence between these derivation path and the app `Makefile` is verified as part of
[Ledger guidelines enforcer GitHub workflow](https://github.com/ledgerhq/ledger-app-workflows),
[which is also a requirement](./development#workflows).

More information regarding how to choose and configure derivation paths are available on the [application permissions page](../../references/app-permissions).

> **Warning:** Ledger will not deploy an app if its derivation paths have not been registered in Ledger app database.

> **Warning:** Ledger will not deploy apps whose BIP32 prefixes have not been properly set.

> **Warning:** If your application derives keys on the hardened path 44'/60' then the chainID parameter must be different from 0 or 1. This is necessary to avoid replaying transactions broadcoast on Ethereum-like chains on Ethereum. As a general recommendation, and to ensure a good level of privacy for the end user, we recommend to always use the correct coin type in the derivation path as defined in [ slip44 ](https://github.com/satoshilabs/slips/blob/master/slip-0044.md)

## Signing settings

### Signing

> **Warning:** All signing transactions/messages action must ask for the user approval before happening.

More information [here](../../explanation/cryptography#signingdisclosing-keys).

### Blind Signing

As a general rule, [blind signing should be avoided](../../explanation/cryptography#avoid-blindly-signing-data), however it is tolerated under some circumstances.

For every transaction, the users must be able to verify on the device the amount being transferred and the destination address or the validator/nominator address(es) in the case of a staking operation, and the fees being paid.

When the display of those parameters (Token, smart contract management) is not possible, the transaction should be rejected by the device unless the user has acknowledged that they will be blind signing.

To implement this requirement it is recommended to have a setting menu with the possibility to enable/disable blind signing.

> **Warning:** If blind signing is implemented, it must be **disabled** by default.

You can find implementation example inside [Ethereum](https://github.com/LedgerHQ/app-ethereum) code base.

## CodeQL

[CodeQL](https://codeql.github.com/docs/) is required to perform security checks and detect vulnerabilities.
It can be directly integrated into your project by creating a new YAML file: `.github/workflows/codeql-workflow.yaml` in your repository.

A complete [codeql-workflow.yml](https://github.com/LedgerHQ/app-boilerplate/blob/0cdb0059e4f374b796b25ed347202c5e4e3e558a/.github/workflows/codeql-workflow.yml) file is available in the repository of the Boilerplate app.

The first part of the file is an initialization of what is needed to build your Ledger app and a declaration of languages used in your code so CodeQL analyzes it in the right way.

```yaml copy
jobs:
  analyse:
    name: Analyse
    strategy:
      matrix:
        sdk: ["$NANOX_SDK", "$NANOSP_SDK", "$STAX_SDK", "$FLEX_SDK"]
        language: [ 'cpp' ]
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder-legacy:lite
```

The action part needs 4 steps:

- Clone your repository
- Initialize CodeQL:
  - Declaration of which languages are used and the chosen queries. Please choose the `security-and-quality` queries.
- Build the app. Be careful : the initialization of CodeQL needs to be done before building the app so that CodeQL makes the code dictionary during the building stage.
- Perform the CodeQL analysis

```yaml copy
steps:
  - name: Clone
    uses: actions/checkout@v4
    with:
      submodules: true

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v3
    with:
      languages: ${{ matrix.language }}
      queries: security-and-quality

  - name: Build
    run: |
      make BOLOS_SDK=${{ matrix.sdk }}

  - name: Perform CodeQL Analysis
    uses: github/codeql-action/analyze@v3
```

Next the results of CodeQL are displayed on your GitHub security view, in the “Code scanning alerts” panel. If CodeQL is configured to run when a pull request (PR) on some branches is made, the results will also be shown in the “Checks” parts of the PR.

![Code Scanning view](/device-app/codeql_codescanning_view.png)

![Pull request view](/device-app/codeql_pr_view.png)

The security issues with a severity level higher than low must be fixed before going through the security audit. The quality issues with a level set to error must also be fixed.

---

<!-- https://developers.ledger.com/docs/device-app/references/app-permissions -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# App permissions

Every application has a set of permissions. These range from system permissions, such as modifying the system configuration or requesting user PIN verification, to signer functions, such as deriving keys that only a specific app can access.

The following sections describe how Ledger grants these permissions. Follow the principle of least privilege: each application must use only the permissions necessary for its operation.

### Application flags

An application's privileges or permissions are defined in its Makefile.

The most notable flags are:

- `HAVE_APPLICATION_FLAG_BOLOS_SETTINGS`: The application can read and modify system parameters, such as the device's name.
- `HAVE_APPLICATION_FLAG_GLOBAL_PIN`: The application can request user PIN verification or query the number of attempts remaining before the signer erases its memory.
- `HAVE_APPLICATION_FLAG_LIBRARY`: The application can act as a library and export functions that other applications can access.

A common use of `HAVE_APPLICATION_FLAG_BOLOS_SETTINGS` is to enable the BLE channel on Ledger Nano X, Ledger Flex, and Ledger Stax:

```makefile copy
ifeq ($(ENABLE_BLUETOOTH), 1)
ifeq ($(TARGET_NAME),$(filter $(TARGET_NAME),TARGET_NANOX TARGET_STAX TARGET_FLEX))
    HAVE_APPLICATION_FLAG_BOLOS_SETTINGS = 1
    DEFINES += HAVE_BLE BLE_COMMAND_TIMEOUT_MS=2000 HAVE_BLE_APDU
    DEFINES += BLE_SEGMENT_SIZE=32
    SDK_SOURCE_PATH += lib_blewbxx lib_blewbxx_impl
endif
endif
```

Other flags are generally not used.

You must justify the use of any flag other than `HAVE_APPLICATION_FLAG_BOLOS_SETTINGS` in the Makefile. Otherwise, Ledger will not sign the application.

### Restrict apps to coin-specific BIP32 prefixes

Ledger signers are hierarchical deterministic wallets. They can derive as many keys as necessary from a single seed, as defined in [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).
The seed generates the master node of a tree of subkeys. Although these trees can have different structures, they should follow established standards.
The first level in the subkey hierarchy should always correspond to a 'purpose', as described in [BIP-0043](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki).

All coins must follow the logic defined in [BIP-0044](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). If a coin is registered in [SLIP-0044](https://github.com/satoshilabs/slips/blob/master/slip-0044.md), its application must derive keys only in the registered subtree. If the coin is not registered, choose a subtree, or 'path', that does not conflict with a subtree used by another application.

> **Warning:** Ledger will not sign apps whose BIP32 prefixes have not been properly set.

Set the `PATH_APP_LOAD_PARAMS` property in the app Makefile to restrict the derivation path.

For example, if your application derives keys on the hardened path 44'/60', specify in your Makefile:

```makefile copy
PATH_APP_LOAD_PARAMS += "44'/60'"
```

Use the wildcard symbol `*` to derive all purposes for a specific coin type:

```makefile copy
PATH_APP_LOAD_PARAMS += "*/0'"
```

> **Warning:** The value 0x7fffffff is used to encode the wildcard symbol and is therefore forbidden.

Use the `CURVE_APP_LOAD_PARAMS` property to restrict derivation to a specific curve. Supported curves are `secp256k1`, `secp256r1`, `ed25519`, and `bls12381g1`.

You can configure several curves and paths at the same time. For example, if your app must derive keys on paths 44'/535348', 13', and 17' with the Ed25519 and prime256r1 curves, add the following to the Makefile:

```makefile copy
CURVE_APP_LOAD_PARAMS += ed25519 prime256r1
```

#### Rationale

Application-specific BIP32 prefixes provide defense in depth. A unique, hardened derivation prefix gives each application a separate cryptographic namespace, even when applications share the same master seed. If an attacker exploits a vulnerable or backdoored application, they cannot use it to extract private keys from other apps, such as Bitcoin or Ethereum.

For example:

- A Bitcoin application may be restricted to the hardened prefix

```
m / * / 0' / …
m / 45' / ...
```

- An Ethereum application may be restricted to

```
m / 44' / 60' / …
```

These apps do not share keys and are therefore isolated from each other.

At least one component of each prefix must be hardened. Unhardened derivation steps are forbidden at the application boundary.
If an application could derive or expose an unhardened child private key together with its extended public key, an attacker could recover the parent private key. In the worst case, this could disclose the master key or higher-level keys, break isolation, and enable cross-application key extraction.

With hardened prefixes, even a fully compromised or malicious application can derive keys only within its assigned subtree. Moving upward in the derivation hierarchy or laterally into another application's subtree is cryptographically infeasible. Examples include the Bitcoin subtree (m / \* / 0') and Ethereum subtree (m / 44' / 60') above.

Application-specific hardened BIP32 prefixes create a strict isolation boundary at the key-derivation layer. They limit the scope of a compromise, prevent master key leakage, and prevent a vulnerable or backdoored application from accessing other applications' private keys.

---

<!-- https://developers.ledger.com/docs/device-app/references/cryptography-api-examples -->

---
title: Cryptography library and syscalls examples
category: reference
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Cryptography library and syscalls examples

This page shows how to call functions from the Ledger OS cryptography API. It covers digital signatures (ECDSA with Secp256k1, EdDSA with Ed25519/Ed448, Schnorr/BIP-0340) and symmetric encryption (AES-CBC).

> **Note:** This page focuses on calling the API correctly. For conceptual background on asymmetric and symmetric cryptography, elliptic curves, and block ciphers, see the [device app architecture overview](../../explanation/architecture).

## Digital signature algorithms

### ECDSA (Secp256k1)

ECDSA is a standard digital signature scheme relying on elliptic curves. A signature scheme usually consists of three algorithms:

- a **key generation** algorithm generates a pair of private key and public key
- a **signature** algorithm signs the digest of a message with the private key
- a **verification** algorithm verifies a signature with the public key

ECDSA uses Weierstrass curves, i.e. curves expressed with a (simple) Weierstrass equation: `y^2 = x^3 + a * x + b`. `a` and `b` are parameters of the curve but they don't need to be detailed in this document (we only write this equation to highlight the difference between a Weierstrass curve and a twisted Edwards curve introduced later in this document).

One of the most common (Weierstrass) curve is Secp256k1.

#### Key generation

The function generates a random integer as the **private key** while the public key is a **point** on the chosen curve. A point is represented by its coordinates `(x,y)` which are each represented by an integer.

There are two ways to get the pair of keys:

1. Generate both randomly with `cx_ecfp_generate_pair_no_throw`. In this case, the function initializes the structures `cx_ecfp_private_key_t` and `cx_ecfp_public_key_t` which hold the private key and the public key respectively.
2. Initialize the private key with `cx_ecfp_init_private_key_no_throw` given a bytes array and generate the public key with `cx_ecfp_generate_pair_no_throw`. `cx_ecfp_init_private_key_no_throw` initializes a structure `cx_ecfp_private_key_t` which holds the private key used to sign a message and `cx_ecfp_generate_pair_no_throw` calculates the public key and initializes a structure `cx_ecfp_public_key_t` which holds the public key used to verify a signature.

For example, a pair of private/public key to be used with the curve Secp256k1 is generated as follows:

Case 1:

```c
cx_ecfp_private_key_t privateKey;
cx_ecfp_public_key_t publicKey;
cx_ecfp_generate_pair_no_throw(CX_CURVE_SECP256K1, &publicKey, &privateKey, 0); /* the '0' indicates that a random private key should be generated */
```

Case 2:

```c
uint8_t rawKey[32] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
                      0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10,
                      0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
                      0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20}; /* The key in a bytes array */
cx_ecfp_private_key_t privateKey;
cx_ecfp_public_key_t publicKey;
cx_ecfp_init_private_key_no_throw(CX_CURVE_SECP256K1, rawKey, sizeof(rawKey), &privateKey);
cx_ecfp_generate_pair_no_throw(CX_CURVE_SECP256K1, &publicKey, &privateKey, 1); /* the '1' indicates that a private key has already been generated and initialized */
```

If one needs only to verify a given signature, there is no need to generated a pair of keys. Thus, only the public key has to be initialized with `cx_ecfp_init_public_key_no_throw` given a bytes array representing the point with the prefix `04` (This convention must be respected).

In the following example, `rawPKey` is a bytes array filled with the prefix `04` followed by the 32-byte x-coordinate and the 32-byte y-coordinate of the point representing the public key.

```c
uint8_t rawPKey[65] = {0x04, 0x84, 0xbf, 0x75, 0x62, 0x26, 0x2b, 0xbd, 0x69,
                             0x40, 0x08, 0x57, 0x48, 0xf3, 0xbe, 0x6a, 0xfa,
                             0x52, 0xae, 0x31, 0x71, 0x55, 0x18, 0x1e, 0xce,
                             0x31, 0xb6, 0x63, 0x51, 0xcc, 0xff, 0xa4, 0xb0,
                             0x8c, 0xc4, 0x3d, 0x63, 0xb2, 0x85, 0x9d, 0x46,
                             0x9f, 0xee, 0x15, 0xf3, 0x1c, 0x9e, 0xdb, 0x53,
                             0x24, 0x26, 0x6e, 0x6f, 0xd0, 0x40, 0x7e, 0x87,
                             0x38, 0x2d, 0x60, 0xfc, 0x45, 0x11, 0xac, 0xd8};
cx_ecfp_public_key_t publicKey;
cx_ecfp_init_public_key_no_throw(CX_CURVE_SECP256K1, rawPKey, sizeof(rawPKey), &publicKey);
```

#### Signing

The signature function takes as input a private key, previously initialized, the digest of a message and outputs an **encoded signature** (DER encoded). The signature algorithm may be:

1. **deterministic**, i.e. the same signature is calculated each time, given the same inputs. In this case the mode `CX_RND_RFC6979` must be specified.

2. **random**, i.e. the signature values change each time, even if the inputs are identical. In this case the mode `CX_RND_TRNG` must be specified.

The message shall be hashed to get the correct input length, depending on the chosen curve. Following the previous example with the curve Secp256k1, a message `msg` is first hashed with the **hash function** `SHA-256` as follows:

```c
uint8_t msg[] = "sample";
uint8_t digest[CX_SHA256_SIZE]; /* CX_SHA256_SIZE is 32 bytes */
cx_hash_sha256(msg, sizeof(msg), digest, CX_SHA256_SIZE);
```

Assuming that `privateKey` has been initialized with the curve Secp256k1 and the `digest` of the message has been computed as in the previous example, an example of a _random signature_ with the curve Secp256k1 is as follows:

```c
uint8_t signature[256];
size_t signatureLen = sizeof(signature);
cx_ecdsa_sign_no_throw(&privateKey, CX_RND_TRNG, CX_SHA256, digest, CX_SHA256_SIZE, signature, &signatureLen, NULL)
```

#### Verification

The verification function takes as input the public key, the digest of the message and the corresponding (encoded) signature and returns `1` if the signature is verified and `0` otherwise.

Assuming that `publicKey` has been initialized with the curve Secp256k1 and the signature `signature` has been calculated as in the previous example, an example of a signature verification with the curve Secp256k1 is as follows:

```c
cx_ecdsa_verify_no_throw(&publicKey, digest, CX_SHA256_SIZE, signature, signatureLen);
```

### EdDSA (Ed25519 and Ed448)

EdDSA is a digital signature scheme relying on specific curves, called **Edwards curves**. Especially, in this section, we consider **twisted Edwards curves**. The equation of these curves is different from the Weierstrass equation. They are defined by: `a * x^2 + y^2 = 1 + d * x^2 * y^2`, where `a` and `d` are parameters of the curve.

We supported two twisted Edwards curves: **Ed25519** and **Ed448**. As before, the signature scheme consists of three algortihms: key generation, signature and verification.

#### Key generation

As for ECDSA, a pair of private key and public keys is generated with `cx_ecfp_generate_pair_no_throw` or the private key is first initialized with `cx_ecfp_init_private_key_no_throw` and the corresponding public key is generated and initialized with `cx_ecfp_generate_pair_no_throw`.

The following code describes the initialization of the private key and the generation of a public key for Ed25519:

```c
uint8_t rawKey[32]; /* All zero key */
cx_ecfp_private_key_t privateKey;
cx_ecfp_public_key_t publicKey;
cx_ecfp_init_private_key_no_throw(CX_CURVE_Ed25519, rawKey, 32, &private_key);
cx_ecfp_generate_pair_no_throw(CX_CURVE_Ed25519, &publicKey, &privateKey, 1);
```

In the case of Ed448:

```c
uint8_t rawKey[57]; /* All zero key */
cx_ecfp_512_private_key_t privateKey;
cx_ecfp_512_public_key_t publicKey;
cx_ecfp_init_private_key_no_throw(CX_CURVE_Ed448, rawKey, 57, (cx_ecfp_private_key_t *)&private_key);
cx_ecfp_generate_pair_no_throw(CX_CURVE_Ed448, (cx_ecfp_public_key_t *)&publicKey, &privateKey, 1);
```

The generation of a random pair for Ed25519 is as follows:

```c
cx_ecfp_private_key_t privateKey;
cx_ecfp_public_key_t publicKey;
cx_ecfp_generate_pair_no_throw(CX_CURVE_Ed25519, &publicKey, &privateKey, 0);
```

In the case of Ed448:

```c
cx_ecfp_512_private_key_t privateKey;
cx_ecfp_512_public_key_t publicKey;
cx_ecfp_generate_pair_no_throw(CX_CURVE_Ed448, (cx_ecfp_public_key_t *)&publicKey, &privateKey, 0);
```

Depending on the length of the keys, one should use the correct structures to hold the keys. For Ed25519, `cx_ecfp_private_key_t` (`cx_ecfp_public_key_t` for the public key) is used since the private key is 32-byte long (the public key is 64-byte long), while the 57-byte (456 bits) private key used with Ed448 must be stored within `cx_ecfp_512_private_key_t` and the 114-byte public key must be stored within `cx_ecfp_512_public_key_t`.

#### Signing

The signature is performed by the function `cx_eddsa_sign_no_throw`. In contrary to ECDSA, the digest of the message is calculated inside the function so it mustn't be calculated before. However, the identifier of the algorithm used to compute the digest (hash function) must be specified. Usually, `SHA-512` is used for Ed25519 and `SHAKE-128` for Ed448. Here are some examples:

Assuming that the keys have been properly generated and initialized as in the previous examples, the signature of a message with the curve Ed25519 is obtained as follows:

```c
uint8_t msg[] = "sample";
uint8_t signature[64]; /* The length of the signature is 64 bytes */
cx_eddsa_sign_no_throw(&privateKey, CX_SHA512, msg, sizeof(msg), signature, 64);
```

Similarly, the signature of a message with the curve Ed448 is obtained as follows:

```c
uint8_t msg[] = "sample";
uint8_t signature[114]; /* The length of the signature is 114 bytes */
cx_eddsa_sign_no_throw((cx_ecfp_private_key_t *)&privateKey, CX_SHAKE128, msg, sizeof(msg), signature, 114);
```

#### Verification

The signature verification is performed by the function `cx_eddsa_verify_no_throw`. As for the signature, the identifier of the hash function is specified.

The verification of the signature is done as follows for Ed25519:

```c
cx_eddsa_verify_no_throw(&publicKey, CX_SHA512, msg, sizeof(msg), signature, 64);
```

And for Ed448:

```c
cx_eddsa_verify_no_throw((cx_ecfp_public_key_t *)&publicKey, CX_SHAKE128, msg, sizeof(msg), signature, 114);
```

### Schnorr signatures (BIP-0340)

Schnorr signatures are variants of ECDSA. In this document, we give examples for the variant specified in BIP0340 for the Taproot upgrade of Bitcoin. The curve used is Secp256k1.

#### Key generation

The key generation is the same as for ECDSA.

#### Signing

The signature is performed by the function `cx_ecschnorr_sign_no_throw` which takes as input the private key, the message (not any digest), and an **auxiliary data** which is usually some random data. The auxiliary data is given to the function through the `sig` parameter and the value `CX_RND_PROVIDED` is set to the `mode` parameter to specify this. The parameter `sig` contains the calculated signature if the function returns properly.

In the example below, the value `CX_ECSCHNORR_BIP0340` is also set to the `mode` parameter to specify that the BIP-0340 implementation is used.

Thus, assuming a properly generated and initialized private key `privateKey`, a message `msg` and an auxiliary data `aux`, the signature is done as follows:

```c
uint8_t msg[32]; /* All zero message */
uint8_t aux[32]; /* All zero auxiliary data */
uint8_t signature[64];
size_t signatureLen = sizeof(signature);
memcpy(signature, aux, sizeof(aux)); /* First copy the auxiliary data to the signature array */
cx_ecschnorr_sign_no_throw(privateKey, CX_ECSCHNORR_BIP0340 | CX_RND_PROVIDED, CX_SHA256, msg, sizeof(msg), signature, &signatureLen);
```

In this example, the hash function used is SHA-256.

## Symmetric encryption (AES-CBC)

An encryption is the process of transforming an **intelligible** message to an **unintelligible** one. This transformation must be reversible, i.e. the intelligible message can be recovered by the recipient. This transformation is the decryption. Both encryption and decryption are parametrized by a secret key.

### Key initialization

The secret key needs to be initialized before one calls the encryption or decryption function. Different sizes of key can be used so it must be specified first. According to the algorithm used, the structure `cx_aes_key_t` or `cx_des_key_t` is initialized given a bytes array with the function `cx_aes_init_key_no_throw` or `cx_des_init_key_no_throw`.

For example, to perform an AES encryption with a 128-bit key, the initialization step is done as follows:

```c
uint8_t rawKey[16]; /* All zero key */
cx_aes_key_t aesKey;
cx_aes_init_key_no_throw(rawKey, sizeof(rawKey), &aesKey);
```

If a 192-bit key is used:

```c
uint8_t rawKey[24];
cx_aes_key_t aesKey;
cx_aes_init_key_no_throw(rawKey, sizeof(rawKey), &aesKey);
```

If a 256-bit key is used:

```c
uint8_t rawKey[32];
cx_aes_key_t aesKey;
cx_aes_init_key_no_throw(rawKey, sizeof(rawKey), &aesKey);
```

### Encryption

The encryption function takes as input a secret key, an **initialization vector** (which is needed to perform a chained encryption), and the plaintext and outputs the ciphertext. Since the block cipher works on blocks, if the length of the plaintext is not a multiple of the block size, the plaintext must be padded, i.e. additional data is added at the end of the message to fulfill this requirement. This is done by specifying a type of **padding method**:

1. `CX_PAD_ISO9797M1` to complete the plaintext with only `0`.

2. `CX_PAD_ISO9797M2` to complete the plaintext with one `1`, then all `0`.

If the padding is not required, `CX_PAD_NONE` is used.

The encryption is performed by `cx_aes_iv_no_throw` or `cx_des_iv_no_throw` depending on the algorithm. This function can perform both encryption and decryption so the value `CX_ENCRYPT` must be passed to the `mode` parameter for encryption and `CX_DECRYPT` for decryption.

The encryption of a 32-byte plaintext using AES in CBC mode and with a 128-bit key is done as follows:

```c
uint8_t plaintext[32]; /* All zero plaintext */
uint8_t iv[16]; /* The length of the initialization vector is always 16 */
uint8_t ciphertext[32];
size_t ciphertextLen = sizeof(ciphertext);
cx_aes_iv_no_throw(&aes_key, CX_ENCRYPT | CX_PAD_NONE | CX_CHAIN_CBC, iv, CX_AES_BLOCK_SIZE, plaintext, sizeof(plaintext), ciphertext, &ciphertextLen); /* CX_AES_BLOCK_SIZE is 16 bytes */
```

The encryption of a 21-byte plaintext using the padding method `CX_PAD_ISO9797M1` (with AES in CBC mode):

```c
uint8_t plaintext[21];
uint8_t iv[16]; /* The length of the initialization vector is always 16 */
uint8_t ciphertext[32];
size_t ciphertextLen = sizeof(ciphertext);
cx_aes_iv_no_throw(&aes_key, CX_ENCRYPT | CX_PAD_ISO9797M1 | CX_CHAIN_CBC, iv, CX_AES_BLOCK_SIZE, plaintext, sizeof(plaintext), ciphertext, &ciphertextLen);
```

### Decryption

The decryption function takes as input a secret key, an initialization vector, and the ciphertext and outputs the plaintext.
If the length of the plaintext that has been encrypted is not a multiple of the block size, the padding method used must be specified when calling the decryption function.

The decryption is performed by `cx_aes_iv_no_throw` or `cx_des_iv_no_throw` depending on the algorithm and with the mode value `CX_DECRYPT`.

Assuming that the plaintext has been encrypted as in the previous example, the decryption of the obtained ciphertext using AES-CBC is as follows:

```c
uint8_t plaintext[21];
uint8_t iv[16]; /* The length of the initialization vector is always 16 */
size_t plaintextLen = sizeof(plaintext);
cx_aes_iv_no_throw(&aes_key, CX_DECRYPT | CX_PAD_ISO9797M1 | CX_CHAIN_CBC, iv, CX_AES_BLOCK_SIZE, ciphertext, ciphertextLen, plaintext, &plaintextLen);
```

## See also

- [Ledger OS syscalls reference](../../references/syscalls) — full list of supported syscalls
- [Device app architecture](../../explanation/architecture) — how apps interact with the Ledger OS
- [Cryptography requirements](../../explanation/cryptography-requirements) — constraints and recommendations for key handling in device apps

---

<!-- https://developers.ledger.com/docs/device-app/references/cryptography-api -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Cryptography library and syscalls reference

The cryptography library provides a C/C++ API for cryptographic operations in Ledger device applications. This Doxygen-generated reference covers the available cryptographic functions, data structures, error codes, and system calls.

## Overview

This API reference covers:

- **Cryptographic algorithms**: Implementations of industry-standard cryptographic primitives
- **Data structures**: Cryptographic data types and structures
- **Function APIs**: Function signatures, parameters, and return values
- **Error handling**: Error codes and exception handling
- **System integration**: Low-level system calls and hardware integration

## Included APIs

The API reference covers the following areas:

### Hash functions

- **BLAKE2b**: Cryptographic hash function with configurable output size
- **RIPEMD160**: 160-bit cryptographic hash function
- **SHA family**: SHA224, SHA256, SHA384, and SHA512 implementations
- **SHA-3**: SHA3-256, SHA3-384, SHA3-512, Keccak, SHAKE128, SHAKE256
- **Groestl**: Hash function with various output sizes

### Symmetric encryption

- **AES (Advanced Encryption Standard)**: AES implementation with hardware acceleration support
- **DES (Data Encryption Standard)**: Legacy DES encryption for compatibility

### Asymmetric cryptography

- **RSA**: RSA encryption, decryption, and digital signatures with key sizes from 1024 to 4096 bits
- **Elliptic curve cryptography (ECC)**:
  - ECDH (Elliptic Curve Diffie-Hellman) key exchange
  - ECDSA (Elliptic Curve Digital Signature Algorithm)
  - EdDSA (Edwards-curve Digital Signature Algorithm)
  - ECSchnorr signatures
- **Curve support**: Weierstrass, Montgomery, and Twisted Edwards curves

### Key management

- **AES keys**: 128-, 192-, and 256-bit key handling
- **RSA keys**: Private and public key structures for various bit lengths
- **ECC keys**: Elliptic curve key pairs with different curve parameters
- **Key generation**: Secure key generation and validation functions

### Mathematical operations

- **Big number arithmetic**: Big number library (`cx_bn_*` functions)
  - Addition, multiplication, modular operations
  - Prime number testing and generation
  - Bit manipulation and comparison operations
- **Modular arithmetic**: Specialized modular math functions (`cx_math_*`)

### Random number generation

- **True random number generator (TRNG)**: Hardware-based entropy source
- **Deterministic random bit generator**: RFC 6979-compliant random number generation
- **Cryptographically secure RNG**: Random number generation functions

### Error handling

- **Error codes**: Error definitions in `cx_errors.h`
- **Exception handling**: Error propagation and handling mechanisms

### Utility functions

- **CRC operations**: Hardware-accelerated CRC16 and CRC32 implementations
- **Memory management**: Secure memory handling and cleanup functions
- **Chaining modes**: Support for CBC, CFB, CTR, ECB, and OFB block cipher modes

## Data structures

The API includes more than 30 specialized data structures for cryptographic operations:

- Hash state structures (`cx_sha256_s`, `cx_sha3_s`, `blake2b_state__`, etc.)
- Key structures for all supported algorithms (`cx_aes_key_s`, `cx_rsa_*_key_s`, `cx_ecfp_*_key_s`)
- Curve domain parameters (`cx_curve_domain_s`, `cx_curve_weierstrass_s`, etc.)
- Big number contexts (`cx_bn_mont_ctx_t`)
- HMAC contexts for various hash functions

## Download the full documentation

The complete cryptography library and syscalls reference is available as an 805KB PDF. This Doxygen-generated reference includes API documentation for all functions, complete data structure definitions, and implementation details.

**📄 [Download complete Cryptography API reference (PDF, 805KB)](https://drive.google.com/file/d/1USFouBpQvinqgQhIpicNsrxMbCcwL38g/view?usp=sharing)**

_Generated: December 18, 2023 | Format: Doxygen PDF Documentation_

## Implementation examples

The [Cryptography API Examples](./cryptography-api-examples) page shows how to implement cryptographic operations with the API. It provides C code for digital signature algorithms, including ECDSA with Secp256k1, Ed25519, and Ed448 curves, as well as Schnorr signatures. It also covers AES and DES encryption and decryption with chaining modes such as CBC. The examples include key generation, message signing and verification, encryption and decryption, initialization, error handling, and explanations of the relevant cryptographic concepts.

---

<!-- https://developers.ledger.com/docs/device-app/references/framework -->

---
title: Device app development framework
category: reference
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Device app development framework

Ledger maintains a set of repositories that, together, give you everything you need to **build**, **test**, **load**, and **submit** a Ledger device application. This page lists each tool, what it does, and when to reach for it.

## At a glance

| Tool                                                                                                                 | What it gives you                                                            | Languages    | OS support              |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------ | ----------------------- |
| [`ledger-app-ai-instructions`](https://github.com/LedgerHQ/ledger-app-ai-instructions)                               | Reusable `CLAUDE.md` / Copilot instruction files for AI-assisted development | —            | GitHub                  |
| [`app-boilerplate-rust`](https://github.com/LedgerHQ/app-boilerplate-rust)                                           | Forkable Rust application skeleton (mandatory for new apps)                  | Rust         | Linux / macOS / Windows |
| [`app-boilerplate`](https://github.com/LedgerHQ/app-boilerplate)                                                     | Forkable C application skeleton (existing C projects)                        | C            | Linux / macOS / Windows |
| [`app-plugin-boilerplate`](https://github.com/LedgerHQ/app-plugin-boilerplate)                                       | Forkable Ethereum-app plugin skeleton                                        | C            | Linux / macOS / Windows |
| [`ledger-dev-tools` VSCode extension](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools) | One-click build / test / load from the IDE                                   | UI           | Linux / macOS / Windows |
| [`speculos`](https://github.com/LedgerHQ/speculos)                                                                   | Emulator for Nano S+, Nano X, Stax, Flex, Nano Gen5                          | Python (CLI) | Linux / macOS / WSL     |
| [`ragger`](https://github.com/LedgerHQ/ragger)                                                                       | `pytest`-based functional test framework                                     | Python       | Linux / macOS / Windows |
| [`ledger-app-workflows`](https://github.com/LedgerHQ/ledger-app-workflows)                                           | Reusable GitHub Actions workflows                                            | YAML         | GitHub Actions          |
| [`ledger-app-builder`](https://github.com/LedgerHQ/ledger-app-builder)                                               | Docker images with the toolchain pre-installed                               | Docker       | Linux / macOS / Windows |

## When to pick which

### Starting a new app

Fork **one of the boilerplates**:

- `app-boilerplate-rust`: **mandatory for new apps.** Comes with Rust unit tests, Ragger functional tests, CI workflows, and a `Cargo.toml` already wired to the SDK.
- `app-boilerplate`: C application skeleton for existing C projects. Comes with C unit tests (cmocka), Ragger functional tests, CI workflows, and a `Makefile` already wired to the SDK.
- `app-plugin-boilerplate`: only for **Ethereum-app plugins** (Clear Signing for an EVM contract). Different lifecycle: a plugin runs alongside the Ethereum app, not as a standalone app.

### Building locally

Pick one of:

- **VSCode + [`ledger-dev-tools`](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools)**: the recommended path on macOS and Windows. The extension launches the `ledger-app-dev-tools` Docker image behind the scenes and exposes Build / Run with Speculos / Run tests / Load on device as IDE tasks.
- **Docker images from [`ledger-app-builder`](https://github.com/LedgerHQ/ledger-app-builder)**, in three flavours:
  - `ledger-app-builder-lite` (C only),
  - `ledger-app-builder` (default, C + Rust),
  - `ledger-app-dev-tools` (full image with Speculos and Ragger; what the VSCode extension uses).
- **Bare host with the SDK directly**: works for advanced users on Linux who already have ARM toolchains; see the [SDK README](https://github.com/LedgerHQ/ledger-secure-sdk).

For each device target you set the matching `BOLOS_SDK` variable: `$NANOX_SDK`, `$NANOSP_SDK`, `$STAX_SDK`, `$FLEX_SDK`, or `$APEX_SDK`.

### Running and emulating

[`Speculos`](https://github.com/LedgerHQ/speculos) emulates Nano S+, Nano X, Stax,and Flex on a desktop computer; install with `pip install speculos` and run, for example:

```bash
speculos --model nanosp build/nanos2/bin/app.elf
```

Caveats from the Speculos README to keep in mind:

- It implements only the subset of syscalls common apps use (no app-install, firmware-update, or OS-info syscalls).
- Memory-alignment behaviour differs from a real Nano S+ device.
- The internal watchdog enforced on Nano X / Flex / Nano Gen5 / Stax is not emulated.

### Writing functional tests

[`Ragger`](https://github.com/LedgerHQ/ragger) gives a single `pytest` interface that runs the same tests against three backends (Speculos, `LedgerComm`, and `LedgerWallet`), so you can switch between emulator and physical device with a flag:

```bash
pytest <tests/path>                                   # Speculos by default
pytest --backend ledgerwallet <tests/path>            # against a connected device
```

Install with `pip install 'ragger[all_backends]'`. The `app-boilerplate` repo ships an example suite you can copy.

### Continuous integration

[`ledger-app-workflows`](https://github.com/LedgerHQ/ledger-app-workflows) provides reusable GitHub Actions workflows:

- `guidelines_enforcer.yml`: checks your repo against Ledger's published app guidelines. Passing this workflow is a **mandatory** step to be listed on the Ledger app store.
- Build-and-test workflows that build the app for every supported device and run the Ragger suite on Speculos.

The boilerplates already wire these in.

## Putting it together

A typical project layout uses these tools as follows:

1. Fork the right boilerplate: `app-boilerplate-rust` for new apps, `app-boilerplate` for existing C apps, or `app-plugin-boilerplate` for Ethereum plugins.
2. Develop locally in VSCode with `ledger-dev-tools`, or directly with `ledger-app-builder` Docker images.
3. Run the app interactively in Speculos and write Ragger tests as features land.
4. Push to GitHub; the workflows from `ledger-app-workflows` build for every device, run the Ragger suite on Speculos, and run the guidelines enforcer.
5. When green, follow the [submission process](../submission-process/process) to ship the app through the Ledger Manager.

## See also

- [Get started](../getting-started): set up a development environment and build your first app.
- [Submission process](../submission-process/process): how an app reaches end users.
- [Architecture](../explanation/architecture-diagram): where the device app fits in the wider system.
- [Ledger Secure SDK](https://github.com/LedgerHQ/ledger-secure-sdk): the underlying SDK referenced by `BOLOS_SDK`.

---

<!-- https://developers.ledger.com/docs/device-app/references/tools -->

---
agent_config:
  entry_point:
    label: Agent Instructions
    url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md
    role: orchestrator
  instruction_files:
    - label: Embedded Constraints
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md
      scope: "*.c, *.h, *.rs"
    - label: C Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md
      scope: "*.c, *.h"
    - label: Rust Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md
      scope: "*.rs"
    - label: Test Rules
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md
      scope: "*.py"
    - label: Review Checklist
      url: https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md
      scope: "*"
---

## Agent Instructions

**Entry point:** [Agent Instructions](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/CLAUDE.md) (orchestrator)

### Instruction Files

- [Embedded Constraints](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/EMBEDDED.instructions.md) — scope: `*.c, *.h, *.rs`
- [C Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/C.instructions.md) — scope: `*.c, *.h`
- [Rust Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/RUST.instructions.md) — scope: `*.rs`
- [Test Rules](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/TEST.instructions.md) — scope: `*.py`
- [Review Checklist](https://raw.githubusercontent.com/LedgerHQ/ledger-app-ai-instructions/master/instructions/REVIEW.instructions.md) — scope: `*`

# Embedded Tools

## Development environment

### Docker images

As the device applications needs to run on a non-standard system, and thus need specific build chain and
configuration, we provide `Docker` images so that building an app and loading it on a device has a minimal
impact on one's computer - given `Docker` is installed.

Several images are available depending on the developer's needs.

> **Note:** These images are maintained and updated on [this repository](https://github.com/LedgerHQ/ledger-app-builder/).

### VScode extension

The `VSCode` extension uses the most complete Docker image we provide and wires it into the `VScode` IDE for a
frictionless development experience.

It includes the following capabilities:

- Build the device application for all existing devices
- Test the app with `Speculos`
- Load an app on your device
- Execute functional tests
- Open a terminal in your Docker container
- Update the development environment
- Execute the [Guideline Enforcer](../integration/requirements/development#workflows)

> **Note:** The extension can be found [here](https://marketplace.visualstudio.com/items?itemName=LedgerHQ.ledger-dev-tools),
> while the sources are updated [here](https://github.com/LedgerHQ/ledger-vscode-extension).

### GitHub Workflows

Ledger provides several workflows to ease the integration of applications into the GitHub CI.

[Some of them are mandatory for an application to be deployed](../integration/requirements/development#workflows), but
the others can still be useful.

> **Note:** Documentation and sources can be found [here](https://github.com/ledgerhq/ledger-app-workflows).\
> Usage examples can be found in the CI of lots of applications, for instance the
> [Boilerplate workflows](https://github.com/LedgerHQ/app-boilerplate/tree/master/.github/workflows), the
> [Ethereum workflows](https://github.com/LedgerHQ/app-ethereum/tree/develop/.github/workflows) or the
> [Exchange workflows](https://github.com/LedgerHQ/app-exchange/tree/develop/.github/workflows).

### AI instructions

`ledger-app-ai-instructions` is a collection of reusable instruction files for Ledger embedded application repositories. AI tools that support `CLAUDE.md` (Claude) or `.github/copilot-instructions.md` (GitHub Copilot, Cursor, and compatible agents) load these files automatically and apply Ledger's embedded development rules when reviewing or generating code.

> **Note:** Sources and setup instructions are in the [ledger-app-ai-instructions repository](https://github.com/LedgerHQ/ledger-app-ai-instructions).

## `Speculos`

`Speculos` is an emulator allowing to run and test an device application without loading it on a physical Ledger
device. While it is not capable of emulating some constraints of the physical devices, it is still a very realistic
and handy tool, and the pillar of any credible testing strategy.

> **Note:** If you need more information about `Speculos`, read [its documentation](https://speculos.ledger.com/). \
> Sources can be found [here](https://github.com/ledgerhq/speculos).

## `Ragger`

`Ragger` is Python library offering abstractions over an Ledger embedded device (Nano and Stax), either real or emulated
(through `Speculos`). It aims at simplifying writing generic communication with an device application and managing
high-level graphical interactions. It is widly used to write functional tests code

> **Note:** You can read the full Ragger documentation [here](https://ledgerhq.github.io/ragger/). \
> Sources can be found [here](https://github.com/ledgerhq/ragger).

## Ledgered

Ledgered is a Python package which goal is to be a collection of small, autonomous utilitaries and libraries.

For now, it only contains a tool (`ledger-manifest`) allowing to check `ledger_app.toml` manifest files (which are a
[requirement](../integration/requirements/development#manifest) for an application to be deployed).

> **Note:** Sources and documentation can be found [in the Ledgered repository](https://github.com/ledgerhq/ledgered).

## Ledgerblue

> **Note:** The sources of this tool can be found [here](https://github.com/LedgerHQ/blue-loader-python).

In Ledger app development, it is necessary to enter your PIN code each time you install an unsigned app. However, Ledger OS supports installing a custom developer certificate. With a custom certificate, you can avoid having to retype your PIN each time you adjust your app. Here are the steps for the Ledger Nano S Plus:

1. Generate a public / private keypair using the following command:
   ```console copy
   foo@bar:~$ python3 -m ledgerblue.genCAPair
   Public key : 0495331cb86e961fc9cb5792a97737e4204b58be99321dcec463cec3057b3304e9875614004e6e540ab0610a1339fae22df6f6f3ec594912b409d69b72f0eaf390
   Private key: 6c1f1df852255e113b23c2e977d6b5c3ea2aaf411f05a5fdab87a3e8f44468ee
   ```

2. Enter in recovery mode on your Ledger device.
   - Nano S Plus: Do this by unplugging it then holding down the left button while plugging it in again. A menu appears and includes the `recovery mode` option. Enter your pin and continue.
   - Stax and Flex: Do this by unplugging it then holding the power button. A menu appears and includes the `recovery mode` option. Enter your pin and continue.

3. Load your public key onto the Ledger Nano S Plus. Paste the public key generated at step 1 after `--public`. You may need to adjust the `--targetId` constant to match your device. Find the right targetId for your device [here](https://gist.github.com/TamtamHero/b7651ffe6f1e485e3886bf4aba673348). Notice that we must include a `--name` parameter containing the name of the custom certificate (any string will do):

   python3 -m ledgerblue.setupCustomCA --targetId 0x31100004 --public yourPublicKey --name dev

   If you receive the error `Invalid status 6985`, review [this link](https://github.com/LedgerHQ/blue-loader-python/issues/42) and go back to step 2. The above command is the simplest that can work however some developers may wish to use the optional `--rootPrivateKey` option to specify a secure channel encryption key (which is the private key generated at step 1) or use the `--name` option for convenient labeling according to local convention.

4. Once you have loaded your custom certificate, load an app you compiled onto your Ledger device to see if you are able to bypass the PIN. Before you try it, set the `SCP_PRIVKEY` environment variable to contain the private key generated at step 1 in your shell or `.bashrc`:

   export SCP\_PRIVKEY=yourPrivateKey

   and rebuild/load your app.

> **Warning:** A Ledger device with a custom CA installed can not pass the Ledger Genuine Check, which is required to install applications from . To make it pass the check, uninstall your custom CA and all the applications installed through it.

**Uninstalling a custom CA is very quick:**

1. Enter in recovery mode on your Ledger device.
   - Nano S Plus: Do this by unplugging it then holding down the left button while plugging it in again. A menu appears and includes the `recovery mode` option. Enter your pin and continue.
   - Stax and Flex: Do this by unplugging it then holding the power button. A menu appears and includes the `recovery mode` option. Enter your pin and continue.

2. Type this command in your terminal:
   ```bash copy
   foo@bar:~$ python3 -m ledgerblue.resetCustomCA --targetId 0x31100004
   ```
   Find the right targetId for your device [here](https://gist.github.com/TamtamHero/b7651ffe6f1e485e3886bf4aba673348).

## Ledgerctl

> **Note:** The sources of this too can be found [here](https://github.com/LedgerHQ/ledgerctl).

### Installation

#### Install Ledgerctl

Run:

```bash copy
pip3 install --upgrade protobuf setuptools ecdsa
pip3 install ledgerwallet
```

And:

```bash copy
git clone https://github.com/LedgerHQ/ledgerctl.git
pip3 install --upgrade protobuf setuptools ecdsa
cd ledgerctl
pip install -e .
```

#### (optional) Install a custom certificate authority

Optionally, install a custom certificate authority (this will help to establish a custom secure channel between the computer and the device, and identifies ledgerctl as a "trusted manager" on the device):

- a. To install a custom CA, boot the device in "Recovery" mode by pressing the right button at boot time.
- b. Then run `ledgerctl install-ca <NAME>` where `<NAME>` is the name that will be displayed on the device to identify the CA. It can be any label, like "ledgerctl", "Dev", or "CA".

The Ledger device will display to you a public key. Allow the “unsafe manager” on the device by pressing at the time the right and left buttons.

### Usage

You’re now ready to use ledgerctl to manage your Nano.

To display the list of the application installed on your device:

```bash copy
ledgerctl list
```

To display the available space on the device:

```bash copy
ledgerctl meminfo
```

To delete an app (for example “Bitcoin Legacy”):

```bash copy
ledgerctl delete "Bitcoin Legacy"
```

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/companion-wallet -->

---
title: Companion wallet
category: reference
---

# Companion wallet

A companion wallet is a desktop or web application, built and maintained by you, that is fully compatible with your device app and lets your users manage assets on your chain. It acts as the host-side counterpart to the device app: the device app handles the secure signing on the Ledger signer, while the companion wallet provides the user interface for constructing and broadcasting transactions.

> **Note:** A companion wallet is required as part of your device app submission. Ledger reviewers verify that the wallet meets the requirements below before your app is published.

## Requirements

### Address verification on device

The companion wallet must give users a way to verify a receive address directly on their Ledger signer. This is a core security feature: it lets users confirm that the address shown in the software matches the address derived on the secure hardware, protecting against address-substitution attacks.

The verification flow typically works as follows:

1. The user navigates to the "Receive" screen in the companion wallet.
2. The wallet requests the address from the device app via APDU.
3. The device app displays the address on the signer's screen and waits for the user to confirm.
4. The companion wallet shows the same address and marks it as device-verified.

### Ledger affiliate link

The companion wallet must display an affiliate link to Ledger next to the "Connect with Ledger" option. This link directs new users to purchase a Ledger device if they do not already own one.

### Desktop platform support

The companion wallet must run on **Windows**, **macOS**, and **Linux**. Web applications accessed through a modern browser are acceptable, provided they meet the other requirements.

## Related

- [Security requirements](../../integration/requirements/security) — derivation-path constraints and APDU security rules your device app must satisfy
- [Submission process](../process) — the full submission checklist and review steps
- [UI flow video](./ui-flow-video) — the screen recording required alongside the companion wallet deliverable

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/documentation -->

---
title: Documentation
category: reference
---

# Documentation

The requirement is to document your app's **APDUs** and **status words** on the app's repository (A)\
and to submit the **user's documentation** in a Google Doc format for review or a **URL** to the already published documentation (B).\
If it is already published, ensure it follows the instructions below.

## A. APDUs and Status words

Your device app repository must have a `docs` folder in which you will document the APDUs and corresponding errors, taking example on the [Bitcoin App](https://github.com/LedgerHQ/app-bitcoin/blob/develop/doc/bitcoin.md).

For the ranges available, follow the stated ranges in the [SDK](https://github.com/LedgerHQ/ledger-secure-sdk/blob/master/include/errors.h).

Name this file `apdu.md` and put it under the `docs` folder of your app.

## B. Users documentation

### Introduction

> **Warning:** Proper documentation is crucial for the approval and release of your app. Ensure your documentation is complete and follows Ledger's guidelines.

It is required for third party teams to provide and host a complete tutorial for users before the app is released on the Ledger Manager. Here are the rules for writing this documentation and it should be followed very carefully.

### Ledger Documentation

> **Note:** Follow the recommended writing style for clear and concise documentation. Short sentences, actionable instructions, and proper terminology are key to effective communication.

Your documentation must follow the requirements below  so that Ledger uses a solid common documentaion basis.
[Ledger Customer Support](https://support.ledgerwallet.com/hc/en-us) will write and publish an article ([example](https://support.ledgerwallet.com/hc/en-us/articles/360007583514-Ontology-ONT-)) that describes:

- Short introduction: what the app does, what crypto assets it can manage, using what service. Who has developed it.
- Requirements: What’s needed before starting.
- Installation instructions: How to install the app using .
- Next steps: link to third party documentation and where to get support.

### Content

The article ([example](https://blog.cyberrepublic.org/2020/06/15/how-to-use-your-ledger-device-with-the-elastos-light-wallet/)) must describe:

- Short introduction: what the app and service do, what crypto assets they can manage, why to use a Ledger device, where to get support.
- Requirements: What’s needed before starting.
- Installation instructions: How to install the app using .
- Setup instructions:
  - For a web app: how to connect the Ledger device.
  - For installable app: how to download and install it, how to connect to it.
- Where to view account balance.
- How to receive crypto assets
  - Document all the steps.
  - Explicitly instruct to verify receive addresses on the device.
- How to send crypto assets
  - Document all the steps and form fields to fill.
  - Explicitly instruct to verify transaction details on the device display, before confirming and signing it.
- Support: where to get help if needed (mail address, Slack/Reddit/Telegram communities).
- Since you will host the final version of the document you are required to prepare the URL address and include it clearly in the Google Doc.

### Style

- Write short and concise sentences.
- Write clear section titles.
- Give actionable instructions: Click this, enter that. Verify this, confirm that.
- Use text formatting for UI text, example: Your device displays BTC app installed.
- Screenshots can support the instructions if the user interface is complicated.
- **Referring to the signer**: Ledger Nano S Plus, Ledger Flex, Ledger Stax, device, , Ledger device.
  Strictly avoid: wallet, , a Ledger.
- **Referring to crypto assets**: name, ticker, crypto asset(s), coin(s), cryptocurrency.
  Please avoid: money.
- Be sure to check [this article](https://blog.cyberrepublic.org/2020/06/15/how-to-use-your-ledger-device-with-the-elastos-light-wallet/) for an example.

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/icons -->

---
title: Icons
category: reference
---

# Icons

The requirement is to provide 2 mandatory icons that should be provided for Ledger to release an app:

- The Manager icon, displayed in the Manager application list in Ledger Wallet
- The Device icon, displayed on the Ledger dashboard (this consists in one Icon for the Nano S Plus and the Nano X, and one for the Ledger Stax)

> **Warning:** Submitting icons that are not compliant will slow down the process of publishing your device App.

## Manager icon

- RGB colors only
- Pictogram color should be white
- Pictrogram stroke should be 4pt

[![Manager icon template (click to access Illustrator file)](/device-app/manager-icon-template.png)](https://drive.google.com/a/ledger.fr/file/d/1OOAZWlnLlBSpScPnF5NGJ4AfczB3D591/view?usp=sharing)
_Manager icon template (click to access Illustrator file)_

## Device icon

> **Note:** You can use [Photopea](https://www.photopea.com/) to create your icons.

### Nano devices

We accept icons in PNG or GIF format.

[![Ledger Nano S Plus and X icon template (click to access Illustrator file)](/device-app/nano-icon-template.png)](https://drive.google.com/a/ledger.fr/file/d/1FVUWDGYPvLuyiwDFgGYiwfwk7YGsxzJ0/view?usp=sharing)
_Ledger Nano S Plus and X icon template (click the image to access Illustrator file)_

### Stax and Flex devices

We accept icons in PNG or GIF format.

The easiest way to  create your Stax and Flex devices icon is to use [the following sript](https://github.com/LedgerHQ/embedded-application-tools).

Alternatively, you can use the following template:

[![Ledger Stax and Flex icon template (click to download the template)](/device-app/stax-flex-icons-template.jpg)](/device-app/stax-flex-icons-template-transparant.png)
_Ledger Stax and Flex icon template (click the image to access downloadable file)_

## Design Warranty

> **Note:** Ensure your app's design is free from encumbrances and does not infringe upon any third-party intellectual property rights. You are responsible for holding Ledger harmless of any claim arising from the use and distribution of your app.

The design of your app must be free from any encumbrances and must not infringe upon any third party intellectual property right, in particular trademark and design rights. You grant Ledger the right to use such design for free with the right to reproduce and exploit the design for the duration of its display on Ledger website.

You represent and warrant that the app you are making available in  is in compliance with all relevant laws and regulations.

You agree to hold Ledger harmless of any claim arising out of the use of the design and or distribution of your app .

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/legal -->

---
title: Warranty and liability
category: reference
---

# Warranty and liability

> **Warning:** Read the terms below before submitting your app. You confirm acceptance in the submission form.

## Disclaimer

The publication of a third party developed application (an “App”) on Ledger Manager (the “Service”) is supported by Ledger on an “as-is” and “as-available” basis. Ledger does not warrant that the Service will be accurate, error-free or uninterrupted. Ledger disclaims all warranties, express or implied, including warranties of accuracy, non-infringement, merchantability and fitness for a particular purpose in respect of the Service. To the extent not prohibited by applicable law, in no event will Ledger be liable for any direct, indirect, incidental, special, consequential or punitive damages, including but not limited to, loss of profits, data, business or goodwill or business interruption.

As part of the onboarding process, Ledger may conduct a technical review of your App to identify bugs or other faults. This technical review does not constitute a vetting or endorsement of the App by Ledger, nor does it create any kind of partnership between you and Ledger or limit your responsibility for your App. Ledger shall not be responsible or liable for any damages caused to any third parties by your App.

The Service, Ledger software, firmware and hardware are subject to change without notice, which may require that you perform an update on your App at your own cost to ensure ongoing compatibility with Ledger software, firmware, hardware products and the Service. Please keep yourself informed of such changes by following the relevant developer channel on Discord.
As an App developer, you assume total responsibility and risks for your use of the Service and any damage that your application may cause to third parties or to Ledger. This responsibility includes, but is not limited to, all the necessary steps to maintain the continuity of the availability and the performance of the App you have developed and submitted to the Service. You shall, at all times and at your own cost, regularly test and update the App you have developed in order for your App to be fully functional with the latest Ledger updates and plugins, as well as, mitigate all risks and incidents that may affect your App, or the use of your App by any third party.

By submitting the App to the Service, you warrant that your App will not cause any fault or malfunction in any software, firmware, hardware or network and information system, nor shall introduce any viruses or vulnerabilities onto the Services. You warrant that the App will operate in accordance with Ledger and user expectations and that the maintenance of your App will be of satisfactory quality and conform to the requirements to function with the Service, Ledger software, firmware and hardware.
The App you submit must be distributed under an open source license. You warrant that your submission of an App is not in breach of any third party’s intellectual property or other rights and you agree to indemnify and hold Ledger harmless in case of a claim brought by a third party against Ledger regarding the application you have submitted. You warrant that you have obtained and will maintain all permissions, licences and consents necessary to provide the App. You are also responsible for ensuring that your App is not in breach of any laws and regulations and that its distribution by Ledger will not expose Ledger to a breach of export controls regulations.

As part of the submission of your App to the Service, you will be required to provide personal information such as your name, country of residence, etc. This information will be processed in accordance with Ledger’s privacy policy and may be communicated to users in , in particular where and when the disclosure of this information to the users is a legal requirement.
Ledger reserves the right to reject the publication of an App or to remove it from  at its sole discretion and without providing any justification.

By publishing an App, you are giving Ledger the right to communicate about the said App. Ledger will use its discretion as to whether or not to communicate on the release of a new App and the way it communicates.
Nothing will impair Ledger’s right to develop, promote or distribute applications that perform the same or similar functions or achieve the same result as the App you have submitted for publication.

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/marketing -->

---
title: Marketing
category: reference
---

# Marketing

The requirement is to submit a Google Doc containing a **marketing plan** that includes roadmap, dates, and actions. See details below.

## Marketing actions

### Twitter announcement (mandatory)

#### On the Blockchain's project account

A Twitter announcement is the minimal communication requirement.

It must include the following:

- A message about the secure storage of assets
- An link to . You can use an affiliate link or a regular link. [Our affiliate program](https://www.ledgerwallet.com/affiliates) allows you to earn 10% of each hardware sale in Bitcoin or Fiat.

#### On Ledger account

- @Ledger\_Support will interact with the project's tweet if the Coin is below the top 100 by market cap.
- @Ledger will interact with the project's tweet if the Coin is in the top 100 by market cap or there is a co-branded partnership with the project

### Blog post / Press Release (optional)

If you choose to publish a blog post (or a press release) and the Blockchain is in top 50 CMC, the blog post can include a quote from Ledger's CEO, CTO, one of our Founders, or another c-level executive regarding the collaboration and the impact it will have on your project.

### Discord AMA (optional)

We can co-host a Discord AMA surrounding the release of the app, either on the project's server or on Ledger's. You will be in touch with us to set up the details about the topic, questions, speakers, etc.

### Co-branded device give-aways (optional)

Finally, Ledger offers a co-branded partnership that will help you customize your marketing and reward your community. All details from standard to dropshipping options are given on [our website](https://www.ledger.com/co-branded-partnership).

> **Warning:** Co-branded partnerships or affiliate links do not change the Ledger marketing plan timeline.

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/security-audit -->

---
title: Security Audit
category: reference
---

# Security audit

## Introduction

Before Device Apps and Plugins can be listed in the My Ledger section of , they must complete our integration process. This process includes a security audit by one of our [trusted partners](../../getting-started#security-audit).

If your project fulfills the [conditions](#conditions), the external audit follows these steps:

1. Contact the auditors and sign a contract with them. [Read more](../../getting-started#security-audit).
2. The auditors review your app based on Ledger specifications. [Read more](#security-audit-specifications).
3. Ledger reviews the security audit report.
4. Ledger publishes your app.

## Conditions

Before starting an external security audit, ensure that your project fulfills these conditions:

- Your Device App works with all our signers (Ledger Nano S Plus, X, Stax, and Flex).
- The Ledger team has functionally validated your Device App.

> **Warning:** 

## Security audit specifications

Ledger provides a detailed specification of the checks required for a security audit that follows Ledger's standards.

The word **must** indicates a requirement.
The word **should** indicates a recommendation. Auditors can deviate from a recommendation when they have a valid justification.

Use the following specification as a checklist.

### AI-assisted review

Large language models (LLMs) can identify vulnerabilities in embedded applications, and auditors are expected to use them.

- The audit **must** include an AI-based review performed with an advanced LLM (such as Claude or GPT).
- The AI-based review **must not** replace the human review. It complements the human review. The auditor remains responsible for confirming findings, eliminating false positives, and signing off on the report.
- The AI-based review **should** follow a structured methodology. Ledger provides a security review skill that can be used to drive the LLM: [SECURITY.REVIEW.md](https://github.com/LedgerHQ/ledger-app-ai-instructions/blob/master/skills/SECURITY.REVIEW.md).
- The context provided to the model **must** include the blockchain protocol that the application implements (see [Clear Signing](#clear-signing)). This context helps surface deeper, protocol-aware vulnerabilities.

### Application privileges

The application must request only the privileges it strictly needs. The audit verifies that flags, derivation paths, and curves follow the principle of least privilege.

- The application flags must abide by the principle of least privilege.
- When required, privileges must be justified.
- The application derivation paths must be restricted to coin-specific BIP32 prefixes.
- The application derivation paths must be declared in the Ledger app database.
- Curve usage must be restricted.

**References:**

- [BIP32 prefix restrictions](../../references/app-permissions#restrict-apps-to-coin-specific-bip32-prefix)
- [Application parameters](../../integration/requirements/security#application-parameters-minimal-and-declared)

### Clear Signing

Auditors must assess clear signing in the context of the underlying blockchain protocol, at least from a security standpoint. This assessment is not a review of the protocol itself. However, the application must follow the protocol correctly and must not allow abuse that could harm the user. Even seemingly functional aspects of transaction signing can have a security impact and should therefore be in scope.

- All signing actions must ask for user approval.
- The user must be able to see all important information (amount, destination address, validator, token, and so on).
- The application must follow its blockchain protocol correctly and must not allow abuse that could harm the user. For example, it must properly handle and present dangerous flows or transaction types.
- The review is not limited to the application code. The auditor must understand the application's blockchain protocol well enough to uncover deeper vulnerabilities. Examples include dangerous transaction types, protocol edge cases, or flows that the application does not represent accurately to the user.
- If blind signing is implemented:
  - It must be disabled by default.
  - It must not apply to basic transactions such as coin transfers, which must be clear signed.
- A security review of the app workflow must use either a live signer or Speculos and the functional test snapshots to ensure:
  - Critical and important information is clear signed in a user-friendly format.
  - The user cannot be confused or tricked by the application workflow and the displayed information.
  - Every possible flow is functionally tested, with the associated snapshots present.

**References:**

- [Signing settings](../../integration/requirements/security#signing-settings)

### Compilation

- Makefiles from the boilerplate app and secure-sdk must be used to compile the project. This requirement ensures that security flags are applied.
- New apps must fork the boilerplate template. Updated apps must upgrade to the latest standard Makefile in the boilerplate app.
- The compilation log review must ensure the following, which can be reviewed in the CI results:
  - No compilation errors are returned.
  - No compilation warnings are returned.
  - No compilation warnings are silenced without a clear reason through compilation flags or pragma directives.
  - No deprecated functions are used.

**References:**

- [Development requirements](../../integration/requirements/development)

### Continuous integration

- Guidelines enforcer and build workflows must be integrated into the Device App.
- All pipelines must succeed for all supported devices.

**References:**

- [Development requirements](../../integration/requirements/development)

### Tests

Test coverage provides confidence during the audit. The application should provide unit, functional, and, where relevant, fuzzing tests that cover both nominal and error cases.

- Unit tests should be implemented for functions that do not require Ledger OS syscalls mocking.
- All unit tests must succeed.
- Functional tests must cover at least the nominal cases, which are the features provided by the applications, and common errors, such as Clear Signing cancellation.
- All functional tests must succeed for all devices.
- Fuzzing targets should be implemented at least for parsers and critical functions that are easy to fuzz. These targets facilitate the audit.
- Ethereum plugin handlers must be fuzzed. A generic target is available in the boilerplate.
- Fuzzing should be done using libfuzzer to integrate with ClusterFuzzLite as shown in the boilerplate apps and plugins.

**References:**

- [Development requirements](../../integration/requirements/development)
- [Be wary of unstrusted input](../../explanation/security-specificities#be-wary-of-untrusted-input)
- [Good practices for transaction handling](../../explanation/architecture-good-practices#good-practices-for-transaction-handling)

### Static analysis

Static analysis tools must run without issues, and their results are reviewed through CI. For C apps, external libraries are part of the application, so the APIs used from those libraries are also in scope.

- Dependencies must be used only when strictly necessary. The selected versions must be maintained and free of impactful vulnerabilities.
- For C apps, `scan-build` must succeed without reporting any defects. This result can be reviewed through CI.
- For C apps, `CodeQL` must succeed without returning any vulnerabilities with the "security and quality" queries.
- For C apps, external libraries are part of the app, so the APIs used from those libraries must also be reviewed.
- For Rust apps, `clippy` must succeed without reporting any issues. This result can be reviewed through CI.
- For Rust apps, dependencies must be checked using `cargo-audit`.
- Other tools may be used as part of the static analysis process.

**References:**

- [Security requirements](../../integration/requirements/security)

### Vulnerabilities and weaknesses

The review must look for technical vulnerabilities, logic errors, and weaknesses that could indirectly affect security. The following lists are not exhaustive.

- The application or its dependencies must not contain any medium or high severity vulnerabilities.
- The application should not contain any low vulnerabilities.
- The review must check for security vulnerabilities, including:
  - read/write out of bounds
  - integer overflow/underflow
  - format string vulnerabilities
  - memory leaks
  - use-after-free or double-free
  - incorrect type conversions
  - usage of unsafe functions (eval, strcpy, strlen, gets, sprintf, …)
  - returning uninitialized memory that could expose sensitive data
  - …
- In particular, input validation must be comprehensive and thoroughly tested. Fuzzing is recommended:
  - All parsing and other relevant functions must validate input lengths before processing.
  - Parser functions handle malformed data gracefully without crashes or infinite loops.
  - All type mismatches are prevented, such as using a uint8 loop counter with a uint32 bound.
  - All array accesses are bounds-checked appropriately.
  - …
- The review must focus on logic errors, including:
  - unsanitized or unconventional user input
  - cryptographic oracle
  - state management handling (the application state is properly initialized and cleared or erased when finalized or when an error occurs; multi-step operations that change state enforce the correct order)
  - security restrictions bypass (autolock, pin entry)
  - secure error handling (all return values are checked, errors do not result in invalid or partial states, and cryptographic operation failures are handled securely)
  - …
- The review must report any other weaknesses that could indirectly affect security, including weaknesses related to code quality and readability:
  - magic numbers such as:
    - Using raw numbers where an enum or a macro would be preferred to ease code reading and maintenance.
    - Using raw numbers instead of computing them with the sizeof operator or a dedicated macro.
  - lack of documentation:
    - APDUs that are not documented.
    - Functions that are not documented (description, parameters, return value, error cases, specific behavior, and so on).
  - complex functions (huge cyclomatic complexity, length, …)
  - Rust application-specific checks:
    - All unsafe code blocks are justified and documented.
    - There are no known panics in production code paths.
    - Error handling is properly performed for all returned `Result` types.
    - Arithmetic overflows and underflows are handled securely by using `saturing_x`, `checked_x`, or a manual check.
    - Utility code for testing is guarded by the `#[cfg(test)]` attribute to ensure that potentially insecure test code is not included in the production application.
  - …

### Cryptography

We do not expect an advanced cryptographic evaluation, such as a formal analysis of a cryptographic scheme. However, some applications implement specific or custom cryptographic schemes that are not directly related to the blockchain protocol. The auditor must ensure that these applications use cryptographic primitives correctly.

- Secrets must be erased from memory as soon as possible after use.
- Secrets derived from the seed must not be stored, exported, or shown.
- The structural integrity of messages must be verified before signing. Never allow the signing of attacker-controlled messages.
- User-supplied messages must use a prefix if they are to be signed.
- Cryptographic primitives must not be re-implemented if they already exist in Ledger OS or the SDK.
- Cryptographic functions that can throw exceptions are deprecated and must not be used (can be reviewed through the CI results).
- Cryptographic helpers and ledger assertions provided by the SDK should be used to handle cryptographic operations.
- The client must not be able to freely manipulate keypairs.
- An authenticated encryption scheme must be used for data being cached on the client.
- If custom cryptographic code is implemented, the implementation should make a best-effort attempt to protect against side-channel leaks and fault injection.
- The review must check for common cryptographic misuse, including:
  - nonce reuse
  - hardcoded secrets
  - lack of randomness or predictable randomness
  - use of weak or deprecated algorithms
  - wrong or insecure mode of operation
  - weak key management
  - homemade or reimplemented cryptography instead of SDK primitives
  - reuse of a single key for different purposes
  - …

**References:**

- [General cryptography concepts](../../explanation/cryptography)
- [Cryptography reference](../../references/cryptography-api)
- [Cryptography examples](../../references/cryptography-api-examples)

### Deliverables

- The report must contain an executive summary that clearly states whether the auditor recommends deploying the app. If not, the summary must state what needs to be done.
- The report must contain the findings, reproduction steps, impacts, and associated recommendations. It should also contain tests that produced no findings.
- The report must include the following checklist in an appendix to show what the audit checked and validated.

### Checklist

- [ ] An AI-based review using an advanced LLM (such as Claude or GPT) has been performed and its findings reviewed.
- [ ] The review accounts for the blockchain protocol: the app follows it correctly and cannot be abused in a way that harms the user (clear signing, dangerous flows, or transaction types).
- [ ] Cryptographic primitives are correctly used (no nonce reuse, no hardcoded secrets, sufficient randomness, strong algorithms/modes, sound key management, no homemade crypto, no key reused across usages).
- [ ] Application flags, derivation paths, and curves are correctly set.
- [ ] Clear Signing correctly displays information and asks for user confirmation.
- [ ] Blind signing is disabled by default or does not exist. If it exists, it applies to complex transactions but not to coin transfers or swaps.
- [ ] The app workflow is considered secure, and snapshots cover the nominal and error cases of app features.
- [ ] The boilerplate Makefiles and SDK are used to compile the app. A new app is based on the C or Rust boilerplate.
- [ ] The app compiles without errors or warnings. No errors or warnings are silenced using compilation flags or pragma directives.
- [ ] Guidelines enforcer and build workflows are integrated and pass.
- [ ] Unit, functional, and fuzzing tests pass.
- [ ] For app-plugins, the generic fuzzing target is integrated.
- [ ] scan-build/CodeQL or clippy succeeds without reporting vulnerabilities.
- [ ] Dependencies are necessary, maintained, and secure, with no known impactful vulnerability in the selected version.
- [ ] The app does not contain any medium or high severity vulnerabilities.
- [ ] The review process looked into technical vulnerabilities as well as logical ones and weaknesses.
- [ ] Secrets are correctly erased from memory, not exported or shown to the user.
- [ ] User-supplied messages use a prefix and are validated before signing.
- [ ] No cryptographic primitives are re-implemented if they already exist in Ledger OS or the SDK.
- [ ] The client cannot freely manipulate the device keypairs.
- [ ] An authenticated encryption scheme is used for data being cached on the client.

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/support -->

---
title: Support
category: reference
---

# Support

This reference describes the support deliverables required from third-party teams before a device app is published on . Ledger does not provide support for third-party applications.

## Requirements

### Hosted user tutorial

**Purpose:** A publicly accessible tutorial that guides users through the app before release.

**Constraints:**

- Must be hosted at a stable, public URL.
- Must be live before the app is submitted for release on "My Ledger" in Ledger Wallet.
- A Google Doc or similar draft document is not accepted; the tutorial must be on a public-facing page.

For expected content and format, see [Documentation requirements](./documentation).

### Support contact information

**Purpose:** Contact details submitted to the Ledger support team so that users can be redirected to your team.

At least one of the following fields must be provided:

| Field                 | Description                             |
| --------------------- | --------------------------------------- |
| URL                   | A dedicated support page or FAQ         |
| Email address         | A monitored support inbox               |
| Phone number          | A support phone line                    |
| Community channel URL | A link to a moderated community channel |

**Constraints:**

- All URLs must be publicly reachable.
- Submit these details in the [submission form](../submission-form).

### Community channel moderation

**Purpose:** Requirement that applies when community channels (Discord, Telegram, Reddit, or similar) are used as a support channel.

**Constraints:**

- Channels must be actively moderated.
- Scam messages and phishing attempts must be removed promptly.

## Further reading

- [Documentation requirements](./documentation) — required content and format for the hosted user tutorial
- [Submission form](../submission-form) — where to submit support contact details
- [Submission process](../process) — complete sequence of deliverables

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/deliverables/ui-flow-video -->

---
title: Demo
category: reference
---# DemoYou are required to submit a video demo of your Device App as described below (For Ledger Nano only).## UI FlowsTo create the flow you will show in the video, we recommend you follow the UI flows shown below.### Send and receive examplesPlease create your flow following the given [Ethereum example](/device-app/eth-flow.pdf).It contains the basic functions App information, Receive and send operations. Include the main operations that your device app contains. Try to apply the same kind of flow design for all of them.![](/device-app/eth-flow.png)### Blind signingIn case you need the users to blind sign transactions, you will need to include the blind signing flows.* This screen should be displayed when blind signing is not enabled and the user wants to sign a transaction requiring blind signing:\
![Blind signing not enabled](/device-app/blind-signing-not-enabled.png)* How to modify the blind signing settings:![](/device-app/blind-signing-settings.png)* When blind signing is enabled:![](/device-app/blind-signing-enabled.png)## VideoYou must **create your own video** using the example given.Embedded: [YouTube video player](https://www.youtube-nocookie.com/embed/pgGZvx30yNw)On the video demo you must show on a real device how to:* Import account
* Verify address
* Accept / reject a coin transfer transaction
* Show settingsIf applicable :* Transfer a token
* Delegate/Stake/VoteIf blind signing is implemented:* Sign a blind signed transaction while setting is disabled
* Sign a blind signed transaction while setting is enabled_&#x52;eminder : Blind signed operations must only be accessible behind a setting that must be disabled by default ([see blind signing section](../../integration/requirements/security#blind-signing))_

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/maintenance -->

---
title: App maintenance
category: reference
---

# App maintenance

This reference describes the requirements for submitting updates to a published device app or plugin on Ledger Wallet. Third-party developers are responsible for all updates following the initial release.

## Requirements

### Required deliverables

Every update must be submitted alongside the following:

| Deliverable      | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| Functional tests | Tests covering all APDU commands and UI flows affected by the changes                          |
| Security audit   | A [security audit](./deliverables/security-audit) scoped to the changes in the updated version |

### Submission forms

Updates are submitted via a dedicated form. Only the sections of the app that have changed need to be selected.

| Update type | Form                                                          |
| ----------- | ------------------------------------------------------------- |
| Device app  | [Device app update form](./submission-form)                   |
| Plugin      | [Plugin update form](https://ledger.typeform.com/to/YZZCHEB8) |

### Timeline

**Constraint:** Updates must be submitted at least one month before the desired release date. Ledger must be informed as early as possible.

## Further reading

- [Security audit](./deliverables/security-audit) — scope and requirements for the security audit deliverable
- [Development requirements](../integration/requirements/development) — CI workflow checks required before submission
- [Security requirements](../integration/requirements/security) — security constraints that apply to app updates

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/process -->

# How to submit your device app

This guide shows you how to submit a Ledger device app for review and release on Ledger Wallet. The following process applies to autonomous device app development.

**Prerequisites:** Complete all [coding requirements](../integration/requirements/development) and prepare all [required deliverables](./submission-form) before starting this process.

## Development and submission phases

Embedded: [Device App Submission Process](https://view.genial.ly/65521d0b3f30120011106193)

### 1. Make sure your app meets the coding requirements

For an app to be deployed, it must comply with a list of requirements expressed in the [Security](../integration/requirements/security), [Cryptography](../integration/requirements/cryptography), and [Development](../integration/requirements/development) requirements documentation.

### 2. Make sure you have all the deliverables ready

For an app to be deployed, you must provide a list of deliverables. These are detailed in the [submission form](./submission-form) and include icons, videos, a companion wallet, support documentation, and a completed security audit.

### 3. Fill in the submission form

When your app or plugin and all deliverables are ready, [fill in the submission form](./submission-form).

> **Note:** Ledger's release of a third-party application must not be considered as any form of partnership or endorsement.

## Release flow

This process applies to first submissions and to app updates.

Embedded: [Device App Release Flow](https://view.genial.ly/655389953d9cc90010ff9fbc)

Embedded: [Device App Release Flow (mobile)](https://view.genial.ly/655389953d9cc90010ff9fbc)

## Application repository flow

To deploy an application (and sometimes test or apply modifications), Ledger forks the application's repository.

Ledger's fork maintains its own Git flow, which tracks what code is deployed to production through branches and tags.

All work and pull requests are made into or against a `develop` branch. Ledger also deploys applications from `develop` to specific test providers (provider number 4).

This application is not available to most  users, who use the default production provider (provider number 1). However, it is accessible to anyone who changes the provider number under **Settings > Experimental features > My Ledger provider**, which enables real-life testing and qualification.

Further fixes or modifications before the application is deemed ready are merged from the developer's repository into the `develop` branch.

![Diagram showing Ledger's fork-based Git flow, with a develop branch for testing and a production branch for the app store](/device-app/fork-app.png)

## Next steps

Read the Deliverables section and see the [submission form](./submission-form) for the full checklist of required deliverables.

---

<!-- https://developers.ledger.com/docs/device-app/submission-process/submission-form -->

# Submission

The submission of a Ledger device app is completed through a form. This will ask you for all the various items required together in one place.

Please make sure you followed this [process](./process) and the coding requirements, and that all the deliverables are ready, else the deployment process will be stopped.

### Ready to submit your App for review?

Once you have finished your work and you have collected all the App items you must enter them in:

- [This form](https://tally.so/r/w8QKbr) for **device apps**
- [This form](https://tally.so/r/woVdEb) for **plugins**

Make sure you thoroughly complete the form to ensure a speedy release process.

> **Warning:** The integration process will only start if you answer accurately to all the questions.

## Submision forms checklist

This section is a summary outline of what is needed in the process od developing a device app or a plugin. The list below is organised by category and some items are quite varied.
Please make sure you have understood what is expected. You may use this list as a checklist.

## Device Apps

#### General information

- App Name
- The name of your token (if any) as displayed in [CoinMarketCap](https://coinmarketcap.com/)
- Legal Entity name
- Postal address
- Email address
- The app compatibility with our devices

#### Technical specifications for clones

- The type of clone (Bitcoin, Ethereum)
- Link to the pull request

#### Technical specifications for other device apps

- If your app is a fork: the link to the repository's branch you have forked
- Link to your pull request (for updates) or repository (for new apps)
- If it is an update: explanation about the purpose of the pull request
- If it is a new app: explanation about the app features
- If your blockchain is not in  yet and you modified the `Transfer` or `Verify address` flow: explanation about your modifications

#### Security and requirements

- I certify that I have read the [coding guidelines](../develop/tutorials) and the [requirements](../develop/requirements)
- I certify that my app repository has a test folder that contains Unit Tests list and functional Tests
- I certify that the App has been fully tested with a [companion wallet](./deliverables/companion-wallet)
- All vulnerabilities have been fixed

#### Deliverables

- The [Guidelines\_enforcer and Build\_and\_functional\_tests workflow](../develop/requirements/development#workflows) succeeds
- Two icons for the Ledger Stax, Nano and for "My Ledger" in , in PNG or GIF
  (see [Icons](./deliverables/icons/))
- [Video](./deliverables/ui-flow-video/#video) of your application running on the Ledger device
- Link to the companion wallet
- Link to a Google doc tutorial about how to install and use your app (see [Third Party Applications Support](./deliverables/support)). The doc must include the link to the published tutorial hosted on third party website.
- Links to your ser application support (email address, Slack/Reddit/Telegram/Discord communities)
- Marketing plan (optional)

#### Warranty and liability

- I have read and agree with information laid out the [warranty and liability disclaimer](./deliverables/legal/)

## Plugins

#### General information

- dApp Name
- The service the dApp provide and the smart contract addresses
- Legal Entity name
- Postal address
- Email address

#### Security and requirements

I certify that I have read the [coding guidelines](../develop/tutorials) and the [requirements](../develop/requirements)

#### Deliverables

- The [Guidelines\_enforcer and Build\_and\_functional\_tests workflow](../develop/requirements/development#workflows) succeeds
- Two icons for the Ledger Stax, Nano and for "My Ledger" in , in PNG or GIF
  (see [Icons](./deliverables/icons/))
- Link to a Google doc tutorial about how to install and use your app (see [Third Party Applications Support](./deliverables/support)). The doc must include the link to the published tutorial hosted on third party website.
- Links to your application user support (email address, Slack/Reddit/Telegram/Discord communities)

#### Warranty and liability

- I have read and agree with information laid out the [warranty and liability disclaimer](./deliverables/legal/)

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/beginner/discover-and-connect -->

# Connecting to a Device

In this guide, you'll learn how to discover and connect to Ledger devices using the Device Management Kit (DMK). By the end, you'll be able to scan for nearby devices, establish connections, and properly disconnect.

## What you'll learn

- How to discover available Ledger devices over USB or BLE
- How to connect to a specific device
- How to disconnect from a device

## Prerequisites

Before starting, make sure you have initialized a DMK instance. If you haven't done so yet, refer to the [Initializing and Configuring the DMK](./init-dmk) guide.

## Step 1: Discover devices

`startDiscoveringDevices()` returns a `Flow<DiscoveryResult>` that emits updates as nearby devices are found.

```kotlin
dmk.startDiscoveringDevices().collect { result ->
    when (result) {
        is DiscoveryResult.DevicesDiscovered -> {
            val devices: List<DiscoveryDevice> = result.devices
            // Present the list to the user and let them pick one
        }
        is DiscoveryResult.Ended -> {
            // Discovery stopped (timeout reached)
        }
        is DiscoveryResult.Failure.BluetoothDisabled -> {
            // Ask the user to enable Bluetooth
        }
        is DiscoveryResult.Failure.BluetoothPermissionNotGranted -> {
            // Request Bluetooth permissions
        }
        else -> { /* Handle other failure cases */ }
    }
}
```

Each `DiscoveryDevice` exposes:

| Property           | Type               | Description                                 |
| ------------------ | ------------------ | ------------------------------------------- |
| `uid`              | `String`           | Unique identifier for the device            |
| `name`             | `String`           | Human-readable device name                  |
| `ledgerDevice`     | `LedgerDevice`     | Device model (e.g. `NanoX`, `Stax`, `Flex`) |
| `connectivityType` | `ConnectivityType` | `USB` or `BLE`                              |

When discovery is no longer needed, stop it to free resources:

```kotlin
dmk.stopDiscoveringDevices()
```

> **Note:** Discovery stops automatically once `discoveryTimeout` is reached (default: 1
> minute). You can configure this value when initializing the DMK.

## Step 2: Connect to a device

Pass a `DiscoveryDevice` from the previous step to `connectDevice()`:

```kotlin
val result: ConnectionResult = dmk.connectDevice(device)

when (result) {
    is ConnectionResult.Connected -> {
        val connectedDevice: ConnectedDevice = result.device
        // Store connectedDevice.uid — you'll need it for all further interactions
    }
    is ConnectionResult.Disconnected -> {
        when (result.failure) {
            is ConnectionResult.Failure.PairingFailed -> {
                // BLE pairing failed — ask the user to retry
            }
            is ConnectionResult.Failure.ConnectionTimeout -> {
                // Connection attempt exceeded connectionTimeout
            }
            is ConnectionResult.Failure.PermissionNotGranted -> {
                // Required permissions were not granted
            }
            else -> { /* Handle other failures */ }
        }
    }
}
```

Once connected, `ConnectedDevice` exposes:

| Property           | Type               | Description                                                    |
| ------------------ | ------------------ | -------------------------------------------------------------- |
| `uid`              | `String`           | Session identifier — **keep this to interact with the device** |
| `name`             | `String`           | Device name                                                    |
| `ledgerDevice`     | `LedgerDevice`     | Device model                                                   |
| `connectivityType` | `ConnectivityType` | `USB` or `BLE`                                                 |

## Step 3: Disconnect from a device

When you are done using the device, disconnect to release the connection:

```kotlin
dmk.disconnectDevice(connectedDevice)
```

## What you've learned

- How to start and stop device discovery with `startDiscoveringDevices()` / `stopDiscoveringDevices()`
- How to connect to a discovered device with `connectDevice()` and handle connection failures
- How to disconnect with `disconnectDevice()`
- How the `ConnectedDevice.uid` is the key identifier for all further device interactions

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/beginner/ethereum-signer -->

# Ethereum Signer

This module provides the implementation of the Ledger Ethereum Signer for the Mobile Device Management Kit. It enables interaction with the Ethereum application on a Ledger device:

- Retrieving the Ethereum address using a given derivation path
- Signing an Ethereum transaction ([Clear Signing](https://www.ledger.com/academy/topics/ledgersolutions/what-is-clear-signing))
- Signing a message displayed on a Ledger device

## How it works

The Ledger Ethereum Signer uses the interface provided by the Device Management Kit to establish communication with the Ledger device and execute operations. Communication with the device is performed using APDUs (Application Protocol Data Units), encapsulated within `Command` objects, which are in turn encapsulated within `DeviceAction` objects to handle real-world scenarios.

For transaction signing, the Signer integrates with the Context Module to provide context data to the device, enabling Clear Signing — the display of human-readable transaction details on the device screen.

## Installation

> **Note:** This module is not standalone: it depends on the `device-management-kit` module,
> which must be installed first.

The module is published as:

- **Android**: `io.github.ledgerhq:device-signer-kit-ethereum` (Maven/Gradle)
- **iOS**: `SignerEth` (XCFramework / Swift Package Manager)

### Android

#### Using the Version Catalog (recommended)

Add the Ledger SDK version catalog to your `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ledger") {
            from("io.github.ledgerhq:sdk-version-catalog:<version>")
        }
    }
}
```

Then in your module's `build.gradle.kts`:

```kotlin
dependencies {
    implementation(platform(ledger.bom))
    implementation(ledger.device.management.kit)
    implementation(ledger.device.signer.kit.ethereum)
}
```

#### Using the BOM only

```kotlin
dependencies {
    implementation(platform("io.github.ledgerhq:sdk-bom:<version>"))
    implementation("io.github.ledgerhq:device-management-kit")
    implementation("io.github.ledgerhq:device-signer-kit-ethereum")
}
```

#### Direct dependency

```kotlin
dependencies {
    implementation("io.github.ledgerhq:device-management-kit:<version>")
    implementation("io.github.ledgerhq:device-signer-kit-ethereum:<version>")
}
```

### iOS (Swift Package Manager)

Add the `SignerEth` XCFramework to your Xcode project or `Package.swift`.

## Initialisation

To create an `EthereumSigner` instance, you need a `DeviceManagementKitApi` instance. Use the `ethereumSigner` builder DSL:

```kotlin
import com.ledger.signer.eth.ethereumSigner

val signerEth = ethereumSigner {
    deviceManagementKit = dmk
    originToken = "your-origin-token" // optional, for context module identification
}
```

You can also customize the context module endpoints:

```kotlin
val signerEth = ethereumSigner {
    deviceManagementKit = dmk
    originToken = "your-origin-token"
    calUrl = "https://your-custom-cal-url"
    metadataServiceUrl = "https://your-custom-metadata-url"
    transactionCheckUrl = "https://your-custom-tx-check-url"
    enableLog = true
}
```

On Android, pass the application context:

```kotlin
val signerEth = ethereumSigner {
    context = applicationContext
    deviceManagementKit = dmk
    originToken = "your-origin-token"
}
```

## Use Cases

The `EthereumSigner` instance exposes 3 methods. Each returns a `Flow<DeviceActionResult<T>>` — a stream of state updates tracking the operation's progress.

### Get Address

Retrieve the Ethereum address for a given derivation path.

```kotlin
val flow: Flow<DeviceActionResult<EthereumAddress>> = signerEth.getAddress(
    deviceUid = connectedDevice.uid,
    request = GetEthereumAddressRequest(
        derivationPath = "44'/60'/0'/0/0",
        checkOnDevice = false, // set to true to require user confirmation on device
        withChainCode = false,
    ),
)
```

**Parameters:**

| Name                     | Type      | Description                                             |
| ------------------------ | --------- | ------------------------------------------------------- |
| `deviceUid`              | `String`  | UID of the connected device, from `ConnectedDevice.uid` |
| `request.derivationPath` | `String`  | e.g. `"44'/60'/0'/0/0"`                                 |
| `request.checkOnDevice`  | `Boolean` | Whether user confirmation is required on the device     |
| `request.withChainCode`  | `Boolean` | Whether to return the chain code                        |

**Returns:** `Flow<DeviceActionResult<EthereumAddress>>`

```kotlin
data class EthereumAddress(
    val publicKey: String,   // Public key derived from the given path
    val address: String,     // Ethereum address (hex format)
    val chainCode: String?,  // Chain code (if requested)
)
```

---

### Sign Transaction

Sign an Ethereum transaction using Clear Signing on the Ledger device. The Context Module automatically enriches the transaction with token, NFT, and trusted name information so the device can display human-readable details.

```kotlin
val flow: Flow<DeviceActionResult<Signature>> = signerEth.signTransaction(
    deviceUid = connectedDevice.uid,
    request = SignEthereumRequest(
        derivationPath = "44'/60'/0'/0/0",
        value = rawTransactionHex, // RLP-encoded transaction as hex string
        isHexadecimalValue = true,
    ),
)
```

**Parameters:**

| Name                         | Type      | Description                            |
| ---------------------------- | --------- | -------------------------------------- |
| `deviceUid`                  | `String`  | UID of the connected device            |
| `request.derivationPath`     | `String`  | e.g. `"44'/60'/0'/0/0"`                |
| `request.value`              | `String`  | RLP-encoded transaction as hex string  |
| `request.isHexadecimalValue` | `Boolean` | Must be `true` for transaction signing |

**Returns:** `Flow<DeviceActionResult<Signature>>`

```kotlin
data class Signature(
    val r: String,  // R component of the ECDSA signature (hex)
    val s: String,  // S component of the ECDSA signature (hex)
    val v: Int,     // Recovery parameter
)
```

---

### Sign Message

Sign a text message (EIP-191 `personal_sign`) displayed on the Ledger device.

```kotlin
val flow: Flow<DeviceActionResult<Signature>> = signerEth.signMessage(
    deviceUid = connectedDevice.uid,
    request = SignEthereumRequest(
        derivationPath = "44'/60'/0'/0/0",
        value = "Hello from Ledger",
        isHexadecimalValue = false,
    ),
)
```

**Parameters:**

| Name                         | Type      | Description                                       |
| ---------------------------- | --------- | ------------------------------------------------- |
| `deviceUid`                  | `String`  | UID of the connected device                       |
| `request.derivationPath`     | `String`  | e.g. `"44'/60'/0'/0/0"`                           |
| `request.value`              | `String`  | The message to sign (UTF-8 string or hex)         |
| `request.isHexadecimalValue` | `Boolean` | Set to `true` if `value` is in hexadecimal format |

**Returns:** `Flow<DeviceActionResult<Signature>>`

---

## Observable Behavior

Each method returns a `Flow` emitting `DeviceActionResult<T>` updates:

- **`DeviceActionResult.IntermediateValue`**: Operation in progress. May include a `userRequirement` indicating what action is needed from the user.
- **`DeviceActionResult.Success`**: Operation completed; the result is available.
- **`DeviceActionResult.Failure`**: An error occurred; the reason is available.

```kotlin
signerEth.signTransaction(deviceUid, request).collect { result ->
    when (result) {
        is DeviceActionResult.IntermediateValue -> {
            when (result.userRequirement) {
                is UserInteractionRequirement.UnlockDevice -> {
                    println("Ask the user to unlock the device.")
                }
                null -> println("Processing: ${result.value}")
            }
        }
        is DeviceActionResult.Success -> {
            val signature: Signature = result.value
            println("Signed: r=${signature.r}, s=${signature.s}, v=${signature.v}")
        }
        is DeviceActionResult.Failure -> {
            println("Signing failed: ${result.reason}")
        }
    }
}
```

To cancel an in-progress signing operation:

```kotlin
deviceAction.cancel()
```

## Lifecycle

The `EthereumSigner` is a singleton within its Koin scope. It must be initialized once before use. If you need to reinitialize it (e.g., after a new session), destroy the previous instance first.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/beginner/exchange-data -->

# Exchange data with the device

In this guide, you'll learn how to send commands to a connected Ledger device and process the responses using the Device Management Kit (DMK). By the end, you'll understand multiple ways to communicate with your device.

## What you'll learn

- How to send low-level APDU commands to a device
- How to use pre-defined commands for common operations
- How to work with Device Actions for complex flows

## Prerequisites

Before starting, make sure you have completed:

- [Initializing and Configuring the DMK](./init-dmk)
- [Connecting to a Device](./discover-and-connect)

You should have a working DMK instance and a connected device with a valid `deviceUid`.

## Step 1: Sending an APDU

APDU (Application Protocol Data Unit) commands are the low-level protocol used to communicate with Ledger devices. While it is generally recommended to use higher-level abstractions, you can send raw APDUs when needed.

```kotlin
import com.ledger.devicemanagement.api.apdu.ApduPayload

val apduPayload: ApduPayload = /* build your APDU payload */

val result: DeviceOperationResult<ByteArray> = dmk.sendApdu(deviceUid, apduPayload)

when (result) {
    is DeviceOperationResult.Success -> {
        val responseBytes: ByteArray = result.value
    }
    is DeviceOperationResult.Failure -> {
        when (result.reason) {
            DeviceOperationFailureReason.DeviceLocked -> { /* Device is locked */ }
            DeviceOperationFailureReason.DeviceBusy -> { /* Device is busy */ }
            DeviceOperationFailureReason.NoResponse -> { /* No response from device */ }
            else -> { /* Handle other failures */ }
        }
    }
}
```

## Step 2: Using pre-defined commands

For most common operations, the DMK provides pre-defined commands. `executeCommand` handles building the APDU, sending it to the device, and parsing the response.

> **Warning:** Most commands return `DeviceOperationResult.Failure` if the device is locked
> or busy. Check the device state with `observeDeviceState` before sending
> commands.

### Opening an app

```kotlin
import com.ledger.devicemanagement.api.command.openapp.OpenApplicationCommand

val command = OpenApplicationCommand(name = "Ethereum")

val result: DeviceOperationResult<Unit> = dmk.executeCommand(deviceUid, command)

when (result) {
    is DeviceOperationResult.Success -> println("App opened successfully")
    is DeviceOperationResult.Failure -> println("Failed: ${result.reason}")
}
```

### Closing an app

```kotlin
import com.ledger.devicemanagement.api.command.closeapp.CloseRunningApplicationCommand

val command = CloseRunningApplicationCommand()

val result: DeviceOperationResult<Unit> = dmk.executeCommand(deviceUid, command)

when (result) {
    is DeviceOperationResult.Success -> println("App closed successfully")
    is DeviceOperationResult.Failure -> println("Failed: ${result.reason}")
}
```

### Getting OS information

```kotlin
import com.ledger.devicemanagement.api.command.getosversion.GetOsVersionCommand
import com.ledger.devicemanagement.api.command.getosversion.OsVersion

val command = GetOsVersionCommand()

val result: DeviceOperationResult<OsVersion> = dmk.executeCommand(deviceUid, command)

when (result) {
    is DeviceOperationResult.Success -> {
        val osVersion: OsVersion = result.value
        println("SE version: ${osVersion.secureElementVersion}")
        println("MCU version: ${osVersion.microcontrollerSephVersion}")
        println("Hardware version: ${osVersion.hardwareVersion}")
    }
    is DeviceOperationResult.Failure -> println("Failed: ${result.reason}")
}
```

### Getting app information

```kotlin
import com.ledger.devicemanagement.api.command.getappandversion.GetAppAndVersionCommand
import com.ledger.devicemanagement.api.command.getappandversion.AppAndVersion

val command = GetAppAndVersionCommand()

val result: DeviceOperationResult<AppAndVersion> = dmk.executeCommand(deviceUid, command)

when (result) {
    is DeviceOperationResult.Success -> {
        val appInfo: AppAndVersion = result.value
        println("Running app: ${appInfo.appName} v${appInfo.appVersion}")
    }
    is DeviceOperationResult.Failure -> println("Failed: ${result.reason}")
}
```

## Step 3: Working with Device Actions

Device Actions define a sequence of commands sent to the device. They are useful for operations that require user interaction, such as opening an app while handling device lock or confirmation screens automatically.

Device Actions return a `Flow<DeviceActionResult<T>>` that emits state updates during execution.

### Opening an app with a Device Action

```kotlin
import com.ledger.devicemanagement.api.deviceaction.openapp.OpenApplicationDeviceAction
import com.ledger.devicemanagement.api.deviceaction.DeviceActionResult
import com.ledger.devicemanagement.api.deviceaction.UserInteractionRequirement

val deviceAction = OpenApplicationDeviceAction(appName = "Ethereum")

dmk.executeDeviceAction(deviceUid, deviceAction).collect { result ->
    when (result) {
        is DeviceActionResult.IntermediateValue -> {
            when (result.userRequirement) {
                is UserInteractionRequirement.UnlockDevice -> {
                    println("Ask the user to unlock the device")
                }
                null -> println("Processing...")
            }
        }
        is DeviceActionResult.Success -> {
            println("App opened successfully")
        }
        is DeviceActionResult.Failure -> {
            println("Action failed: ${result.reason}")
        }
    }
}
```

The `OpenApplicationDeviceAction` automatically handles the full flow:

1. Checks if the device is onboarded
2. Checks if the requested app is already open
3. Closes the current app if a different one is running
4. Opens the requested app and waits for user confirmation on the device

To cancel an in-progress action:

```kotlin
deviceAction.cancel()
```

## What you've learned

- How to send raw APDU commands with `sendApdu()`
- How to use pre-defined commands (`OpenApplicationCommand`, `CloseRunningApplicationCommand`, `GetOsVersionCommand`, `GetAppAndVersionCommand`) with `executeCommand()`
- How to use `OpenApplicationDeviceAction` to handle complex multi-step flows with user interaction

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/beginner/init-dmk -->

# Initializing and Configuring the DMK

In this guide, you'll learn how to initialize and configure the Device Management Kit (DMK) for your application. By the end, you'll have a working DMK instance ready to interface with Ledger devices.

## What you'll learn

- How to initialize the DMK using the Kotlin DSL
- What configuration options are available
- How to maintain the DMK instance as a singleton

## Step 1: Create the DMK instance

Use the `deviceManagementKit` builder DSL to obtain an instance of `DeviceManagementKitApi`. This should be done **once** in your application lifecycle.

**Android (Kotlin):**

```kotlin
import com.ledger.devicemanagement.DeviceManagementKitApi
import com.ledger.devicemanagement.deviceManagementKit

val dmk: DeviceManagementKitApi = deviceManagementKit {
    context = applicationContext
    enableLog = true
}
```

**iOS (Swift):**

```swift
import LedgerDMK

let dmk = DeviceManagementKit.build()
```

## Step 2: Configuration options

The builder DSL exposes the following parameters:

| Parameter           | Type       | Default      | Description                                                   |
| ------------------- | ---------- | ------------ | ------------------------------------------------------------- |
| `context`           | `Any?`     | `null`       | Android application context — required on Android             |
| `discoveryTimeout`  | `Duration` | `1.minutes`  | How long the SDK scans for nearby devices before stopping     |
| `connectionTimeout` | `Duration` | `15.seconds` | How long the SDK waits for a device connection before failing |
| `enableLog`         | `Boolean`  | `false`      | Enable SDK-wide logging                                       |
| `enableFake`        | `Boolean`  | `false`      | Use fake device implementations — useful for testing          |

Example with all options:

```kotlin
val dmk: DeviceManagementKitApi = deviceManagementKit {
    context = applicationContext
    discoveryTimeout = 2.minutes
    connectionTimeout = 30.seconds
    enableLog = true
    enableFake = false
}
```

> **Warning:** Both `discoveryTimeout` and `connectionTimeout` must be strictly greater than
> zero, otherwise the builder will throw an exception.

## Step 3: Keep it as a singleton

> **Caution:** The DMK can only be initialized **once** per application runtime. Attempting
> to create a second instance will throw an exception. Always keep a single
> reference and share it across your application.

```kotlin
// Application.kt
class MyApplication : Application() {
    lateinit var dmk: DeviceManagementKitApi

    override fun onCreate() {
        super.onCreate()
        dmk = deviceManagementKit {
            context = applicationContext
            enableLog = BuildConfig.DEBUG
        }
    }
}
```

## Step 4: Release resources

Call `destroy()` when your application closes to release all resources held by the DMK:

```kotlin
dmk.destroy()
```

## What you've learned

- How to initialize the DMK with the `deviceManagementKit { }` Kotlin DSL
- The available configuration parameters and their defaults
- Why the DMK must be treated as a singleton
- How to properly release resources on shutdown

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/beginner/setup -->

# Setup

> The following steps describe only a minimal setup. You will need to perform additional steps depending on the module you want to work on — refer to its dedicated page.

## Add dependencies

### Version Catalog (recommended)

Add the Ledger SDK version catalog to your `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("ledger") {
            from("io.github.ledgerhq:sdk-version-catalog:<version>")
        }
    }
}
```

---

### Device Management Kit

#### Using the Version Catalog

```kotlin
dependencies {
    implementation(platform(ledger.bom))
    implementation(ledger.device.management.kit)
}
```

#### Using the BOM only

```kotlin
dependencies {
    implementation(platform("io.github.ledgerhq:sdk-bom:<version>"))
    implementation("io.github.ledgerhq:device-management-kit")
}
```

#### Direct dependency

```kotlin
dependencies {
    implementation("io.github.ledgerhq:device-management-kit:<version>")
}
```

#### iOS (Swift Package Manager)

Add the `LedgerDMK` XCFramework to your Xcode project or `Package.swift`.

---

### Ethereum Signer

> **Note:** This module depends on the `device-management-kit` module, which must be installed
> first.

#### Using the Version Catalog

```kotlin
dependencies {
    implementation(platform(ledger.bom))
    implementation(ledger.device.management.kit)
    implementation(ledger.device.signer.kit.ethereum)
}
```

#### Using the BOM only

```kotlin
dependencies {
    implementation(platform("io.github.ledgerhq:sdk-bom:<version>"))
    implementation("io.github.ledgerhq:device-management-kit")
    implementation("io.github.ledgerhq:device-signer-kit-ethereum")
}
```

#### Direct dependency

```kotlin
dependencies {
    implementation("io.github.ledgerhq:device-management-kit:<version>")
    implementation("io.github.ledgerhq:device-signer-kit-ethereum:<version>")
}
```

#### iOS (Swift Package Manager)

Add the `SignerEth` XCFramework to your Xcode project or `Package.swift`.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/how_to/build_custom_command -->

# Build a Custom Command

You can build your own command by implementing the `Command<T>` interface and providing an APDU payload and a response parser.

You can then execute it with `dmk.executeCommand()`, exactly like any pre-defined command. This is strongly recommended over direct usage of `sendApdu`.

## The `Command` Interface

```kotlin
public interface Command<out T> {
    val apduPayload: ApduPayload
    fun parseResponse(connectedDevice: ConnectedDevice, response: ByteArray): DeviceOperationResult<T>
    fun checkPreconditions(): DeviceOperationResult.Failure?
}
```

| Member               | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `apduPayload`        | The APDU to send to the device                           |
| `parseResponse`      | Parses the raw response bytes into a typed result        |
| `checkPreconditions` | Validates inputs before sending — return `null` if valid |

## Quick Example

Here is a complete custom command that retrieves a hypothetical device serial number:

```kotlin
import com.ledger.devicemanagement.api.DeviceOperationFailureReason
import com.ledger.devicemanagement.api.DeviceOperationResult
import com.ledger.devicemanagement.api.apdu.ApduParser
import com.ledger.devicemanagement.api.apdu.ApduPayload
import com.ledger.devicemanagement.api.apdu.apdu
import com.ledger.devicemanagement.api.apdu.uniqueApduPayload
import com.ledger.devicemanagement.api.command.Command
import com.ledger.devicemanagement.api.connection.ConnectedDevice

data class SerialNumber(val value: String)

class GetSerialNumberCommand : Command<SerialNumber> {

    override val apduPayload: ApduPayload = uniqueApduPayload(
        apdu = apdu {
            classInstruction = 0xE0.toByte()
            instructionMethod = 0x02.toByte()
            parameter1 = 0x00.toByte()
            parameter2 = 0x00.toByte()
        },
    )

    override fun parseResponse(
        connectedDevice: ConnectedDevice,
        response: ByteArray,
    ): DeviceOperationResult<SerialNumber> {
        if (response.size < 2) {
            return DeviceOperationResult.Failure(DeviceOperationFailureReason.Unknown)
        }
        val parser = ApduParser(response)
        val length = parser.extract1BytesValue().toInt()
        val serial = parser.extractValueString(nbrBytes = length)
        return DeviceOperationResult.Success(SerialNumber(serial))
    }

    override fun checkPreconditions(): DeviceOperationResult.Failure? = null
}
```

## Usage

Once your command is implemented, execute it with `dmk.executeCommand()`:

```kotlin
val command = GetSerialNumberCommand()

val result: DeviceOperationResult<SerialNumber> = dmk.executeCommand(deviceUid, command)

when (result) {
    is DeviceOperationResult.Success -> println("Serial: ${result.value.serial}")
    is DeviceOperationResult.Failure -> println("Failed: ${result.reason}")
}
```

## Building the APDU

Use the `apdu { }` DSL to construct the APDU header and optional data payload, then wrap it with `uniqueApduPayload`:

```kotlin
override val apduPayload: ApduPayload = uniqueApduPayload(
    apdu = apdu {
        classInstruction = 0xE0.toByte()  // CLA
        instructionMethod = 0xD8.toByte() // INS
        parameter1 = 0x00.toByte()        // P1
        parameter2 = 0x00.toByte()        // P2
        data = "Ethereum".encodeToByteArray() // optional data
    },
)
```

> **Note:** Use `uniqueApduPayload` for single-APDU commands. For commands whose data
> exceeds 255 bytes and must be split across multiple APDUs, use
> `chunkApduPayload`.

## Parsing the Response

`ApduParser` reads the response bytes sequentially. Use the appropriate extraction method for each field:

```kotlin
val parser = ApduParser(response)

val singleByte  = parser.extractByteValue()               // 1 byte as Byte
val rawByte     = parser.extract1BytesValue()             // 1 byte as ByteArray
val twoBytes    = parser.extract2BytesValue()             // 2 bytes
val fourBytes   = parser.extract4BytesValue()             // 4 bytes
val nBytes      = parser.extractBytesValue(nbrBytes = 6)  // N bytes
val text        = parser.extractValueString(nbrBytes = 10) // N bytes decoded as String
val remaining   = parser.extractRemainingBytesValue()     // everything left
```

A typical pattern for length-prefixed strings:

```kotlin
val length = parser.extract1BytesValue().toInt()
val value  = parser.extractValueString(nbrBytes = length)
```

## Custom Failure Reasons

For command-specific errors, extend `DeviceOperationFailureReason`:

```kotlin
sealed class GetSerialNumberFailureReason : DeviceOperationFailureReason() {
    data object NotSupported : GetSerialNumberFailureReason()
    data object InvalidResponse : GetSerialNumberFailureReason()
}
```

Then return them in `parseResponse`:

```kotlin
private const val SW_NOT_SUPPORTED = "6D00"

override fun parseResponse(
    connectedDevice: ConnectedDevice,
    response: ByteArray,
): DeviceOperationResult<SerialNumber> {
    if (response.toHexadecimalString() == SW_NOT_SUPPORTED) {
        return DeviceOperationResult.Failure(GetSerialNumberFailureReason.NotSupported)
    }
    // ... parse normally
}
```

## Precondition Checking

Use `checkPreconditions` to validate inputs before the APDU is sent — for example to reject empty strings or out-of-range values:

```kotlin
override fun checkPreconditions(): DeviceOperationResult.Failure? =
    if (name.isEmpty()) {
        DeviceOperationResult.Failure(GetSerialNumberFailureReason.InvalidResponse)
    } else {
        null
    }
```

Return `null` if all preconditions are met.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/how_to/eth_signer -->

# Use the Ethereum Signer

This module provides the implementation of the Ledger Ethereum Signer for the Mobile Device Management Kit. It enables interaction with the Ethereum application on a Ledger device:

- Retrieving the Ethereum address using a given derivation path
- Signing an Ethereum transaction ([Clear Signing](https://www.ledger.com/academy/topics/ledgersolutions/what-is-clear-signing))
- Signing a message displayed on a Ledger device

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Initialisation](#-initialisation)
3. [Use Cases](#-use-cases)
   - [Get Address](#use-case-1-get-address)
   - [Sign Transaction](#use-case-2-sign-transaction)
   - [Sign Message](#use-case-3-sign-message)

## 🔹 How it works

The Ledger Ethereum Signer uses the interface provided by the Device Management Kit to establish communication with the Ledger device and execute operations. Communication is performed using [APDUs](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit), encapsulated within `Command` objects, which are in turn encapsulated within `DeviceAction` objects to handle real-world scenarios.

For transaction signing, the Signer integrates with the Context Module to provide context data to the device, enabling Clear Signing — the display of human-readable transaction details on the device screen.

## 🔹 Initialisation

To initialize an Ethereum signer instance, you need a `DeviceManagementKitApi` instance. Use the `ethereumSigner` builder DSL:

```kotlin
import com.ledger.signer.eth.ethereumSigner

val signerEth = ethereumSigner {
    context = applicationContext // required on Android
    deviceManagementKit = dmk
    originToken = "your-origin-token"
}
```

> **Note:** The `originToken` is required by the default Context Module for transaction
> checks. It should be delivered by Ledger — without it, Transaction Checks will
> not be available.

You can also customize the Context Module endpoints:

```kotlin
val signerEth = ethereumSigner {
    context = applicationContext
    deviceManagementKit = dmk
    originToken = "your-origin-token"
    calUrl = "https://your-custom-cal-url"
    metadataServiceUrl = "https://your-custom-metadata-url"
    transactionCheckUrl = "https://your-custom-tx-check-url"
    enableLog = true
}
```

## 🔹 Use Cases

The `EthereumSigner` exposes 3 dedicated methods. Each returns a `Flow<DeviceActionResult<T>>` — a stream of state updates tracking the operation's progress.

---

### Use Case 1: Get Address

Retrieve the Ethereum address for a given derivation path.

```kotlin
val flow: Flow<DeviceActionResult<EthereumAddress>> = signerEth.getAddress(
    deviceUid = connectedDevice.uid,
    request = GetEthereumAddressRequest(
        derivationPath = "44'/60'/0'/0/0",
        checkOnDevice = false,
        withChainCode = false,
    ),
)
```

#### **Parameters**

- `deviceUid`

  - **Required**
  - **Type:** `String`
  - The UID of the connected device, from `ConnectedDevice.uid`.

- `request`

  - **Required**
  - **Type:** `GetEthereumAddressRequest`

  | Field            | Type      | Description                                         |
  | ---------------- | --------- | --------------------------------------------------- |
  | `derivationPath` | `String`  | Derivation path, e.g. `"44'/60'/0'/0/0"`            |
  | `checkOnDevice`  | `Boolean` | Whether user confirmation is required on the device |
  | `withChainCode`  | `Boolean` | Whether to return the chain code                    |

#### **Returns**

`Flow<DeviceActionResult<EthereumAddress>>`

```kotlin
data class EthereumAddress(
    val publicKey: String,   // Public key derived from the given path
    val address: String,     // Ethereum address (hex format)
    val chainCode: String?,  // Chain code (if requested)
)
```

---

### Use Case 2: Sign Transaction

Sign an Ethereum transaction using Clear Signing on the Ledger device. The Context Module automatically enriches the transaction with token, NFT, and trusted name information so the device can display human-readable details.

```kotlin
val flow: Flow<DeviceActionResult<Signature>> = signerEth.signTransaction(
    deviceUid = connectedDevice.uid,
    request = SignEthereumRequest(
        derivationPath = "44'/60'/0'/0/0",
        value = rawTransactionHex,
        isHexadecimalValue = true,
    ),
)
```

#### **Parameters**

- `deviceUid`

  - **Required**
  - **Type:** `String`
  - The UID of the connected device.

- `request`

  - **Required**
  - **Type:** `SignEthereumRequest`

  | Field                | Type      | Description                              |
  | -------------------- | --------- | ---------------------------------------- |
  | `derivationPath`     | `String`  | Derivation path, e.g. `"44'/60'/0'/0/0"` |
  | `value`              | `String`  | RLP-encoded transaction as hex string    |
  | `isHexadecimalValue` | `Boolean` | Must be `true` for transaction signing   |

#### **Returns**

`Flow<DeviceActionResult<Signature>>`

```kotlin
data class Signature(
    val r: String,  // R component of the ECDSA signature (hex)
    val s: String,  // S component of the ECDSA signature (hex)
    val v: Int,     // Recovery parameter
)
```

---

### Use Case 3: Sign Message

Sign a text message (EIP-191 `personal_sign`) displayed on the Ledger device.

```kotlin
val flow: Flow<DeviceActionResult<Signature>> = signerEth.signMessage(
    deviceUid = connectedDevice.uid,
    request = SignEthereumRequest(
        derivationPath = "44'/60'/0'/0/0",
        value = "Hello from Ledger",
        isHexadecimalValue = false,
    ),
)
```

#### **Parameters**

- `deviceUid`

  - **Required**
  - **Type:** `String`
  - The UID of the connected device.

- `request`

  - **Required**
  - **Type:** `SignEthereumRequest`

  | Field                | Type      | Description                              |
  | -------------------- | --------- | ---------------------------------------- |
  | `derivationPath`     | `String`  | Derivation path, e.g. `"44'/60'/0'/0/0"` |
  | `value`              | `String`  | Message to sign (UTF-8 string or hex)    |
  | `isHexadecimalValue` | `Boolean` | Set to `true` if `value` is hexadecimal  |

#### **Returns**

`Flow<DeviceActionResult<Signature>>`

```kotlin
data class Signature(
    val r: String,  // R component of the ECDSA signature (hex)
    val s: String,  // S component of the ECDSA signature (hex)
    val v: Int,     // Recovery parameter
)
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-kmp/index -->

# Mobile SDK

> **Warning:** The current version of this Device Management Kit is in **alpha stage** and is
> subject to significant changes.Any feedback is welcome — get in touch with us on the [Ledger Discord
> server](https://developers.ledger.com/discord/) to share your thoughts.

## Who is this for?

The Mobile SDK is aimed at developers who want to integrate Ledger hardware device support into **native mobile applications** (Android and/or iOS):

- **Android developers** — using Kotlin, with native access to Bluetooth and USB transports.
- **iOS developers** — using Swift or Kotlin via KMP, with Bluetooth support.
- **KMP teams** — sharing business logic between Android and iOS through Kotlin Multiplatform.

This SDK is distinct from the TypeScript SDK: it is not based on React Native but on a native Kotlin Multiplatform implementation, making it better suited for mobile projects seeking native performance and deep OS integration.

## Libraries

Here you can find a summary of all the libraries that compose the DMK.

| Device Management Kit (DMK) | Maven                                      | Version |
| --------------------------- | ------------------------------------------ | ------- |
| Device Management Kit       | `io.github.ledgerhq:device-management-kit` | 0.0.4   |

| Signers         | Maven                                           | Version |
| --------------- | ----------------------------------------------- | ------- |
| Ethereum Signer | `io.github.ledgerhq:device-signer-kit-ethereum` | 0.0.4   |
| Context Module  | `io.github.ledgerhq:context-module`             | 0.0.4   |

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/beginner/ble_flex_stax -->

---
title: "Add BLE and USB support for Flex and Stax"
category: tutorial
---

# Add BLE and USB support for Flex and Stax

## DMK

### Prerequisites

Device Management Kit: v0.4.0 (and later)

### Implementation

```typescript
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import { webBleTransportFactory } from "@ledgerhq/device-transport-kit-web-ble";
import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";

const dmk = new DeviceManagementKitBuilder()
  .addTransport(webBleTransportFactory)
  .addTransport(webHidTransportFactory)
  .build();
```

Find more information [here](../integration/how_to/transports).

## LedgerJS

### Prerequisites

LedgerJS transport libraries: v8.3.0 (and later)

### Implementation

```typescript
import TransportBLE from "@ledgerhq/hw-transport-web-ble";
import TransportUSB from "@ledgerhq/hw-transport-web-usb";

// Example of connecting to a device via BLE
const transportBLE = await TransportBLE.create();
const ethAppBLE = new AppEth(transportBLE);

// Example of connecting to a device via USB
const transportUSB = await TransportUSB.create();
const ethAppUSB = new AppEth(transportUSB);
```

Find more information [here](../ledgerjs/info).

## Custom Integration

Use the identifiers for devices and transport [as describred in the reference section](../references/identifiers).

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/beginner/discover_and_connect -->

---
title: "Connecting to a Device"
category: tutorial
---

# Connecting to a Device

In this guide, you'll learn how to discover and connect to hardware devices using the Device Management Kit (DMK). By the end, you'll be able to scan for nearby devices, establish connections, and monitor their status.

## What you'll learn

- How to discover available devices
- How to establish a connection with a specific device
- How to monitor device status and session state
- How to properly disconnect from a device

## Prerequisites

Before starting this tutorial, make sure you have initialized the DMK instance and imported it in your project. If you haven't done so, please refer to the [Initializing the DMK](./init_dmk) tutorial.

> 💡 **Hands-on Workshop:** If you prefer to learn through practical exercises, check out our [Device Management Kit Workshop](https://github.com/LedgerHQ/device-management-kit-ts-workshop). This workshop provides a complete React project with step-by-step instructions to implement device discovery, connection, and data exchange features using the DMK.

## Step 1: Initialize device discovery

Let's start the discovery process:

- **Discovery**: `dmk.startDiscovering()`
  - Returns an observable which will emit a new `DiscoveredDevice` for every scanned device.
  - The `DiscoveredDevice` objects contain information about the device model.
  - Use one of these values to connect to a given discovered device.
- **Connection**:

```ts
dmk.connect({
  deviceId: device.id,
  {
    isRefresherDisabled: boolean;
    pollingInterval?: number;
  }
})
```

- Returns a Promise resolving in a device session identifier `DeviceSessionId`.
- **Keep this device session identifier to further interact with the device.**
- Then, `dmk.getConnectedDevice({ sessionId })` returns the `ConnectedDevice`, which contains information about the device model and its name.

```ts
// Start discovering devices
const discoverySubscription = dmk.startDiscovering({}).subscribe({
  next: (device) => {
    dmk
    .connect({
      deviceId: device.id,
      { isRefresherDisabled: true }
    })
    .then((sessionId) => {
      const connectedDevice = dmk.getConnectedDevice({ sessionId });
    });
  },
  error: (error) => {
    console.error("Discovery error:", error);
  },
});

// When you're done discovering, don't forget to unsubscribe to free up resources
// discoverySubscription.unsubscribe();
```

The `startDiscovering()` method returns an Observable that emits a `DiscoveredDevice` object each time a new device is found.

## Step 2: Connect to a discovered device

Once you've discovered a device you want to use, you can connect to it by passing the device object:

```ts
async function connectToDevice(device) {
  try {
    // Connect to the device by passing the full device object
    const sessionId = await dmk.connect({ device });
    console.log(`Connected! Session ID: ${sessionId}`);

    // Get information about the connected device
    const connectedDevice = dmk.getConnectedDevice({ sessionId });
    console.log(`Device name: ${connectedDevice.name}`);
    console.log(`Device model: ${connectedDevice.modelId}`);

    return sessionId;
  } catch (error) {
    console.error("Connection failed:", error);
  }
}
```

The connection process returns a `sessionId` which you'll need for all further interactions with the device.

## Step 3: Monitor the device session state

After connecting, you can monitor the device's state to stay updated on its status, battery level, and other information:

```ts
function monitorDeviceState(sessionId) {
  const stateSubscription = dmk.getDeviceSessionState({ sessionId }).subscribe({
    next: (state) => {
      // The state object contains all the current information about the device
      console.log(`Device status: ${state.deviceStatus}`);
      // Device status can be:
      // - LOCKED: device is waiting for the user to enter their PIN
      // - BUSY: device is processing a command
      // - CONNECTED: device is connected and available
      // - NOT_CONNECTED: device is disconnected

      // Battery information might not always be available
      if (state.batteryStatus) {
        console.log(`Battery level: ${state.batteryStatus.level}%`);
      }

      // Information about the current running app
      if (state.currentApp) {
        console.log(`Current app: ${state.currentApp.name}`);
        console.log(`App version: ${state.currentApp.version}`);
      }

      // Basic device information is always available
      console.log(`Device model: ${state.deviceModelId}`);
    },
    error: (error) => {
      console.error("State monitoring error:", error);
    },
  });

  return stateSubscription;
}
```

## Step 4: Disconnect from the device

When you're finished using the device, always disconnect properly:

```ts
async function disconnectDevice(sessionId) {
  try {
    await dmk.disconnect({ sessionId });
    console.log("Device disconnected successfully");
  } catch (error) {
    console.error("Disconnection error:", error);
  }
}
```

## Complete example

Here's a complete example that combines all the steps:

```ts
import { DeviceStatus } from "@ledgerhq/device-management-kit";

// Global variables to store subscriptions and session info
let discoverySubscription;
let stateSubscription;
let currentSessionId;

function startDiscoveryAndConnect() {
  // Clear any previous discovery
  if (discoverySubscription) {
    discoverySubscription.unsubscribe();
  }

  console.log("Starting device discovery...");

  // Start discovering - this will scan for any connected devices
  discoverySubscription = dmk.startDiscovering({}).subscribe({
    next: async (device) => {
      console.log(
        `Found device: ${device.id}, model: ${device.deviceModel.model}`,
      );

      // Connect to the first device we find
      try {
        // Pass the full device object, not just the ID
        currentSessionId = await dmk.connect({ device });
        console.log(`Connected! Session ID: ${currentSessionId}`);

        // Stop discovering once we connect
        discoverySubscription.unsubscribe();

        // Get device information
        const connectedDevice = dmk.getConnectedDevice({
          sessionId: currentSessionId,
        });
        console.log(`Device name: ${connectedDevice.name}`);
        console.log(`Device model: ${connectedDevice.modelId}`);

        // Start monitoring device state
        stateSubscription = monitorDeviceState(currentSessionId);
      } catch (error) {
        console.error("Connection failed:", error);
      }
    },
    error: (error) => {
      console.error("Discovery error:", error);
    },
  });
}

function monitorDeviceState(sessionId) {
  return dmk.getDeviceSessionState({ sessionId }).subscribe({
    next: (state) => {
      console.log(`Device status: ${state.deviceStatus}`);

      // Check for specific status conditions
      if (state.deviceStatus === DeviceStatus.LOCKED) {
        console.log("Device is locked - please enter your PIN");
      }

      // Show battery level if available
      if (state.batteryStatus) {
        console.log(`Battery level: ${state.batteryStatus.level}%`);
      }

      // Show app information if available
      if (state.currentApp) {
        console.log(`Current app: ${state.currentApp.name}`);
        console.log(`App version: ${state.currentApp.version}`);
      }

      // Basic device model info
      console.log(`Device model: ${state.deviceModelId}`);
    },
    error: (error) => {
      console.error("State monitoring error:", error);
    },
  });
}

// Always clean up resources when done
async function cleanup() {
  // Unsubscribe from all observables
  if (discoverySubscription) {
    discoverySubscription.unsubscribe();
  }

  if (stateSubscription) {
    stateSubscription.unsubscribe();
  }

  // Disconnect from device if connected
  if (currentSessionId) {
    try {
      await dmk.disconnect({ sessionId: currentSessionId });
      console.log("Device disconnected successfully");
      currentSessionId = null;
    } catch (error) {
      console.error("Disconnection error:", error);
    }
  }
}

// Example usage:
// startDiscoveryAndConnect();
// ...later when done...
// cleanup();
```

> Important: Always remember to unsubscribe from observables and disconnect from devices when you're done. This helps manage resources and prevents potential issues with device connections.

## What you've learned

Congratulations! You've now learned how to:

- Discover available hardware devices
- Connect to a specific device using the device object from discovery
- Retrieve information about a connected device
- Monitor device state in real-time
- Properly disconnect from a device when finished

With these skills, you're ready to start building applications that interact with hardware devices using the DMK.

> 📚 **Next Steps:** To build a complete working example with these concepts, check out our [Device Management Kit Workshop](https://github.com/LedgerHQ/device-management-kit-ts-workshop), which guides you through creating a React application that integrates with Ledger devices.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/beginner/exchange_data -->

---
title: "Exchange data with the device"
category: tutorial
---

# Exchange data with the device

In this guide, you'll learn how to send commands to a connected Ledger device and process the responses using the Device Management Kit (DMK). By the end, you'll understand multiple ways to communicate with your hardware device.

## What you'll learn

- How to send low-level APDU commands to a device
- How to use pre-defined commands for common operations
- How to work with device actions for complex flows
- How to handle user interactions during device communication

## Prerequisites

Before starting this tutorial, make sure you've completed:

- [Setting up your environment](./setup)
- [Initializing the DMK](./init_dmk)
- [Connecting to a Device](./discover_and_connect)

You should have a working DMK instance and a connected device with a valid `sessionId`.

## Step 1: Sending an APDU command

APDU (Application Protocol Data Unit) commands are the low-level protocol used to communicate with Ledger devices. While it's generally recommended to use higher-level abstractions, understanding APDUs can be helpful for advanced use cases.

```ts
import {
  ApduBuilder,
  ApduParser,
  CommandUtils,
} from "@ledgerhq/device-management-kit";

// Build the APDU to open the Bitcoin app
const openAppApduArgs = {
  cla: 0xe0,
  ins: 0xd8,
  p1: 0x00,
  p2: 0x00,
};
const apdu = new ApduBuilder(openAppApduArgs)
  .addAsciiStringToData("Bitcoin")
  .build();

// Send the APDU to the device
const apduResponse = await dmk.sendApdu({ sessionId, apdu });

// Parse the result
const parser = new ApduParser(apduResponse);

// Check if the command was successful
if (!CommandUtils.isSuccessResponse(apduResponse)) {
  throw new Error(
    `Unexpected status word: ${parser.encodeToHexaString(
      apduResponse.statusCode,
    )}`,
  );
}
```

## Step 2: Using pre-defined commands

For most common operations, the DMK provides pre-defined commands that are easier to use and maintain. The `sendCommand` method handles building the APDU, sending it to the device, and parsing the response.

> ## ❗️ Error Handling
>
> Most commands will reject with an error if:
>
> - The device is locked - check the device session state with `dmk.getDeviceSessionState({ sessionId })` first
> - The response status word is not `0x9000` (success)

### Opening an app

```ts
import { OpenAppCommand } from "@ledgerhq/device-management-kit";

// Create the command to open the Bitcoin app
const command = new OpenAppCommand("Bitcoin");

// Send the command and wait for the user to confirm on the device
await dmk.sendCommand({ sessionId, command });

// You can also send the command with a timeout to abort the command if it takes too long (in milliseconds)
await dmk.sendCommand({ sessionId, command, abortTimeout: 10000 });
```

### Closing an app

```ts
import { CloseAppCommand } from "@ledgerhq/device-management-kit";

// Create the command to close the current app
const command = new CloseAppCommand();

// Send the command
await dmk.sendCommand({ sessionId, command });
```

### Getting OS information

```ts
import { GetOsVersionCommand } from "@ledgerhq/device-management-kit";

// Create the command to get OS version information
const command = new GetOsVersionCommand();

// Send the command and get the response
const { seVersion, mcuSephVersion, mcuBootloaderVersion } =
  await dmk.sendCommand({ sessionId, command });

console.log(`OS Version: ${seVersion}`);
```

> ℹ️ Tip: This information is also available in the device session state, which you can access with `dmk.getDeviceSessionState({ sessionId })`.

### Getting app information

```ts
import { GetAppAndVersionCommand } from "@ledgerhq/device-management-kit";

// Create the command to get app information
const command = new GetAppAndVersionCommand();

// Send the command and get the response
const { name, version } = await dmk.sendCommand({ sessionId, command });

console.log(`Running app: ${name} v${version}`);
```

## Step 3: Working with Device Actions

Device actions define a sequence of commands to be sent to the device. They're useful for complex operations that require user interaction, like opening an app and performing operations within it.

Device actions return an observable that emits different states during execution, allowing your application to respond to intermediate steps.

### Opening an app with a Device Action

```ts
import {
  OpenAppDeviceAction,
  OpenAppDAState,
  DeviceActionStatus,
  UserActionRequiredType,
} from "@ledgerhq/device-management-kit";

// Create the device action
const openAppDeviceAction = new OpenAppDeviceAction({ appName: "Bitcoin" });

// Execute the device action
const { observable, cancel } = await dmk.executeDeviceAction({
  sessionId,
  deviceAction: openAppDeviceAction,
});

// Subscribe to state changes
observable.subscribe({
  next: (state: OpenAppDAState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted:
        console.log("Action not started yet");
        break;
      case DeviceActionStatus.Pending:
        const {
          intermediateValue: { userActionRequired },
        } = state;
        switch (userActionRequired) {
          case UserActionRequiredType.None:
            console.log("No user action required");
            break;
          case UserActionRequiredType.ConfirmOpenApp:
            console.log(
              "The user should confirm the app opening on the device",
            );
            break;
          case UserActionRequiredType.UnlockDevice:
            console.log("The user should unlock the device");
            break;
          default:
            // Always handle all possible user actions
            throw new Error("Unhandled user action required");
        }
        break;
      case DeviceActionStatus.Stopped:
        console.log("Action has been cancelled");
        break;
      case DeviceActionStatus.Completed:
        const { output } = state;
        console.log("App opened successfully", output);
        break;
      case DeviceActionStatus.Error:
        const { error } = state;
        console.error("An error occurred during the action", error);
        break;
    }
  },
  error: (error) => {
    console.error("Subscription error:", error);
  },
  complete: () => {
    console.log("Device action complete");
  },
});

// If you need to cancel the action
// cancel();
```

## What you've learned

In this tutorial, you've learned how to:

- Send low-level APDU commands to a Ledger device
- Use pre-defined commands for common operations
- Work with device actions for complex flows
- Handle user interactions during device communication

## Next steps

- Check out the [sample app](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/apps/sample) a comprehensive demonstration of the Device Management Kit's capabilities in a React application.
- Learn how to [build custom commands](../integration/how_to/build_custom_command) for specific applications

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/beginner/init_dmk -->

---
title: "Initializing and Configuring the DMK"
category: tutorial
---

# Initializing and Configuring the DMK

In this guide, you'll learn how to initialize and configure the Device Management Kit (DMK) for your application. By the end, you'll have a working DMK instance that's ready to interface with hardware devices.

## What you'll learn

- How to set up the DMK in your project
- How to configure loggers and transports
- How to maintain the DMK instance as a singleton

## Step 1: Install the required packages

First, you'll need to install the Device Management Kit and related packages:

```bash
npm install @ledgerhq/device-management-kit @ledgerhq/device-transport-kit-web-hid
```

## Step 2: Create the DMK configuration

> Important: Make sure the DMK instance is properly initialized with at least one transport. The transport is what enables communication with the device. Without it, none of the data exchange commands in this example will work.

In this example, to initialize the DMK, we'll create a new file called `dmk.ts`:

```ts
import {
  ConsoleLogger,
  DeviceManagementKitBuilder,
} from "@ledgerhq/device-management-kit";
import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";

// Initialize the DMK with a console logger and WebHID transport
export const dmk = new DeviceManagementKitBuilder()
  .addLogger(new ConsoleLogger())
  .addTransport(webHidTransportFactory) // Transport is required!
  .build();
```

This code sets up the DMK with:

- A console logger that will output information to your browser's console
- The WebHID transport, which allows communication with hardware devices via the browser's WebHID API

## Step 3: Use the DMK instance

Import the DMK instance in any file where you need to interact with devices:

```ts
import { dmk } from "./dmk";

// Now you can use the DMK for device operations
async function connectToDevice() {
  const subscription = dmk.listenToAvailableDevices().subscribe({
    next: (devices) => {
      // Handle the available devices here
      console.log("Available devices:", devices);
    },
    error: (error) => {
      console.error("Error:", error);
    },
    complete: () => {
      console.log("Completed");
    },
  });

  // Stop listening to available devices
  subscription.unsubscribe();
}
```

> Important: The DMK should be initialized only once in your application. Always import the same instance rather than creating multiple instances.

## What you've learned

Congratulations! You've now:

- Set up a working DMK instance
- Configured it with a logger and transport
- Learned how to maintain it as a singleton
- Know how to import and use it in your application

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/beginner/setup -->

---
title: "Setup"
category: tutorial
---

# Setup

## What is the DMK?

This package contains the core of the Device Management Kit (DMK). It provides a simple interface to handle Ledger devices and features the Device Management Kit's entry points, classes, types, structures, and models.

## Installation

Add the DMK to your project with this command:

```sh
npm install @ledgerhq/device-management-kit
```

## Browser Compatibility

This library is compatible with any browser that supports the [WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility).

## Understanding RxJS: A Quick Primer

The DMK uses [RxJS](https://rxjs.dev/) to handle asynchronous operations. If you're new to RxJS, here's what you need to know:

1. **Observables**: Most DMK functions return "Observables" instead of Promises
2. **Subscription**: You need to "subscribe" to an Observable to get its data

Basic example:

```ts
dmk.someFunction().subscribe({
  next: (data) => console.log("Data received:", data),
  error: (error) => console.error("Error:", error),
  complete: () => console.log("Operation completed"),
});
```

## What's Next?

Now that you have the DMK installed, proceed to the next guide to learn how to initialize it in your application.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/explanation/introduction -->

---
title: "Why choose the Device Management Kit?"
category: explanation
---

# Why choose the Device Management Kit?

The Device Management Kit (DMK) offers a comprehensive suite of tools and libraries tailored for secure and efficient management of Ledger devices. It is specifically crafted for external developers to enhance the experience of interacting with Ledger hardware securely.

## Seamless Integration with Device Signer Kit

The DMK works seamlessly with the Device Signer Kit, providing a robust ecosystem for secure transaction signing. This integration ensures that developers have access to comprehensive tools for both device management and transaction handling.

## Developer-Centric Design

The DMK is purpose-built for developers, focusing on simplifying interactions with Ledger devices. By providing an intuitive and straightforward API, the DMK abstracts much of the underlying complexity involved in device communication, empowering developers to integrate Ledger functionalities with ease.

## Simplified Device Interaction

One of the core objectives of the DMK is to remove the complexities associated with device communication. Its user-friendly API is designed to provide a simple and efficient way to manage Ledger hardware, allowing developers to focus on building applications rather than dealing with low-level device interactions.

## Future-Proof Solution

The DMK is intended to replace existing LedgerJS libraries, such as `hw-app-XXX` and `transport-XXX`. As these older libraries are set to be deprecated, adopting the DMK represents a forward-looking solution that aligns with Ledger's evolving technology stack, preparing developers for future updates and innovations.

By choosing the Device Management Kit, developers can leverage a powerful, secure, and developer-focused toolkit that simplifies the integration with Ledger devices and supports the secure signing of transactions.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/explanation/ledgerjs -->

---
title: "Differences with LedgerJS"
category: explanation
---

# Differences with LedgerJS

The Device Management Kit (DMK) is designed to replace the existing LedgerJS libraries, including the `hw-app-XXX` and `hw-transport-XXX` series.

## Legacy Challenges

The LedgerJS libraries were originally developed to support **Ledger Live** applications. Given that Ledger Live has been evolving for over seven years, the libraries have accumulated technical debt over this extensive period. Consequently, some components of the libraries have grown more complex, making them challenging to maintain and extend.

A few behaviors in the device libraries do not align perfectly with expected outcomes. For example, the act of opening an application on the device might lead to unanticipated disconnections.

Additionally, feedback from our partners, including software wallet developers, indicates that the libraries could benefit from enhanced simplicity and a reduction in the need for low-level programming knowledge (such as understanding the APDU communication protocol).

## Target Audience

While LedgerJS was primarily designed for use with Ledger Live, the Device Management Kit is specifically tailored to prioritize the needs of **third-party developers**.

## Simplifying Interactions

Our goal with the DMK is to significantly lower the barrier for developers interacting with Ledger devices.
By abstracting much of the underlying complexity, the DMK provides a straightforward and user-friendly API, facilitating easier integration.

## Support for Multiple Devices

LedgerJS restricted simultaneous connections to multiple devices. In contrast, the DMK introduces the ability to connect and interact with multiple devices concurrently, enhancing multi-device management capabilities.

## When to Use LedgerJS Instead of DMK

While the DMK offers advanced features, there are certain scenarios where LedgerJS may still be necessary due to current feature gaps in the DMK.
For example, the DMK is still expanding its support for signers specific to certain blockchains. In such cases, continuing to use LedgerJS for transaction signing might be beneficial.
We are actively working on solutions to bridge these gaps and improve compatibility between the DMK and LedgerJS.

In summary, the DMK represents a modern solution tailored to current development needs, with a focus on ease of use and expanded functionality.
As we continue to enhance its features, we are committed to maintaining compatibility with existing solutions.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/explanation/signers -->

---
title: "Understanding Device Signer Kits"
category: explanation
---

# Understanding Device Signer Kits

Device Signer Kits represent a fundamental architectural choice in how developers interact with Ledger hardware devices across different blockchain ecosystems. To understand their importance, it's helpful to first consider the challenges they address and the conceptual model they implement.

## The Challenge: Bridging Hardware and Software

Ledger devices operate as secure, air-gapped hardware designed to protect cryptographic keys and sign transactions. However, this security comes with complexity: each blockchain has its own transaction formats, signing algorithms, and communication protocols. Without Device Signer Kits, developers would need to:

- Understand the low-level USB/Bluetooth communication protocols with Ledger devices
- Handle blockchain-specific transaction serialization formats
- Manage the intricacies of each Ledger embedded app's API
- Deal with device state management and error handling
- Implement proper security practices for each blockchain

This creates significant friction and potential security vulnerabilities, especially as applications need to support multiple blockchains.

## The Conceptual Model: Abstraction Through Specialization

Device Signer Kits implement a deliberate design philosophy: **specialized abstraction**. Rather than creating a single, monolithic interface that attempts to handle all blockchains, the architecture embraces the reality that different blockchains have fundamentally different models for transactions, addresses, and signing.

Each Device Signer Kit operates as a dedicated bridge between:

- **The universal interface**: A consistent, developer-friendly API that follows common patterns
- **The specific reality**: The unique requirements and constraints of a particular blockchain and its corresponding Ledger embedded app

This approach acknowledges that while the _process_ of signing can be standardized (connect, prepare transaction, sign, broadcast), the _details_ vary significantly between blockchains.

## Why This Architecture Matters

### Security Through Specialization

Each signer kit is purpose-built for its target blockchain, allowing for:

- **Validation**: Blockchain-specific transaction validation before sending to the device
- **Error handling**: Meaningful error messages that relate to the specific blockchain context
- **Best practices**: Built-in implementation of security patterns specific to each blockchain

### Developer Experience Through Consistency

Despite their specialization, all signer kits follow consistent patterns:

- **Uniform APIs**: Similar method names and interaction patterns across different blockchains
- **Predictable behavior**: Consistent error handling and state management
- **Shared concepts**: Common abstractions for devices, connections, and signing flows

### Maintainability Through Separation

The modular approach provides:

- **Independent evolution**: Each kit can evolve with its blockchain without affecting others
- **Clear responsibilities**: Well-defined boundaries between blockchain-specific and universal concerns
- **Reduced complexity**: Developers only need to understand the kits relevant to their use case

## The Ecosystem Integration

Device Signer Kits don't exist in isolation—they're part of a broader ecosystem:

**Ledger Embedded Apps** run on the hardware device itself, implementing the cryptographic operations and security policies for each blockchain. These apps are developed and audited by Ledger, ensuring security standards.

**Device Signer Kits** act as the software counterpart, translating between application needs and embedded app capabilities. They handle the communication protocol, data formatting, and provide the developer-facing API.

**Your Application** uses the appropriate signer kit(s) to interact with user devices, focusing on application logic rather than hardware integration details.

## Available Implementations

The current signer kit ecosystem includes:

- **Ethereum Signer Kit** (`signer-kit-eth`): Designed for EVM-compatible blockchains, handling gas estimation, transaction types, and Ethereum-specific address formats
- **Solana Signer Kit**: Specialized for Solana's unique transaction model, including program interactions and account structures
- **Bitcoin Signer Kit**: Focused on UTXO-based transaction models and Bitcoin's specific signing requirements

Each implementation reflects the distinct characteristics of its target blockchain while maintaining the consistent developer experience that makes the overall architecture successful.

## Design Principles and Benefits

This architectural approach reflects several key design principles:

**Specialization enables excellence**: By focusing each kit on a specific blockchain, we can provide APIs that feel natural to developers familiar with that ecosystem, while implementing blockchain-specific optimizations and best practices.

**Embracing blockchain diversity** allows each kit to leverage the unique strengths of its target blockchain rather than forcing a lowest-common-denominator approach. This results in more intuitive APIs and better error messages that speak the language of each blockchain community.

**Security through purpose-built design** means each kit can implement the exact validation rules, transaction formats, and safety checks appropriate for its blockchain, providing stronger guarantees than a generic solution could offer.

This design philosophy ensures that Device Signer Kits provide both the consistency developers expect from a unified SDK and the specialized capabilities needed to excel in each blockchain ecosystem.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/index -->

# TypeScript DMK

The TypeScript DMK is a collection of libraries that allow you to interact with Ledger devices using TypeScript.

# Platforms

The TypeScript DMK is available for the following platforms:

- Web
- React Native
- Node.js

You just need to import the right transport library for your platform.

# Libraries

Here you can find a summary of all the libraries that compose the TypeScript DMK.

## Device Management Kit (DMK)

| Device Management Kit (DMK) | NPM                                                                                              | Version |
| --------------------------- | ------------------------------------------------------------------------------------------------ | ------- |
| Device Management Kit       | [@ledgerhq/device-management-kit](https://www.npmjs.com/package/@ledgerhq/device-management-kit) | 1.9.0   |
| Ledger Wallet               | [@ledgerhq/dmk-ledger-wallet](https://www.npmjs.com/package/@ledgerhq/dmk-ledger-wallet)         | 0.5.0   |

## Signers & Trusted App Kit

| Signers & Trusted App Kit | NPM                                                                                                                                                | Version |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Device Signer Ethereum    | [@ledgerhq/device-signer-kit-ethereum](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-ethereum)                                         | 1.18.0  |
| Device Signer Bitcoin     | [@ledgerhq/device-signer-kit-bitcoin](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-bitcoin)                                           | 1.3.3   |
| Device Signer Solana      | [@ledgerhq/device-signer-kit-solana](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-solana)                                             | 1.13.0  |
| Device Signer Cosmos      | [@ledgerhq/device-signer-kit-cosmos](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-cosmos)                                             | 1.0.1   |
| Device Signer Hyperliquid | [@ledgerhq/device-signer-kit-hyperliquid](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-hyperliquid)                                   | 1.1.0   |
| Device Signer Zcash       | [@ledgerhq/device-signer-kit-zcash](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-zcash)                                               | 0.7.0   |
| Device Signer ICP         | [@ledgerhq/device-signer-kit-icp](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-icp)                                                   | 0.2.0   |
| Device Signer Concordium  | [@ledgerhq/device-signer-kit-concordium](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-concordium)                                     | 0.5.0   |
| Device Signer Aleo        | [@ledgerhq/device-signer-kit-aleo](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-aleo)                                                 | 0.4.0   |
| Device Signer Polkadot    | [@ledgerhq/device-signer-kit-polkadot](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-polkadot)                                         | 0.2.0   |
| Device Signer Tron        | [@ledgerhq/device-signer-kit-tron](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-tron)                                                 | 0.2.0   |
| Device Signer XRP         | [@ledgerhq/device-signer-kit-xrp](https://www.npmjs.com/package/@ledgerhq/device-signer-kit-xrp)                                                   | 0.2.0   |
| Trusted App Ledger Sync   | [@ledgerhq/device-trusted-app-kit-ledger-keyring-protocol](https://www.npmjs.com/package/@ledgerhq/device-trusted-app-kit-ledger-keyring-protocol) | 0.5.0   |
| Context Module            | [@ledgerhq/context-module](https://www.npmjs.com/package/@ledgerhq/context-module)                                                                 | 2.5.0   |
| Device Contacts Kit       | [@ledgerhq/device-contacts-kit](https://www.npmjs.com/package/@ledgerhq/device-contacts-kit)                                                       | 0.4.0   |

| Transports                 | NPM                                                                                                                              | Version |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Web HID Transport          | [@ledgerhq/device-transport-kit-web-hid](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-web-hid)                   | 1.2.4   |
| Web BLE Transport          | [@ledgerhq/device-transport-kit-web-ble](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-web-ble)                   | 1.3.2   |
| React Native BLE Transport | [@ledgerhq/device-transport-kit-react-native-ble](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-react-native-ble) | 1.3.2   |
| React Native HID Transport | [@ledgerhq/device-transport-kit-react-native-hid](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-react-native-hid) | 1.0.4   |
| Node HID Transport         | [@ledgerhq/device-transport-kit-node-hid](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-node-hid)                 | 1.0.0   |
| Speculos Transport         | [@ledgerhq/device-transport-kit-speculos](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-speculos)                 | 1.2.1   |
| Speculos Device Controller | [@ledgerhq/speculos-device-controller](https://www.npmjs.com/package/@ledgerhq/speculos-device-controller)                       | 0.3.0   |

| DevTools                     | NPM                                                                                                                                                        | Version |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| DevTools Core                | [@ledgerhq/device-management-kit-devtools-core](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-core)                               | 1.1.1   |
| DevTools UI                  | [@ledgerhq/device-management-kit-devtools-ui](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-ui)                                   | 1.1.1   |
| DevTools Rozenite            | [@ledgerhq/device-management-kit-devtools-rozenite](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-rozenite)                       | 0.1.1   |
| DevTools Websocket Common    | [@ledgerhq/device-management-kit-devtools-websocket-common](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-websocket-common)       | 1.0.2   |
| DevTools Websocket Connector | [@ledgerhq/device-management-kit-devtools-websocket-connector](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-websocket-connector) | 1.1.1   |
| DevTools Websocket Server    | [@ledgerhq/device-management-kit-devtools-websocket-server](https://www.npmjs.com/package/@ledgerhq/device-management-kit-devtools-websocket-server)       | 1.0.1   |

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/how_to/build_custom_command -->

---
title: "Build a Custom Command"
category: how-to
---

# Build a Custom Command

You can build your own command simply by extending the `Command` class and implementing the `getApdu` and `parseResponse` methods.

Then you can use the `sendCommand` method to send it to a connected device.

This is strongly recommended over direct usage of `sendApdu`.

## Prerequisites

Before building custom commands, ensure you have:

- Device Management Kit v1.0.0 or higher
- Understanding of APDU protocol basics
- A connected device session (see [Getting Started](../../getting-started))

## Quick Example

Here's a complete example of a custom command:

```typescript
import {
  Command,
  CommandResult,
  CommandResultFactory,
  CommandUtils,
  GlobalCommandErrorHandler,
  ApduBuilder,
  ApduBuilderArgs,
  ApduParser,
  ApduResponse,
  InvalidStatusWordError,
} from "@ledgerhq/device-management-kit";

export interface MyCustomCommandArgs {
  customParam: number;
}

export interface MyCustomResponse {
  customAttributes1: number;
  customAttributes2: string;
}

export class MyCustomCommand
  implements Command<MyCustomResponse, MyCustomCommandArgs>
{
  args: MyCustomCommandArgs;

  constructor(args: MyCustomCommandArgs) {
    this.args = args;
  }

  getApdu(): Apdu {
    // Main args for the APDU
    const apduArgs: ApduBuilderArgs = {
      cla: 0xe0, // Command CLA
      ins: 0x02, // Command INS
      p1: 0x00, // Parameter P1
      p2: 0x00, // Parameter P2
    };

    // Add the data attached to the APDU with the builder
    const builder = new ApduBuilder(apduArgs);
    builder.add32BitUIntToData(this.args.customParam);

    return builder.build();
  }

  parseResponse(response: ApduResponse): CommandResult<MyCustomResponse> {
    // Create Apdu Parser
    const parser = new ApduParser(response);

    // FIRST: check status word
    if (!CommandUtils.isSuccessResponse(response)) {
      return CommandResultFactory({
        error: GlobalCommandErrorHandler.handle(response),
      });
    }

    // Extract fields from the response
    const customAttributes1 = parser.extract8BitUInt();
    if (customAttributes1 === undefined) {
      return CommandResultFactory({
        error: new InvalidStatusWordError("Custom attribute 1 is missing"),
      });
    }

    const customAttributes2 = parser.encodeToString(
      parser.extractFieldLVEncoded(),
    );
    if (!customAttributes2) {
      return CommandResultFactory({
        error: new InvalidStatusWordError("Custom attribute 2 is missing"),
      });
    }

    return CommandResultFactory({
      data: {
        customAttributes1,
        customAttributes2,
      },
    });
  }
}
```

## Usage

Once you've created your custom command, use it with the Device Management Kit:

```typescript
import { MyCustomCommand } from "./MyCustomCommand";

// Create and send your custom command
const command = new MyCustomCommand({ customParam: 42 });

const result = await dmk.sendCommand({
  sessionId,
  command,
});

if (result.isSuccess()) {
  console.log("Custom attributes:", result.data);
} else {
  console.error("Command failed:", result.error);
}
```

## ApduBuilder Usage

The `ApduBuilder` class helps you construct APDU commands with proper data encoding:

```typescript
const builder = new ApduBuilder({
  cla: 0xe0,
  ins: 0x02,
  p1: 0x00,
  p2: 0x00,
});

// Add different data types
builder.add8BitUIntToData(0x01); // Single byte
builder.add16BitUIntToData(0x1234); // Two bytes
builder.add32BitUIntToData(0x12345678); // Four bytes
builder.addHexaStringToData("deadbeef"); // Hex string
builder.addAsciiStringToData("hello"); // ASCII string
builder.addBufferToData(buffer); // Raw buffer

const apdu = builder.build();
```

### Available Builder Methods

| Method                       | Description        | Example                                            |
| ---------------------------- | ------------------ | -------------------------------------------------- |
| `add8BitUIntToData(value)`   | Add single byte    | `builder.add8BitUIntToData(255)`                   |
| `add16BitUIntToData(value)`  | Add 2-byte integer | `builder.add16BitUIntToData(65535)`                |
| `add32BitUIntToData(value)`  | Add 4-byte integer | `builder.add32BitUIntToData(0xFFFFFFFF)`           |
| `addHexaStringToData(hex)`   | Add hex string     | `builder.addHexaStringToData("deadbeef")`          |
| `addAsciiStringToData(text)` | Add ASCII text     | `builder.addAsciiStringToData("hello")`            |
| `addBufferToData(buffer)`    | Add raw buffer     | `builder.addBufferToData(new Uint8Array([1,2,3]))` |

## ApduParser Usage

The `ApduParser` class helps you extract data from APDU responses:

```typescript
const parser = new ApduParser(response);

// Extract different data types
const byte = parser.extract8BitUInt();
const short = parser.extract16BitUInt();
const int = parser.extract32BitUInt();

// Extract fields by length
const fixedField = parser.extractFieldByLength(32);

// Extract length-value encoded fields
const lvField = parser.extractFieldLVEncoded();

// Convert to different formats
const hexString = parser.encodeToHexaString(field);
const asciiString = parser.encodeToString(field);
```

### Available Parser Methods

| Method                         | Description                | Returns                   |
| ------------------------------ | -------------------------- | ------------------------- |
| `extract8BitUInt()`            | Extract 1-byte integer     | `number \| undefined`     |
| `extract16BitUInt()`           | Extract 2-byte integer     | `number \| undefined`     |
| `extract32BitUInt()`           | Extract 4-byte integer     | `number \| undefined`     |
| `extractFieldByLength(length)` | Extract fixed-length field | `Uint8Array \| undefined` |
| `extractFieldLVEncoded()`      | Extract length-value field | `Uint8Array \| undefined` |
| `encodeToHexaString(field)`    | Convert to hex string      | `string`                  |
| `encodeToString(field)`        | Convert to ASCII string    | `string`                  |

## Error Handling and Troubleshooting

### Common Error Patterns

Always implement proper error handling in your `parseResponse` method:

```typescript
parseResponse(response: ApduResponse): CommandResult<MyResponse> {
  const parser = new ApduParser(response);

  // 1. Check status word first
  if (!CommandUtils.isSuccessResponse(response)) {
    return CommandResultFactory({
      error: GlobalCommandErrorHandler.handle(response),
    });
  }

  // 2. Validate extracted fields
  const field = parser.extract8BitUInt();
  if (field === undefined) {
    return CommandResultFactory({
      error: new InvalidStatusWordError("Required field is missing"),
    });
  }

  // 3. Check remaining data length
  if (parser.getUnparsedRemainingLength() < expectedLength) {
    return CommandResultFactory({
      error: new InvalidStatusWordError("Insufficient response data"),
    });
  }

  return CommandResultFactory({ data: { field } });
}
```

### Common Error Codes

| Status Code | Error Type           | Description           | Solution                  |
| ----------- | -------------------- | --------------------- | ------------------------- |
| `5515`      | DeviceLockedError    | Device is locked      | Ask user to unlock device |
| `5501`      | ActionRefusedError   | User refused action   | Retry or inform user      |
| `5502`      | PinNotSetError       | PIN not set           | Guide user to set PIN     |
| `6e00`      | CLA not supported    | Invalid command class | Check your CLA value      |
| `6d00`      | INS not supported    | Invalid instruction   | Check your INS value      |
| `6a86`      | Incorrect parameters | Invalid P1/P2         | Verify parameter values   |

### Debugging Tips

1. **Enable Logging**: Use the logger to debug command execution:

   ```typescript
   // The SDK automatically logs APDU exchanges when in development mode
   ```

2. **Validate APDU Construction**: Check your APDU before sending:

   ```typescript
   const apdu = builder.build();
   console.log("APDU:", apdu.getRawApdu());
   ```

3. **Check Response Length**: Ensure you're not reading beyond the response:
   ```typescript
   const parser = new ApduParser(response);
   console.log("Response length:", response.data.length);
   console.log("Remaining:", parser.getUnparsedRemainingLength());
   ```

### Custom Error Types

For app-specific errors, create custom error types:

```typescript
export type MyCommandErrorCodes = "custom_error_1" | "custom_error_2";

export const MY_COMMAND_ERRORS = {
  "6f01": { message: "Custom error 1", tag: "CustomError1" },
  "6f02": { message: "Custom error 2", tag: "CustomError2" },
} as const;

export class MyCommandError extends DeviceExchangeError<MyCommandErrorCodes> {
  constructor(args: CommandErrorArgs<MyCommandErrorCodes>) {
    super(args);
  }
}

// In your parseResponse method:
if (!CommandUtils.isSuccessResponse(response)) {
  const errorCode = parser.encodeToHexaString(response.statusCode);
  if (isCommandErrorCode(errorCode, MY_COMMAND_ERRORS)) {
    return CommandResultFactory({
      error: new MyCommandError({
        ...MY_COMMAND_ERRORS[errorCode],
        errorCode,
      }),
    });
  }
  return CommandResultFactory({
    error: GlobalCommandErrorHandler.handle(response),
  });
}
```

## Examples and References

### Built-in Command Examples

Study these existing commands for reference:

- [`ListAppsCommand`](https://github.com/LedgerHQ/device-sdk-ts/blob/main/packages/device-management-kit/src/api/command/os/ListAppsCommand.ts) - Simple command with parsing
- [`GetOsVersionCommand`](https://github.com/LedgerHQ/device-sdk-ts/blob/main/packages/device-management-kit/src/api/command/os/GetOsVersionCommand.ts) - Complex response parsing
- [`OpenAppCommand`](https://github.com/LedgerHQ/device-sdk-ts/blob/main/packages/device-management-kit/src/api/command/os/OpenAppCommand.ts) - Command with parameters

### Sample Applications

See complete implementations in:

- [Sample App](https://github.com/LedgerHQ/device-sdk-ts/tree/main/apps/sample) - Web-based example
- [Mobile App](https://github.com/LedgerHQ/device-sdk-ts/tree/main/apps/mobile) - React Native example

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/how_to/dmk -->

---
title: "Device Management Kit"
category: how-to
---

# Device Management Kit

The device management kit is the entry point for all the other libraries related to it.
As we wanted to make the project modular.

## Main Features

- Discovering and connecting to Ledger devices via USB, through [WebHID](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API).
- Discovering and connecting to Ledger devices via BLE, through [WebBLE](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API).
- Observing the state of a connected device.
- Sending custom APDU commands to Ledger devices.
- Sending a set of pre-defined commands to Ledger devices.
  - Get OS version
  - Get app and version
  - Open app
  - Close app
  - Get battery status
- Execute a flow of commands with **DeviceAction**.

> \[!NOTE]
> At the moment we do not provide the possibility to distinguish two devices of the same model, via WebHID and to avoid connection to the same device twice.

## Connection Management

### Reconnect Device Session

The `reconnect` method allows you to refresh a device connection by disconnecting and reconnecting to the device. This is useful when you need to refresh the connection state or reconfigure session refresher options.

**Parameters**:

- `device`: ConnectedDevice - The connected device to reconnect (obtained from `getConnectedDevice`).
- `sessionRefresherOptions`: (optional) Configuration for session refreshing.
  - `isRefresherDisabled`: boolean - Whether the refresher is disabled.
  - `pollingInterval`: number - The refresh interval in milliseconds.

```typescript
// Get the connected device
const connectedDevice = dmk.getConnectedDevice({ sessionId });

// Reconnect the device session
// newSessionId = sessionId
const newSessionId = await dmk.reconnect({
  device: connectedDevice,
  sessionRefresherOptions: {
    isRefresherDisabled: false,
    pollingInterval: 3000,
  },
});
```

## Communicate with a Ledger device

The DMK is offering several ways to communicate with a Ledger device.

### Send APDU

> **Warning:** This method is not recommended for most of the use cases. We recommend using
> the _Command_ or _DeviceAction_ instead.

You can send APDU commands to the device using the `sendApdu` method of the Device Management Kit instance (here `dmk`) instance.

**Parameters**:

- `sessionId`: string - The session ID, identifier of the connection with a device.
- `apdu`: UInt8Array - bytes array of data to be send to the device.

```typescript
await dmk.sendApdu({ sessionId, apdu });
```

### Commands

Commands are pre-defined actions that you can send to the device.
You can use the `sendCommand` method of the `dmk` instance to send a command to the device.

**Parameters**:

- `sessionId`: string - The session ID, which an identifier of the connection with a device.
- `command`: Command - The command to be sent to the device.
- `abortTimeout`: number - (optional) The timeout to abort the command (in milliseconds).

```typescript
import { OpenAppCommand } from "@ledgerhq/device-management-kit";

const command = new OpenAppCommand("Bitcoin"); // Open the Bitcoin app
await dmk.sendCommand({ sessionId, command });

// You can also send the command with a timeout to abort the command if it takes too long (in milliseconds)
await dmk.sendCommand({ sessionId, command, abortTimeout: 10000 });

// If the command times out, sendCommand will throw a SendApduTimeoutError
```

### Device Actions

Device actions are a set of commands that are executed in a sequence.
You can use the `executeDeviceAction` method of the `dmk` instance to execute a device action.

It is returning an observable that will emit different states of the action execution.
A device action is cancellable, you can cancel it by calling the `cancel` function returned by the `executeDeviceAction` method.

**Parameters**:

- `sessionId`: string - The session ID, which an identifier of the connection with a device.
- `deviceAction`: DeviceAction - The DeviceAction to be sent to the device.

```typescript
const openAppDeviceAction = new OpenAppDeviceAction({ appName: "Bitcoin" });

const { observable, cancel } = await dmk.executeDeviceAction({
  sessionId,
  openAppDeviceAction,
});
```

## State Management

For each connected device, we are managing and providing a device state.

The different states are:

- `connected`: The device is connected.
- `locked`: The device is locked. User needs to unlock it to perform operations.
- `busy`: The device is busy, so not reachable.
- `disconnected`: The device is disconnected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/how_to/how_to_use_a_signer -->

---
title: "Use a signer"
category: how-to
---

# Use a signer

As ledger devices are able to install applications that will allow to be compatible with different blockchains,
we have created these kits.

Each **signer kit** is coming along with a Ledger Embedded App (ex: _signer-kit-eth_ is coming with _ledger app ethereum_ ).

The main goal of each signer is to ease interaction with the app in the most seamless way possible.

> **Note:** We will show the usage of the signer with the Ethereum signer.
> The same logic can be applied to the other signers.

## Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-ethereum` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-ethereum
```

## Usage

To initialize an Ethereum signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerEthBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:

```typescript
// Initialize an Ethereum signer instance using default context module
const signerEth = new SignerEthBuilder({
  dmk,
  sessionId,
  originToken: "origin-token",
}).build();
```

> **Note:** The `originToken` parameter is required by the default context module to work.
> Token should be delivered by Ledger, otherwise the Transactions Checks will not be available.

You can also configure the context module yourself:

```typescript
// Initialize an Ethereum signer instance using customized context module
const signerEth = new SignerEthBuilder({ dmk, sessionId })
  .withContextModule(customContextModule)
  .build();
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/how_to/transports -->

---
title: "Transports"
category: how-to
---

# Transports

The Device Management Kit is offering several transports to communicate with a Ledger device.
Depending on the environment and usecase, you can choose the transport that best suits your needs.

## Available transports

| Transport                                                                               | Description                                                                                                   |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [Web HID](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-web-hid)         | The WebHID transport uses the Web HID API (usb) to communicate with a Ledger device.                          |
| [Web BLE](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-web-ble)         | The WebBLE transport uses the Web BLE API (bluetooth) to communicate with a Ledger device.                    |
| [RN HID](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-react-native-hid) | The React Native HID transport uses the react-native (usb) to communicate with a Ledger device.               |
| [RN BLE](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-react-native-ble) | The React Native BLE transport uses the react-native-ble-plx (bluetooth) to communicate with a Ledger device. |
| [Node HID](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-node-hid)       | The Node HID transport uses the node-hid library (usb) to communicate with a Ledger device.                   |
| [Speculos](https://www.npmjs.com/package/@ledgerhq/device-transport-kit-speculos)       | The Speculos transport is used to communicate with the speculos device simulator.                             |

## How to use a transport

Transports are injected in the DeviceManagementKitBuilder before building the Device Management Kit instance.
This is done by calling the `addTransport` method on the builder.
You can inject the transport in two different ways:

- Using the default transport factory provided by the package
- Using directly the transport creating your own factory (for custom transports or additional configuration...)

```typescript
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import { WebHidTransport, webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";

// Using the default transport factory
const dmk = new DeviceManagementKitBuilder()
  .addTransport(webHidTransportFactory)
  .build();

// Using the transport directly
const dmk = new DeviceManagementKitBuilder()
  .addTransport(({
    deviceModelDataSource: DeviceModelDataSource;
    loggerServiceFactory: (tag: string) => LoggerPublisherService;
    config: DmkConfig;
    apduSenderServiceFactory: ApduSenderServiceFactory;
    apduReceiverServiceFactory: ApduReceiverServiceFactory;
  }) => {
    // Some extra code here to configure the transport
    // Then we return the transport instance
    return new WebHidTransport(
      deviceModelDataSource,
      loggerServiceFactory,
      config,
      apduSenderServiceFactory,
      apduReceiverServiceFactory,
    );
  })
  .build();
```

## How to use the Speculos transport

The Speculos transport is used to communicate with the speculos device simulator.
The factory function accepts a `speculosUrl` parameter that is the url of the speculos server.

```typescript
const dmk = new DeviceManagementKitBuilder()
  .addTransport(speculosTransportFactory("http://localhost:5000"))
  .build();
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/dmk/05_to_06 -->

---
title: "Migration from 0.5.0 to 0.6.0"
category: how-to
---

# Migration from 0.5.0 to 0.6.0

We made some breaking changes to the Device Management Kit in 0.6 which are detailed below.

## Transports

The transports implementation have been moved to their own packages.

- `@ledgerhq/device-transport-kit-web-hid`
- `@ledgerhq/device-transport-kit-web-ble`

To use a transport, you need to install the corresponding package and inject it in the DeviceManagementKit.

**DMK v0.5**

Transports were built-in the DeviceManagementKit.

```typescript
import {
  DeviceManagementKitBuilder,
  ConsoleLogger,
} from "@ledgerhq/device-management-kit";

const dmk = new DeviceManagementKitBuilder()
  .addLogger(new ConsoleLogger())
  .build();
```

**DMK v0.6**

In v0.6, you need to manually inject the transport you want to use.

```typescript
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();
```

```diff
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();
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/dmk/0_6_1_to_0_6_2 -->

---
title: "Migration from 0.6.1 to 0.6.2"
category: how-to
---

# Migration from 0.6.1 to 0.6.2

This guide walks you through migrating your Device Management Kit integration from version 0.6.1 to 0.6.2.

## Before you start

Ensure you have the following minimum transport versions:

- `@ledgerhq/device-transport-kit-web-hid`: `>= 1.1.0`
- `@ledgerhq/device-transport-kit-web-ble`: `>= 1.1.0`

## Step 1: Update device discovery method

The `listenToKnownDevices` method has been replaced with `listenToAvailableDevices`, which now includes additional functionality like RSSI field support and transport scoping.

### Before (v0.6.1)

```typescript
// This method no longer exists
dmk.listenToKnownDevices().subscribe((devices) => {
  console.log("Discovered devices:", devices);
});
```

### After (v0.6.2)

```typescript
// Listen to all available devices from all transports
dmk.listenToAvailableDevices({}).subscribe((devices) => {
  console.log("Available devices:", devices);
  // Each device now includes an rssi field for BLE devices
});

// Or scope to a specific transport
dmk.listenToAvailableDevices({ transport: "web-hid" }).subscribe((devices) => {
  console.log("Web HID devices:", devices);
});
```

## Step 2: Update session refresher control

The `toggleDeviceSessionRefresher` method has been replaced with `disableDeviceSessionRefresher`, which provides more granular control and returns a function to re-enable the refresher.

### Before (v0.6.1)

```typescript
// This method no longer exists
dmk.toggleDeviceSessionRefresher(sessionId, isDisabled);
```

### After (v0.6.2)

```typescript
// Disable the refresher and get a function to re-enable it
const enableRefresher = dmk.disableDeviceSessionRefresher({
  sessionId: "your-session-id",
  blockerId: "your-unique-blocker-id", // Used to identify this specific disable request
});

// Later, re-enable the refresher when done
enableRefresher();
```

### Example usage

```typescript
async function performLongRunningOperation(sessionId: string) {
  // Disable refresher during the operation
  const enableRefresher = dmk.disableDeviceSessionRefresher({
    sessionId,
    blockerId: "long-operation",
  });

  try {
    // Perform your operation that requires the refresher to be disabled
    await someDeviceOperation();
  } finally {
    // Always re-enable the refresher
    enableRefresher();
  }
}
```

## Step 3: Update your package.json

Update your transport dependencies to the minimum required versions:

```json
{
  "dependencies": {
    "@ledgerhq/device-management-kit": "^0.6.2",
    "@ledgerhq/device-transport-kit-web-hid": "^1.1.0",
    "@ledgerhq/device-transport-kit-web-ble": "^1.1.0"
  }
}
```

## What changed

### Enhanced device discovery

- **New method name**: `listenToAvailableDevices` replaces `listenToKnownDevices`
- **Transport scoping**: You can now limit discovery to specific transports
- **RSSI support**: BLE devices now include signal strength information
- **Improved reliability**: Better handling of multiple transport scenarios

### Improved refresher control

- **New method name**: `disableDeviceSessionRefresher` replaces `toggleDeviceSessionRefresher`
- **Blocker ID system**: Multiple components can disable the refresher independently
- **Automatic cleanup**: The returned function ensures proper re-enabling
- **Better error handling**: Clearer error messages when sessions are not found

## Troubleshooting

### "listenToKnownDevices is not a function"

Replace all instances of `listenToKnownDevices` with `listenToAvailableDevices({})`.

### "toggleDeviceSessionRefresher is not a function"

Replace `toggleDeviceSessionRefresher` calls with `disableDeviceSessionRefresher` and handle the returned re-enable function.

### Transport compatibility issues

Ensure your transport packages are updated to the minimum required versions listed above.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/ledgerjs-to-dmk -->

---
title: "Migrate from LedgerJS to the DMK"
category: how-to
---

# Migrate from LedgerJS to the DMK

LedgerJS (`hw-transport-*` and `hw-app-*`) is deprecated. Starting in September 2026, it will no longer work with the Ethereum app due to a breaking change in EIP-712 signing. All integrations must move to the [Device Management Kit (DMK)](../../../getting-started).

This guide covers the cross-chain migration steps that apply to every signer: replacing transports, initializing the DMK, connecting to a device, and adapting from a promise-based API to an observable-based one.

For method-by-method API mappings, see the per-chain guides:

- [Ethereum (hw-app-eth → device-signer-kit-ethereum)](./signers/eth/hw_app_eth_to_dmk)
- [Solana (hw-app-solana → device-signer-kit-solana)](./signers/solana/hw_app_solana_to_dmk)

> **Note:** For chains that do not yet have a DMK signer (Algorand, Stellar, Tezos, Tron, XRP, and others), you can still communicate with the device using `dmk.sendCommand()` and `dmk.sendApdu()`. See [Build a custom command](../how_to/build_custom_command).

---

## Step 1: Update your packages

Replace `hw-transport-*` packages with the corresponding DMK transport packages, and `hw-app-*` packages with the corresponding signer kits.

### Transport packages

```diff
- npm install @ledgerhq/hw-transport-webhid
+ npm install @ledgerhq/device-management-kit @ledgerhq/device-transport-kit-web-hid
```

```diff
- npm install @ledgerhq/hw-transport-web-ble
+ npm install @ledgerhq/device-management-kit @ledgerhq/device-transport-kit-web-ble
```

```diff
- npm install @ledgerhq/hw-transport-node-hid
+ npm install @ledgerhq/device-management-kit @ledgerhq/device-transport-kit-node-hid
```

**Full transport package map:**

| LedgerJS                                  | DMK                                               | Factory export            |
| ----------------------------------------- | ------------------------------------------------- | ------------------------- |
| `@ledgerhq/hw-transport-webhid`           | `@ledgerhq/device-transport-kit-web-hid`          | `webHidTransportFactory`  |
| `@ledgerhq/hw-transport-web-ble`          | `@ledgerhq/device-transport-kit-web-ble`          | `webBleTransportFactory`  |
| `@ledgerhq/hw-transport-node-hid`         | `@ledgerhq/device-transport-kit-node-hid`         | `nodeHidTransportFactory` |
| `@ledgerhq/react-native-hw-transport-ble` | `@ledgerhq/device-transport-kit-react-native-ble` | `RNBleTransportFactory`   |

### Signer packages

| LedgerJS                  | DMK                                    |
| ------------------------- | -------------------------------------- |
| `@ledgerhq/hw-app-eth`    | `@ledgerhq/device-signer-kit-ethereum` |
| `@ledgerhq/hw-app-btc`    | `@ledgerhq/device-signer-kit-bitcoin`  |
| `@ledgerhq/hw-app-solana` | `@ledgerhq/device-signer-kit-solana`   |

---

## Step 2: Initialize the DMK

LedgerJS required you to create a transport object directly. The DMK uses a builder instead, and you register transports into it at startup.

### Before

```typescript
import TransportWebHID from "@ledgerhq/hw-transport-webhid";

const transport = await TransportWebHID.create();
```

### After

```typescript
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";

const dmk = new DeviceManagementKitBuilder()
  .addTransport(webHidTransportFactory)
  .build();
```

Build the DMK once at application startup and keep the instance for the lifetime of your app. You can register multiple transports in a single instance.

---

## Step 3: Discover and connect

LedgerJS created a transport for a single device. The DMK uses session-based discovery that can manage multiple devices.

### Before

```typescript
// WebHID: browser prompts the user to pick a device
const transport = await TransportWebHID.create();
// `transport` is ready to use
```

### After

```typescript
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid";

const dmk = new DeviceManagementKitBuilder()
  .addTransport(webHidTransportFactory)
  .build();

// startDiscovering must be called from a user gesture (e.g. a button click)
const sessionId = await new Promise<string>((resolve) => {
  const sub = dmk.startDiscovering({}).subscribe({
    next: async (device) => {
      const id = await dmk.connect({ device });
      sub.unsubscribe();
      resolve(id);
    },
  });
});
```

`sessionId` identifies the connected device for all subsequent calls. Store it alongside your signer instance.

> **Note:** `startDiscovering` for WebHID must be called as a direct result of a user gesture (such as a button `click` event) because browsers require user activation before showing the HID device picker.

---

## Step 4: Create a signer

LedgerJS instantiated the app layer by passing a transport. The DMK uses builder classes that receive the `dmk` instance and `sessionId`.

### Before

```typescript
import Eth from "@ledgerhq/hw-app-eth";

const eth = new Eth(transport);
```

### After

```typescript
import { SignerEthBuilder } from "@ledgerhq/device-signer-kit-ethereum";

const signerEth = new SignerEthBuilder({ dmk, sessionId }).build();
```

**Signer builder reference:**

| Chain    | Builder                                                         | Required arguments                         |
| -------- | --------------------------------------------------------------- | ------------------------------------------ |
| Ethereum | `SignerEthBuilder` from `@ledgerhq/device-signer-kit-ethereum`  | `dmk`, `sessionId`, optional `originToken` |
| Bitcoin  | `SignerBtcBuilder` from `@ledgerhq/device-signer-kit-bitcoin`   | `dmk`, `sessionId`                         |
| Solana   | `SignerSolanaBuilder` from `@ledgerhq/device-signer-kit-solana` | `dmk`, `sessionId`                         |

> **Note:** For the Ethereum signer, `originToken` is optional but required if you want Ledger's Transaction Checks (security service). Contact Ledger to obtain a token for your application.

---

## Step 5: Migrate API calls from promises to observables

Every method in LedgerJS returned a `Promise`. Every method in the DMK returns an object with two properties:

- `observable`: an [RxJS Observable](https://rxjs.dev/guide/observable) that emits [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts) updates
- `cancel`: a function to cancel the in-progress action

```typescript
import { DeviceActionStatus } from "@ledgerhq/device-management-kit";

const { observable, cancel } = signerEth.getAddress("44'/60'/0'/0/0");

observable.subscribe({
  next: (state) => {
    switch (state.status) {
      case DeviceActionStatus.Completed:
        console.log("Address:", state.output.address);
        break;
      case DeviceActionStatus.Error:
        console.error("Error:", state.error);
        break;
      case DeviceActionStatus.Pending:
        // state.intermediateValue.requiredUserInteraction tells you
        // what the user needs to do on the device right now
        break;
    }
  },
});
```

### Optional: wrap observables in promises

If your codebase is heavily promise-based, you can use this helper to keep the call sites familiar while you migrate incrementally:

```typescript
import { type Observable } from "rxjs";
import { DeviceActionStatus } from "@ledgerhq/device-management-kit";

function toPromise<Output>(action: {
  observable: Observable<{ status: string; output?: Output; error?: unknown }>;
}): Promise<Output> {
  return new Promise((resolve, reject) => {
    const sub = action.observable.subscribe({
      next: (state: any) => {
        if (state.status === DeviceActionStatus.Completed) {
          sub.unsubscribe();
          resolve(state.output);
        } else if (state.status === DeviceActionStatus.Error) {
          sub.unsubscribe();
          reject(state.error);
        } else if (state.status === DeviceActionStatus.Stopped) {
          sub.unsubscribe();
          reject(new Error("Action cancelled"));
        }
      },
      error: (err: unknown) => reject(err),
    });
  });
}

// Usage
const { address } = await toPromise(signerEth.getAddress("44'/60'/0'/0/0"));
```

> **Caution:** The `toPromise` wrapper discards intermediate states, including `requiredUserInteraction`. These states are important for building responsive wallet UIs (for example, showing a "Confirm on your Ledger" message). Prefer the full observable subscription for production code.

---

## Key differences to be aware of

### The app opens automatically

In LedgerJS, you had to open the correct coin app on the device yourself before calling any signer method. The DMK signers open the app automatically as part of every operation.

### Transport failures and reconnection

LedgerJS had no reconnection logic. The DMK exposes `dmk.reconnect({ device, sessionId })` and `dmk.getDeviceSessionState({ sessionId })` to monitor and recover from disconnections.

### `rxjs` is a peer dependency

Install it explicitly if it is not already a dependency of your project:

```bash
npm install rxjs
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/signers/context-module/1_17_1_to_2_0_0 -->

# Context Module 1.17.1 → 2.0.0

## Breaking changes

### `setChain()` now required

`ContextModuleBuilder.build()` now throws if `setChain()` has not been called.

Signer builders (`SignerEthBuilder`, `SignerSolanaBuilder`, `SignerConcordiumBuilder`) already call `setChain()` internally — **no change is needed** if you only use those builders with the default context module.

**Who is affected:** any code that calls `new ContextModuleBuilder(...)` directly (for example, to create a custom context module for a specific signer).

#### Before (v1.17.1)

```typescript
import { ContextModuleBuilder } from "@ledgerhq/context-module";

const contextModule = new ContextModuleBuilder({ originToken }).build();
```

#### After (v2.0.0)

Pass the chain that matches your signer using `ContextModuleChainID`:

```typescript
import {
  ContextModuleBuilder,
  ContextModuleChainID,
} from "@ledgerhq/context-module";

// Ethereum signer
const contextModule = new ContextModuleBuilder({ originToken })
  .setChain(ContextModuleChainID.Ethereum)
  .build();

// Solana signer
const contextModule = new ContextModuleBuilder({ originToken })
  .setChain(ContextModuleChainID.Solana)
  .build();

// Concordium signer
const contextModule = new ContextModuleBuilder({ originToken })
  .setChain(ContextModuleChainID.Concordium)
  .build();
```

#### Available chains

| `ContextModuleChainID` | Value          | Signer                    |
| ---------------------- | -------------- | ------------------------- |
| `Ethereum`             | `"ethereum"`   | `SignerEthBuilder`        |
| `Solana`               | `"solana"`     | `SignerSolanaBuilder`     |
| `Concordium`           | `"concordium"` | `SignerConcordiumBuilder` |

#### Error message

If `setChain()` is omitted, `build()` throws:

```
[ContextModuleBuilder] setChain() must be called before build()
```

### `getSolanaContext()` removed from `ContextModule`

The `getSolanaContext()` method has been removed from the `ContextModule` interface and `DefaultContextModule`. Solana context is now fetched through the standard `getContexts()` path like any other chain.

**Who is affected:** any code that calls `contextModule.getSolanaContext()` directly.

#### Before (v1.17.1)

```typescript
const solanaContext = await contextModule.getSolanaContext(transaction);
```

#### After (v2.0.0)

```typescript
const contexts = await contextModule.getContexts(transaction);
```

## What changed

- The context module is now chain-aware at build time. The DI container loads only the factories relevant to the declared chain.
- `ContextModuleChainID` enum is now exported from `@ledgerhq/context-module`.
- Solana and Concordium are now first-class supported chains alongside Ethereum.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/signers/eth/1_1_0_to_1_2_0 -->

---
title: "Migration from 1.1.0 to 1.2.0"
category: how-to
---

# Migration from 1.1.0 to 1.2.0

We made some breaking changes to the Ethereum Signer in 1.2.0 which are detailed below.

## signTransaction

The transaction type has been changed to `Uint8Array` instead of `Transaction` from ethers `v5` or `v6`.

To sign a transaction, you need to serialize it to a `Uint8Array` before calling `signTransaction`.

### From a `string`

You can use the `hexaStringToBuffer` utility from the DeviceManagementKit to convert a hexa string to a `Uint8Array`.

```typescript
const rawTx = hexaStringToBuffer(tx);
if (!rawTx) {
  throw new Error("Invalid transaction format");
}

signer.signTransaction(derivationPath, rawTx, { domain });
```

### From a `Transaction` object from ethers `v6`

You can use the `unsignedSerialized` property from the `Transaction` object
combined with the `hexaStringToBuffer` utility from the DeviceManagementKit to convert a hexa string to a `Uint8Array`.

```typescript
const rawTx = hexaStringToBuffer(tx.unsignedSerialized);
if (!rawTx) {
  throw new Error("Invalid transaction format");
}

signer.signTransaction(derivationPath, rawTx, { domain });
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/signers/eth/1_3_3_to_1_4_0 -->

---
title: "Migration from 1.3.3 to 1.4.0"
category: how-to
---

# Migration from 1.3.3 to 1.4.0

This guide walks you through migrating your Ethereum Signer integration from version 1.3.3 to 1.4.0.

## What changed

Version 1.4.0 introduces a **breaking change**: the `originToken` parameter is now required for the default context module to enable transaction security features like Web3 checks, trusted names, and Solana owner information.

## Before you start

Ensure you have an origin token from Ledger. This token identifies your application when making requests to Ledger's security services.

## Step 1: Update your SignerEthBuilder usage

If you're using `SignerEthBuilder` with the default context module, add the `originToken` parameter to the constructor.

### Before (v1.3.3)

```typescript
const signer = new SignerEthBuilder({
  dmk,
  sessionId,
}).build();
```

### After (v1.4.0)

```typescript
const signer = new SignerEthBuilder({
  dmk,
  sessionId,
  originToken: "your-origin-token", // Replace with your actual token
}).build();
```

## Step 2: Update custom ContextModuleBuilder usage

If you're building a custom context module with `ContextModuleBuilder`, you must now provide the `originToken` parameter.

### Before (v1.3.3)

```typescript
const contextModule = new ContextModuleBuilder().build();

const signer = new SignerEthBuilder({ dmk, sessionId })
  .withContextModule(contextModule)
  .build();
```

### After (v1.4.0)

```typescript
import {
  ContextModuleBuilder,
  ContextModuleChainID,
} from "@ledgerhq/context-module";

const contextModule = new ContextModuleBuilder({
  originToken: "your-origin-token", // Required for security features
})
  .setChain(ContextModuleChainID.Ethereum)
  .build();

const signer = new SignerEthBuilder({ dmk, sessionId })
  .withContextModule(contextModule)
  .build();
```

## Step 3: Update your package.json

Update your Ethereum Signer dependency to version 1.4.0 or higher:

```json
{
  "dependencies": {
    "@ledgerhq/device-signer-kit-ethereum": "^1.4.0"
  }
}
```

## What the origin token enables

The `originToken` parameter enables several security features:

- **Web3 checks**: Transaction simulation and security analysis
- **Trusted names**: Display of verified contract and address names
- **Solana owner information**: Enhanced Solana transaction context
- **Request authentication**: Identifies your application to Ledger services

## Troubleshooting

### "Origin token is required" error

This error occurs when you try to build a context module without providing the `originToken` parameter. Make sure you:

1. Have obtained an origin token from Ledger
2. Pass it to either `SignerEthBuilder` or `ContextModuleBuilder`
3. Replace placeholder values like `"your-origin-token"` with your actual token

### Features not working as expected

If transaction security features aren't working:

1. Verify your origin token is valid and active
2. Check that you're passing the token to the correct constructor
3. Ensure your token has the necessary permissions for the features you're using

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/signers/eth/hw_app_eth_to_dmk -->

---
title: "Migrate from hw-app-eth to device-signer-kit-ethereum"
category: how-to
---

# Migrate from hw-app-eth to device-signer-kit-ethereum

This guide walks you through migrating from the LedgerJS Ethereum package (`@ledgerhq/hw-app-eth`) to the DMK Ethereum signer (`@ledgerhq/device-signer-kit-ethereum`).

> **Warning:** `hw-app-eth` will stop working with the Ethereum app after September 2026. Complete this migration before that date.

Before reading this guide, complete the [general LedgerJS → DMK migration](../../ledgerjs-to-dmk) to set up the DMK, register a transport, and create a session.

## Why migrate?

| Feature                  | `hw-app-eth` (LedgerJS)                                                           | `device-signer-kit-ethereum` (DMK)                             |
| ------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **EIP-712 support**      | `signEIP712HashedMessage` (hashed data) and `signEIP712Message` (structured data) | `signTypedData` (full structured-data signing)                 |
| **API style**            | Promise-based                                                                     | Observable-based, with cancellation                            |
| **Transport management** | Manual: you create and manage the `Transport`                                     | Automatic: DMK manages discovery, connection, reconnection     |
| **App lifecycle**        | Manual: you open the Ethereum app yourself                                        | Automatic: the signer opens the Ethereum app for you           |
| **Clear signing**        | Manual: `ledgerService.resolveTransaction()` before every `signTransaction`       | Automatic: the context module resolves metadata during signing |
| **Device state**         | No visibility                                                                     | Observable state machine with `requiredUserInteraction`        |
| **Cancellation**         | Not supported                                                                     | Built-in `cancel()` on every operation                         |
| **EIP-7702**             | Not supported                                                                     | `signDelegationAuthorization`                                  |
| **Safe address**         | Not supported                                                                     | `verifySafeAddress`                                            |

---

## Step 1: Update your dependencies

```diff
- npm install @ledgerhq/hw-app-eth @ledgerhq/hw-transport-webhid
+ npm install @ledgerhq/device-signer-kit-ethereum @ledgerhq/device-management-kit @ledgerhq/device-transport-kit-web-hid
```

`rxjs` is a peer dependency; install it if it is not already in your project:

```bash
npm install rxjs
```

---

## Step 2: Update initialization

If you haven't already, follow [Steps 2–3 of the general migration guide](../../ledgerjs-to-dmk#step-2-initialize-the-dmk) to build the DMK instance and obtain a `sessionId`. Then create the Ethereum signer:

### Before

```typescript
import Eth from "@ledgerhq/hw-app-eth";

const eth = new Eth(transport);
```

### After

```typescript
import { SignerEthBuilder } from "@ledgerhq/device-signer-kit-ethereum";

const signerEth = new SignerEthBuilder({ dmk, sessionId }).build();
```

### With an origin token (recommended, required for full clear signing)

```typescript
const signerEth = new SignerEthBuilder({
  dmk,
  sessionId,
  originToken: "your-origin-token",
}).build();
```

`originToken` enables Ledger's Transaction Checks service, which shows users whether a transaction is potentially malicious. It also unlocks full clear signing: without it, only basic clear signing (e.g. ERC-20 transfers) is available, and transactions calling more complex contract selectors fall back to blind signing. Contact Ledger to obtain a token for your application.

---

## Step 3: Migrate API calls

All methods now return `{ observable, cancel }` instead of a `Promise`.

```typescript
import { DeviceActionStatus } from "@ledgerhq/device-management-kit";
```

---

### `getAddress`

#### Before

```typescript
// boolDisplay: show address on device for verification
// boolChaincode: return the chain code
// chainId: optional, displayed on Stax/Flex
const result = await eth.getAddress(
  "44'/60'/0'/0/0",
  boolDisplay,
  boolChaincode,
  chainId,
);
// result.publicKey: string (hex, no 0x prefix)
// result.address: string ('0x...')
// result.chainCode?: string
```

#### After

```typescript
const { observable, cancel } = signerEth.getAddress("44'/60'/0'/0/0", {
  checkOnDevice: boolDisplay, // was boolDisplay
  returnChainCode: boolChaincode, // was boolChaincode
  chainId: 1, // was chainId (number, not string)
});

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const { publicKey, address, chainCode } = state.output;
      // publicKey: string
      // address: `0x${string}`
      // chainCode?: string
    }
  },
});
```

**Key differences:**

- Parameters move from positional arguments to a named options object.
- `chainId` is now a `number` (was a `string` in LedgerJS).
- A new `skipOpenApp` boolean option lets you skip the automatic app-open step if the Ethereum app is already running.

---

### `signTransaction`

#### Before

```typescript
import { ledgerService } from "@ledgerhq/hw-app-eth";

// rawTxHex is the hex-encoded RLP of the unsigned transaction (no 0x prefix)
const resolution = await ledgerService.resolveTransaction(rawTxHex, {}, {});
const sig = await eth.signTransaction("44'/60'/0'/0/0", rawTxHex, resolution);
// sig.r: string (hex, no 0x prefix)
// sig.s: string (hex, no 0x prefix)
// sig.v: string (decimal)
```

#### After

```typescript
// The DMK expects a Uint8Array, not a hex string
const txBytes = Buffer.from(rawTxHex, "hex"); // Buffer extends Uint8Array

const { observable, cancel } = signerEth.signTransaction(
  "44'/60'/0'/0/0",
  txBytes,
);

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const { r, s, v } = state.output;
      // r: `0x${string}`
      // s: `0x${string}`
      // v: number
    }
  },
});
```

**Key differences:**

- `ledgerService.resolveTransaction` is gone. The context module resolves ERC-20 tokens, NFT metadata, and plugin data automatically during the signing flow.
- The transaction input changes from a hex string to a `Uint8Array` (use `Buffer.from(rawTxHex, "hex")` to convert).
- The signature's `v` field changes type: LedgerJS returns it as a decimal string, the DMK returns it as a `number`.
- The signature's `r` and `s` fields now include the `0x` prefix.

---

### `signPersonalMessage` → `signMessage`

#### Before

```typescript
// messageHex is the hex-encoded message bytes
const sig = await eth.signPersonalMessage(
  "44'/60'/0'/0/0",
  Buffer.from("Hello, Ledger!").toString("hex"),
);
// sig.v: number
// sig.r: string (hex, no 0x prefix)
// sig.s: string (hex, no 0x prefix)
```

#### After

```typescript
// Pass the message as a plain string or Uint8Array
const { observable, cancel } = signerEth.signMessage(
  "44'/60'/0'/0/0",
  "Hello, Ledger!",
);

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const { r, s, v } = state.output;
      // r: `0x${string}`
      // s: `0x${string}`
      // v: number
    }
  },
});
```

**Key differences:**

- Method renamed from `signPersonalMessage` to `signMessage`.
- Input changes from a hex-encoded string to a plain `string` or `Uint8Array`. If you were passing `Buffer.from(text).toString("hex")`, pass `text` directly.
- The signature's `r` and `s` fields now include the `0x` prefix.

---

### `signEIP712Message` → `signTypedData`

#### Before

```typescript
const sig = await eth.signEIP712Message("44'/60'/0'/0/0", {
  domain: {
    name: "My App",
    version: "1",
    chainId: 1,
    verifyingContract: "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
  },
  types: {
    EIP712Domain: [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
      { name: "chainId", type: "uint256" },
      { name: "verifyingContract", type: "address" },
    ],
    Mail: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "contents", type: "string" },
    ],
  },
  primaryType: "Mail",
  message: { from: "0x...", to: "0x...", contents: "Hello!" },
});
// sig.v: number
// sig.r: string (hex, no 0x prefix)
// sig.s: string (hex, no 0x prefix)
```

#### After

```typescript
const { observable, cancel } = signerEth.signTypedData("44'/60'/0'/0/0", {
  domain: {
    name: "My App",
    version: "1",
    chainId: 1,
    verifyingContract: "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
  },
  types: {
    EIP712Domain: [
      { name: "name", type: "string" },
      { name: "version", type: "string" },
      { name: "chainId", type: "uint256" },
      { name: "verifyingContract", type: "address" },
    ],
    Mail: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "contents", type: "string" },
    ],
  },
  primaryType: "Mail",
  message: { from: "0x...", to: "0x...", contents: "Hello!" },
});

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const { r, s, v } = state.output;
      // r: `0x${string}`
      // s: `0x${string}`
      // v: number
    }
  },
});
```

**Key differences:**

- Method renamed from `signEIP712Message` to `signTypedData`.
- The `TypedData` structure (`domain`, `types`, `primaryType`, `message`) is identical; no changes to the data you pass.
- The `fullImplem` boolean parameter is gone; the DMK always uses the full implementation.
- The signature's `r` and `s` fields now include the `0x` prefix.

---

### `signEIP712HashedMessage` → `signTypedData`

The `SignerEth` interface does not have a `signEIP712HashedMessage` method. The only EIP-712 signing method in the DMK is `signTypedData`, which takes the full structured data, not pre-computed hashes. When migrating, you must move to `signTypedData`.

This is an upgrade: instead of computing `domainHash` and `messageHash` yourself and doing blind signing, you pass the original typed data and the DMK handles the hashing. It also tries clear signing first (so the device can display human-readable field values), and automatically falls back to the hash-based APDU if clear signing is unavailable.

```typescript
// Before: manually computed hashes, blind-signed
await eth.signEIP712HashedMessage(
  path,
  domainSeparatorHex,
  hashStructMessageHex,
);

// After: pass the structured data — the DMK hashes and signs
const { observable } = signerEth.signTypedData(path, {
  domain: {
    /* original domain object */
  },
  types: {
    /* original types */
  },
  primaryType: "...",
  message: {
    /* original message */
  },
});
```

If your code only holds the pre-computed hashes and no longer has access to the original `TypedData`, you will need to retrieve or reconstruct it before you can migrate.

---

### `getChallenge`: no equivalent

`getChallenge` was a low-level method used internally as part of some clear-signing flows. It has no public equivalent in the DMK signer. The context module handles this internally.

---

### `getAppConfiguration`: no equivalent

`getAppConfiguration` returned the Ethereum app version and feature flags (arbitrary data, Stark support, etc.). There is no equivalent method on the DMK `SignerEth` interface.

If you need the app version, you can send the underlying APDU directly using `dmk.sendCommand()`. See [Build a custom command](../../../how_to/build_custom_command).

---

## Step 4: Converting from promises to observables

If you want to migrate incrementally, use the `toPromise` helper from the [general migration guide](../../ledgerjs-to-dmk#step-5-migrate-api-calls-from-promises-to-observables). This lets you keep `await` call sites unchanged while the rest of your code catches up.

---

## Quick reference: API mapping

| `hw-app-eth`                                       | `device-signer-kit-ethereum`                                                     | Notes                                                  |
| -------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `new Eth(transport)`                               | `new SignerEthBuilder({ dmk, sessionId, originToken? }).build()`                 |                                                        |
| `getAddress(path, display?, chaincode?, chainId?)` | `getAddress(path, { checkOnDevice?, returnChainCode?, skipOpenApp?, chainId? })` | `chainId` is now a `number`                            |
| `signTransaction(path, rawTxHex, resolution?)`     | `signTransaction(path, txBytes: Uint8Array, { skipOpenApp? }?)`                  | Input: hex string → `Uint8Array`; `resolution` removed |
| `clearSignTransaction(path, rawTxHex, config)`     | `signTransaction(path, txBytes)`                                                 | Resolution is automatic                                |
| `signPersonalMessage(path, messageHex)`            | `signMessage(path, message: string \| Uint8Array, { skipOpenApp? }?)`            | Input: hex string → plain string                       |
| `signEIP712Message(path, typedData, fullImplem?)`  | `signTypedData(path, typedData: TypedData, { skipOpenApp? }?)`                   | Same data structure                                    |
| `signEIP712HashedMessage(path, domainHex, msgHex)` | Use `signTypedData` when structured data is available                            | EIP-712 APDU refactor in progress                      |
| `getChallenge()`                                   | No equivalent                                                                    | Handled internally                                     |
| `getAppConfiguration()`                            | No equivalent                                                                    | Use `dmk.sendCommand()` for raw access                 |
| _(none)_                                           | `signDelegationAuthorization(path, chainId, contractAddress, nonce)`             | New in DMK (EIP-7702)                                  |
| _(none)_                                           | `verifySafeAddress(safeAddress, { chainId, skipOpenApp? })`                      | New in DMK                                             |

---

## Troubleshooting

| Issue                                          | Solution                                                                                                                                                                                            |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Observable never reaches `Completed`           | The device may be waiting for user confirmation. Check `state.intermediateValue.requiredUserInteraction` in the `Pending` state.                                                                    |
| `rxjs` not found                               | Run `npm install rxjs` (it is a peer dependency of the DMK).                                                                                                                                        |
| Transaction bytes rejected                     | Ensure you are passing a `Uint8Array` (or `Buffer`), not a hex string. `Buffer.from(rawTxHex, "hex")` converts correctly.                                                                           |
| `signEIP712HashedMessage` not available in DMK | The DMK does not expose a hashed-message signing API. Use `signTypedData` if you have the full structured data.                                                                                     |
| No Transaction Checks shown on device          | Pass an `originToken` to `SignerEthBuilder`. Contact Ledger to obtain one.                                                                                                                          |
| Device shows "blind signing" warning           | Without an `originToken`, only basic clear signing (e.g. ERC-20 transfers) is supported; complex contract selectors fall back to blind signing. Pass an `originToken` to unlock full clear signing. |

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/integration/migrations/signers/solana/hw_app_solana_to_dmk -->

# Migration from @ledgerhq/hw-app-solana to @ledgerhq/device-signer-kit-solana

This guide walks you through migrating from the legacy LedgerJS Solana package (`@ledgerhq/hw-app-solana`) to the new Device Management Kit (DMK) Solana Signer (`@ledgerhq/device-signer-kit-solana`).

## Why migrate?

| Feature                  | `hw-app-solana` (legacy)                                                                       | `device-signer-kit-solana` (DMK)                                   |
| ------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **API style**            | Promise-based, imperative                                                                      | Observable-based, reactive                                         |
| **Transport management** | Manual: you create and manage the `Transport`                                                  | Automatic: DMK handles discovery, connection, reconnection         |
| **App lifecycle**        | Manual: you must open the Solana app yourself                                                  | Automatic: the signer opens the Solana app for you                 |
| **Clear signing**        | Not built-in (you must call `provideTrustedName` / `provideTrustedDynamicDescriptor` manually) | Built-in: the context module resolves token metadata automatically |
| **Device state**         | No visibility                                                                                  | Full observable state machine (pending, user interaction, etc.)    |
| **Cancellation**         | Not supported                                                                                  | Built-in `cancel()` on every operation                             |
| **Off-chain messages**   | Single method (`signOffchainMessage`)                                                          | Unified `signMessage` with version support (V0, V1, Legacy, Raw)   |
| **Multi-device**         | One transport = one device                                                                     | Session-based: multiple devices on a single DMK instance           |
| **Error handling**       | Raw status codes / thrown errors                                                               | Typed error states per operation                                   |

## Step 1: Update your dependencies

```diff
- npm install @ledgerhq/hw-app-solana @ledgerhq/hw-transport-webhid
+ npm install @ledgerhq/device-management-kit @ledgerhq/device-signer-kit-solana @ledgerhq/device-transport-kit-web-hid
```

## Step 2: Update initialisation

If you haven't already, follow [Steps 2–3 of the general migration guide](../../ledgerjs-to-dmk#step-2-initialize-the-dmk) to build the DMK instance and obtain a `sessionId`. Then create the Solana signer:

### Before (hw-app-solana)

```typescript
import Solana from "@ledgerhq/hw-app-solana";

const solana = new Solana(transport);
```

### After (DMK Solana Signer)

```typescript
import { SignerSolanaBuilder } from "@ledgerhq/device-signer-kit-solana";

const signer = new SignerSolanaBuilder({ dmk, sessionId }).build();
```

## Step 3: Migrate API calls

Each method now returns `{ observable, cancel }` instead of a `Promise`. Subscribe to the `observable` to receive `DeviceActionState` updates.

```typescript
import { DeviceActionStatus } from "@ledgerhq/device-management-kit";
```

### `getAddress`

#### Before

```typescript
const { address } = await solana.getAddress("44'/501'/0'", true);
// address is a Buffer
const hexAddress = address.toString("hex");
// or encode as base58: const base58Address = bs58.encode(address);
```

#### After

```typescript
const { observable } = signer.getAddress("44'/501'/0'", {
  checkOnDevice: true,
});

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const base58Address = state.output; // already base58
    }
  },
});
```

**Key differences:**

- The `display: boolean` parameter becomes `{ checkOnDevice: boolean }`.
- The address is returned as a **base58 `string`** directly.
- The signer automatically opens the Solana app if needed.

### `signTransaction`

#### Before

```typescript
const { signature } = await solana.signTransaction("44'/501'/0'", txBuffer);
// signature is a Buffer
```

#### After

```typescript
const { observable } = signer.signTransaction("44'/501'/0'", txBytes, {
  // optional — provide mintAddress for SPL basic clear signing;
  // if omitted the signer resolves it automatically, degrading to "???"
  // on the device if resolution fails
  transactionResolutionContext: {
    mintAddress: "EPjFWdd5...",
  },
});

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const signature = state.output; // Uint8Array
    }
  },
});
```

**Key differences:**

- Input is `Uint8Array` instead of `Buffer` (though `Buffer` extends `Uint8Array`, so existing buffers work).
- The `userInputType` parameter (`"ata" | "sol"`) is replaced by the richer `transactionResolutionContext` in the options object.
- Clear-signing metadata (trusted names, descriptors) is resolved **automatically** by the built-in context module; you no longer need to call `provideTrustedName` or `provideTrustedDynamicDescriptor` manually.

### `signOffchainMessage` → `signMessage`

#### Before

```typescript
const { signature } = await solana.signOffchainMessage(
  "44'/501'/0'",
  msgBuffer,
);
// signature is a Buffer
```

#### After

```typescript
import { SignMessageVersion } from "@ledgerhq/device-signer-kit-solana";

const { observable } = signer.signMessage(
  "44'/501'/0'",
  "Hello World", // string or Uint8Array
  {
    version: SignMessageVersion.V0,
    appDomain: "myapp.xyz",
  },
);

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const signature = state.output.signature; // base58 string
    }
  },
});
```

**Key differences:**

- Method renamed from `signOffchainMessage` to `signMessage`.
- Accepts a `string` (auto-encoded as UTF-8) or `Uint8Array`.
- Supports multiple signing versions (V0, V1, Legacy, Raw) with automatic fallback.
- Signature is returned as a **base58 string**, not a `Buffer`.

### `getAppConfiguration`

#### Before

```typescript
const config = await solana.getAppConfiguration();
// { blindSigningEnabled: boolean, pubKeyDisplayMode: number, version: string }
```

#### After

```typescript
const { observable } = signer.getAppConfiguration();

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const { blindSigningEnabled, pubKeyDisplayMode, version } = state.output;
    }
  },
});
```

**Key differences:**

- Same data shape; only the invocation pattern changes from promise to observable.

### `getChallenge` / `provideTrustedName` / `provideTrustedDynamicDescriptor`

These low-level methods **do not have direct equivalents** in the DMK signer. Their functionality is handled automatically by the **context module** during `signTransaction`. The context module resolves token metadata, trusted names, and descriptors transparently.

If you need to send raw APDUs for advanced use cases, the DMK provides `dmk.sendCommand()` and `dmk.sendApdu()` on the core `DeviceManagementKit` instance.

## Step 4: Converting from Promises to Observables

If your existing codebase is heavily promise-based, use the `toPromise` helper from the [general migration guide](../../ledgerjs-to-dmk#step-5-migrate-api-calls-from-promises-to-observables). This lets you keep `await` call sites unchanged while the rest of your code catches up.

> **Note:** While this helper works for simple integrations, subscribing to the full observable gives you access to pending states and `requiredUserInteraction` values, which are essential for building responsive wallet UIs.

## Quick reference: API mapping

| `hw-app-solana`                              | `device-signer-kit-solana`                            | Notes                                          |
| -------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
| `new Solana(transport)`                      | `new SignerSolanaBuilder({ dmk, sessionId }).build()` | DMK manages the transport                      |
| `getAddress(path, display)`                  | `getAddress(path, { checkOnDevice })`                 | Returns base58 string, not Buffer              |
| `signTransaction(path, buf, userInputType?)` | `signTransaction(path, bytes, options?)`              | Clear-signing context replaces `userInputType` |
| `signOffchainMessage(path, buf)`             | `signMessage(path, msg, options?)`                    | Supports string input and version selection    |
| `getAppConfiguration()`                      | `getAppConfiguration()`                               | Same output, observable wrapper                |
| `getChallenge()`                             | _Handled by context module_                           | No direct equivalent needed                    |
| `provideTrustedName(data)`                   | _Handled by context module_                           | Automatic during `signTransaction`             |
| `provideTrustedDynamicDescriptor(data)`      | _Handled by context module_                           | Automatic during `signTransaction`             |

## Troubleshooting

| Issue                       | Solution                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `6808` error during signing | Enable blind signing in the Solana app settings on the device                                     |
| Observable never completes  | Ensure the device is unlocked and the Solana app is accessible                                    |
| `Buffer` type errors        | Replace `Buffer` with `Uint8Array`, or use `Buffer.from(...)` since `Buffer` extends `Uint8Array` |
| Missing `rxjs`              | Install it: `npm install rxjs` (it is a peer dependency of the DMK)                               |
| Discovery finds no devices  | Check that the browser supports WebHID and the device is connected via USB                        |

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/beginner/cosmos-app -->

# Interact with the Cosmos App## IntroductionIn this section, we will guide you through the creation of a web application. This application will connect to your Nano and will allow you to use the Cosmos Embedded App.Web USB and Web HID applications are implemented with `@ledgerhq/hw-transport-webusb` and `@ledgerhq/hw-transport-webhid` respectively.This web application was originally developed by the Zondax team (here is a link to [their website](https://zondax.ch/) and to their [Twitter feed](https://twitter.com/_zondax_)) through [this source repo](https://github.com/cosmos/ledger-cosmos-js.git)). Zondax has been developing innovative end-to-end software solutions that are used by a large number of exchanges, hardware wallets, privacy coins, and decentralized finance (DeFi) protocols. Zondax has proven to be a reliable partner for Ledger apps development with more than 35 applications built to date.## Use caseYou will be able to do the following actions:* Get information about the Cosmos Embedded App installed on your Nano device
* Get information about the public key and the public address
* Sign an example of transaction with your Ledger Nano device## Tutorial prerequisites* Ensure you have gone through the [prerequisites](../info#prerequisites).
* Install or update your Cosmos Embedded app to the last version.## InstallationFirst, open a terminal and create a new folder in your usual working directory. For this tutorial, the folder will be named “use-cosmos-webapp”.Run:```bash copy
mkdir use-cosmos-webapp
cd use-cosmos-webapp
```Clone the repo (master branch) and go to the repo folder:```bash copy
git clone https://github.com/LedgerHQ/ledger-cosmos-js.git
cd ledger-cosmos-js
```Run:```bash copy
yarn install
npm install -g @vue/cli
npm install -g @vue/cli-plugin-typescript
npm install vue-template-compiler
npm install --save-dev webpack
```## UsageNow, that all the needed packages are installed, you can launch the webapp by runnig:```bash copy
npm run serve
```The application is up and running. Open the browser and go to `http://localhost:8080`, it will display:![Cosmos integration example](/device-interaction/cosmos-01.png)* Make sure to select the **WebUSB** option (as the U2F option is deprecated).

* Connect your Nano to the USB port, unlock it and run the cosmos application. You’re now able to interact with the cosmos application.

* Click on **Get Version**:![Cosmos integration example](/device-interaction/cosmos-02.png)You’re able to retrieve the app version installed on your Ledger Nano device and some other information using the `getVersion()` function.* Click on **AppInfo**:![Cosmos integration example](/device-interaction/cosmos-03.png)You’re able to retrieve the app version but also the app name and some other information using the `appInfo()` function.* Click on **Get pubkey only**:![Cosmos integration example](/device-interaction/cosmos-04.png)You can retrieve the data contained in the public key and some other information using the `getPublicKey()` function.* Click on **Get Address and Pubkey**:![Cosmos integration example](/device-interaction/cosmos-05.png)You can retrieve the public address, the data contained in the public key and some other information using the `getAddress()` and `getPublicKey()` functions.* Click on **Show Address and Pubkey**:

  ![Cosmos integration example](/device-interaction/cosmos-06.png)

  As in the previous step, you can retrieve the public address, the data contained in the public key and some other information, but here you can preview the public address on your Nano. The address you see on the Nano is the same as what you can have on your web app. In this case, the `showAddressAndPubKey()` function is used.

  - Press the right button to do the review:

  \


  ![Cosmos integration example](/device-interaction/please-review-cosmos.png)

  - Verify that the correct address is showing on your Nano. Then, you can press the right button to approve or reject.

    \


    ![Cosmos integration example](/device-interaction/address-cosmos.png)

  - You can confirm by pressing both buttons.

    \


    ![Cosmos integration example](/device-interaction/approve-cosmos.png)

  - You can also reject.
    \

    ![Cosmos integration example](/device-interaction/reject-cosmos.png)

  After approving the review, the webapp will display to you the public address, the data of the public key and some other information.

* Click on **Sign Example TX**:![Cosmos integration example](/device-interaction/cosmos-07.png)Here, it provides you with an example of a transaction to sign on your Ledger Nano device using the `signExampleTx()` function. You’ll have to review the Chain ID, the Account, the Sequence, the Type, the Amount, the Delegator, the Validator, the Memo, the Fees and the Gas. Then you can approve or decline the transaction.\
![Cosmos integration example](/device-interaction/please-review-cosmos.png)\
![Cosmos integration example](/device-interaction/chain-id-cosmos.png)\
![Cosmos integration example](/device-interaction/account-cosmos.png)\
![Cosmos integration example](/device-interaction/sequence-cosmos.png)\
![Cosmos integration example](/device-interaction/type-cosmos.png)\
![Cosmos integration example](/device-interaction/amount-cosmos.png)\
![Cosmos integration example](/device-interaction/delegator-cosmos.png)\
![Cosmos integration example](/device-interaction/validator-cosmos.png)\
![Cosmos integration example](/device-interaction/memo-cosmos.png)\
![Cosmos integration example](/device-interaction/fee-cosmos.png)\
![Cosmos integration example](/device-interaction/gas-cosmos.png)\
![Cosmos integration example](/device-interaction/approve-cosmos.png)If approved, your transaction is signed and the webapp will display it along with the type of transaction (here, a signature) and some other information.![Cosmos integration example](/device-interaction/cosmos-08.png)

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/beginner/personal-message -->

# Sign a personal message## IntroductionIn this section, we will guide you through the creation of a web application. This application will connect to your Nano and will display the “test“ message to be signed with an Ethereum account using the personal sign message functionality introduced by EIP-191.Web USB and Web HID applications are implemented with `@ledgerhq/hw-transport-webusb` and `@ledgerhq/hw-transport-webhid` respectively.## Use caseThis tutorial will let you sign a message with your private key in order to verify and prove that you’re the owner of the address.## Tutorial Prerequisites* Ensure you have gone through the [prerequisites](../info#prerequisites).
* Install or update your Ethereum Embedded App to the version 1.9.19 or later.## Coding### App setupFirst, open a terminal and create a new folder in your usual working directory. For this tutorial, the folder will be named “example-sign-personal-message”.Run:```bash copy
mkdir example-sign-personal-message
cd example-sign-personal-message
```Initialize the project by running:```bash copy
npm init
```Answer the questions displayed or by default press enter. There is no incidence on the execution.Run:```bash copy
mkdir src
touch src/index.html
touch src/main.js
```The folder will contain these files:![Folder USB and HID](/device-interaction/folderUsbHid.png)### CodingOpen the folder example-sign-personal-message in a code editor.#### index.htmlIn index.html copy and paste the following code:```html copy
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My First Embedded App</title>
    <script type="module" src="main.js"></script>
  </head>
  <body>
    <div id="main"></div>
    <button id="hashMessage">Hash my message</button>
  </body>
</html>
```#### main.jsIn main.js copy and paste the following code:> **Warning:** Comment out or remove the Transport package you are not using (
> @ledgerhq/hw-transport-webusb or
> @ledgerhq/hw-transport-webhid) and the corresponding
> const. In the example, we use webusb. Webhid is already commented
> in line 8 and line 23.```js copy
import "core-js/actual";
import { listen } from "@ledgerhq/logs";
import Eth from "@ledgerhq/hw-app-eth";

// Keep this import if you want to use a Ledger Nano S/X/S Plus with the USB protocol and delete the @ledgerhq/hw-transport-webhid import
//import TransportWebUSB from "@ledgerhq/hw-transport-webusb";
// Keep this import if you want to use a Ledger Nano S/X/S Plus with the HID protocol and delete the @ledgerhq/hw-transport-webusb import
import TransportWebHID from "@ledgerhq/hw-transport-webhid";

//Display the header in the div which has the ID "main"
const initial =
  "<h1>Connect your Nano and open the Ethereum app. Click on “Hash my message”</h1>";
const $main = document.getElementById("main");
$main.innerHTML = initial;

document.querySelector("#hashMessage").addEventListener("click", async () => {
  $main.innerHTML = initial;
  try {
    //trying to connect to your Ledger device with USB protocol
    // const transport = await TransportWebUSB.create();

    //trying to connect to your Ledger device with HID protocol
    const transport = await TransportWebHID.create();

    //listen to the events which are sent by the Ledger packages in order to debug the app
    listen((log) => console.log(log));

    //When the Ledger device connected it is trying to display the bitcoin address
    const eth = new Eth(transport);
    const signature = await eth.signPersonalMessage(
      "44'/60'/0'/0/0",
      Buffer.from("test").toString("hex"),
    );
    const signedHash =
      "0x" + signature.r + signature.s + signature.v.toString(16);

    //Display your bitcoin address on the screen
    const h2 = document.createElement("h2");
    h2.textContent = signedHash;
    $main.innerHTML = "<h1>Your signed message:</h1>";
    $main.appendChild(h2);

    //Display the address on the Ledger device and ask to verify the address
    const { address } = await eth.getAddress("44'/60'/0'/0/0");
    const add = document.createElement("div");
    add.textContent = address;
    $main.appendChild(add);
  } catch (e) {
    //Catch any error thrown and displays it on the screen
    const $err = document.createElement("code");
    $err.style.color = "#f66";
    $err.textContent = String(e.message || e);
    $main.appendChild($err);
  }
});
```## Dependencies Installation### Install the packagesRun:```bash copy
npm install --save core-js
npm install --save @ledgerhq/logs
npm install --save-dev parcel
npm install --save @ledgerhq/hw-app-eth
npm install --save eth-crypto
npm install --save-dev buffer
npm install --save-dev process
npm install --save-dev stream-browserify
```### Install the Transport HID or USB packageThen depending on your choice install one of the corresponding packages:* Install the Ledger package `@ledgerhq/hw-transport-webhid` which provide you with all the methods to interact with your Nano with an HID connection (make sure that you use the 6.27.1 version):
  `npm install --save @ledgerhq/hw-transport-webhid@6.27.1`

* Install the Ledger package `@ledgerhq/hw-transport-webusb` which provide you with all the methods to interact with your Nano with a USB connection (make sure that you use the 6.27.1 version):
  `npm install --save @ledgerhq/hw-transport-webusb@6.27.1`### Package.jsonModify `“main”: “index.js”` to `“source”:”src/index.html”`.Ensure you have this line in your `package.json`:```json copy
"scripts": {
   "build": "parcel build",
   "start": "parcel"
 },
```And:```json copy

  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es",
    "@ledgerhq/domain-service": "@ledgerhq/domain-service/lib-es",
    "@ledgerhq/evm-tools": "@ledgerhq/evm-tools/lib-es",
    "@ledgerhq/cryptoassets": "@ledgerhq/cryptoassets/lib-es",
    "@ledgerhq/live-network": "@ledgerhq/live-network/lib-es"
  }
```Your `package.json` should look like this:```json copy
{
  "name": "example-sign-personal-message",
  "version": "1.0.0",
  "description": "",
  "source": "src/index.html",
  "scripts": {
    "build": "parcel build",
    "start": "parcel"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.35.6",
    "@ledgerhq/hw-transport-webhid": "^6.28.4",
    "@ledgerhq/logs": "^6.12.0",
    "core-js": "^3.36.0",
    "eth-crypto": "^2.6.0"
  },
  "devDependencies": {
    "buffer": "^6.0.3",
    "parcel": "^2.12.0",
    "process": "^0.11.10",
    "stream-browserify": "^3.0.0"
  },
  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es",
    "@ledgerhq/domain-service": "@ledgerhq/domain-service/lib-es",
    "@ledgerhq/evm-tools": "@ledgerhq/evm-tools/lib-es",
    "@ledgerhq/cryptoassets": "@ledgerhq/cryptoassets/lib-es",
    "@ledgerhq/live-network": "@ledgerhq/live-network/lib-es"
  }
}
```## Usage### Start the development serverNow that the Setup is finished, the app has to be built to be displayed. Start the development server:```bash copy
npm run start
```Now the application is up and running. Open the browser and go to `localhost:1234`, it will display:![Hash Message](/device-interaction/hash-message.png)### Plug your NanoBefore clicking on the “Hash my message”, connect your Nano to the USB port, unlock it and run the ethereum application. Then, click on “Hash my message”.### Go to your NanoWhen you click on the “Hash my message”, a popup message will be prompt inviting you to sign a message.\
![Hash Message](/device-interaction/sign-message-01.png)Click the right button to see the content of the message that you are going to sign with your Ethereum address:\
![Hash Message](/device-interaction/sign-message-02.png)### Sign the messageClick the right button to the next screens to sign the “test” message or decline it:\
![Hash Message](/device-interaction/sign-message-03.png)\
![Hash Message](/device-interaction/sign-message-04.png)Once signed, the webapp will display:* The signed message (“hash”)
* The Ethereum address used to sign the message### Verify on runkit.comYou can verify that you are the one who signed the message by signing in on [runkit.com](https://runkit.com/home) and running the following piece of code.1) Adapt the code with the message you signed and the hash of the message:```js copy
const { ethers } = require("ethers");
ethers.verifyMessage(
  "test",
  "0xefb42c22baa0143b322e93b24b0903a0ef47a64b716fbb77debbea55a93dec3e4417aff7dce845723240916c6e34cf17c674828b3addfb0afad966334df5b6311b",
);
```2) Run your code, it should now display the Ethereum address linked to the signed message (the run can take a bit of time):![Runkit](/device-interaction/runkit-verification.png)

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/beginner/smart-contract -->

# Call a Smart Contract## IntroductionIn this section, we will guide you through the creation of an application that will call a smart contract to read and write.## Tutorial PrerequisitesBefore starting, make sure you have gone through the [prerequisites](../info#prerequisites).### Receive Ether token in your Ledger Nano Ethereum Sepolia account* Create an Ethereum Sepolia account in Ledger Live
* Send Sepolia Eth to your account with [Infura faucet](https://www.infura.io/faucet/sepolia). You will need to create an account that will be useful later for the API key.![Sepolia Ethereum Faucet](/device-interaction/tutorial-infura-sepolia-faucet.png)
_Fig. 1: Sepolia Ethereum Faucet_## Web App Bluetooth (only Nano X)The Ledger Nano S and S Plus do not have the Bluetooth functionality. This tutorial will only work with a Ledger Nano X.Please be aware that the Bluetooth implementation is only supported by a few browsers.
You can check the [browser support](https://caniuse.com/web-bluetooth) for the Web Bluetooth transport.### Project InitializationThe app is build with React, which is a frontend Javascript framework.First, open a terminal and create a new project. For this tutorial the project will be named "e2e-tutorial-contract".
Run:```console copy
npx create-react-app e2e-tutorial-contract
cd e2e-tutorial-contract
```Open the folder in an text editor.Run:```console copy
mkdir pages
mkdir styles
touch ./ConnectLedger.js
touch ./SmartContract.js
touch ./ethereum.js
touch ./styles/global.css
touch ./styles/Home.module.css
mv src/index.js pages
mv src/App.js ./
rm -r src
```The folder will contain these files:![Folder of the Application](/device-interaction/tutorial-2-folder.png)
_Fig. 1: Folder of the Applicatio&#x6E;_To implement the Ledger connexion you will only modify "App.js", "index.js", "ConnectLedger.js”,"SmartContract.js", and ethereum.js”### Code Implementation#### App.jsIn App.js copy-paste the following code:```javascript copy
import React, { useState } from "react";
import ConnectLedger from "./ConnectLedger.js";
import SmartContract from "./SmartContract.js";

function App() {
  const [transport, setTransport] = useState(undefined);
  const [eth, setEth] = useState(undefined);
  const [address, setAddress] = useState(undefined);

  const saveInfo = (info) => {
    setAddress(info.address);
    setEth(info.eth);
    setTransport(info.transport);
  };

  return (
    <div className="container">
      {!transport ? (
        <ConnectLedger onTransport={(info) => saveInfo(info)}></ConnectLedger>
      ) : (
        <SmartContract address={address} eth={eth}></SmartContract>
      )}
    </div>
  );
}

export default App;
```#### ConnectLedger.jsIn ConnectLedger.js, copy-paste the following code:```javascript copy
import React from "react";

import TransportWebBLE from "@ledgerhq/hw-transport-web-ble";
import Eth from "@ledgerhq/hw-app-eth";

function ConnectLedger({ onTransport }) {
  const connectLedger = async () => {
    const transport = await TransportWebBLE.create();
    const eth = new Eth(transport);
    const { address } = await eth.getAddress("44'/60'/0'/0/0", false);
    onTransport({ address, eth, transport });
  };

  return (
    <div className="container">
      <div className="row">
        <div className="col-sm-4 mt-5 mx-auto">
          <button onClick={connectLedger}>Connect Your Ledger</button>
        </div>
      </div>
    </div>
  );
}

export default ConnectLedger;
```#### SmartContract.jsIn "SmartContract.js", copy-paste the following code and replace `{YOUR_INFURA_APIKEY}` by the API key you will find on your Infura account:```javascript copy
import React, { useState } from "react";
import getBlockchain from "./ethereum.js";
import { ethers } from "ethers";
import { ledgerService } from "@ledgerhq/hw-app-eth";

function SmartContract({ eth, address }) {
  const [simpleStorage, setSimpleStorage] = useState(undefined);
  const [data, setData] = useState(undefined);
  const [provider, setProvider] = useState(undefined);
  const [url, setUrl] = useState(undefined);

  const smartContractRead = async () => {
    const provider = new ethers.providers.JsonRpcProvider(
      "https://sepolia.infura.io/v3/{YOUR_INFURA_APIKEY}",
    );
    const { simpleStorage } = await getBlockchain(provider);
    console.log(simpleStorage);
    const data = await simpleStorage.readData();
    setProvider(provider);
    setSimpleStorage(simpleStorage);
    setData(data);
  };

  const updateData = async (e) => {
    e.preventDefault();
    const dataInput = e.target.elements[0].value;
    console.log(simpleStorage);
    const { data } =
      await simpleStorage.populateTransaction["updateData(uint256)"](dataInput);

    const unsignedTx = {
      to: simpleStorage.address,
      gasPrice: (await provider.getGasPrice())._hex,
      gasLimit: ethers.utils.hexlify(100000),
      nonce: await provider.getTransactionCount(address, "latest"),
      chainId: 11155111,
      data: data,
    };
    console.log(unsignedTx);

    const defaultLoadConfig = {
      nftExplorerBaseURL: "https://nft.api.live.ledger.com/v1/ethereum",
      pluginBaseURL: "https://cdn.live.ledger.com",
      extraPlugins: null,
      cryptoassetsBaseURL: "https://cdn.live.ledger.com/cryptoassets",
    };

    const serializedTx = ethers.utils.serializeTransaction(unsignedTx).slice(2);
    const resolution = await ledgerService.resolveTransaction(
      serializedTx,
      defaultLoadConfig,
      {},
    );

    console.log(serializedTx);
    const signature = await eth.signTransaction(
      "44'/60'/0'/0/0",
      serializedTx,
      resolution,
    );

    console.log(signature);
    //Parse the signature
    signature.r = "0x" + signature.r;
    signature.s = "0x" + signature.s;
    signature.v = parseInt("0x" + signature.v);
    signature.from = address;
    console.log(signature);

    //Serialize the same transaction as before, but adding the signature on it
    const signedTx = ethers.utils.serializeTransaction(unsignedTx, signature);
    console.log(signedTx);

    const hash = (await provider.sendTransaction(signedTx)).hash;
    console.log(hash);
    setUrl("https://sepolia.etherscan.io/tx/" + hash);
  };

  return (
    <div className="container">
      <div className="row">
        <div className="col-sm-4">
          <h2>Data:</h2>
          <p>{data ? data.toString() : "..."}</p>
          <button onClick={() => smartContractRead()}>Get Data</button>
        </div>

        <div className="col-sm-4">
          <h2>Change data</h2>
          <form className="form-inline" onSubmit={(e) => updateData(e)}>
            <input type="text" className="form-control" placeholder="data" />
            <button type="submit" className="btn btn-primary">
              Submit
            </button>
          </form>
        </div>
        <div className="mt-5 mx-auto d-flex flex-column">
          <p>Sepolia Etherscan :</p>
          <p>
            <a href={url} target="_blank" rel="noreferrer">
              {url}
            </a>
          </p>
        </div>
      </div>
    </div>
  );
}

export default SmartContract;
```#### ethereum.jsIn "ethereum.js", copy-paste the following code:```javascript copy
import { Contract } from "ethers";

const getBlockchain = (provider) =>
  new Promise(async (resolve, reject) => {
    if (provider) {
      const simpleStorage = new Contract(
        "0xA0aB0fae9C6b4882dC3690cb1705D5Aeb8c436d7",
        [
          {
            inputs: [],
            name: "data",
            outputs: [
              {
                internalType: "uint256",
                name: "",
                type: "uint256",
              },
            ],
            stateMutability: "view",
            type: "function",
          },
          {
            inputs: [],
            name: "readData",
            outputs: [
              {
                internalType: "uint256",
                name: "",
                type: "uint256",
              },
            ],
            stateMutability: "view",
            type: "function",
          },
          {
            inputs: [
              {
                internalType: "uint256",
                name: "_data",
                type: "uint256",
              },
            ],
            name: "updateData",
            outputs: [],
            stateMutability: "nonpayable",
            type: "function",
          },
        ],
        provider,
      );
      resolve({ simpleStorage });
      return;
    }
    reject("Provider not recognized");
  });

export default getBlockchain;
```### Dependencies InstallationRun:```console copy
npm install --save bootstrap
npm install --save ethers@5.4.7
npm install --save @ledgerhq/hw-app-eth
npm install --save @ledgerhq/hw-transport-web-ble
npm install --save buffer
npm install --save next
```| Package                                                                                                                            | What does it do?                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [bootstrap](https://getbootstrap.com/)                                                                                             | It allows you to use the Bootstrap CSS framework.                                                                           |
| [ethers](https://docs.ethers.io/v5/)                                                                                               | It provides you with all the methods to interact with the Ethereum blockchain. For this tutorial, we use the 5.4.7 version. |
| [@ledgerhq/hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                     | It will help you ask your Nano to access the ethereum address.                                                              |
| [@ledgerhq/hw-transport-web-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-web-ble) | It provides you with all the methods to interact with your Ledger Nano X with a Bluetooth connexion.                        |
| [buffer](https://www.npmjs.com/package/buffer)                                                                                     | The goal is to provide an API that is 100% identical to node's Buffer API.                                                  |#### Package.json DependenciesNow that the dependencies are installed you can find them in the "package.js".
This is how your "package.json" shoud look like:```javascript copy
{
  "name": "e2e-tutorial-contract",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.35.6",
    "@ledgerhq/hw-transport-web-ble": "^6.28.4",
    "@testing-library/jest-dom": "^5.17.0",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "bootstrap": "^5.3.3",
    "buffer": "^6.0.3",
    "eip55": "^2.1.1",
    "ethers": "^5.4.7",
    "next": "^14.1.3",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "build": "next build",
    "dev": "next dev",
    "start": "next start"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}
```## Web App Test### Start the Development ServerRun:```console copy
npm run dev
```> **Warning:** All the browser do not support the Bluetooth please look at the[{" "}browser support{" "}](https://caniuse.com/web-bluetooth).Now the application is up and running. Open the browser and go to `localhost:3000`, it will display :![Application Running on Browser](/device-interaction/tutorial-2-connect.png)
_Fig. 2: Application Running on Browse&#x72;_Don't click on the button yet.### Launch the Ethereum AppBefore clicking on the button, unlock your Nano X and run the Ethereum application.
The steps are described below.\
![Nano Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 3: Ledger Enter Code Pin\
![Embedded Application](/device-interaction/ledgerEth.jpg)Fig. 4: Ledger Application\
![Nano Run Application](/device-interaction/ledgerReady.jpg)Fig. 5: Application is running> **Warning:** For the tutorial to work, go to the Ethereum app settings and enable Blind
> Signing.### Connect Your Nano to the ApplicationNow you can click on the button and a popup opens. Choose your Ledger Nano X and click connexion.![Connect the Ledger with Bluetooth](/device-interaction/tutorial-2-pairing.png)
_Fig. 6: Connect the Ledger with Bluetooth_### Read the data of a Smart ContractNow you can click on the button "Get Data" to read the data of the smart contract. Then the data will be displayed on the screen.![Get data from a smart contract](/device-interaction/tutorial-2-getdata.png)
_Fig. 7: Get data from a smart contract_### Update the data of a Smart ContractNow instead of reading data, we will overwrite the data by calling a function of the smart contract which is "UpdateData".![Change data from a smart contract](/device-interaction/tutorial-2-changedata.png)
_Fig. 8: Change data from a smart contract_### Verify the Address on your NanoFor security reasons, the address will also be displayed on your Ledger Nano X to verify and confirm the address.\
![Nano Review Screen](/device-interaction/ledger-tx-review.jpg)\
![Nano Blind Signing alert](/device-interaction/ledger-blind-signing.png)\
![Nano Amount Screen](/device-interaction/ledger-tx-amount.jpg)Fig. 9: Nano Review ScreenFig. 10: Blind Signing info ScreenFig. 11: Nano Amount Screen\
![Nano Address Screen](/device-interaction/ledger-tx-address.jpg)\
![Nano Network Screen](/device-interaction/ledger-tx-network.png)Fig. 12: Nano Address ScreenFig. 13: Nano Network Screen\
![Nano Max Fees Screen](/device-interaction/ledger-tx-fees.jpg)\
![Nano Accept and Send Screen](/device-interaction/ledger-tx-accept.jpg)Fig. 14: Nano Max Fees ScreenFig. 15: Nano Accept and Send Screen> **Warning:** For the Smart Contract call you need to allow blind signing because the smart
> contract that is called in the tutorial is not yet verified and reviewed by
> Ledger. But if the smart contract you are calling is accepted by Ledger do not
> enable blind signing. Moreover, we do not recommend enabling blind signing in
> other situations as the main purpose to sign with Ledger is the 'Sign what you
> see' system. And by enabling blind signing it can not ensure that what you see
> is what you get.### Review the Transaction on Sepolia EtherscanBy updating the data a transaction is created to change this data, it can be verified on Sepolia Etherscan.![Sepolia Etherscan](/device-interaction/tutorial-2-etherscan1.png)\
_Fig. 15: Sepolia Ethersca&#x6E;_Wait till the status passes to Success.![Sepolia Etherscan](/device-interaction/tutorial-2-etherscan2.png)\
_Fig. 16: Sepolia Etherscan_### Verify the update of dataFinally, to verify if data was updated, open the web application and click on "Get data".![Verify the data](/device-interaction/tutorial-2-getdata2.png)\
_Fig. 17: Verify the data_![Verify the data](/device-interaction/tutorial-2-getdata3.png)\
_Fig. 18: Verify the dat&#x61;_Congratulations, you have successfully built your first application connected with Ledger!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/beginner/transfer-eth -->

# Transfer of Ethers between accounts## IntroductionIn this section, we will guide you through the creation of an application that:* creates a transaction
* signs it using the Ledger Nano then
* sends it to the blockchain.The purpose of the application is to transfer ethers from your ethereum account on your Ledger to another account.## Tutorial PrerequisitesBefore starting, make sure you have gone through the [prerequisites](../info#prerequisites).### Receive Ether token in your Ledger Nano Ethereum Sepolia account* Create an Ethereum Sepolia account in Ledger Live
* Send Sepolia Eth to your account with [Infura faucet](https://www.infura.io/faucet/sepolia). You will need to create an account that will be useful later for the API key.![Sepolia Ethereum Faucet](/device-interaction/tutorial-infura-sepolia-faucet.png)
_Fig. 1: Sepolia Ethereum Faucet_## Tutorial implementationIn this implementation, we will be building a web application with vanilla javascript that uses the HID protocol from a [Ledger package](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webhid) to communicate with the ledger.### Project InitializationIt is time to implement the application and test it. First, open a terminal and create a new folder. For this tutorial, the folder will be named "e2e-eth-tutorial”.
Run:```console copy
mkdir e2e-eth-tutorial
cd e2e-eth-tutorial
```Initialize the project by running the following:```console copy
npm init
```Answer the questions displayed or by default press enter. There is no incidence on the execution.Run:```console copy
touch index.html
touch index.js
touch style.css
mkdir assets
```Copy the logo in the assets folder.The folder will contain these files:![Folder tutorial](/device-interaction/folder-e2e-eth.png)
_Fig. 3: Folder of the Application_### Code Implementation#### index.htmlIn index.html copy-paste the following code :```html copy
<!DOCTYPE html>
<html>
  <head>
    <title>Parcel Sandbox</title>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="style.css" />
    <link
      href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css"
      rel="stylesheet"
      integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3"
      crossorigin="anonymous"
    />
    <script
      src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"
      integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p"
      crossorigin="anonymous"
    ></script>
    <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
    <script type="module" src="index.js"></script>
  </head>

  <body className="m-5">
    <div
      className="d-flex flex-column justify-content-center m-5 align-items-center"
    >
      <p>Click on the bellow button to connect your Ledger Wallet</p>
      <button
        className="btn btn-primary w-25"
        data-bs-toggle="modal"
        data-bs-target="#WalletModal"
      >
        Connect your Wallet
      </button>
    </div>
    <div className="d-flex flex-row">
      <div id="app" className="w-50">
        <form className="row g-3">
          <div className="col-md-12">
            <label for="wallet" className="form-label">Wallet Public Key</label>
            <input type="text" className="form-control" id="wallet" disabled />
          </div>
          <div className="col-md-12">
            <label for="recipient" className="form-label">Recipient</label>
            <input type="text" className="form-control" id="recipient" />
          </div>
          <div className="col-md-6">
            <label for="gasPrice" className="form-label"
              >Gas Price in wei</label
            >
            <input
              type="text"
              className="form-control"
              id="gasPrice"
              disabled
            />
          </div>
          <div className="col-md-6">
            <label for="gasLimit" className="form-label"
              >Gas Limit in wei</label
            >
            <input type="text" className="form-control" id="gasLimit" />
          </div>
          <div className="col-md-6">
            <label for="chainId" className="form-label">Chain ID</label>
            <input type="text" className="form-control" id="chainId" disabled />
          </div>
          <div className="col-md-6">
            <label for="value" className="form-label">Value</label>
            <input type="text" className="form-control" id="value" />
          </div>
          <div className="col-12">
            <button type="button" id="tx-transfer" className="btn btn-primary">
              Create Transaction
            </button>
          </div>
        </form>
      </div>
      <div className="w-50 d-flex flex-column">
        <p className="url">Ropsten etherscan:</p>
        <p id="url"></p>
      </div>
    </div>

    <!-- Modal -->
    <div
      className="modal fade"
      id="WalletModal"
      tabindex="-1"
      aria-labelledby="WalletModalLabel"
      aria-hidden="true"
    >
      <div className="modal-dialog">
        <div className="modal-content">
          <div className="modal-header">
            <h5 className="modal-title" id="WalletModalLabel">
              Choose your Wallet
            </h5>
            <button
              type="button"
              className="btn-close"
              data-bs-dismiss="modal"
              aria-label="Close"
            ></button>
          </div>
          <div className="modal-body d-flex justify-content-center">
            <button
              id="connect-ledger"
              className="rounded-3 align-self-center"
              data-bs-dismiss="modal"
            >
              <img
                src="./assets/ledger-logo.jpg"
                className="card-img-top"
                alt="Ledger"
              />
            </button>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```#### index.jsIn index.js copy-paste the following code and replace `{YOUR_INFURA_APIKEY}` by the API key you will find on your Infura account:```javascript copy
import { ethers } from "ethers";
import { InfuraProvider } from "ethers";
import TransportWebHID from "@ledgerhq/hw-transport-webhid";
import Eth from "@ledgerhq/hw-app-eth";
import ledgerService from "@ledgerhq/hw-app-eth/lib/services/ledger";

var ethers = require("ethers");
//Infuria provider for Sepolia network
const provider = new ethers.JsonRpcProvider(
  "https://sepolia.infura.io/v3/{YOUR_INFURA_APIKEY}",
);

const chainId = 11155111; // Sepolia chainId
let gasPrice;
let addressWallet;
let recipient = "0x920f19c7F7Ce5b3170AdB94fDcC4570Da95D286b";
let value = 0.001;
let gasLimit = 1000000;
let nonce;
let _eth;

document.getElementById("connect-ledger").onclick = async function () {
  //Connecting to the Ledger Nano with HID protocol
  const transport = await TransportWebHID.create();

  //Getting an Ethereum instance and get the Ledger Nano ethereum account public key
  _eth = new Eth(transport);
  const { address } = await _eth.getAddress("44'/60'/0'/0/0", false);

  //Get some properties from provider
  addressWallet = address;
  gasPrice = (await provider.getFeeData()).gasPrice;

  //Fill the inputs with the default value
  document.getElementById("wallet").value = address;
  document.getElementById("gasPrice").value = ethers.formatUnits(
    gasPrice,
    "wei",
  );
  document.getElementById("chainId").value = chainId;
  document.getElementById("value").value = value;
  document.getElementById("recipient").value = recipient;
  document.getElementById("gasLimit").value = gasLimit;
};

document.getElementById("tx-transfer").onclick = async function () {
  //Getting information from the inputs
  addressWallet = document.getElementById("wallet").value;
  recipient = document.getElementById("recipient").value;
  value = document.getElementById("value").value;
  gasLimit = parseInt(document.getElementById("gasLimit").value);
  nonce = await provider.getTransactionCount(addressWallet, "latest");

  //Building transaction with the information gathered
  const transaction = {
    to: recipient,
    gasPrice: "0x" + parseInt(gasPrice).toString(16),
    gasLimit: ethers.toBeHex(gasLimit),
    nonce: nonce,
    chainId: chainId,
    data: "0x00",
    value: ethers.toBeHex(ethers.parseUnits(value, "ether")),
  };

  //Serializing the transaction to pass it to Ledger Nano for signing
  let unsignedTx =
    ethers.Transaction.from(transaction).unsignedSerialized.substring(2);
  const resolution = await ledgerService.resolveTransaction(unsignedTx, {}, {});

  //Sign with the Ledger Nano (Sign what you see)
  const signature = await _eth.signTransaction(
    "44'/60'/0'/0/0",
    unsignedTx,
    resolution,
  );

  //Serialize the same transaction as before, but adding the parsed signature on it
  let signedTx = ethers.Transaction.from({
    ...transaction,
    signature: {
      r: "0x" + signature.r,
      s: "0x" + signature.s,
      v: parseInt(signature.v),
    },
  }).serialized;

  //Sending the transaction to the blockchain
  const hash = (await provider.broadcastTransaction(signedTx)).hash;

  //Display the Sepolia etherscan on the screen
  const url = "https://sepolia.etherscan.io/tx/" + hash;
  document.getElementById("url").innerHTML = url;
};
```#### style.cssIn style.css copy-paste the following code :```css copy
.modal-content {
  width: 300px;
  height: 400px;
}

#connect-ledger {
  width: 17rem;
  height: 9rem;
  background-color: white;
  border: none;
}

#connect-ledger:hover {
  background-color: #edeff3;
}

.modal-body {
  background-color: #f7f9fd;
}

#url,
.url {
  text-align: center;
  margin-top: 160px;
  color: green;
}
```### Dependencies Installation#### Install the packagesRun:```console copy
npm install --save-dev parcel
npm install --save @ledgerhq/hw-app-eth
npm install --save @ledgerhq/hw-transport-webhid
npm install --save ethers
```| Package                                                                                                                          | What does it do?                                                                         |
| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [parcel](https://parceljs.org/)                                                                                                  | It is a build tool that will help you package your application to run it in the browser. |
| [@ledgerhq/hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                   | It will help you ask your Ledger Nano to access the ethereum address.                    |
| [@ledgerhq/hw-transport-webhid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webhid) | It provides you with all the methods to interact with your Ledger with an HID connexion. |
| [ethers](https://docs.ethers.io/v5/)                                                                                             | It provides you with all the methods to interact with the ethereum blockchain.           |#### Modify Package.jsonModify the 5th line: `"main": "index.js"` => `"source": "index.html"`
And ensure you have this line in scripts:```javascript copy
  "scripts": {
    "start": "parcel"
  },
```Add this at the end of the script:```javascript copy
  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }
```Your file should now look like this:```javascript copy
{
    "name": "e2e-eth-tutorial",
    "version": "1.0.0",
    "description": "",
    "source": "index.html",
    "scripts": {
      "start": "parcel"
    },
    "author": "",
    "license": "ISC",
    "devDependencies": {
      "parcel": "^2.3.2"
    },
    "dependencies": {
      "@ledgerhq/hw-app-eth": "^6.26.0",
      "@ledgerhq/hw-transport-webhid": "^6.24.1",
      "ethers": "^5.5.4"
    },
    "alias": {
      "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
    }
}
```## Tutorial Test### Start the Development ServerNow that the Setup is finished, the app has to be built to be displayed.
Start the development server:```console copy
npm run start
```Now the application is up and running. Open the browser and go to `localhost:1234`, it will display :![Application running on browser](/device-interaction/tutorial-1-view.png)
_Fig. 5: Application Running on Browser_### Plug Your Ledger DeviceBefore clicking on the text connect your Ledger to the USB port, unlock it and run the ethereum application.
The steps are described below.\
![Nano Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 6: Nano Enter Code Pin\
![Run Ethereum Application on Ledger Nano](/device-interaction/ledgerEth.jpg)Fig. 7: Run Ethereum Application on Ledger Nano\
![Ethereum Application is Running on Ledger Nano](/device-interaction/ledgerReady.jpg)Fig. 8: Ethereum Application is Running on Ledger Nano### Connect Your Ledger to the ApplicationNow you can click on the "Connect your Wallet" button and a modal will be opened.
Click on the Ledger logo.![Choice of Wallet](/device-interaction/tutorial-1-connect.png)
_Fig. 9: Choice of Walle&#x74;_Now choose the Ledger Nano to connect it to the browser.![Connect the Ledger Nano](/device-interaction/tutorial-1-pairing.png)
_Fig. 10: Connect the Ledger Nan&#x6F;_If all goes well, the input fields will be filled with data. The greyed input is not to be changed and it is directly extracted either from the blockchain or from your Ledger Embedded application.![Application After Connecting Ledger Nano](/device-interaction/tutorial-1-view2.png)
_Fig. 11: Application After Connecting Ledger Nano_### Create a transaction to transfer ethereumNow that the inputs are filled with data. It is time to transfer some ether tokens from your Ledger ethereum account to another account (you can keep the default account on the "index.js" file).\
Therefore, click on "Create Transaction" to create the transaction which will be signed by your ledger before sending it to the blockchain.![Application After Connecting Ledger Nano](/device-interaction/tutorial-1-view2.png)
_Fig. 12: Application After Connecting Ledger Nan&#x6F;_When the transaction proceed and finalize, an URL will be displayed on the screen. This URL is a link to Ropsten Etherscan to review the transaction.\
There you can find all the information concerning the transaction you have previously sent.![Result after Sending Transaction](/device-interaction/tutorial-1-result.png)
_Fig. 13: Result after Sending Transactio&#x6E;_If you go on Etherscan you can see the information of your transaction.![Result after Sending Transaction](/device-interaction/tutorial-1-etherscan.png)
_Fig. 14: Transaction Information on Sepolia Ethersca&#x6E;_Congratulations, you have successfully built your first transfer application connected with Ledger !!!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/beginner/transfer-sol -->

# Transfer of Sol between accounts## IntroductionIn this section, we will guide you through the creation of an application. This application will create a transaction that will be signed with the Ledger Nano before sending it to the blockchain.
The purpose of the application is to transfer sol from your solana account on your Ledger to another account.## Tutorial PrerequisitesBefore starting, make sure you have gone through the [prerequisites](../info#prerequisites).### Install the Solana Embedded AppFirst you need to install the Solana Embedded App from Ledger Live as shown in the [prerequisites](../info#prerequisites) for Ethereum.## Tutorial implementationIn this implementation, we will be building a web application with vanilla javascript that uses the USB protocol from a [Ledger package](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webusb) to communicate with the ledger.### Project InitializationIt is time to implement the application and test it. First, open a terminal and create a new folder. For this tutorial, the folder will be named "e2e-sol-tutorial”.
Run:```console copy
mkdir e2e-sol-tutorial
cd e2e-sol-tutorial
```Then, initialize the project by running the following:```console copy
npm init
```Answer the questions displayed or by default press enter. There is no incidence on the execution.Run:```console copy
touch index.html
touch index.js
touch style.css
mkdir assets
```Put the logo in the assets folder and name it `ledger-logo`.The folder will contain these files:![Folder tutorial](/device-interaction/folder-e2e-sol.png)
_Fig. 1: Folder of the Application_### Code Implementation#### index.htmlIn index.html copy-paste the following code :```html copy
<!DOCTYPE html>
<html>
  <head>
    <title>Parcel Sandbox</title>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="style.css" />
    <link
      href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css"
      rel="stylesheet"
      integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3"
      crossorigin="anonymous"
    />
    <script
      src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"
      integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p"
      crossorigin="anonymous"
    ></script>
    <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
    <script type="module" src="index.js"></script>
  </head>

  <body class="m-5">
    <div
      class="d-flex flex-column justify-content-center m-5 align-items-center"
    >
      <p>Click on the bellow button to connect your Ledger Wallet</p>
      <div class="d-flex flex-row w-100 justify-content-around">
        <button
          class="btn btn-primary w-25"
          data-bs-toggle="modal"
          data-bs-target="#WalletModal"
        >
          Connect your Wallet
        </button>
        <button class="btn btn-primary w-25" id="get-information">
          Get Information
        </button>
      </div>
    </div>
    <div class="d-flex flex-row">
      <div id="app" class="w-50">
        <form class="row g-3">
          <div class="col-md-12">
            <label for="wallet" class="form-label">Wallet Public Key</label>
            <input type="text" class="form-control" id="wallet" disabled />
          </div>
          <div class="col-md-12">
            <label for="recipient" class="form-label" disabled>Balance</label>
            <input type="text" class="form-control" id="balance" />
          </div>
          <div class="col-md-12">
            <label for="recipient" class="form-label">Recipient</label>
            <input type="text" class="form-control" id="recipient" />
          </div>
          <div class="col-md-6">
            <label for="gasPrice" class="form-label"
              >Gas Price in lamports</label
            >
            <input type="text" class="form-control" id="gasPrice" disabled />
          </div>
          <div class="col-md-6">
            <label for="value" class="form-label">Value</label>
            <input type="text" class="form-control" id="value" />
          </div>
          <div class="col-12">
            <button type="button" id="tx-transfer" class="btn btn-primary">
              Create Transaction
            </button>
          </div>
        </form>
      </div>
      <div class="w-50 d-flex flex-column">
        <p class="url">Solana explorer:</p>
        <a id="url" href="" target="_blank"></a>
      </div>
    </div>

    <!-- Modal -->
    <div
      class="modal fade"
      id="WalletModal"
      tabindex="-1"
      aria-labelledby="WalletModalLabel"
      aria-hidden="true"
    >
      <div class="modal-dialog">
        <div class="modal-content">
          <div class="modal-header">
            <h5 class="modal-title" id="WalletModalLabel">
              Choose your Wallet
            </h5>
            <button
              type="button"
              class="btn-close"
              data-bs-dismiss="modal"
              aria-label="Close"
            ></button>
          </div>
          <div class="modal-body d-flex justify-content-center">
            <button
              id="connect-ledger"
              class="rounded-3 align-self-center"
              data-bs-dismiss="modal"
            >
              <img
                src="./assets/ledger-logo.png"
                class="card-img-top"
                alt="Ledger"
              />
            </button>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```#### index.jsIn index.js copy-paste the following code :```javascript copy
import * as SolanaWeb3 from "@solana/web3.js";
import TransportWebUSB from "@ledgerhq/hw-transport-webusb";
import Solana from "@ledgerhq/hw-app-solana";
import { listen } from "@ledgerhq/logs";
import bs58 from "bs58";

//Infuria provider for Solana devnet network
const connection = new SolanaWeb3.Connection(
  SolanaWeb3.clusterApiUrl("devnet"),
  "confirmed",
);

let transport;
let _sol;
let addressWallet;
let recipient = SolanaWeb3.Keypair.generate().publicKey;
let value = 0.1;
let gasPrice;

//listen to all errors thrown by the Transport
listen((log) => console.log(log));

document.getElementById("connect-ledger").onclick = async function () {
  //Connecting to the Ledger Nano with USB protocol
  transport = await TransportWebUSB.create();
};

document.getElementById("get-information").onclick = async function () {
  //Getting an Solana instance and get the Ledger Nano solana account public key
  _sol = new Solana(transport);
  const { address } = await _sol.getAddress("44'/501'/0'");
  addressWallet = new SolanaWeb3.PublicKey(bs58.encode(address));

  //Get some properties from provider
  const balance = await connection.getBalance(addressWallet);
  gasPrice = SolanaWeb3.LAMPORTS_PER_SOL / 100;

  //Fill the inputs with the default value
  document.getElementById("wallet").value = bs58.encode(address);
  document.getElementById("balance").value =
    balance / SolanaWeb3.LAMPORTS_PER_SOL;
  document.getElementById("gasPrice").value = parseInt(gasPrice) + " wei";
  document.getElementById("value").value = value;
  document.getElementById("recipient").value = recipient.toBase58();
};

document.getElementById("tx-transfer").onclick = async function () {
  //Getting information from the inputs
  recipient = new SolanaWeb3.PublicKey(
    document.getElementById("recipient").value,
  );
  value = document.getElementById("value").value;

  //Building transaction with the information gathered
  try {
    const recentBlockhash = await connection.getRecentBlockhash();
    const transaction = new SolanaWeb3.Transaction({
      feePayer: addressWallet,
      recentBlockhash: recentBlockhash.blockhash,
    }).add(
      SolanaWeb3.SystemProgram.transfer({
        fromPubkey: addressWallet,
        toPubkey: recipient,
        lamports: SolanaWeb3.LAMPORTS_PER_SOL * value,
      }),
    );

    //Serializing the transaction to pass it to Ledger Nano for signing
    const unsignedTx = transaction.serializeMessage();

    //Sign with the Ledger Nano (Sign what you see)
    const { signature } = await _sol.signTransaction("44'/501'/0'", unsignedTx);
    transaction.addSignature(addressWallet, signature);

    //Serialize the same transaction as before, but added the signature on it
    const signedTx = transaction.serialize();

    //Sending the transaction to the blockchain
    const hash = await connection.sendRawTransaction(signedTx, {
      preflightCommitment: "confirmed",
      skipPreflight: false,
    });

    //Display the Solana explorer url on the screen
    const url = "https://explorer.solana.com/tx/" + hash + "?cluster=devnet";
    document.getElementById("url").innerHTML = url;
    document.getElementById("url").href = url;
  } catch (error) {
    console.log(error);
  }
};
```#### style.cssIn style.css copy-paste the following code :```css copy
.modal-content {
  width: 300px;
  height: 400px;
}

#connect-ledger {
  width: 17rem;
  height: 9rem;
  background-color: white;
  border: none;
}

#connect-ledger:hover {
  background-color: #edeff3;
}

.modal-body {
  background-color: #f7f9fd;
}

#url,
.url {
  text-align: center;
  margin-top: 160px;
  color: green;
}
```### Dependencies Installation#### Install the packagesRun:```console copy
npm install --save-dev parcel
npm install --save @ledgerhq/hw-app-solana
npm install --save @ledgerhq/hw-transport-webusb
npm install --save @ledgerhq/logs
npm install --save @solana/web3.js
npm install --save bs58
```| Package                                                                                                                          | What does it do?                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [parcel](https://parceljs.org/)                                                                                                  | It is a build tool that will help you package your application to run it in the browser.                              |
| [@ledgerhq/hw-app-solana](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-solana)             | It will help you ask your Ledger Nano to access the solana application on the Ledger Nano.                            |
| [@ledgerhq/hw-transport-webusb](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webusb) | It provides you with all the methods to interact with your Ledger with an USB connexion.                              |
| [@ledgerhq/logs](https://www.npmjs.com/package/@ledgerhq/logs)                                                                   | It provides you the log of all the error from your connexion with your Ledger device that may appear when developing. |
| [@solana/web3.js](https://solana-labs.github.io/solana-web3.js/index.html)                                                       | It provides you with all the methods to interact with the solana blockchain.                                          |
| [bs58](https://www.npmjs.com/package/bs58)                                                                                       | It provides you with all the methods to compute base 58 encoding.                                                     |#### Modify Package.jsonModify the 5th line: `"main": "index.js"` => `"source": "index.html"`Ensure you have this line in scripts:```javascript copy
  "scripts": {
    "start": "parcel"
  },
```Add this at the end of the script:```javascript copy
  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }
```Your file should know look like this:```javascript copy
{
    "name": "e2e-sol-tutorial",
    "version": "1.0.0",
    "description": "",
    "source": "index.html",
    "scripts": {
        "start": "parcel"
    },
    "author": "",
    "license": "ISC",
    "devDependencies": {
        "parcel": "^2.3.2"
    },
    "dependencies": {
        "@ledgerhq/hw-app-solana": "^6.26.0",
        "@ledgerhq/hw-transport-webusb": "^6.24.1",
        "@ledgerhq/logs": "^6.10.0",
        "@solana/web3.js": "^1.36.0",
        "bs58": "^5.0.0"
    },
    "alias": {
        "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
    }
}
```## Tutorial Test### Start the Development ServerNow that the Setup is finished, the app has to be built to be displayed.
Start the development server:```console copy
npm run start
```Now the application is up and running. Open Chrome and go to `localhost:1234`, it will display :![Application running on browser](/device-interaction/tutorial-1-solana.png)
_Fig. 2: Application Running on Browser_### Plug Your Ledger DeviceBefore clicking on the text connect your Ledger to the USB port, unlock it and run the solana application.
The steps are described below.\
![Ledger Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 3: Ledger Enter Code Pin\
![Run Solana Application on Ledger Nano](/device-interaction/ledgerSol.jpg)Fig. 4: Run Solana Application on Ledger Nano\
![Ethereum Application is Running on Ledger Nano](/device-interaction/ledgerReady.jpg)Fig. 5: Solana Application is Running on Ledger Nano### Connect Your Ledger to the ApplicationNow you can click on the "Connect your Wallet" button and a modal will be opened.
Click on the Ledger logo.![Choice of Wallet](/device-interaction/tutorial-1-solana-wallet.png)\
_Fig. 6: Choice of Walle&#x74;_Now choose the Ledger Nano to connect it to the browser.![Connect the Ledger Nano](/device-interaction/tutorial-1-solana-pairing.png)
_Fig. 7: Connect the Ledger Nan&#x6F;_After connecting the Nano, click on "Get Information". If all goes well, the input fields will be filled with data. The greyed input is not to be changed and it is directly extracted either from the blockchain or from your Ledger Embedded application.![Application After Connecting Ledger Nano](/device-interaction/tutorial-1-solana-info.png)
_Fig. 8: Application After Connecting Ledger Nano_### Send Sol token to your Ledger Nano solana accountTo send some sol tokens on the Devnet network, you can either go to one of the solana faucet websites or do it with the solana cli:* [Solana Faucet](https://solfaucet.com/)
* [Solana CLI](https://docs.solana.com/cli/transfer-tokens)If you are looking for the easier and quicker way, use the Solana Faucet. If you would rather use the Solana CLI, please read this documentation to [install it](https://docs.solana.com/cli) before starting sending Sol.The Solana Devnet is not visible on Ledger Live, you can then check the transaction passed on [the Solana Explorer](https://explorer.solana.com/?cluster=devnet).#### Option n°1 - Solana FaucetGo to the [Solana Faucet](https://solfaucet.com/) website put your Wallet Public Key (displayed on the web app) on the input and click on "Devnet"![Solana Faucet](/device-interaction/solana-faucet.png)
_Fig. 9: Solana Faucet_#### Option n°2 -Solana CLIGo to the [Solana CLI](https://docs.solana.com/cli/transfer-tokens) website, there are the steps to add some sol to your account.```console copy
solana airdrop 1 <RECIPIENT_ACCOUNT_ADDRESS> --url https://api.devnet.solana.com
```For example```console copy
solana airdrop 1 72tCcW6F4gRWJLCXf3RGejNDZBwUvWCfxHTdxoLGV4ht --url https://api.devnet.solana.com
```### Create a transaction to transfer solNow that the inputs are filled with data. It is time to transfer some sol tokens from your Ledger solana account to another account (you can keep the default account on the "index.js" file).\
Therefore, click on "Create Transaction" to create the transaction which will be signed by your ledger before sending it to the blockchain.![Application After Connecting Ledger Nano](/device-interaction/tutorial-1-solana-create.png)
_Fig. 10: Application After Connecting Ledger Nan&#x6F;_When the transaction proceed and finalize, an URL will be displayed on the screen. This URL is a link to Solana Explorer to review the transaction.\
There you can find all the information concerning the transaction you have previously sent.![Result after Sending Transaction](/device-interaction/tutorial-1-solana-transaction.png)
_Fig. 11: Transaction Information UR&#x4C;_If you go on Solana Explorer you can see the information of your transaction.![Result after Sending Transaction](/device-interaction/solana-explorer-1.png)
_Fig. 12: Result on Solana Explorer after Sending Transaction_![Result after Sending Transaction](/device-interaction/solana-explorer-2.png)
_Fig. 13: Result on Solana Explorer after Sending Transactio&#x6E;_Congratulations, you have successfully built your first transfer application connected with Ledger !!!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/explanation/architecture-diagram -->

---
title: Architecture diagrams
discription: Understand how your application will interact with a device app.
---

# Architecture diagrams

## Application architecture

### Architecture Overview

![Ledger Live Prerequisites](/device-interaction/application-architecture.png)
_Fig. 1: Overall Architecture_

On the client side we have your core application containing your business logic and workflows.
You need to integrate at least the Device Management Kit or the LedgerJS Transport libraries in order to discuss with the Ledger device.

Some major networks have dedicated JS Library, like Bitcoin / Ethereum. You should use them if you are planning to integrate with these apps. This will provide a good abstraction level and allow you to use a proper SDK.
You can see how to use them in [Integration Walkthrough - Web USB/HID](../guides/web-application/web-hid-usb/).

### Nano API calls

This section describes what are the role of the Nano API.
Indeed we call Nano API the "LedgerJS Dedicated App Lib" on the above image at the top of the page.
You must have encontered few of the APIs if you have gone through the Integration Walkthrough.
In the Walkthroughs, we have mostly used the Bitcoin and Ethereum API provided by Ledger.

The Nano API role is to help you to carry out operations in the "Embedded Apps" (rf. image at the top).

The APIs are not written in the same way for all Embedded apps. In addition, while some of them are provided by ledger, others are written by the various crypto communities.

You can have a look at how they are coded and documented at the [LedgerHQ repository](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs).
You can also see the different Nano API provided by Ledger below.

#### Nano APIs provided by Ledger

Here is the list of all the APIs provided by Ledger.

| Blockchain | Nano API                                                                                                                                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Algorand   | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-algorand.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-algorand) [@ledgerhq/hw-app-algorand](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-algorand)              |
| Bitcoin    | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-btc.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-btc) [@ledgerhq/hw-app-btc](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-btc)                                  |
| Cosmos     | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-cosmos.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-cosmos) [@ledgerhq/hw-app-cosmos](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-cosmos)                      |
| Elrond     | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-elrond.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-elrond) [@ledgerhq/hw-app-elrond](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledger-live-common/src/families/elrond/hw-app-elrond) |
| Ethereum   | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-eth.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-eth) [@ledgerhq/hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                                  |
| Polkadot   | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-polkadot.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-polkadot) [@ledgerhq/hw-app-polkadot](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-polkadot)              |
| Solana     | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-solana.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-solana) [@ledgerhq/hw-app-solana](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-solana)                      |
| Stellar    | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-str.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-str) [@ledgerhq/hw-app-str](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-str)                                  |
| Tezos      | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-tezos.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-tezos) [@ledgerhq/hw-app-tezos](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-tezos)                          |
| Tron       | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-trx.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-trx) [@ledgerhq/hw-app-trx](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-trx)                                  |
| Ripple     | [![npm](https://img.shields.io/npm/v/@ledgerhq/hw-app-xrp.svg)](https://www.npmjs.com/package/@ledgerhq/hw-app-xrp) [@ledgerhq/hw-app-xrp](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-xrp)                                  |

#### Nano APIs provided by the crypto-asset community

You may find these libraries on the GitHub repositories written by the community.

We currently do not have an updated list of all community-developed Nano APIs. If you wish to contribute yours, please use the comment box at the bottom of this page.

Here is the list of all the APIs from the community that you can find on npm.

| Blockchain | Nano API                                                                                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vite       | [![npm](https://img.shields.io/npm/v/@vite/ledgerjs-hw-app-vite.svg)](https://www.npmjs.com/package/@vite/ledgerjs-hw-app-vite) [ledgerjs-hw-app-vite](https://github.com/vitelabs/ledgerjs-hw-app-vite)                                                                  |
| Ergo       | [![npm](https://img.shields.io/npm/v/ledgerjs-hw-app-ergo.svg)](https://www.npmjs.com/package/ledgerjs-hw-app-ergo) [ledgerjs-hw-app-ergo](https://github.com/tesseract-one/ledger-app-ergo)                                                                              |
| Cardano    | [![npm](https://img.shields.io/npm/v/@cardano-foundation/ledgerjs-hw-app-cardano.svg)](https://www.npmjs.com/package/@cardano-foundation/ledgerjs-hw-app-cardano) [@cardano-foundation/ledgerjs-hw-app-cardano](https://github.com/cardano-foundation/ledger-app-cardano) |
| Sia        | [![npm](https://img.shields.io/npm/v/@siacentral/ledgerjs-sia.svg)](https://www.npmjs.com/package/@siacentral/ledgerjs-sia) [@siacentral/ledgerjs-sia](https://github.com/siacentral/ledgerjs-sia)                                                                        |

### Nano API-less calls

When there is no available Nano API, the way to make your Nano calls is by constructing the ADPU call yourself, by using the syntax information found in each application documentation.

Here are some examples:

| Blockchain App | Application documentation                                                         |
| -------------- | --------------------------------------------------------------------------------- |
| Polymath       | [Polymath](https://github.com/LedgerHQ/app-polymesh/blob/master/docs/APDUSPEC.md) |
| Filecoin       | [Filecoin](https://github.com/LedgerHQ/app-filecoin/blob/master/docs/APDUSPEC.md) |

## Dataflow architecture

### Dataflow Overview

During a transaction handled by Ledger Device several exchanges are done between different application & hardware components.
These exchanges allow to read data from Ledger Device & Sign Transactions with internal private key without sharing it.

![Application Sequence Diagram](/device-interaction/application-sequence.png)
_Fig. 1: Application Sequence Diagram_

This diagram demonstrate the sequence of different calls done by each application layer during a transaction.
5 different layers are used to handle a transaction:

- **Your Application Core Code:** your software wallet
- **Ledger JS Transport API:** packages that allow you to implement several kind communication between the software wallet and a Ledger hardware wallet
- **Ledger JS Dedicated App Lib:** packages that allow you to communicate with specific Ledger Embedded Apps
- **Embedded App:** the application that run on a Ledger hardware wallet to interact with a specific blockchain
- **Ledger Device Software:** the operating system of Ledger harware devices

This workflow demonstrate a typical use case of Ledger Device using an Embedded App Lib. If you are planning to integrate with a embedded app with no API, you have to complete all actions done by LedgerJS Dedicated App Lib within your application core code.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/info -->

# Info note> **Warning:** LedgerJS Transport libraries are no longer maintained.For any new project, we recommend you use the Device Management Kit.For existing projects, you can still access the LedgerJS documentation but we recommend that you consider updating your integration.## Languages| Type of App | Required skills  |
| ----------- | ---------------- |
| Web App     | JavaScript       |
| Mobile App  | React Native     |
| Desktop App | Electron/Node.js |## Prerequisites### SummaryTo connect your app you will need to install:* [Node (for Desktop apps) and NPM](#node-and-npm)
* [Ledger Live](#ledger-live-installation)
* [The Ledger Embedded App](#embedded-app-installation) of the coin that you are going to use (to use this documentation you will need Bitcoin, Ethereum and Solana)
* At least [one account](#account-creation) for each coin (except for Solana).### Node and NPMIf not already installed, install [Node & npm](https://nodejs.org/en/download/), choose the LTS version of your operating system. You can check if you have it installed by checking the version with the following commands:```
$ node -v
v20.9.0

$ npm -v
10.5.0
```The commands should print the versions of Node.js and npm accordingly. Ensure Node.JS is 20.9.0.---### Ledger Live InstallationNow that node and npm are installed, you have to install the [Ledger Live](https://www.ledger.com/ledger-live) desktop application to connect your Ledger device.
After the installation, open Ledger Live and go to the **Manager** tab.![Ledger Live Prerequisites](/device-interaction/ledgerlivetabs.png)
_Fig. 1: Ledger Live Prerequisite&#x73;_Then connect your Ledger Nano to your computer and unlock it.![Ledger Device Unlock](/device-interaction/ledgerCodePin.jpg)Fig. 2: Ledger Device UnlockThen Ledger Live will ask you to allow the Ledger device, just press the two buttons simultaneously to allow it.![Ledger Live Animation](/device-interaction/ledgerConnect.png)Fig. 3: Ledger Live Animation\
![Ledger Live Notification on Ledger Device](/device-interaction/ledgerAllow.jpg)Fig. 4: Ledger Live Notification on Ledger Device### Embedded App InstallationNow you can install the Ethereum and bitcoin application into your Ledger Nano S/X/S Plus, as in the tutorials and walkthroughs, we will use the Ethereum and Bitcoin application.![Ethereum App Installation](/device-interaction/ethereumInstallation.png)
_Fig. 5: Ethereum App Installation_### Account CreationTo use the Bitcoin/Ethereum Embedded Apps you have to create a Bitcoin/Ethereum account.
We will present there the creation of a bitcoin account but it is the same for any application supported by Ledger Live.To create your Bitcoin account:* Launch the Bitcoin application on your Ledger Nano S/X/S Plus

* Open the Bitcoin app on your ledger device![Bitcoin App Launch](/device-interaction/ledgerBtc.jpg)Fig. 6: Bitcoin App Launch\
![Bitcoin App Ready](/device-interaction/ledgerReady.jpg)Fig. 7: Bitcoin App Ready* Create an account by going to the **Manager** tab and click on **Add account**.![Bitcoin App Add Account](/device-interaction/bitcoinInstalled.png)
_Fig. 8: Bitcoin App Add Account_* Click on **Add account** button.![Bitcoin Account Creation](/device-interaction/step1account.png)
_Fig. 9: Bitcoin Account Creation_* Your account is created.![Bitcoin Account Selection](/device-interaction/step2account.png)
_Fig. 10: Bitcoin Account Selectio&#x6E;_You have now a secured bitcoin account on your Ledger Device, congratulations!![Bitcoin Account Created](/device-interaction/step3account.png)
_Fig. 11: Bitcoin Account Created_

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/desktop-application/node-electron-hid -->

---
title: Node HID integration
description: In this section, we will guide you through the creation of a desktop electron application. This application will be connected to your Nano to display the address of your account (eg. bitcoin account, ethereum account).
---# Node HID integration## IntroductionIn this section, we will guide you through the creation of a desktop electron application. This application will be connected to your Nano to display the address of your account (eg. bitcoin account, ethereum account).Implementation for Web USB and Web HID on Nano S/X/S Plus.For this application we will use the Ledger node hid package which is [@ledgerhq/hw-transport-node-hid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-node-hid).## One-time setup### EnvironmentMake sure you have gone through the [prerequisites](../../info#prerequisites).## App Coding### App setupFirst, open a terminal and create a new folder. For this tutorial the folder will be named “examples-node-electron-hid”.From your `Github folder` or favourite `examples folder`, run:```console copy
mkdir examples-node-electron-hid
cd examples-node-electron-hid
```Then, initialize the project:```console copy
npm init
```Answer the questions displayed or by default press enter. There is no incidence on the execution.Run:```console copy
touch index.html
touch main.js
touch renderer.js
```The folder will contain these files:![Folder of the Application](/device-interaction/folderNodeHID.png)
_Fig. 1: Folder of the Application_### Files#### index.htmlIn index.html copy-paste the following code:```html copy
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Ledger Basic Electron HID</title>
    <style>
      #main {
        display: flex;
        flex-direction: column;
        align-items: center;
        justify-content: center;
        height: 100vh;
        font-family: sans-serif;
      }
      h1 {
        font-size: 32px;
      }
      h2 {
        font-size: 20px;
        font-weight: normal;
      }
    </style>
  </head>
  <body>
    <div id="main"></div>
    <script src="./renderer.js"></script>
  </body>
</html>
```#### main.jsIn main.js copy-paste the following code:```javascript copy
// Modules to control application life and create native browser window
require("babel-polyfill");
const TransportNodeHid = require("@ledgerhq/hw-transport-node-hid").default;
const AppBtc = require("@ledgerhq/hw-app-btc").default;
const { listen } = require("@ledgerhq/logs");

const { app, BrowserWindow, ipcMain } = require("electron");

// This a very basic example
// Ideally you should not run this code in main thread
// but run it in a dedicated node.js process
function getBitcoinInfo(verify) {
  return TransportNodeHid.open("")
    .then((transport) => {
      listen((log) => console.log(log));
      const appBtc = new AppBtc({ transport, currency: "bitcoin" });
      return appBtc
        .getWalletPublicKey("44'/0'/0'/0/0", {
          verify: verify,
          format: "legacy",
        })
        .then((r) =>
          transport
            .close()
            .catch((e) => {})
            .then(() => r),
        );
    })
    .catch((e) => {
      console.warn(e);
      // try again until success!
      return new Promise((s) => setTimeout(s, 1000)).then(() =>
        getBitcoinInfo(verify),
      );
    });
}

// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the JavaScript object is garbage collected.
let mainWindow;

function createWindow() {
  // Create the browser window.
  mainWindow = new BrowserWindow({
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
    },
  });

  // and load the index.html of the app.
  mainWindow.loadFile("index.html");

  // Open the DevTools.
  // mainWindow.webContents.openDevTools()

  // Emitted when the window is closed.
  mainWindow.on("closed", function () {
    // Dereference the window object, usually you would store windows
    // in an array if your app supports multi windows, this is the time
    // when you should delete the corresponding element.
    mainWindow = null;
  });

  // ~~~ BASIC LEDGER EXAMPLE ~~~

  ipcMain.on("requestBitcoinInfo", () => {
    getBitcoinInfo(false).then((result) => {
      mainWindow.webContents.send("bitcoinInfo", result);
    });
  });

  ipcMain.on("verifyBitcoinInfo", () => {
    getBitcoinInfo(true);
  });

  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
}

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.on("ready", createWindow);

// Quit when all windows are closed.
app.on("window-all-closed", function () {
  // On macOS it is common for applications and their menu bar
  // to stay active until the user quits explicitly with Cmd + Q
  if (process.platform !== "darwin") {
    app.quit();
  }
});

app.on("activate", function () {
  // On macOS it's common to re-create a window in the app when the
  // dock icon is clicked and there are no other windows open.
  if (mainWindow === null) {
    createWindow();
  }
});

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.
```#### renderer.jsIn renderer.js copy-paste the following code:```javascript copy
const electron = require("electron");
const { ipcRenderer } = electron;

document.getElementById("main").innerHTML =
  "<h1>Connect your Nano and open Bitcoin app...</h1>";

ipcRenderer.on("bitcoinInfo", (event, arg) => {
  const h1 = document.createElement("h2");
  h1.textContent = arg.bitcoinAddress;
  document.getElementById("main").innerHTML =
    "<h1>Your first Bitcoin address:</h1>";
  document.getElementById("main").appendChild(h1);
  ipcRenderer.send("verifyBitcoinInfo");
});

ipcRenderer.send("requestBitcoinInfo");
```### Dependencies#### InstallationRun:```console copy
npm install --save-dev electron
npm install --save babel-polyfill
npm install --save @ledgerhq/logs
npm install --save @ledgerhq/hw-app-btc
npm install --save browserify
npm install --save @ledgerhq/hw-transport-node-hid
```| Package                                                                                                                              | What does it do?                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| [Electron](https://www.electronjs.org/)                                                                                              | It is a build tool that will help you package your application to run it as a desktop application.                         |
| [Babel polyfill](https://www.npmjs.com/package/@babel/polyfill)                                                                      |                                                                                                                            |
| [@ledgerhq/logs](https://www.npmjs.com/package/@ledgerhq/logs)                                                                       | It provides you with the log of all the error from your connexion with your Ledger device that may appear when developing. |
| [@ledgerhq/hw-app-btc](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-btc)                       | It helps you ask your Ledger Nano to access the bitcoin address.                                                           |
| [Browserify](https://browserify.org/)                                                                                                | It helps you use "require" like Node does.                                                                                 |
| [@ledgerhq/hw-transport-node-hid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-node-hid) | It provides you with all the methods to interact with your Nano with an HID connexion.                                     |Since automatic polyfills have been removed in webpack 5, run the following command to avoid errors when building the app locally:```console copy
npm install node-polyfill-webpack-plugin
npm i stream
```#### Package.json1) Modify the 5th line: `"main": "index.js"` => `"source": "index.html"`
2) Ensure you have this line in scripts:```javascript copy
  "scripts": {
    "start": "electron"
  },
```Your file should know look like this:```javascript copy
{
  "name": "nodehid",
  "version": "1.0.0",
  "description": "",
  "source": "index.html",
  "scripts": {
    "start": "electron"
  },
  "devDependencies": {
    "electron": "^27.1.2"
  },
  "dependencies": {
    "@ledgerhq/hw-app-btc": "^10.1.0",
    "@ledgerhq/hw-transport-node-hid": "^6.28.0",
    "@ledgerhq/logs": "^6.12.0",
    "babel-polyfill": "^6.26.0",
    "browserify": "^17.0.0",
    "node-polyfill-webpack-plugin": "^2.0.1",
    "stream": "^0.0.2"
  }
}
```## App Launch### 1. Launch the AppNow that the Setup is finished, let's start the application.```console copy
node_modules/electron/dist/Electron.app/Contents/MacOS/Electron ./main.js
```Now the application is up and running. A window must have been launched on your machine, it will display:![Node Desktop Application](/device-interaction/electron-node-hid-window.png)\
_Fig. 2: Node Desktop Application_### 2. Plug Your Nano and open Bitcoin AppConnect your Nano to the USB port, unlock it and open the Bitcoin application.
The steps are described below.
If you do not have a Bitcoin account, or you want to created one for the purposes of this walkthrough, you can [create one here](../../getting-started#account-creation).\
![Nano Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 3: Nano Enter Code Pin\
![Embedded Application](/device-interaction/ledgerBtc.jpg)Fig. 4: Embedded Application\
![Nano Run Application](/device-interaction/ledgerReady.jpg)Fig. 5: Nano Run Application### 5. Check displayed addressCheck that the address displayed on the App is the same as the one displayed on the Ledger device.![Address Account Displayed](/device-interaction/electron-node-address.png)\
_Fig. 6: Address Account Displaye&#x64;_Congratulations you have successfully built your first Node Electron HID application connected to your Ledger!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/mobile-application/environment-setup -->

# Mobile Environment Setup## OverviewMake sure you have all of the following:\
---## Setup### Development Environment#### Android StudioDownload and install [Android Studio](https://developer.android.com/studio).
Choose the right version for your operating system.When Android Studio is installed, open it.![Android Studio Window](/device-interaction/android-studio.png)
_Fig. 1: Android Studio Windo&#x77;_Go to Settings => Appearance & Behaviour => System Settings => Android SDK
Check the "Show Package Details" checkbox on the bottom right of the windows.![Android Studio Settings](/device-interaction/android-studio-settings.png)
_Fig. 2: Android Studio Setting&#x73;_Install the latest SDK version. Select the packages shown below and click apply.![Android Studio SDK Settings](/device-interaction/android-studio-SDK.png)
_Fig. 3: Android Studio SDK Settings_#### XcodeTo develop an iOS application we have to install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) via the Mac App Store.When the installation is complete, open Xcode then go to Settings => Locations.![Xcode Settings](/device-interaction/Xcode-settings.png)
_Fig. 1: Xcode Setting&#x73;_Select the most recent version from the "Command Line Tools" dropdown.![Xcode Location Settings](/device-interaction/Xcode-locations.png)
_Fig. 2: Xcode Location Setting&#x73;_Finally, install cocoapods by running:```console copy
sudo gem install cocoapods
```### Install HomebrewHomebrew is a package manager for macOS. When it needs to install software from third-party websites. To install it, run:```console copy
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
```### Install WatchmanReact Native uses watchman to detect real-time code changes and it automatically builds and pushes the update to your device without manually refreshing.```console copy
brew install watchman
```### Install Java JRE and JDKThere is a risk of react-native build failure if you don’t have a complete installation of Java. Downloading Android Studio is not enough since it comes bundled with its own JRE.```console copy
brew install --cask adoptopenjdk/openjdk/adoptopenjdk8
```### Install React NativeWith React Native, you can write an application in Javascript and then the React Native Compiler will convert your Javascript code into native code for iOS and Android environments.
React Native command line interface can be installed using npm as below.```console copy
npm install -g react-native-cli
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/mobile-application/react-native-android-hid -->

---
title: React Native HID (Android only)
description: In this section, you will see how to create a React Native application using the @ledgerhq/react-native-hid (Only on Android).
---# React Native HID (Android only)## IntroductionIn this section, you will see how to create a React Native application using the [@ledgerhq/react-native-hid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/react-native-hid) (Only on Android).
For this project some general prerequisites are mandatory and you can find them [here](../../getting-started#prerequisites).Then you can now go through the prerequisite for Android development below.## One-time setup### EnvironnementMake sure you go through:1) the [prerequisites](../../info#prerequisites).
2) the [Mobile Environment Setup](./environment-setup).### Environnement variablesIf you are using bash, put the environment variable into the bash\_profile as below:```console copy
cd ~/
touch ~/.bash_profile;
open -e .bash_profile
``````console copy
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```Do the same if you are using zsh or anything else. Remember the file will be named differently (eg. zsh => .zprofile)## App CodingNow that we have set up the prerequisites, you can now create the application.
In this integration, we will use the ethereum application.### App setupFirst, open a terminal and create a new project. For this tutorial the project will be named “myAndroidHidApp”.Run:```console copy
react-native init myAndroidHidApp
cd myAndroidHidApp
```> **Note:** The dependencies of 'CocoaPods' may take some time to initialize.### FilesRun:```console copy
touch App.js
touch polyfill.js
```Open your folder in a code editor, it must look like this.\
![Folder of the Application](/device-interaction/folder-rn-android.png)Fig. 4: Folder of the Application#### polyfill.jsIn "polyfill.js", copy-paste the following code:```javascript copy
global.Buffer = require("buffer").Buffer;
```#### index.jsThen import the "polyfill.js" in "index.js" as shown below:```javascript copy
/**
 * @format
 */

import "./polyfill"; //import this
import { AppRegistry } from "react-native";
import App from "./App";
import { name as appName } from "./app.json";

AppRegistry.registerComponent(appName, () => App);
```#### App.jsIn App.js copy-paste the following code:```javascript copy
import React, { Component } from "react";
import { StyleSheet, Text, View } from "react-native";
import { listen } from "@ledgerhq/logs";

import TransportHID from "@ledgerhq/react-native-hid";
import AppEth from "@ledgerhq/hw-app-eth";

// This is helpful if you want to see BLE logs. (only to use in dev mode)

class App extends Component {
  state = {
    transport: null,
  };

  onSelectDevice = async () => {
    try {
      const transport = await TransportHID.create();
      listen((log) => console.log(log));
      const eth = new AppEth(transport);
      const path = "44'/60'/0'/0/0"; // HD derivation path
      const { address } = await eth.getAddress(path, false);
      this.setState({ transport: address });
      await eth.getAddress(path, true);
    } catch (e) {
      throw new Error(e);
      return null;
    }
  };

  render() {
    const { transport } = this.state;
    if (!transport) {
      return (
        <View style={styles.header}>
          <Text style={styles.headerTitle}>Scanning for Ledger...</Text>
          <Text
            style={styles.headerSubtitle}
            onPress={() => {
              this.onSelectDevice();
            }}
          >
            Power up your Ledger and enter your pin. Then tap the screen
          </Text>
        </View>
      );
    } else {
      return (
        <View style={styles.header}>
          <Text style={styles.title}>Ledger Live Ethereum Account 1</Text>
          <Text style={styles.headerTitle}>{transport}</Text>
        </View>
      );
    }
  }
}

export default App;

const styles = StyleSheet.create({
  header: {
    paddingTop: 80,
    paddingBottom: 36,
    alignItems: "center",
  },
  headerTitle: {
    fontSize: 22,
    marginBottom: 16,
  },
  headerSubtitle: {
    fontSize: 12,
    color: "#999",
  },
  list: {
    flex: 1,
  },
  errorTitle: {
    color: "#c00",
    fontSize: 16,
    marginBottom: 16,
  },
});
```### Dependencies#### InstallationRun:```console copy
npm install --save buffer
npm install --save @ledgerhq/logs
npm install --save @ledgerhq/hw-app-eth
npm install --save @ledgerhq/hw-transport-webusb
```| Package                                                                                                                    | What it does                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [buffer](https://www.npmjs.com/package/buffer)                                                                             | The goal is to provide an API that is 100% identical to node's Buffer API.                        |
| [@ledgerhq/logs](https://www.npmjs.com/package/@ledgerhq/logs)                                                             | It helps you ask your Ledger device to access the ethereum address.                               |
| [rxjs](https://www.npmjs.com/package/rxjs)                                                                                 | It is a rewrite of "Reactive-Extensions/RxJS" and is the latest production-ready version of RxJS. |
| [@ledgerhq/hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)             | It helps you ask your Ledger device to access the ethereum address.                               |
| [@ledgerhq/react-native-hid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/react-native-hid) | It provides you with all the methods to interact with your Ledger with an HID connexion.          |#### package.jsonNow that the dependencies are installed you can find them in the “package.js”.
This is how your “package.json” must look like.```javascript copy
{
  "name": "myAndroidHidApp",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "start": "react-native start",
    "test": "jest",
    "lint": "eslint ."
  },
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.15.2",
    "@ledgerhq/logs": "^6.10.0",
    "@ledgerhq/react-native-hid": "^6.11.2",
    "buffer": "^6.0.3",
    "react": "17.0.2",
    "react-native": "0.66.3"
  },
  "devDependencies": {
    "@babel/core": "^7.16.0",
    "@babel/runtime": "^7.16.3",
    "@react-native-community/eslint-config": "^3.0.1",
    "babel-jest": "^27.3.1",
    "eslint": "^8.3.0",
    "jest": "^27.3.1",
    "metro-react-native-babel-preset": "^0.66.2",
    "react-test-renderer": "17.0.2"
  },
  "jest": {
    "preset": "react-native"
  }
}
```#### Build.gradle ModificationIn “build.gradle”, in the "android" folder change `minSdkVersion = 21` to `minSdkVersion = 24`.![Build.gradle Modify the minSdkVersion](/device-interaction/change-minSDK.png)
_Fig. 5: Build.gradle Modify the minSdkVersio&#x6E;_You can now test the application you have built.## App LaunchApp testing is done on your smartphone because the Android Studio emulator cannot use Bluetooth or USB connexions.> **Note:** Please refer to the information for [Android Emulator
> Limitation](https://stackoverflow.com/questions/22604305/how-to-use-android-emulator-for-testing-bluetooth-application).### Enable Developer SettingsTo integrate an application on your Android smartphone you have to enable the developer role.
To do that go to Settings > About Phone > Build Number, and tap 7 times on build number to enable the developer settings.Then go to Settings > System > Advanced > Developer Options and enable the "USB debugging" as well as "Install via USB"Connect your phone to your computer, and run the command below to check your device is connected:```console copy
adb devices
```If all goes well, the list of devices is displayed as shown below:\
![Device Connected On The Machine](/device-interaction/adb-devices.png)Fig. 6: Device Connected On The Machine> **Note:** For more information about enabling the developer settings on your android
> device go to [android studio
> docs](https://developer.android.com/studio/debug/dev-options).### Start the Development ServerYou can now open a terminal, go to the "myAndroidHidApp" folder, and start the server by running:```console copy
npm start
```### Install the App on DeviceKeep the terminal where "metro" is running open and open a new terminal.
In this new terminal go to your app folder:```console copy
cd myAndroidHidApp
```Run the command below to install the application on your android device. It assumes your smartphone is connected and your device is recognized by the command `adb devices` as mentioned in the [Previous Step](#enable-developer-settings).```console copy
npm run android
```A window will pop up on your android device to install the application. Click on "Yes" to install it and run it.### Launching the AppWhen launching the application it will be displayed as the image below.\
![Application Displayed on Smartphone](/device-interaction/android-device-hid.jpg)Fig. 7: Application Displayed on Smartphone### Plug Your NanoConnect your Ledger Nano to your android device, unlock it and open the ethereum application.
The steps are described below.\
![Nano Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 8: Nano Enter Code Pin\
![Embedded Application](/device-interaction/ledgerEth.jpg)Fig. 9: Embedded Application\
![Nano Run Application](/device-interaction/ledgerReady.jpg)Fig. 10: Nano Run ApplicationNow that the two devices are connected, the address will be displayed as shown below:\
![Address Account Displayed on Smartphone](/device-interaction/android-device-hid-address.jpg)Fig. 11: Address Account Displayed on SmartphoneCongratulations you have successfully built your first Android HID application connected to your Ledger!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/mobile-application/react-native-bluetooth-android -->

# React Native Bluetooth on Android (Nano X only)## IntroductionIn this section you will see how to create a React Native application using the [@ledgerhq/react-native-hw-transport-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/react-native-hw-transport-ble).
For this project some general prerequisites are mandatory and you can find them [here](../../getting-started#prerequisites).Then you can now go through the prerequisite for Android development below.## One-time setup### EnvironnementMake sure you go through:1) the [prerequisites](../../info#prerequisites).
2) the [Mobile Environment Setup](./environment-setup).### Environnement variablesIf you are using bash, put the environment variable into the bash\_profile as below:```console copy
cd ~/
touch ~/.bash_profile;
open -e .bash_profile
``````console copy
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```Do the same if you are using zsh or anything else. Remember the file will be named differently (eg. zsh => .zprofile)## App CodingNow that we have set up the prerequisites, you can now create the application.
In this integration, we will use the ethereum application.### App setupFirst, open a terminal and create a new project. For this tutorial the project will be named “myAndroidBTApp”.Run:```console copy
react-native init myAndroidBTApp
cd myAndroidBTApp
```> **Note:** The dependencies of 'CocoaPods' may take some time to initialize.### FilesRun:```console copy
mkdir src
touch polyfill.js
touch src/DeviceItem.js
touch src/DeviceSelectionScreen.js
touch src/ShowAddressScreen.js
```#### polyfill.jsIn "polyfill.js", copy-paste the following code:```javascript copy
global.Buffer = require("buffer").Buffer;
```#### index.jsThen import the "polyfill.js" in "index.js" as shown below:```javascript copy
/**
 * @format
 */

import "./polyfill"; //import this
import { AppRegistry } from "react-native";
import App from "./src/App"; //modify this import
import { name as appName } from "./app.json";

AppRegistry.registerComponent(appName, () => App);
```#### App.jsMove the file named "App.js" in the "src" folder and copy-paste the following code:```javascript copy
import React, { Component } from "react";

import DeviceSelectionScreen from "./DeviceSelectionScreen";
import ShowAddressScreen from "./ShowAddressScreen";

import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";

// This is helpful if you want to see BLE logs. (only to use in dev mode)

class App extends Component {
  state = {
    transport: null,
  };

  onSelectDevice = async (device) => {
    const transport = await TransportBLE.open(device);
    transport.on("disconnect", () => {
      // Intentionally for the sake of simplicity we use a transport local state
      // and remove it on disconnect.
      // A better way is to pass in the device.id and handle the connection internally.
      this.setState({ transport: null });
    });
    this.setState({ transport });
  };

  render() {
    const { transport } = this.state;
    if (!transport) {
      return <DeviceSelectionScreen onSelectDevice={this.onSelectDevice} />;
    }
    return <ShowAddressScreen transport={transport} />;
  }
}

export default App;
```In "DeviceItem.js" copy-paste the following code:```javascript copy
import React, { Component } from "react";
import {
  Text,
  TouchableOpacity,
  StyleSheet,
  ActivityIndicator,
} from "react-native";

class DeviceItem extends Component {
  state = {
    pending: false,
  };
  onPress = async () => {
    this.setState({ pending: true });
    try {
      await this.props.onSelect(this.props.device);
    } finally {
      this.setState({ pending: false });
    }
  };

  render() {
    const { device } = this.props;
    const { pending } = this.state;
    return (
      <TouchableOpacity
        style={styles.deviceItem}
        onPress={this.onPress}
        disabled={pending}
      >
        <Text style={styles.deviceName}>{device.name}</Text>
        {pending ? <ActivityIndicator /> : null}
      </TouchableOpacity>
    );
  }
}
export default DeviceItem;

const styles = StyleSheet.create({
  deviceItem: {
    paddingVertical: 16,
    paddingHorizontal: 32,
    marginVertical: 8,
    marginHorizontal: 16,
    borderColor: "#ccc",
    borderWidth: 1,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
  },
  deviceName: {
    fontSize: 20,
    fontWeight: "bold",
  },
});
```In "DeviceSelectionScreen.js" copy-paste the following code:```javascript copy
import React, { Component } from "react";
import {
  StyleSheet,
  Text,
  View,
  TouchableOpacity,
  FlatList,
  Platform,
  PermissionsAndroid
} from "react-native";
import { Observable } from "rxjs";
import AppEth from "@ledgerhq/hw-app-eth";
import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";
import QRCode from "react-native-qrcode-svg";
import DeviceItem from "./DeviceItem";

const deviceAddition = device => ({ devices }) => ({
  devices: devices.some(i => i.id === device.id)
    ? devices
    : devices.concat(device)
});

class DeviceSelectionScreen extends Component {
  state = {
    devices: [],
    error: null,
    refreshing: false
  };

  async componentDidMount() {
    // NB: this is the bare minimal. We recommend to implement a screen to explain to user.
    if (Platform.OS === "android") {
      await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION
      );
    }
    let previousAvailable = false;
    new Observable(TransportBLE.observeState).subscribe(e => {
      if (e.available !== previousAvailable) {
        previousAvailable = e.available;
        if (e.available) {
          this.reload();
        }
      }
    });

    this.startScan();
  }

  componentWillUnmount() {
    if (this.sub) this.sub.unsubscribe();
  }

  startScan = async () => {
    this.setState({ refreshing: true });
    this.sub = new Observable(TransportBLE.listen).subscribe({
      complete: () => {
        this.setState({ refreshing: false });
      },
      next: e => {
        if (e.type === "add") {
          this.setState(deviceAddition(e.descriptor));
        }
        // NB there is no "remove" case in BLE.
      },
      error: error => {
        this.setState({ error, refreshing: false });
      }
    });
  };

  reload = async () => {
    if (this.sub) this.sub.unsubscribe();
    this.setState(
      { devices: [], error: null, refreshing: false },
      this.startScan
    );
  };

  keyExtractor = (item: *) => item.id;

  onSelectDevice = async device => {
    try {
      await this.props.onSelectDevice(device);
    } catch (error) {
      this.setState({ error });
    }
  };

  renderItem = ({ item }: { item: * }) => {
    return <DeviceItem device={item} onSelect={this.onSelectDevice} />;
  };

  ListHeader = () => {
    const { error } = this.state;
    return error ? (
      <View style={styles.header}>
        <Text style={styles.headerTitle}>Sorry, an error occured</Text>
        <Text style={styles.errorTitle}>{String(error.message)}</Text>
      </View>
    ) : (
      <View style={styles.header}>
        <Text style={styles.headerTitle}>Scanning for Bluetooth...</Text>
        <Text style={styles.headerSubtitle}>
          Power up your Ledger Nano X and enter your pin.
        </Text>
      </View>
    );
  };

  render() {
    const { devices, error, refreshing } = this.state;

    return (
      <FlatList
        extraData={error}
        style={styles.list}
        data={devices}
        renderItem={this.renderItem}
        keyExtractor={this.keyExtractor}
        ListHeaderComponent={this.ListHeader}
        onRefresh={this.reload}
        refreshing={refreshing}
      />
    );
  }
}

export default DeviceSelectionScreen;

const styles = StyleSheet.create({
  header: {
    paddingTop: 80,
    paddingBottom: 36,
    alignItems: "center"
  },
  headerTitle: {
    fontSize: 22,
    marginBottom: 16
  },
  headerSubtitle: {
    fontSize: 12,
    color: "#999"
  },
  list: {
    flex: 1
  },
  errorTitle: {
    color: "#c00",
    fontSize: 16,
    marginBottom: 16
  }
});
```In "ShowAddressScreen.js" copy-paste the following code:```javascript copy
import React, { Component } from "react";
import { StyleSheet, Text, View } from "react-native";

import AppEth from "@ledgerhq/hw-app-eth";
import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";
import QRCode from "react-native-qrcode-svg";

const delay = (ms) => new Promise((success) => setTimeout(success, ms));

class ShowAddressScreen extends Component {
  state = {
    error: null,
    address: null,
  };

  async componentDidMount() {
    while (!this.state.address) {
      if (this.unmounted) return;
      await this.fetchAddress(false);
      await delay(500);
    }
    await this.fetchAddress(true);
  }

  async componentWillUnmount() {
    this.unmounted = true;
  }

  fetchAddress = async (verify) => {
    const { transport } = this.props;
    try {
      const eth = new AppEth(transport);
      const path = "44'/60'/0'/0/0"; // HD derivation path
      const { address } = await eth.getAddress(path, verify);
      if (this.unmounted) return;
      this.setState({ address });
    } catch (error) {
      // in this case, user is likely not on Ethereum app
      if (this.unmounted) return;
      this.setState({ error });
      return null;
    }
  };

  render() {
    const { address, error } = this.state;

    return (
      <View style={styles.ShowAddressScreen}>
        {!address ? (
          <>
            <Text style={styles.loading}>Loading your Ethereum address...</Text>
            {error ? (
              <Text style={styles.error}>
                A problem occurred, make sure to open the Ethereum application
                on your Ledger Nano X. (
                {String((error && error.message) || error)})
              </Text>
            ) : null}
          </>
        ) : (
          <>
            <Text style={styles.title}>Ledger Live Ethereum Account 1</Text>
            <QRCode value={address} size={300} />
            <Text style={styles.address}>{address}</Text>
          </>
        )}
      </View>
    );
  }
}

export default ShowAddressScreen;

const styles = StyleSheet.create({
  ShowAddressScreen: {
    flex: 1,
    padding: 16,
    alignItems: "center",
    justifyContent: "center",
  },
  error: {
    color: "#c00",
    fontSize: 16,
  },
  loading: {
    color: "#999",
    fontSize: 16,
  },
  title: {
    fontSize: 22,
    marginBottom: 16,
  },
  address: {
    marginTop: 16,
    color: "#555",
    fontSize: 14,
  },
});
```The folder will contain these files:![Folder of the Application](/device-interaction/folder-rn-ble.png)
_Fig. 4: Folder of the Application_### Dependencies#### InstallationRun:```console copy
npm install --save react-native-qrcode-svg
npm install --save react-native-svg
npm install --save rxjs
npm install --save @ledgerhq/react-native-hw-transport-ble
npm install --save react-native-ble-plx
npx react-native link react-native-ble-plx
npm install --save buffer
npm install --save @ledgerhq/hw-app-eth
```| Package                                                                                                                            | What it does                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [react-native-qrcode-svg](https://www.npmjs.com/package/react-native-qrcode-svg)                                                   | It allows you to create a QR code.                                                                   |
| [react-native-svg](https://www.npmjs.com/package/react-native-svg)                                                                 | It is a mandatory package to use **react-native-qrcode-svg**                                         |
| [rxjs](https://www.npmjs.com/package/rxjs)                                                                                         | It is a rewrite of "Reactive-Extensions/RxJS" and is the latest production-ready version of RxJS.    |
| [@ledgerhq/hw-transport-web-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-web-ble) | It provides you with all the methods to interact with your Ledger Nano X with a Bluetooth connexion. |
| [react-native-ble-plx](https://www.npmjs.com/package/react-native-ble-plx)                                                         | It scans the bluetooth devices.                                                                      |
| [buffer](https://www.npmjs.com/package/buffer)                                                                                     | The goal is to provide an API that is 100% identical to node's Buffer API.                           |
| [hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                               | It helps you ask your Ledger device to access the ethereum address.                                  |#### package.jsonNow that the dependencies are installed you can find them in the “package.js”.
This is how your “package.json” has to look like.```javascript copy
{
  "name": "myAndroidBTApp",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "start": "react-native start",
    "test": "jest",
    "lint": "eslint ."
  },
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.16.2",
    "@ledgerhq/react-native-hw-transport-ble": "^6.15.0",
    "buffer": "^6.0.3",
    "react": "17.0.2",
    "react-native": "0.66.3",
    "react-native-ble-plx": "^2.0.3",
    "react-native-qrcode-svg": "^6.1.1",
    "react-native-svg": "^12.1.1",
    "rxjs": "^7.4.0"
  },
  "devDependencies": {
    "@babel/core": "^7.16.0",
    "@babel/runtime": "^7.16.3",
    "@react-native-community/eslint-config": "^3.0.1",
    "babel-jest": "^27.3.1",
    "eslint": "^8.3.0",
    "jest": "^27.3.1",
    "metro-react-native-babel-preset": "^0.66.2",
    "react-test-renderer": "17.0.2"
  },
  "jest": {
    "preset": "react-native"
  }
}

```#### Build.gradle ModificationIn “build.gradle”, in the "android" folder change `minSdkVersion = 21` to `minSdkVersion = 24`.![Build.gradle Modify the minSdkVersion](/device-interaction/change-minSDK.png)
_Fig. 5: Build.gradle Modify the minSdkVersio&#x6E;_You can now test the application you have built.## App LaunchApp testing is done on your smartphone because the Android Studio emulator cannot use Bluetooth or USB connexions.> **Note:** Please refer to the information for [Android Emulator Limitation](https://stackoverflow.com/questions/22604305/how-to-use-android-emulator-for-testing-bluetooth-application).### Enable Developer SettingsTo integrate an application on your Android smartphone you have to enable the developer role.
To do that go to Settings > About Phone > Build Number, and tap 7 times on build number to enable the developer settings.Then go to Settings > System > Advanced > Developer Options and enable the "USB debugging" as well as "Install via USB"Connect your phone to your computer, and run the command below to check your device is connected:```console copy
adb devices
```If all goes well, the list of devices is displayed as shown below:\
![Device Connected On The Machine](/device-interaction/adb-devices.png)Fig. 6: Device Connected On The Machine> **Note:** For more information about enabling the developer settings on your android
> device go to [android studio
> docs](https://developer.android.com/studio/debug/dev-options).### Start the Development ServerYou can now open a terminal, go to the "myAndroidBTApp" folder, and start the server by running:```console copy
npm start
```### Install the App on DeviceKeep the terminal where "metro" is running open and open a new terminal.
In this new terminal go to your app folder:```console copy
cd myAndroidBTApp
```Run the command below to install the application on your android device. It assumes your smartphone is connected and your device is recognized by the command `adb devices` as mentioned in the [Previous Step](#enable-developer-settings).```console copy
npm run android
```A window will pop up on your android device to install the application. Click on "Yes" to install it and run it.\
![Mobile Application Installation](/device-interaction/mobile-install-app.jpg)Fig. 7: Mobile Application Installation### Launching the AppWhen launching the application it will be displayed as the image below. You must have the Bluetooth and location activated.\
![Application Displayed on Smartphone](/device-interaction/android-rn-ble.jpg)Fig. 8: Application Displayed on SmartphoneIf this is not what you see, you may get:\
![Bluetooth Not Authorized](/device-interaction/android-ble-error.jpg)\
![App Settings 1](/device-interaction/android-settings-1.jpg)\
![App Settings 2](/device-interaction/android-settings-2.jpg)\
![App Settings 3](/device-interaction/android-settings-3.jpg)Fig. 9: Authorize the Bluetooth> **Note:** For more information about enabling the Bluetooth settings on your android
> device go to the troubleshooting tab.### Pairing the Ledger Nano XTo pair your Ledger Nano X, unlock it.\
![Nano Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 10: Nano Code PinNow try to pair the Ledger Nano X to your android smartphone.\
![Pairing the Ledger Nano X](/device-interaction/android-rn-ble-list.jpg)\
![Pairing the Ledger Nano X](/device-interaction/android-rn-pairing.jpg)Fig. 11: Pairing the Ledger Nano X### Pairing and Launching the Ethereum App on Nano XWhen pairing, the pairing code will be displayed on your Ledger Nano X to confirm.\
![Confirm the pairing](/device-interaction/ledgerPairing.jpg)Fig. 12: Confirm the pairing\
![Ethereum Application](/device-interaction/ledgerEth.jpg)Fig. 13: Ethereum Application\
![Nano Run Application](/device-interaction/ledgerReady.jpg)Fig. 14: Nano Run ApplicationNow that the pairing is complete, the Nano X is ready with the ethereum application.
If all goes well you see the address of your ethereum account displayed.\
![Address Account Displayed on Smartphone](/device-interaction/android-rn-ble-address.jpg)Fig. 15: Address Account Displayed on Smartphone### Verify the AddressFor security purposes, we display on your Nano X the same ethereum address for you to confirm.\
![Nano Verify Screen](/device-interaction/ledgerVerify.jpg)Fig. 16: Nano Verify Screen\
![Nano Verify Address Screen](/device-interaction/ledgerAddress.jpg)Fig. 17: Nano Verify Address Screen\
![Device Approve Screen](/device-interaction/ledgerApprove.jpg)Fig. 18: Device Approve ScreenCongratulations you have successfully built your first Android Bluetooth application connected to your Ledger!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/mobile-application/react-native-bluetooth-ios -->

# React Native Bluetooth on iOS (Nano X only)## IntroductionIn this section, you will see how to create a React Native application using the [@ledgerhq/react-native-hw-transport-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-web-ble).
For this project some general prerequisites are mandatory and you can find them [here](../../getting-started#prerequisites).Then you can now go through the prerequisite for iOS development below.## One-time setup### EnvironnementMake sure you go through:1) the [prerequisites](../../info#prerequisites).
2) the [Mobile Environment Setup](./environment-setup).## App CodingNow that we have set up the prerequisites, you can now create the application.
In this integration, we will use the ethereum application.### App setupFirst, open a terminal and create a new project. For this tutorial the project will be named “myiOSBTApp”.Run:```console copy
react-native init myiOSBTApp
cd myiOSBTApp
```> **Note:** The dependencies of 'CocoaPods' may take some time to initialize.### FilesRun:```console copy
mkdir src
touch polyfill.js
touch src/DeviceItem.js
touch src/DeviceSelectionScreen.js
touch src/ShowAddressScreen.js
```#### polyfill.jsIn "polyfill.js", copy-paste the following code:```javascript copy
global.Buffer = require("buffer").Buffer;
```#### index.jsThen import the polyfill in "index.js" as shown below:```javascript copy
/**
 * @format
 */

import "./polyfill"; //import this
import { AppRegistry } from "react-native";
import App from "./src/App"; //modify this import
import { name as appName } from "./app.json";

AppRegistry.registerComponent(appName, () => App);
```#### App.jsMove the file named "App.js" in the "src" folder and copy-paste the following code:```javascript copy
import React, { Component } from "react";

import DeviceSelectionScreen from "./DeviceSelectionScreen";
import ShowAddressScreen from "./ShowAddressScreen";

import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";

// This is helpful if you want to see BLE logs. (only to use in dev mode)

class App extends Component {
  state = {
    transport: null,
  };

  onSelectDevice = async (device) => {
    const transport = await TransportBLE.open(device);
    transport.on("disconnect", () => {
      // Intentionally for the sake of simplicity we use a transport local state
      // and remove it on disconnect.
      // A better way is to pass in the device.id and handle the connection internally.
      this.setState({ transport: null });
    });
    this.setState({ transport });
  };

  render() {
    const { transport } = this.state;
    if (!transport) {
      return <DeviceSelectionScreen onSelectDevice={this.onSelectDevice} />;
    }
    return <ShowAddressScreen transport={transport} />;
  }
}

export default App;
```In "DeviceItem.js" copy-paste the following code:```javascript copy
import React, { Component } from "react";
import {
  Text,
  TouchableOpacity,
  StyleSheet,
  ActivityIndicator,
} from "react-native";

class DeviceItem extends Component {
  state = {
    pending: false,
  };
  onPress = async () => {
    this.setState({ pending: true });
    try {
      await this.props.onSelect(this.props.device);
    } finally {
      this.setState({ pending: false });
    }
  };

  render() {
    const { device } = this.props;
    const { pending } = this.state;
    return (
      <TouchableOpacity
        style={styles.deviceItem}
        onPress={this.onPress}
        disabled={pending}
      >
        <Text style={styles.deviceName}>{device.name}</Text>
        {pending ? <ActivityIndicator /> : null}
      </TouchableOpacity>
    );
  }
}
export default DeviceItem;

const styles = StyleSheet.create({
  deviceItem: {
    paddingVertical: 16,
    paddingHorizontal: 32,
    marginVertical: 8,
    marginHorizontal: 16,
    borderColor: "#ccc",
    borderWidth: 1,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
  },
  deviceName: {
    fontSize: 20,
    fontWeight: "bold",
  },
});
```In "DeviceSelectionScreen.js", copy-paste the following code:```javascript copy
import React, { Component } from "react";
import {
  StyleSheet,
  Text,
  View,
  TouchableOpacity,
  FlatList,
  Platform,
  PermissionsAndroid
} from "react-native";
import { Observable } from "rxjs";
import AppEth from "@ledgerhq/hw-app-eth";
import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";
import QRCode from "react-native-qrcode-svg";
import DeviceItem from "./DeviceItem";

const deviceAddition = device => ({ devices }) => ({
  devices: devices.some(i => i.id === device.id)
    ? devices
    : devices.concat(device)
});

class DeviceSelectionScreen extends Component {
  state = {
    devices: [],
    error: null,
    refreshing: false
  };

  async componentDidMount() {
    // NB: this is the bare minimal. We recommend to implement a screen to explain to user.
    if (Platform.OS === "android") {
      await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION
      );
    }
    let previousAvailable = false;
    new Observable(TransportBLE.observeState).subscribe(e => {
      if (e.available !== previousAvailable) {
        previousAvailable = e.available;
        if (e.available) {
          this.reload();
        }
      }
    });

    this.startScan();
  }

  componentWillUnmount() {
    if (this.sub) this.sub.unsubscribe();
  }

  startScan = async () => {
    this.setState({ refreshing: true });
    this.sub = new Observable(TransportBLE.listen).subscribe({
      complete: () => {
        this.setState({ refreshing: false });
      },
      next: e => {
        if (e.type === "add") {
          this.setState(deviceAddition(e.descriptor));
        }
        // NB there is no "remove" case in BLE.
      },
      error: error => {
        this.setState({ error, refreshing: false });
      }
    });
  };

  reload = async () => {
    if (this.sub) this.sub.unsubscribe();
    this.setState(
      { devices: [], error: null, refreshing: false },
      this.startScan
    );
  };

  keyExtractor = (item: *) => item.id;

  onSelectDevice = async device => {
    try {
      await this.props.onSelectDevice(device);
    } catch (error) {
      this.setState({ error });
    }
  };

  renderItem = ({ item }: { item: * }) => {
    return <DeviceItem device={item} onSelect={this.onSelectDevice} />;
  };

  ListHeader = () => {
    const { error } = this.state;
    return error ? (
      <View style={styles.header}>
        <Text style={styles.headerTitle}>Sorry, an error occured</Text>
        <Text style={styles.errorTitle}>{String(error.message)}</Text>
      </View>
    ) : (
      <View style={styles.header}>
        <Text style={styles.headerTitle}>Scanning for Bluetooth...</Text>
        <Text style={styles.headerSubtitle}>
          Power up your Ledger Nano X and enter your pin.
        </Text>
      </View>
    );
  };

  render() {
    const { devices, error, refreshing } = this.state;

    return (
      <FlatList
        extraData={error}
        style={styles.list}
        data={devices}
        renderItem={this.renderItem}
        keyExtractor={this.keyExtractor}
        ListHeaderComponent={this.ListHeader}
        onRefresh={this.reload}
        refreshing={refreshing}
      />
    );
  }
}

export default DeviceSelectionScreen;

const styles = StyleSheet.create({
  header: {
    paddingTop: 80,
    paddingBottom: 36,
    alignItems: "center"
  },
  headerTitle: {
    fontSize: 22,
    marginBottom: 16
  },
  headerSubtitle: {
    fontSize: 12,
    color: "#999"
  },
  list: {
    flex: 1
  },
  errorTitle: {
    color: "#c00",
    fontSize: 16,
    marginBottom: 16
  }
});
```In "ShowAddressScreen.js", copy-paste the following code:```javascript copy
import React, { Component } from "react";
import { StyleSheet, Text, View } from "react-native";

import AppEth from "@ledgerhq/hw-app-eth";
import TransportBLE from "@ledgerhq/react-native-hw-transport-ble";
import QRCode from "react-native-qrcode-svg";

const delay = (ms) => new Promise((success) => setTimeout(success, ms));

class ShowAddressScreen extends Component {
  state = {
    error: null,
    address: null,
  };

  async componentDidMount() {
    while (!this.state.address) {
      if (this.unmounted) return;
      await this.fetchAddress(false);
      await delay(500);
    }
    await this.fetchAddress(true);
  }

  async componentWillUnmount() {
    this.unmounted = true;
  }

  fetchAddress = async (verify) => {
    const { transport } = this.props;
    try {
      const eth = new AppEth(transport);
      const path = "44'/60'/0'/0/0"; // HD derivation path
      const { address } = await eth.getAddress(path, verify);
      if (this.unmounted) return;
      this.setState({ address });
    } catch (error) {
      // in this case, user is likely not on Ethereum app
      if (this.unmounted) return;
      this.setState({ error });
      return null;
    }
  };

  render() {
    const { address, error } = this.state;

    return (
      <View style={styles.ShowAddressScreen}>
        {!address ? (
          <>
            <Text style={styles.loading}>Loading your Ethereum address...</Text>
            {error ? (
              <Text style={styles.error}>
                A problem occurred, make sure to open the Ethereum application
                on your Ledger Nano X. (
                {String((error && error.message) || error)})
              </Text>
            ) : null}
          </>
        ) : (
          <>
            <Text style={styles.title}>Ledger Live Ethereum Account 1</Text>
            <QRCode value={address} size={300} />
            <Text style={styles.address}>{address}</Text>
          </>
        )}
      </View>
    );
  }
}

export default ShowAddressScreen;

const styles = StyleSheet.create({
  ShowAddressScreen: {
    flex: 1,
    padding: 16,
    alignItems: "center",
    justifyContent: "center",
  },
  error: {
    color: "#c00",
    fontSize: 16,
  },
  loading: {
    color: "#999",
    fontSize: 16,
  },
  title: {
    fontSize: 22,
    marginBottom: 16,
  },
  address: {
    marginTop: 16,
    color: "#555",
    fontSize: 14,
  },
});
```Your folder will look like this.![Folder of the Application](/device-interaction/folder-rn-ble.png)
_Fig. 3: Folder of the Application_### Dependencies#### InstallationRun:```console copy
npm install --save react-native-qrcode-svg
npm install --save react-native-svg
npm install --save rxjs
npm install --save @ledgerhq/react-native-hw-transport-ble
npm install --save react-native-ble-plx
npx react-native link react-native-ble-plx
npm install --save buffer
npm install --save @ledgerhq/hw-app-eth
```| Package                                                                                                                            | What it does                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [react-native-qrcode-svg](https://www.npmjs.com/package/react-native-qrcode-svg)                                                   | It allows you to create a QR code.                                                                   |
| [react-native-svg](https://www.npmjs.com/package/react-native-svg)                                                                 | It is a mandatory package to use **react-native-qrcode-svg**                                         |
| [rxjs](https://www.npmjs.com/package/rxjs)                                                                                         | It is a rewrite of "Reactive-Extensions/RxJS" and is the latest production-ready version of RxJS.    |
| [@ledgerhq/hw-transport-web-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-web-ble) | It provides you with all the methods to interact with your Ledger Nano X with a Bluetooth connexion. |
| [react-native-ble-plx](https://www.npmjs.com/package/react-native-ble-plx)                                                         | It scans the bluetooth devices.                                                                      |
| [buffer](https://www.npmjs.com/package/buffer)                                                                                     | The goal is to provide an API that is 100% identical to node's Buffer API.                           |
| [hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                               | It helps you ask your Ledger device to access the ethereum address.                                  |#### package.jsonNow that the dependencies are installed you can find them in the “package.js”.
This is how your “package.json” has to look like.```javascript copy
{
  "name": "myiOSBTApp",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "start": "react-native start",
    "test": "jest",
    "lint": "eslint ."
  },
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.16.2",
    "@ledgerhq/react-native-hw-transport-ble": "^6.15.0",
    "buffer": "^6.0.3",
    "react": "17.0.2",
    "react-native": "0.66.3",
    "react-native-ble-plx": "^2.0.3",
    "react-native-qrcode-svg": "^6.1.1",
    "react-native-svg": "^12.1.1",
    "rxjs": "^7.4.0"
  },
  "devDependencies": {
    "@babel/core": "^7.16.0",
    "@babel/runtime": "^7.16.3",
    "@react-native-community/eslint-config": "^3.0.1",
    "babel-jest": "^27.3.1",
    "eslint": "^8.3.0",
    "jest": "^27.3.1",
    "metro-react-native-babel-preset": "^0.66.2",
    "react-test-renderer": "17.0.2"
  },
  "jest": {
    "preset": "react-native"
  }
}

```#### Pod InstallationThen the pod has to be installed in the "ios" folder:```console copy
cd ios/
pod install
pod update
```#### Enable BluetoothLaunch Xcode and open the ios folder in the "myiOSBTApp" folder to add the "NSBluetoothAlwaysUsageDescription" key to the "info.plist".![Open a Project on Xcode](/device-interaction/Xcode.png)
_Fig. 4: Open a Project on Xcode_![Choose the Project](/device-interaction/Xcode-project.png)
_Fig. 5: Choose the Project_![Add NSBluetoothAlwaysUsageDescription in info.plist](/device-interaction/infoplist.png)
_Fig. 6: Add NSBluetoothAlwaysUsageDescription in info.plis&#x74;_You can now test the application you have built.## App LaunchApp testing is done on your smartphone because the Xcode emulator cannot use Bluetooth or USB connexions.> **Note:** Please refer to the information for [iOS Emulator
> limitation](https://developer.apple.com/forums/thread/14983).### Build the AppTo build your application on your Apple device you have to connect Xcode to an Apple account as shown below.![Connect Xcode to an Apple Account](/device-interaction/Xcode-signing-capabilities.png)
_Fig. 7: Connect Xcode to an Apple Accoun&#x74;_Then connect your Apple device to your computer to build the application directly on the Apple device.
If all goes well the device name will be displayed on the top of the Xcode window, all you have to do is click on the triangle icon on the top left corner to build the app on your Apple device.![Build the Application](/device-interaction/Xcode-build.png)
_Fig. 8: Build the Application_### Trusting the Apple DevelopmentTo accept the installation of the application.
You have to trust the "Apple development" on your device. Follow the steps below.\
![Iphone Settings 1](/device-interaction/iphone-settings-1.png)\
![Iphone Settings 2](/device-interaction/iphone-settings-2.png)\
![Iphone Settings 3](/device-interaction/iphone-settings-3.png)\
![Iphone Settings 4](/device-interaction/iphone-settings-4.png)\
![Iphone Settings 5](/device-interaction/iphone-settings-5.png)Fig. 9: Trusting the Apple DevelopmentYou can finally test the application by launching it.### Launching the ApplicationWhen launching the application it will be displayed as shown below. You must have the Bluetooth and location activated.\
![Launching the Application](/device-interaction/iphone-rn-ble1.png)\
![Launching the Application](/device-interaction/iphone-rn-ble2.png)\
![Launching the Application](/device-interaction/iphone-rn-ble3.png)Fig. 10: Launching the Application### Pairing the Ledger Nano XTo pair your Ledger Nano X you must unlock it.\
![Nano Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 11: Nano Code PinPair the Ledger Nano X to your Apple device.\
![Pairing the Ledger Nano](/device-interaction/iphone-rn-ble4.png)\
![Pairing the Ledger Nano](/device-interaction/iphone-rn-ble5.png)Fig. 12: Pairing the Ledger Nano X### Pairing and Launching the Ethereum App on the Nano XThe pairing code displayed on your Ledger Nano X needs to be confirmed.\
![Confirm the pairing](/device-interaction/ledgerPairing.jpg)Fig. 13: Confirm the pairing\
![Embedded Application](/device-interaction/ledgerEth.jpg)Fig. 14: Embedded Application\
![Nano Run Application](/device-interaction/ledgerReady.jpg)Fig. 15: Nano Run ApplicationNow that the pairing is done, the Nano X is ready with the ethereum application.
If all goes well you must see the address of your ethereum account displayed.\
![Address Account Displayed on Smartphone](/device-interaction/iphone-rn-ble6.png)Fig. 16: Address Account Displayed on Smartphone### Verify the AddressFor security purposes, we display on your Nano X the same ethereum address for you to confirm.\
![Nano Verify Screen](/device-interaction/ledgerVerify.jpg)Fig. 17: Nano Verify Screen\
![Nano Verify Address Screen](/device-interaction/ledgerAddress.jpg)Fig. 18: Nano Verify Address Screen\
![Embedded Approve Screen](/device-interaction/ledgerApprove.jpg)Fig. 19: Embedded Approve ScreenCongratulations you have successfully built your first iOS Bluetooth application connected to your Ledger!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/web-application/web-bluetooth -->

---
title: Web Bluetooth
description: In this section, we will guide you through the creation of an application. This application will connect to your Ledger Nano X to display the address of your account (eg. bitcoin account, ethereum account).
---# Web Bluetooth## IntroductionIn this section, we will guide you through the creation of an application.\
This application will connect to your Ledger Nano X to display the address of your account (eg. bitcoin account, ethereum account).> **Warning:** **This walkthrough will only work with a Ledger Nano X**.\
> The Ledger Nano S and S Plus do not have `Bluetooth` connection.Please be aware that the Bluetooth implementation is only supported by a few browsers. \
> You can check if [your browser supports](https://caniuse.com/web-bluetooth) connections via Web Bluetooth.## One-time setup### EnvironmentMake sure you go through the [prerequisites](../../info#prerequisites).This web application is built with Next.js, which is a frontend React framework.## App Coding### App setupFirst, open a terminal and create a new project. For this tutorial the project will be named “examples-web-bluetooth”.From your `Github folder` or favourite `examples folder`, run:```console copy
npx create-next-app@latest examples-web-bluetooth
```You will prompted a series of questions, answer as indicated below:```console copy
Would you like to use TypeScript? No
Would you like to use ESLint? No
Would you like to use Tailwind CSS? No
Would you like to use `src/`directory” No
Would you like to use App Router? (recommended) › No
Would you like to customize the default import alias (@/*)? No
```Navigate to your app’s directory:```console copy
cd examples-web-bluetooth
```Open the folder in an editor. The folder will contain these files:![Folder of the Application](/device-interaction/folderWebBle.png)
_Fig. 1: Folder of the Application_### FilesFor this implemetation, you will only modify "index.js", "\_app.js", and "Home.module.css".#### index.jsIn pages/index.js replace the existing coe with the following:```javascript copy
export default function Home() {
  return (
    <div className={styles.container}>
      <App />
    </div>
  );
}
```#### \_app.jsIn pages/\_app.js replace the existing coe with the following:```javascript copy
import React, { Component } from "react";
import eip55 from "eip55";
import BluetoothTransport from "@ledgerhq/hw-transport-web-ble";
import AppEth from "@ledgerhq/hw-app-eth";
import styles from "../styles/Home.module.css";
import QRCode from "qrcode";

const delay = (ms) => new Promise((success) => setTimeout(success, ms));

class DeviceSelectionScreen extends Component {
  state = {
    devices: [],
  };

  createBLE = async () => {
    const transport = await BluetoothTransport.create();
    this.props.onSelectDevice(transport);
  };

  render() {
    return (
      <div className={styles.DeviceSelectionScreen}>
        <p>
          Power up your Ledger Nano X and enter your pin before continuing...
        </p>
        <button onClick={this.createBLE}>Connect with Bluetooth</button>
      </div>
    );
  }
}

class ShowAddressScreen extends Component {
  state = {
    error: null,
    address: null,
  };

  async componentDidMount() {
    while (!this.state.address) {
      if (this.unmounted) return;
      await this.fetchAddress(false);
      await delay(500);
    }
    this.fetchAddress(true);
    this.generateQRCode();
  }

  async componentWillUnmount() {
    this.unmounted = true;
  }

  fetchAddress = async (verify) => {
    const { transport } = this.props;
    try {
      const eth = new AppEth(transport);
      const path = "44'/60'/0'/0/0"; // HD derivation path
      const r = await eth.getAddress(path, verify);
      const address = eip55.encode(r.address);
      if (this.unmounted) return;
      this.setState({ address });
    } catch (error) {
      // in this case, user is likely not on Ethereum app
      console.warn("Failed: " + error.message);
      if (this.unmounted) return;
      this.setState({ error });
      return null;
    }
  };

  async generateQRCode() {
    try {
      const response = await QRCode.toCanvas(this.state.address);
      document.getElementById("qrcode").appendChild(response);
    } catch (error) {
      console.log(error);
    }
  }

  render() {
    const { address, error } = this.state;

    return (
      <div className={styles.ShowAddressScreen}>
        {!address ? (
          <>
            <p className={styles.loading}>Loading your Ethereum address...</p>
            {error ? (
              <p className={styles.error}>
                A problem occurred, make sure to open the Ethereum application
                on your Ledger Nano X. (
                {String((error && error.message) || error)})
              </p>
            ) : null}
          </>
        ) : (
          <>
            <strong>Ledger Live Ethereum Account 1</strong>
            <strong>{address}</strong>
            <div id="qrcode"></div>
          </>
        )}
      </div>
    );
  }
}

class App extends Component {
  state = {
    transport: null,
  };

  onSelectDevice = (transport) => {
    window.ledgerTransport = transport;
    transport.on("disconnect", () => {
      this.setState({ transport: null });
    });
    this.setState({ transport });
  };

  render() {
    const { transport } = this.state;
    return (
      <div className={styles.App}>
        {!transport ? (
          <DeviceSelectionScreen onSelectDevice={this.onSelectDevice} />
        ) : (
          <ShowAddressScreen transport={transport} />
        )}
      </div>
    );
  }
}

export default App;
```#### Home.module.cssIn Styles/Home.module.css replace the existing code with the following:```css copy
.container {
  min-height: 100vh;
  padding: 0 0.5rem;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  font-family:
    -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu",
    "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

.App {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.App .DeviceSelectionScreen {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.App .ShowAddressScreen {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.App .error {
  color: #a00;
}

.App .ShowAddressScreen strong {
  margin: 1em;
}
```#### Modify next.config.jsRemove `reactStrictMode: true,````
/** @type {import('next').NextConfig} */
const nextConfig = {}

module.exports = nextConfig
```### Dependencies#### InstallationRun:```console copy
npm install --save @ledgerhq/hw-app-eth
npm install --save @ledgerhq/hw-transport-web-ble
npm install --save eip55
```| Package                                                                                                                            | What does it do?                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [@ledgerhq/hw-app-eth](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-eth)                     | It will help you ask your Nano to access the ethereum address.                                       |
| [@ledgerhq/hw-transport-web-ble](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-web-ble) | It provides you with all the methods to interact with your Ledger Nano X with a Bluetooth connexion. |
| [eip55](https://www.npmjs.com/package/eip55)                                                                                       | An EIP55 compatible address encoding library.                                                        |#### Package.jsonNow that the dependencies are installed you can find them in the “package.js”.1) Modify Scripts
2) Check Contents##### Modify Scripts```javascript copy
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
```##### Check your “package.json” looks like this:```javascript copy
{
  "name": "test-bluetooth",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@ledgerhq/hw-app-eth": "^6.35.1",
    "@ledgerhq/hw-transport-web-ble": "^6.28.1",
    "eip55": "^2.1.1",
    "next": "14.0.4",
    "react": "^18",
    "react-dom": "^18"
  }
}
```## App Launch### Enable BluetoothMake sure the Bluetooth feature of your Nano is enabled. To check, see [here](https://support.ledger.com/hc/en-us/articles/360019115193-Access-Control-Center?docs=true).> **Warning:** If it was not enabled, you need to: 1. enable it 2. power OFF your Nano 3. and
> power it back ON.### Start de Development ServerNow that the Setup is finished, the app has to be available to be displayed.
Therefore start the development server:```console copy
npm run dev
```> **Warning:** Not all browsers support Bluetooth. \
> Please look at the [browser support page](https://caniuse.com/web-bluetooth).Now the application is up and running. Open the browser and go to `localhost:3000`, it will display :![Application Running on Browser](/device-interaction/webBle1.png)
_Fig. 2: Application Running on Browser_### Launch Ethereum AppBefore clicking on the button, unlock it and run the Ethereum application.
The steps are described below.\
![Nano Enter Code Pin](:connectivity/ledgerCodePin.jpg)Fig. 4: Nano Enter Code Pin\
![Embedded Application](/device-interaction/ledgerEth.jpg)Fig. 5: Embedded Application\
![Embedded App is Running](/device-interaction/ledgerReady.jpg)Fig. 6: The App is running### Connect Your Nano to the ApplicationNow you can click on the button and a popup will be prompt. Choose your Ledger Nano X and click connexion![Connect the Nano with Bluetooth](/device-interaction/webBle2.png)
_Fig. 7: Connect the Nano with Bluetoot&#x68;_Then another popup will be prompt to ask you to confirm the pairing![Request of Pairing](/device-interaction/webBle3.png)
_Fig. 8: Request of Pairin&#x67;_Finally, if all goes well the address must be displayed with the QR code![Address Account Displayed](/device-interaction/webBle4.png)
_Fig. 9: Address Account Displayed_### Verify the Address on NanoFor security reasons, the address will also be displayed on your Ledger Nano X to verify and confirm the address.\
![Nano Verify Screen](/device-interaction/ledgerVerify.jpg)Fig. 10: Nano Verify Screen\
![Nano Verify Address Screen](/device-interaction/ledgerAddress.jpg)Fig. 11: Nano Verify Address Screen\
![Embedded Approve Screen](/device-interaction/ledgerApprove.jpg)Fig. 12: Embedded Approve ScreenCongratulations you have successfully built your first application connected to your Ledger Nano X!

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/integration/web-application/web-hid-usb -->

---
title: Web USB/HID
description: In this section, we will guide you through the creation of a web application. This application will connect to your Nano to display the address of a Bitcoin account. If you want it for Ethereum you can easily modify it.
---# Web USB/HID## IntroductionIn this section, we will guide you through the creation of a web application.\
The instructions for Web USB and Web HID are very similar, with only a few lines to comment out, so this is a combined walkthrough.\
This application will connect to your Nano to display the address of a Bitcoin account.
You can easily modify the code, if you want it for Ethereum.Reference note: the packages referenced here are\
Web USB: [@ledgerhq/hw-transport-webusb](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webusb)\
Web HID: [@ledgerhq/hw-transport-webhid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webhid).## One-time setupMake sure you go through the [prerequisites](../../info#prerequisites).## App Coding (Desktop)### App setupFor this tutorial, the folder will be named `example-web-hid-usb`, so that it can be used for either Web USB or Web HID.From your `Github folder` or favourite `examples folder`, run:```console copy
mkdir example-web-hid-usb
cd example-web-hid-usb
```Initialize the project by running:```console copy
npm init
```Answer the questions displayed or by default press enter. There is no incidence on the execution.Run:```console copy
mkdir src
touch src/index.html
touch src/main.js
```The folder will contain these files:![Folder USB and HID](/device-interaction/folderUsbHid.png)
_Fig. 1: File structure_### FilesOpen the folder example-web-hid-usb in an code editor.#### index.htmlIn index.html copy-paste the following code :```html copy
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My First Embedded App</title>
    <script type="module" src="main.js"></script>
  </head>
  <body id="main"></body>
</html>
```#### main.jsIn main.js copy-paste the following code:> **Warning:** Comment out or remove the `import` package you don't need \
> (`@ledgerhq/hw-transport-webusb` or `@ledgerhq/hw-transport-webhid`) \
> and the `const transport` you don't use.```javascript copy
import "core-js/actual";
import { listen } from "@ledgerhq/logs";
import AppBtc from "@ledgerhq/hw-app-btc";

// Keep this import if you want to use a Ledger Nano S/X/S Plus with the USB protocol and delete the @ledgerhq/hw-transport-webhid import
import TransportWebUSB from "@ledgerhq/hw-transport-webusb";
// Keep this import if you want to use a Ledger Nano S/X/S Plus with the HID protocol and delete the @ledgerhq/hw-transport-webusb import
import TransportWebHID from "@ledgerhq/hw-transport-webhid";

//Display the header in the div which has the ID "main"
const initial =
  "<h1>Connect your Nano and open the Bitcoin app. Click anywhere to start...</h1>";
const $main = document.getElementById("main");
$main.innerHTML = initial;

document.body.addEventListener("click", async () => {
  $main.innerHTML = initial;
  try {
    // Keep if you chose the USB protocol
    const transport = await TransportWebUSB.create();

    // Keep if you chose the HID protocol
    const transport = await TransportWebHID.create();

    //listen to the events which are sent by the Ledger packages in order to debug the app
    listen((log) => console.log(log));

    //When the Ledger device connected it is trying to display the bitcoin address
    const appBtc = new AppBtc({ transport, currency: "bitcoin" });
    const { bitcoinAddress } = await appBtc.getWalletPublicKey(
      "44'/0'/0'/0/0",
      { verify: false, format: "legacy" },
    );

    //Display your bitcoin address on the screen
    const h2 = document.createElement("h2");
    h2.textContent = bitcoinAddress;
    $main.innerHTML = "<h1>Your first Bitcoin address:</h1>";
    $main.appendChild(h2);

    //Display the address on the Ledger device and ask to verify the address
    await appBtc.getWalletPublicKey("44'/0'/0'/0/0", {
      format: "legacy",
      verify: true,
    });
  } catch (e) {
    //Catch any error thrown and displays it on the screen
    const $err = document.createElement("code");
    $err.style.color = "#f66";
    $err.textContent = String(e.message || e);
    $main.appendChild($err);
  }
});
```### Dependencies#### InstallationRun:```console copy
npm install --save core-js
npm install --save @ledgerhq/logs
npm install --save-dev parcel
npm install --save @ledgerhq/hw-app-btc
```| Package                                                                                                        | What does it do?                                                                                               |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [core-js](https://www.npmjs.com/package/core-js)                                                               | Modular standard library for JavaScript.                                                                       |
| [@ledgerhq/logs](https://www.npmjs.com/package/@ledgerhq/logs)                                                 | It provides you the log of all the errors from your connection with your Nano that may appear when developing. |
| [parcel](https://parceljs.org/)                                                                                | It is a build tool that will help you package your application to run it in the browser.                       |
| [@ledgerhq/hw-app-btc](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-btc) | It will help you ask your Nano to access the Bitcoin address.                                                  |#### Install the Transport HID or USB packageThen depending on your choice install one of the corresponding packages:* Install the Ledger package [@ledgerhq/hw-transport-webhid](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webhid) which provide you with all the methods to interact with your Nano with an HID connection:
  ```console copy
  npm install --save @ledgerhq/hw-transport-webhid
  ```
* Install the Ledger package [@ledgerhq/hw-transport-webusb](https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-transport-webusb) which provide you with all the methods to interact with your Nano with a USB connection:
  ```console copy
  npm install --save @ledgerhq/hw-transport-webusb
  ```#### Package.jsonModify `"main": "index.js"` to `"source": "src/index.html"`.And ensure you have this line in your package.json:```javascript copy
  "scripts": {
    "build": "parcel build",
    "start": "parcel"
  },
```Add this at the end of the script:```javascript copy
  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }
```Your "package.json" should look like this:> **Warning:** In the `dependencies` section of package.json, comment out or remove the line
> you don't need \
> (`@ledgerhq/hw-transport-webusb` or `@ledgerhq/hw-transport-webhid`) \
> Do not copy-paste as is, without removing the other line.```javascript copy
{
  "name": "update-doc-web-hid-usb",
  "version": "1.0.0",
  "description": "",
  "source": "src/index.html",
  "dependencies": {
    "@ledgerhq/hw-app-btc": "^10.1.0",
    "@ledgerhq/hw-transport-webhid": "^6.28.0",
    "@ledgerhq/hw-transport-webusb": "^6.28.4",
    "@ledgerhq/logs": "^6.12.0",
    "core-js": "^3.33.3"
  },
  "scripts": {
    "build": "parcel build",
    "start": "parcel"
  },
  "devDependencies": {
    "buffer": "^6.0.3",
    "parcel": "^2.10.3",
    "process": "^0.11.10",
    "stream-browserify": "^3.0.0"
  },
  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }
}
```## App Launch### 1. Start the ServerNow that the Setup is finished, the app has to be built to be displayed.
Start the development server:```console copy
npm run start
```### 2. Launch the AppNow the application is up and running. Open the browser and go to `localhost:1234`, it will display :![Application running on browser](/device-interaction/webapp1.png)
_Fig. 3: Application Running on Browse&#x72;_Before clicking on the text connect your Nano to the USB port, unlock it and run the bitcoin application. The steps are described below.### 3. Plug your Nano![Nano Enter Code Pin](/device-interaction/ledgerCodePin.jpg)Fig. 4: Enter Pin\
![Select Bictoin](/device-interaction/ledgerBtc.jpg)Fig. 5: Select Bictoin\
![Embedded Run Application](/device-interaction/ledgerReady.jpg)Fig. 6: Embedded Run Application### 4. Connect the ApplicationNow you can click on the text and a popup will be prompt. Choose your Nano and click connect:![Connect your Nano](/device-interaction/webapp2.png)
_Fig. 7: Connect your Nano_### 5. Check displayed addressThe App gets the Bitcoin address and displays it.\
Check that the address displayed on the App is the same as the one displayed on the Ledger device.![Address Account Displayed](/device-interaction/webapp3.png)
_Fig. 8: Address Account Displaye&#x64;_Congratulations, you have successfully built your first application connected to a Nano!> **Note:** Note that if your finalize the operation on your Nano by accepting or
> rejecting, the corresponding message appears on your web application.## App Coding (Android Chrome)Android chrome supports HID and USB.\
For smartphones, only Android supports web applications.\
For Android, only Chrome supports web application.### package.jsonTo test your application on android, a little change has to be made.\
Add the `--https` flag in your `"start"` script> **Warning:** In the `dependencies` section of package.json, comment out or remove the line
> you don't need \
> (`@ledgerhq/hw-transport-webusb` or `@ledgerhq/hw-transport-webhid`) \
> Do not copy-paste as is, without removing the other line.```javascript copy
{
  "name": "example-web-hid-usb",
  "version": "1.0.0",
  "description": "",
  "source": "src/index.html",
  "dependencies": {
    "@ledgerhq/hw-app-btc": "^6.12.1",
    "@ledgerhq/hw-transport-webhid": "^6.11.2",
    "@ledgerhq/hw-transport-webusb": "^6.11.2",
    "@ledgerhq/logs": "^6.10.0",
    "core-js": "^3.20.2"
  },
  "devDependencies": {
    "parcel": "^2.0.0"
  },
  "scripts": {
    "build": "parcel build",
    "start": "parcel --https"
  },
  "author": "",
  "license": "ISC"
}
```The browser will warn that the website is malicious, to continue, click on "advanced settings" and then on "continue to the localhost site". Now you can test to connect your Nano on your Android.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/ledgerjs/references/identifiers -->

---
title: Where can I find the devices USB identifiers?
---

# Where can I find the devices USB identifiers?

USB identifiers are essential for applications that need to detect and communicate with Ledger hardware wallets. These identifiers consist of **Vendor ID (VID)** and **Product ID (PID)** pairs that uniquely identify different Ledger device models.

## What are USB identifiers?

USB identifiers are standardized codes used by the USB protocol to identify connected devices:

- **Vendor ID (VID)**: Identifies the manufacturer (Ledger uses `0x2c97`)
- **Product ID (PID)**: Identifies the specific device model within that vendor's product line

## When do you need them?

You'll need these identifiers when:

- Building applications that detect Ledger devices automatically
- Implementing device filtering in transport layers
- Setting up USB permissions for desktop applications
- Configuring device access rules in operating systems

## Available identifiers

The complete list of Devices USB identifiers can be found in the [ledger-live repository](https://github.com/LedgerHQ/ledger-live/blob/develop/libs/ledgerjs/packages/devices/src/index.ts).

This file contains:

- **Device descriptors** for all Ledger hardware wallet models (Nano S, Nano S Plus, Nano X, Flex, Stax, etc.)
- **USB product IDs** for each device variant
- **Device capabilities** and supported communication protocols
- **Bootloader mode identifiers** for firmware update scenarios

---

**Note**: The repository linked above is part of the official Ledger Live monorepo and is the authoritative source maintained by the Ledger team.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/device-management-kit/secure-channel -->

---
title: "Secure Channel"
category: reference
---

# Secure Channel

The secure connection is established between the connected device and Ledger HSM backend service via WebSocket. The following device actions will be executed with the secure connection.

1. **Genuine Check Device Action**: Verifies the genuineness of the connected device.
2. **List Installed Apps Device Action**: Lists all installed applications on the device.
3. **Install App Device Action**: Installs a specified application on the device by name.
4. **Uninstall App Device Action**: Uninstalls a specified application from the device name.

All device actions below may require a specific user interaction(`AllowSecureConnection`) during execution. However, this interaction is only requested **once per device reboot**.

## 🔹 Index

1. [Genuine Check Device Action](#genuine-check-device-action)
2. [List Installed Apps Device Action](#list-installed-apps-device-action)
3. [Install App Device Action](#install-app-device-action)
4. [Uninstall App Device Action](#uninstall-app-device-action)

## 🔹 Device Actions

### Genuine Check Device Action

This device action checks the genuineness of the connected device. It returns `true` if the device is genuine, and `false` otherwise. This step is typically performed first to ensure the device's integrity before executing other operations.

#### **Input**

- `unlockTimeout`
  - Optional
  - Type: `number`
  - The maximum waiting time for the user to unlock the device

#### **Output**

- `isGenuine`
  - **Type**: `boolean`
  - The result indicates whether the device is genuine

#### **Intermediate Value**

- `requiredUserInteraction`
  - **Type**: `UserInteractionRequired`
  - The user interactions that are required during the execution of the device action.

```typescript
import {
  GenuineCheckDeviceAction,
  GenuineCheckDAState,
  DeviceActionStatus,
  UserInteractionRequired,
} from "@ledgerhq/device-management-kit";

const deviceAction = new GenuineCheckDeviceAction({
  input: { unlockTimeout: 60000 },
});

const { observable, cancel } = await dmk.executeDeviceAction({
  deviceAction,
});

observable.subscribe({
  next: (state: GenuineCheckDAState) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        switch (requiredUserInteraction) {
          case UserInteractionRequired.None:
            console.log("No user action required");
            break;
          case UserInteractionRequired.AllowSecureConnection:
            console.log(
              "User should allow the secure connection on the device",
            );
            break;
          case UserInteractionRequired.UnlockDevice:
            console.log("User should unlock the device");
            break;
          default:
            throw new Error("Unknown user interaction required");
        }
        break;
      case DeviceActionStatus.Completed:
        const { output } = state;
        console.log("Device action completed", output);
        break;
      case DeviceActionStatus.Error:
        const { error } = state;
        console.log("Error occurred during the execution", error);
        break;
    }
  },
});
```

### List Installed Apps Device Action

This device action retrieves a list of all applications currently installed on the connected device. It will **not** request the `AllowListApps` user permission to execute.

#### **Input**

- `unlockTimeout`
  - Optional
  - Type: `number`
  - The maximum waiting time for the user to unlock the device.

#### **Output**

- `installedApps`
  - **Type**: `Array<InstalledApp>`
  - All installed apps on the connected device.

#### **Intermediate Value**

- `requiredUserInteraction`
  - **Type**: `UserInteractionRequired`
  - The user interactions that are required during the execution of the device action.

```typescript
import {
  DeviceActionStatus,
  UserInteractionRequired,
  ListInstalledAppsDeviceAction,
  ListInstalledAppsDAState,
} from "@ledgerhq/device-management-kit";

const deviceAction = new ListInstalledAppsDeviceAction({
  input: { unlockTimeout: 60000 },
});

const { observable, cancel } = await dmk.executeDeviceAction({
  deviceAction,
});

observable.subscribe({
  next: (state: ListInstalledAppsDAState) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        switch (requiredUserInteraction) {
          case UserInteractionRequired.None:
            console.log("No user action required");
            break;
          case UserInteractionRequired.AllowSecureConnection:
            console.log(
              "User should allow the secure connection on the device",
            );
            break;
          case UserInteractionRequired.UnlockDevice:
            console.log("User should unlock the device");
            break;
          default:
            throw new Error("Unknown user interaction required");
        }
        break;
      case DeviceActionStatus.Completed:
        const { output } = state;
        console.log("Device action completed", output);
        break;
      case DeviceActionStatus.Error:
        const { error } = state;
        console.log("Error occurred during the execution", error);
        break;
    }
  },
});
```

### Install App Device Action

This device action installs an application on the device by its name. The progress of the installation can be accessed through the `progress` field in the intermediate value.

#### **Input**

- `appName`
  - **Required**
  - **Type**: `string` (e.g.,`Solana`)
  - The name of the application to install.
- `unlockTimeout`
  - Optional
  - Type: `number`
  - The maximum waiting time for the user to unlock the device.

#### **Output**

- There is no output for this device action.

#### **Intermediate Value**

- `requiredUserInteraction`

  - **Type**: `UserInteractionRequired`
  - The user interactions that are required during the execution of the device action.

- `progress`
  - **Type**: `number`
  - The progress of the installation.

```typescript
import {
  DeviceActionStatus,
  UserInteractionRequired,
  InstallAppDAState,
  InstallAppDeviceAction,
} from "@ledgerhq/device-management-kit";

const deviceAction = new InstallAppDeviceAction({
  input: { unlockTimeout: 60000, appName: "Solana" },
});

const { observable, cancel } = await dmk.executeDeviceAction({
  deviceAction,
});

observable.subscribe({
  next: (state: InstallAppDAState) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        const {
          intermediateValue: { requiredUserInteraction, progress },
        } = state;
        switch (requiredUserInteraction) {
          case UserInteractionRequired.None:
            console.log(
              `Installing app progress ${progress}, no user action required`,
            );
            break;
          case UserInteractionRequired.AllowSecureConnection:
            console.log(
              "User should allow the secure connection on the device",
            );
            break;
          case UserInteractionRequired.UnlockDevice:
            console.log("User should unlock the device");
            break;
          default:
            throw new Error("Unknown user interaction required");
        }
        break;
      case DeviceActionStatus.Completed:
        const { output } = state;
        console.log("Device action completed", output);
        break;
      case DeviceActionStatus.Error:
        const { error } = state;
        console.log("Error occurred during the execution", error);
        break;
    }
  },
});
```

### Uninstall App Device Action

This device action uninstalls an application by its name. If the specified application is not installed on the device, the action will complete immediately without any changes.

#### **Input**

- `appName`
  - **Required**
  - **Type**: `string` (e.g.,`Solana`)
  - The name of the application to uninstall.
- `unlockTimeout`
  - Optional
  - Type: `number`
  - The maximum waiting time for the user to unlock the device.

#### **Output**

- There is no output for this device action.

#### **Intermediate Value**

- `requiredUserInteraction`
  - **Type**: `UserInteractionRequired`
  - The user interactions that are required during the execution of the device action.

```typescript
import {
  DeviceActionStatus,
  UserInteractionRequired,
  UninstallAppDAState,
  UninstallAppDeviceAction,
} from "@ledgerhq/device-management-kit";

const deviceAction = new UninstallAppDeviceAction({
  input: { unlockTimeout: 60000, appName: "Solana" },
});

const { observable, cancel } = await dmk.executeDeviceAction({
  deviceAction,
});

observable.subscribe({
  next: (state: UninstallAppDAState) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        switch (requiredUserInteraction) {
          case UserInteractionRequired.None:
            console.log(`Uninstalling ongoing, no user action required`);
            break;
          case UserInteractionRequired.AllowSecureConnection:
            console.log(
              "User should allow the secure connection on the device",
            );
            break;
          case UserInteractionRequired.UnlockDevice:
            console.log("User should unlock the device");
            break;
          default:
            throw new Error("Unknown user interaction required");
        }
        break;
      case DeviceActionStatus.Completed:
        const { output } = state;
        console.log("Device action completed", output);
        break;
      case DeviceActionStatus.Error:
        const { error } = state;
        console.log("Error occurred during the execution", error);
        break;
    }
  },
});
```

## 🔹 Example

We encourage you to explore these device actions by trying them out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how they work and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/identifiers -->

---
title: "Device and Transport Identifiers"
category: reference
---

# Device and Transport Identifiers

Technical identifiers for Ledger devices when implementing custom USB and Bluetooth integrations outside of DMK or LedgerJS.

## Common Identifiers

- **USB Vendor ID**: `0x2c97` (Ledger)
- **Bluetooth Service Name**: `Ledger`

## Device-Specific Identifiers

### Ledger Nano S Plus

| Identifier Type | Mode       | Value    |
| --------------- | ---------- | -------- |
| USB Product ID  | Normal     | `0x50`   |
| USB Product ID  | Bootloader | `0x0005` |

**Bluetooth**: Not supported

---

### Ledger Nano X

| Identifier Type         | Mode/Service  | Value                                  |
| ----------------------- | ------------- | -------------------------------------- |
| USB Product ID          | Normal        | `0x40`                                 |
| USB Product ID          | Bootloader    | `0x0004`                               |
| BLE Service UUID        | Main          | `13d63400-2c97-0004-0000-4c6564676572` |
| BLE Characteristic UUID | Notify        | `13d63400-2c97-0004-0001-4c6564676572` |
| BLE Characteristic UUID | Write         | `13d63400-2c97-0004-0002-4c6564676572` |
| BLE Characteristic UUID | Write Command | `13d63400-2c97-0004-0003-4c6564676572` |

---

### Ledger Stax

| Identifier Type         | Mode/Service  | Value                                  |
| ----------------------- | ------------- | -------------------------------------- |
| USB Product ID          | Normal        | `0x60`                                 |
| USB Product ID          | Bootloader    | `0x0006`                               |
| BLE Service UUID        | Main          | `13d63400-2c97-6004-0000-4c6564676572` |
| BLE Characteristic UUID | Notify        | `13d63400-2c97-6004-0001-4c6564676572` |
| BLE Characteristic UUID | Write         | `13d63400-2c97-6004-0002-4c6564676572` |
| BLE Characteristic UUID | Write Command | `13d63400-2c97-6004-0003-4c6564676572` |

---

### Ledger Flex

| Identifier Type         | Mode/Service  | Value                                  |
| ----------------------- | ------------- | -------------------------------------- |
| USB Product ID          | Normal        | `0x70`                                 |
| USB Product ID          | Bootloader    | `0x0007`                               |
| BLE Service UUID        | Main          | `13d63400-2c97-3004-0000-4c6564676572` |
| BLE Characteristic UUID | Notify        | `13d63400-2c97-3004-0001-4c6564676572` |
| BLE Characteristic UUID | Write         | `13d63400-2c97-3004-0002-4c6564676572` |
| BLE Characteristic UUID | Write Command | `13d63400-2c97-3004-0003-4c6564676572` |

---

### Ledger Nano Gen5

| Identifier Type | Mode/Service | Value    |
| --------------- | ------------ | -------- |
| USB Product ID  | Normal       | `0x80`   |
| USB Product ID  | Bootloader   | `0x0008` |

**Bluetooth**: Nano Gen5 devices may use one of two BLE identifier sets. The DMK automatically detects which set is used by the device.

**BLE Identifier Set 1:**

| Identifier Type         | Service       | Value                                  |
| ----------------------- | ------------- | -------------------------------------- |
| BLE Service UUID        | Main          | `13d63400-2c97-8004-0000-4c6564676572` |
| BLE Characteristic UUID | Notify        | `13d63400-2c97-8004-0001-4c6564676572` |
| BLE Characteristic UUID | Write         | `13d63400-2c97-8004-0002-4c6564676572` |
| BLE Characteristic UUID | Write Command | `13d63400-2c97-8004-0003-4c6564676572` |

**BLE Identifier Set 2 (this happens rarely, only in Bootloader Mode, and only in early versions of the OS):**

| Identifier Type         | Service       | Value                                  |
| ----------------------- | ------------- | -------------------------------------- |
| BLE Service UUID        | Main          | `13d63400-2c97-9004-0000-4c6564676572` |
| BLE Characteristic UUID | Notify        | `13d63400-2c97-9004-0001-4c6564676572` |
| BLE Characteristic UUID | Write         | `13d63400-2c97-9004-0002-4c6564676572` |
| BLE Characteristic UUID | Write Command | `13d63400-2c97-9004-0003-4c6564676572` |

## Usage Notes

- **Normal Mode**: Standard device operation
- **Bootloader Mode**: Device firmware update mode
- **Notify Characteristic**: Receives data from device
- **Write Characteristic**: Sends data with response
- **Write Command Characteristic**: Sends data without response

## Device Support Matrix

| Device      | USB | Bluetooth |
| ----------- | --- | --------- |
| Nano S Plus | ✅   | ❌         |
| Nano X      | ✅   | ✅         |
| Stax        | ✅   | ✅         |
| Flex        | ✅   | ✅         |
| Nano Gen 5  | ✅   | ✅         |

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/aleo -->

# Aleo Signer Kit

This module provides the implementation of the Ledger aleo signer of the Device Management Kit. It enables interaction with the aleo application on a Ledger device including:

- Retrieving the aleo address using a given derivation path
- Retrieving the aleo view key using a given derivation path
- Signing a aleo transaction
- Signing a message displayed on a Ledger device
- Retrieving the app configuration

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Address](#use-case-2-get-address)
   - [Get View Key](#use-case-3-get-view-key)
   - [Sign Transaction](#use-case-4-sign-transaction)
   - [Sign Message](#use-case-5-sign-message)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Aleo Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-aleo` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-aleo
```

## 🔹 Initialisation

To initialise a Aleo signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerAleoBuilder`:

```typescript
const signerAleo = new SignerAleoBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerAleoBuilder.build()` method will return a `SignerAleo` instance that exposes 5 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get App Configuration

This method allows users to retrieve the app configuration from the Ledger device.

```typescript
const { observable, cancel } = signerAleo.getAppConfig();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAppConfigCommandResponse = {
  version: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Address

This method allows users to retrieve the aleo address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerAleo.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/683'/0"`)
  - The derivation path used for the aleo address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the aleo app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  address: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Get View Key

This method allows users to retrieve the aleo view key based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerAleo.getViewKey(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/683'/0"`)
  - The derivation path used for the aleo view key. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the aleo app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetViewKeyCommandResponse = {
  viewKey: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign Transaction

This method allows users to sign a aleo transaction.

```typescript
const { observable, cancel } = signerAleo.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/683'/0"`)
  - The derivation path used for the aleo transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the aleo app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Sign Message

This method allows users to sign a text string that is displayed on Ledger devices.

```typescript
const { observable, cancel } = signerAleo.signMessage(derivationPath, message);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the aleo message. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `message`

  - **Required**
  - **Type:** `string | Uint8Array`
  - The message to be signed, which will be displayed on the Ledger device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Aleo Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/btc -->

---
title: "Bitcoin Signer Kit"
category: reference
---

# Bitcoin Signer Kit

This module provides the implementation of the Ledger Bitcoin signer of the Device Management Kit. It enables interaction with the Bitcoin application on a Ledger device including:

- Retrieving the Bitcoin extended public key and master fingerprint;
- Signing a message displayed on a Ledger device;
- Signing a Bitcoin partially signed transaction (PSBT);
- Signing a Bitcoin transaction;
- Retrieving wallet addresses;
- Registering custom wallet policies (e.g., multisig wallets);

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get Extended Public Key](#use-case-1-get-extended-public-key)
   - [Get Master Fingerprint](#use-case-2-get-master-fingerprint)
   - [Sign Message](#use-case-3-sign-message)
   - [Sign Partially Signed Transaction (PSBT)](#use-case-4-sign-psbt)
   - [Sign Transaction](#use-case-5-sign-transaction)
   - [Get Wallet address](#use-case-6-get-wallet-address)
   - [Register Wallet](#use-case-7-register-wallet)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Bitcoin Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-bitcoin` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-bitcoin
```

## 🔹 Initialisation

To initialise a Bitcoin signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerBtcBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:

```typescript
// Initialise a Bitcoin signer instance
const signerBitcoin = new SignerBtcBuilder({ sdk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerBtcBuilder.build()` method will return a `SignerBitcoin` instance that exposes 7 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get extended public key

This method allows users to retrieve the Bitcoin extended public key based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerBitcoin.getExtendedPublicKey(
  derivationPath,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g. `"84'/0'/0'"` for a Native SegWit wallet)
  - The derivation path used for the Bitcoin address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  extendedPublicKey: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get master fingerprint

This method allows users to retrieve the master fingerprint of the wallet. The master fingerprint is a 4-byte identifier derived from the master public key, commonly used in BIP32 derivation paths and PSBTs.

```typescript
const { observable, cancel } = signerBitcoin.getMasterFingerprint(options);
```

#### **Parameters**

- `options`

  - Optional

  - Type: `MasterFingerprintOptions`

    ```typescript
    type MasterFingerprintOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Bitcoin app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetMasterFingerprintCommandResponse = {
  masterFingerprint: Uint8Array; // 4-byte master fingerprint
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign message

This method allows users to sign a text string that is displayed on Ledger devices.

```typescript
const { observable, cancel } = signerBitcoin.signMessage(
  derivationPath,
  message,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g. `"84'/0'/0'"` for a Native SegWit wallet)
  - The derivation path used for the Bitcoin address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `message`

  - **Required**
  - **Type:** `string`
  - The message to be signed, which will be displayed on the Ledger device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: `0x${string}`; // R component of the signature
  s: `0x${string}`; // S component of the signature
  v: number; // Recovery parameter
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign PSBT

This method allows users to sign a partially signed transaction.

```typescript
const { observable, cancel } = signerBitcoin.signPsbt(
  new DefaultWallet(path, descriptorTemplate),
  psbt,
);
```

#### **Parameters**

- `wallet`

  - **Required**
  - **Type:** `Wallet`

  ```typescript
  type Wallet = DefaultWallet | RegisteredWallet;

  class DefaultWallet {
    constructor(
      // Derivation path without master key representation.
      // Format example: /44'/0'/0'
      public derivationPath: string,
      public template: DefaultDescriptorTemplate,
    ) {}
  }

  class RegisteredWallet {
    constructor(
      public name: string,
      public descriptorTemplate: string,
      public keys: string[],
      public hmac: Uint8Array,
    ) {}
  }
  ```

- `psbt`
  - **Required**
  - **Type:** `string | Psbt`
  - A base64/hex psbt string or [bitcoin-js Psbt](https://github.com/bitcoinjs/bitcoinjs-lib/blob/151173f05e26a9af7c98d8d1e3f90e97185955f1/ts_src/psbt.ts#L131)

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type PartialSignature = {
  inputIndex: number;
  pubkey: Uint8Array;
  signature: Uint8Array;
  tapleafHash?: Uint8Array;
};

type MusigPubNonce = {
  inputIndex: number;
  participantPubkey: Uint8Array;
  aggregatedPubkey: Uint8Array;
  tapleafHash: Uint8Array;
  pubnonce: Uint8Array;
};

type MusigPartialSignature = {
  inputIndex: number;
  participantPubkey: Uint8Array;
  aggregatedPubkey: Uint8Array;
  tapleafHash: Uint8Array;
  partialSignature: Uint8Array;
};

type PsbtSignature = PartialSignature | MusigPartialSignature | MusigPubNonce;
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Sign transaction

This method allows users to sign a Bitcoin transaction.

```typescript
const { observable, cancel } = signerBitcoin.signTransaction(
  new DefaultWallet(path, descriptorTemplate),
  psbt,
);
```

#### **Parameters**

- `wallet`

  - **Required**
  - **Type:** `Wallet`

  ```typescript
  type Wallet = DefaultWallet | RegisteredWallet;

  class DefaultWallet {
    constructor(
      // Derivation path without master key representation.
      // Format example: /44'/0'/0'
      public derivationPath: string,
      public template: DefaultDescriptorTemplate,
    ) {}
  }

  class RegisteredWallet {
    constructor(
      public name: string,
      public descriptorTemplate: string,
      public keys: string[],
      public hmac: Uint8Array,
    ) {}
  }
  ```

  - `psbt`
    - **Required**
    - **Type:** `string | Psbt`
    - A base64/hex psbt string or [bitcoin-js Psbt](https://github.com/bitcoinjs/bitcoinjs-lib/blob/151173f05e26a9af7c98d8d1e3f90e97185955f1/ts_src/psbt.ts#L131)

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type TransactionHash = `0x${string}`;
```

- `cancel` A function to cancel the action on the Ledger device.

### Use Case 6: Get wallet address

This method allows users to get the wallet address linked to a Ledger device.

```typescript
const { observable, cancel } = signerBitcoin.getWalletAddress(
  derivationPath,
  addressIndex,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g. `"84'/0'/0'"` for a Native SegWit wallet)
  - The derivation path used for the Bitcoin address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `addressIndex`

  - **Required**
  - **Type:** `number`
  - The desired address index on the Ledger device.

- `options`

  - Optional
  - Type: `WalletAddressOptions`

  ```typescript
  type WalletAddressOptions = {
    checkOnDevice?: boolean;
    change?: boolean;
  };
  ```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type WalletAddress = {
  address: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 7: Register wallet

This method allows users to register a custom wallet policy on the Ledger device. Wallet policies describe complex wallet setups like multisig wallets. Once registered, the device returns an HMAC that must be stored and provided for future operations (signing, address generation) with this wallet.

```typescript
const { observable, cancel } = signerBitcoin.registerWallet(
  walletPolicy,
  options,
);
```

#### **Parameters**

- `walletPolicy`

  - **Required**
  - **Type:** `WalletPolicy`

  ```typescript
  class WalletPolicy {
    constructor(
      public name: string, // Human-readable wallet name (displayed on device)
      public descriptorTemplate: string, // Descriptor template (e.g., "wsh(sortedmulti(2,@0/**,@1/**))")
      public keys: string[], // Array of key origin info + xpubs
    ) {}
  }
  ```

  - `name`: A human-readable name for the wallet (max 64 characters), displayed on the device during registration.
  - `descriptorTemplate`: A Bitcoin descriptor template using placeholders like `@0`, `@1` for keys. See [wallet policies documentation](https://github.com/LedgerHQ/app-bitcoin-new/blob/master/doc/wallet.md).
  - `keys`: Array of extended public keys with key origin info in the format `[fingerprint/derivation/path]xpub...`.

- `options`

  - Optional

  - Type: `RegisterWalletOptions`

    ```typescript
    type RegisterWalletOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Bitcoin app automatically.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
class RegisteredWallet {
  constructor(
    public name: string,
    public descriptorTemplate: string,
    public keys: string[],
    public hmac: Uint8Array, // 32-byte HMAC to store for future operations
  ) {}
}
```

The returned `RegisteredWallet` includes the HMAC which must be stored securely. This HMAC is required for any subsequent operations with this wallet (signing transactions, generating addresses).

- `cancel` A function to cancel the action on the Ledger device.

#### **Example**

```typescript
import {
  WalletPolicy,
  RegisteredWallet,
} from "@ledgerhq/device-signer-kit-bitcoin";

// Define a 2-of-2 multisig wallet policy
const walletPolicy = new WalletPolicy(
  "My Multisig",
  "wsh(sortedmulti(2,@0/**,@1/**))",
  [
    "[76223a6e/48'/1'/0'/2']tpubDE7NQymr4AFtewpAsWtnreyq9ghkzQBXpCZjWLFVRAvnbf7vya2eMTvT2fPapNqL8SuVvLQdbUbMfWLVDCZKnsEBqp6UK93QEzL8Ck23AwF",
    "[f5acc2fd/48'/1'/0'/2']tpubDFAqEGNyad35aBCKUAXbQGDjdVhNueno5ZZVEn3sQbW5ci457gLR7HyTmHBg93oourBssgUxuWz1jX5uhc1qaqFo9VsybY1J5FuedLfm4dK",
  ],
);

// Register the wallet
const { observable } = signerBitcoin.registerWallet(walletPolicy);

observable.subscribe({
  next: (state) => {
    if (state.status === DeviceActionStatus.Completed) {
      const registeredWallet: RegisteredWallet = state.output;
      // Store the HMAC securely for future use
      console.log("Wallet registered! HMAC:", registeredWallet.hmac);
    }
  },
});
```

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation’s progress and status:

- **NotStarted**: The operation hasn’t started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTypedData: {
    // User needs to sign the typed data displayed on the device
    console.log("User needs to sign the typed data displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  case UserInteractionRequired.RegisterWallet: {
    // User needs to review and approve the wallet policy on the device
    console.log(
      "The user needs to review and approve the wallet policy on the device.",
    );
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Bitcoin Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/concordium -->

# Concordium Signer Kit

This module provides the implementation of the Ledger Concordium signer of the Device Management Kit. It enables interaction with the Concordium application on a Ledger device including:

- Querying the device app configuration and version
- Retrieving the Concordium public key using a given derivation path
- Signing a Concordium transaction (Transfer, TransferWithMemo and TokenUpdate / PLT)
- Signing a Concordium credential deployment transaction
- Verifying a Concordium address on-device using a trusted backend

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Public Key](#use-case-2-get-public-key)
   - [Sign Transaction](#use-case-3-sign-transaction)
   - [Sign Credential Deployment Transaction](#use-case-4-sign-credential-deployment-transaction)
   - [Verify Address](#use-case-5-verify-address)
5. [Observable Behavior](#-observable-behavior)

## 🔹 How it works

The Ledger Concordium Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-concordium` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-concordium
```

## 🔹 Initialisation

To initialise a Concordium signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerConcordiumBuilder`:

```typescript
const signerConcordium = new SignerConcordiumBuilder({
  dmk,
  sessionId,
}).build();
```

The builder creates a default `ContextModule` out of the box, which is used by `verifyAddress` to communicate with the trusted metadata service. You can also provide a customized context module:

```typescript
import {
  ContextModuleBuilder,
  ContextModuleChainID,
} from "@ledgerhq/context-module";

const customContextModule = new ContextModuleBuilder({ originToken })
  .setChain(ContextModuleChainID.Concordium)
  .build();

const signerConcordium = new SignerConcordiumBuilder({
  dmk,
  sessionId,
})
  .withContextModule(customContextModule)
  .build();
```

## 🔹 Use Cases

The `SignerConcordiumBuilder.build()` method will return a `SignerConcordium` instance that exposes 5 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get App Configuration

This method allows users to query the Concordium app version running on the device.

> **Note:** This command is supported starting from app-concordium `5.4.1`. Older app-concordium versions will return an `INS_NOT_SUPPORTED` (`0x6D00`) error.

```typescript
const { observable, cancel } = signerConcordium.getAppConfiguration();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type AppConfiguration = {
  version: string; // e.g. "5.5.0"
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Public Key

This method allows users to retrieve the Concordium Ed25519 public key based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerConcordium.getPublicKey(
  derivationPath,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/919'/0'/0'/0'"`)
  - The derivation path used for the Concordium key. Concordium uses hardened paths: `44'/919'/account'/identity'/credential'`.

- `options`

  - Optional

  - Type: `PublicKeyOptions`

    ```typescript
    type PublicKeyOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Concordium app on the device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type PublicKey = {
  publicKey: Uint8Array; // 32-byte Ed25519 public key
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Transaction

Securely sign a Concordium transaction on Ledger devices. The transaction kind is detected automatically from the kind byte at offset 60 of the serialized payload.

| Kind             | Byte          | Name                                 |
| ---------------- | ------------- | ------------------------------------ |
| Transfer         | `3` (`0x03`)  | Plain CCD transfer                   |
| TransferWithMemo | `22` (`0x16`) | CCD transfer with a memo             |
| TokenUpdate      | `27` (`0x1B`) | Protocol Level Token (PLT) operation |

Any other kind byte is rejected with `UnsupportedTransactionTypeError` (errorCode `"unsupported_transaction_type"`) before anything is sent to the device.

```typescript
const { observable, cancel } = signerConcordium.signTransaction(
  derivationPath,
  transaction,
  maxFee,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/919'/0'/0'/0'"`)
  - The derivation path used for the signing key.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction bytes to sign. The transaction kind is detected automatically from the kind byte at offset 60.
  - For **TokenUpdate (PLT)** the expected layout is flat:

    ```text
    [header:60][kind:1 = 0x1B][token_id_length:1][token_id:1..128][cbor_total_length:4 BE][cbor:N]
    ```

    This matches the serialization produced by the official Concordium JS SDK: a token id with a word8 length prefix, followed by the operations payload with a word32 length prefix.

    The signer streams this to the device as one INIT frame carrying everything up to and including `cbor_total_length`, then CONT frames carrying the CBOR payload. Chunking is byte-oriented, so a CBOR field may span a frame boundary.

    The CBOR payload is passed through **opaque**. The signer does not decode or validate PLT semantics — the operation type, amount, recipient and memo are parsed and displayed by the device app. The signer checks only the framing: `token_id_length` within `1..128`, `cbor_total_length` within `1..512` and consistent with the remaining byte count. A layout failure is reported as `InvalidPltTransactionError` (errorCode `"invalid_plt_transaction"`) with the offending field named in the message, before any APDU is sent.

- `maxFee`

  - **Required**
  - **Type:** `bigint` (µCCD)
  - The max-fee value to display, as a uint64 in µCCD. Rendered on-device alongside the recipient and amount. The value is **display-only**: it is not part of the canonical signed bytes, so the on-chain transaction hash is unaffected.
  - Requires Concordium app version **5.6.0 or newer** on the device. On older firmware the value is dropped at the wire boundary and the device falls back to the legacy display. Signing still succeeds; only the on-device display degrades. Callers should always pass a real value; do not gate on detected firmware version.
  - **Ignored for TokenUpdate (PLT) transactions.** The device displays no fee for `INS 0x27`, and the handler rejects both a non-zero P2 and any trailing fee suffix. The value is still validated for range, so pass `0n` unless you have a real figure.
  - Invalid values (non-bigint, negative, or above uint64 range) are rejected with `InvalidMaxFeeError` (errorCode `"invalid_max_fee"`).

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Concordium app on the device.

#### **PLT app-version requirement**

PLT signing requires a Concordium app that implements `INS 0x27`, currently **5.7.0 or newer**. The signer checks the running app version before sending anything and rejects an older app with `UnsupportedAppVersionError` (errorCode `"unsupported_app_version"`). This is deliberately distinct from a signing failure, so an integrator can prompt the user to update the app rather than reporting a failed transaction. Transfer and TransferWithMemo are unaffected and keep working on older apps.

#### **PLT status words**

Device-originated errors on the PLT path are surfaced via `DeviceActionStatus.Error` and discriminated by the `errorCode` string:

| `errorCode` | Meaning                                                                    | Integrator action                         |
| ----------- | -------------------------------------------------------------------------- | ----------------------------------------- |
| `"6b00"`    | P2 was not `0x00`                                                          | Signer bug; report it                     |
| `"6b01"`    | INIT sent twice, or CONT before INIT                                       | Signer bug; report it                     |
| `"6b02"`    | Derivation path invalid or deeper than 8 nodes                             | Correct the derivation path               |
| `"6b03"`    | P1 was neither `0x00` nor `0x01`                                           | Signer bug; report it                     |
| `"6b04"`    | Kind byte was not `27`, or the header is too short                         | Correct the serialized transaction        |
| `"6b06"`    | Display formatting overflow                                                | Report with the payload that triggered it |
| `"6b07"`    | Device crypto initialisation failed                                        | Retry; escalate if persistent             |
| `"6b0d"`    | Empty CONT frame, CBOR overflow, or a CBOR payload the device cannot parse | Check the CBOR against CIS-7              |
| `"6b0e"`    | `cbor_total_length` is `0` or above `512`                                  | Reduce the payload                        |
| `"6b0f"`    | `token_id_length` outside `1..128`                                         | Correct the token id                      |
| `"6b10"`    | The CBOR array carries more than one operation                             | Send one operation per transaction        |

The device accepts exactly **one** operation per PLT transaction. Batching several into the outer CBOR array is refused with `"6b10"`, so that the user cannot approve a screen showing only part of what they are signing.

The generic codes apply here too: `"6985"` user rejected, `"5515"` locked device, `"6d00"` the app does not implement `INS 0x27`.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array; // 64-byte Ed25519 signature
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign Credential Deployment Transaction

Sign a credential deployment transaction on Ledger devices. Credential deployment is required before an account can send its first transaction on the Concordium blockchain. The signer parses the serialized credential deployment bytes and orchestrates the multi-step APDU sequence with the device.

```typescript
const { observable, cancel } =
  signerConcordium.signCredentialDeploymentTransaction(
    derivationPath,
    transaction,
    options,
  );
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/919'/0'/0'/0'"`)
  - The derivation path used for the signing key.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized credential deployment bytes. The wire format contains credential values, identity ownership proofs, and expiry, concatenated in the order expected by the Concordium device app.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Concordium app on the device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array; // 64-byte Ed25519 signature
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Verify Address

Securely verify a Concordium account address on the Ledger device using the trusted backend pattern. The signer fetches a signed account ownership descriptor from the trusted metadata service, loads it onto the device via the PKI infrastructure, then triggers address verification. The device validates the descriptor's signature chain, derives the public key from the given path, and displays the address for user confirmation only if the key matches.

```typescript
const { observable, cancel } = signerConcordium.verifyAddress(
  derivationPath,
  address,
  network,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/919'/0'/0'/0'"`)
  - The derivation path for the account's signing key.

- `address`

  - **Required**
  - **Type:** `string`
  - The Concordium Base58Check account address to verify (e.g., `"3kFkntk2H5FGMzeR3GjQKPhdZK9LShKdPHsj2fiGKCdmDXj2WB"`).

- `network`

  - **Required**
  - **Type:** `"mainnet" | "testnet"`
  - The Concordium network for which to verify the address.

- `options`

  - Optional

  - Type: `VerifyAddressOptions`

    ```typescript
    type VerifyAddressOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Concordium app on the device.

#### **Returns**

- `observable` Emits DeviceActionState updates. On completion, the output is `true` (the address was verified and approved by the user).

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const { intermediateValue } = state;
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.None: {
    console.log("No user action needed.");
    break;
  }
  default:
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/cosmos -->

# Cosmos Signer Kit

This module provides the implementation of the Ledger Cosmos signer of the Device Management Kit. It enables interaction with the Cosmos application on a Ledger device including:

- Retrieving the Cosmos address using a given derivation path
- Signing a Cosmos transaction
- Retrieving the app configuration

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Address](#use-case-2-get-address)
   - [Sign Transaction](#use-case-3-sign-transaction)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Cosmos Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-cosmos` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-cosmos
```

## 🔹 Initialisation

To initialise a Cosmos signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerCosmosBuilder`:

```typescript
const signerCosmos = new SignerCosmosBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerCosmosBuilder.build()` method will return a `SignerCosmos` instance that exposes 3 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get App Configuration

This method allows users to retrieve the app configuration from the Ledger device.

```typescript
const { observable, cancel } = signerCosmos.getAppConfig();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type AppConfig = {
  major: number;
  minor: number;
  patch: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Address

This method allows users to retrieve the Cosmos address based on a given `derivationPath` and `hrp` (Human-Readable Part).

```typescript
const { observable, cancel } = signerCosmos.getAddress(
  derivationPath,
  hrp,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/118'/0'/0/0"`)
  - The derivation path used for the Cosmos address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `hrp`

  - **Required**
  - **Type:** `string` (e.g., `"cosmos"`)
  - The Human-Readable Part that identifies the Cosmos chain (e.g. `"cosmos"`, `"osmosis"`).

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Cosmos app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type PubKey = {
  publicKey: Uint8Array;
  address: string; // Bech32 address
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Transaction

This method allows users to sign a Cosmos transaction.

```typescript
const { observable, cancel } = signerCosmos.signTransaction(
  derivationPath,
  hrp,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/118'/0'/0/0"`)
  - The derivation path used for the Cosmos transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `hrp`

  - **Required**
  - **Type:** `string` (e.g., `"cosmos"`)
  - The Human-Readable Part that identifies the Cosmos chain (e.g. `"cosmos"`, `"osmosis"`).

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Cosmos app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array;
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Cosmos Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/eth -->

---
title: "Ethereum Signer Kit"
category: reference
---

# Ethereum Signer Kit

This module provides the implementation of the Ledger Ethereum signer of the Device Management Kit. It enables interaction with the Ethereum application on a Ledger device including:

- Retrieving the Ethereum address using a given derivation path;
- Signing an Ethereum transaction ([Clear Signing](https://www.ledger.com/academy/topics/ledgersolutions/what-is-clear-signing));
- Signing a message displayed on a Ledger device;
- Signing an [EIP-712](https://eips.ethereum.org/EIPS/eip-712) specified message.

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get Address](#use-case-1-get-address)
   - [Sign Transaction](#use-case-2-sign-transaction)
   - [Sign Message](#use-case-3-sign-message)
   - [Sign Typed Data](#use-case-4-sign-typed-data)
   - [Sign Delegation Authorization](#use-case-5-sign-delegation-authorization-eip-7702)
   - [Display Safe Account](#use-case-6-display-safe-account)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Ethereum Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations, including signing transactions. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-ethereum` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-ethereum
```

## 🔹 Initialisation

To initialise an Ethereum signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerEthBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:

```typescript
// Initialise an Ethereum signer instance using default context module
const signerEth = new SignerEthBuilder({
  sdk,
  sessionId,
  originToken: "origin-token", // replace with your origin token
}).build();
```

> **Note:** The `originToken` parameter is required by the default context module to work.
> Token should be delivered by Ledger, otherwise the Transactions Checks will not be available.

You can also configure the context module yourself:

```typescript
// Initialise an Ethereum signer instance using customized context module
const signerEth = new SignerEthBuilder({ sdk, sessionId })
  .withContextModule(customContextModule)
  .build();
```

### Address book

Give the signer the user's address book to have the device show a saved contact
name in place of the raw recipient address when it reviews a transaction:

```typescript
const signerEth = new SignerEthBuilder({ sdk, sessionId })
  .withAddressBook({
    contactGroups: [
      {
        contactName: "Alice",
        groupHandle, // returned when the contact was registered on the device
        hmacProof,
        externalAddresses: [
          {
            scope: "Ethereum",
            address: "0x...",
            chainId: 1n,
            hmacRest,
          },
        ],
      },
    ],
    ledgerAccounts: [],
  })
  .build();
```

Points to know:

- The snapshot must be complete, and it is read as-is: the signer neither
  mutates nor persists it. Build a new signer to pick up later changes.
- Only EVM entries belong here. Filter by blockchain family before you build the
  snapshot.
- A contact matches on address **and** `chainId`, and only against the
  transaction recipient. A recipient carried in calldata — an ERC-20 `transfer`,
  for example — still reviews as a raw address.
- A matched contact replaces the trusted name (ENS) for the same recipient.
- Nothing here can break a signature. An address book you do not supply, a
  recipient that does not match, an app too old to support contacts, or a
  contact the device rejects all leave the transaction signing as before,
  against the raw address.

> **Note:** Contacts are supported on every device model except Nano S, and
> need a recent enough Ethereum app. Register contacts on the device with
> [`@ledgerhq/device-contacts-kit`](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-contacts-kit).

## 🔹 Use Cases

The `SignerEthBuilder.build()` method will return a `SignerEth` instance that exposes 6 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get Address

This method allows users to retrieve the Ethereum address according to given `derivationPath`.

```typescript
const { observable, cancel } = signerEth.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/60'/0'/0/0"`)
  - The derivation path used for the Ethereum address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      returnChainCode?: boolean;
      chainId?: number;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `returnChainCode`: An optional boolean indicating whether the chain code should be returned (`true`) or not (`false`).

  - `chainId`: An optional number for the Ethereum chain ID (e.g., `1` for mainnet, `137` for Polygon). **Only used when `checkOnDevice` is `true`.** When enabled, it is sent to the device for address verification and is used to load dynamic network context (e.g. network name and icon). When `checkOnDevice` is `false`, `chainId` is ignored.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  publicKey: string; // Public key derived from the given path
  address: `0x${string}`; // Ethereum address in hex format
  chainCode?: string; // Optional chain code
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Sign Transaction

This method enables users to securely sign transactions using Clear Signing on Ledger devices.

```typescript
const { observable, cancel } = signerEth.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/60'/0'/0/0"`)
  - The derivation path used in the transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `transaction`

  - **Required**
  - **Type:**`Uint8Array`
  - The transaction buffer that needs to be signed.

- `options`

  - **Optional**

  - **Type:** `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      domain?: string;
    };
    ```

  - `domain` An optional string representing the domain present in the transaction. Currently, only ENS domains are supported.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: `0x${string}`; // R component of the signature
  s: `0x${string}`; // S component of the signature
  v: number; // Recovery parameter
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Message

This method allows users to sign a text string that is displayed on Ledger devices.

```typescript
const { observable, cancel } = signerEth.signMessage(derivationPath, message);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/60'/0'/0/0"`)
  - The derivation path used by the Ethereum message. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `message`

  - **Required**
  - **Type:** `string`
  - The message to be signed, which will be displayed on the Ledger device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: `0x${string}`; // R component of the signature
  s: `0x${string}`; // S component of the signature
  v: number; // Recovery parameter
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign Typed Data

This method enables users to sign an Ethereum message following the [EIP-712](https://eips.ethereum.org/EIPS/eip-712) specification.

```typescript
const { observable, cancel } = signerEth.signTypedData(
  derivationPath,
  typedData,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/60'/0'/0/0"`)
  - The derivation path used by the Ethereum message. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `typedData`

  - **Required**

  - **Type:** `TypedData`

    ```typescript
    interface TypedData {
      domain: TypedDataDomain;
      types: Record<string, Array<TypedDataField>>;
      primaryType: string;
      message: Record<string, unknown>;
    }

    interface TypedDataDomain {
      name?: string;
      version?: string;
      chainId?: number;
      verifyingContract?: string;
      salt?: string;
    }

    interface TypedDataField {
      name: string;
      type: string;
    }
    ```

  - The typed data as defined at [EIP-712](https://eips.ethereum.org/EIPS/eip-712).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: `0x${string}`; // R component of the signature
  s: `0x${string}`; // S component of the signature
  v: number; // Recovery parameter
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Sign Delegation Authorization (EIP-7702)

This method enables users to sign a delegation authorization message following the [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) specification.

```typescript
const { observable, cancel } = signerEth.signDelegationAuthorization(
  derivationPath,
  chainId,
  contractAddress,
  nonce,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/60'/0'/0/0"`)
  - The derivation path used by the Ethereum message. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `chainId`

  - **Required**
  - **Type:** `number`
  - The chain ID of the Ethereum network.

- `contractAddress`

  - **Required**
  - **Type:** `string`
  - The address of the contract to be authorized.

- `nonce`

  - **Required**
  - **Type:** `number`
  - The nonce of the transaction.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: `0x${string}`; // R component of the signature
  s: `0x${string}`; // S component of the signature
  v: number; // Recovery parameter
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 6: Verify Safe Address

This method enables users to display and verify a Safe account address on their Ledger device. This is particularly useful for verifying Safe (formerly Gnosis Safe) multi-signature wallet addresses.

```typescript
const { observable, cancel } = signerEth.verifySafeAddress(
  safeContractAddress,
  options,
);
```

#### **Parameters**

- `safeContractAddress`

  - **Required**
  - **Type:** `string`
  - The address of the Safe contract to display and verify on the device.

- `options`

  - **Optional**

  - **Type:** `SafeAddressOptions`

    ```typescript
    type SafeAddressOptions = {
      chainId: number;
      skipOpenApp?: boolean;
    };
    ```

  - `chainId`: The chain ID of the Ethereum network where the Safe contract is deployed (e.g., `1` for Ethereum mainnet, `137` for Polygon).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Ethereum app on the device (`true`) or not (`false`). Defaults to `false`.

#### **Returns**

- `observable` Emits DeviceActionState updates. On successful completion, the output is `void` (no return value), indicating that the Safe account address was successfully verified on the device.

- `cancel` A function to cancel the action on the Ledger device.

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation’s progress and status:

- **NotStarted**: The operation hasn’t started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction. The intermediateValue contains:

- `requiredUserInteraction`: Indicates what action is needed from the user
- `step`: The current step in the device action flow, available for the 'signTransaction' and 'signTypedData' flow.

```typescript
const { requiredUserInteraction, step /* if available */ } = intermediateValue;

if (step !== undefined) {
  console.log("Current step:", step);
}

switch (requiredUserInteraction) {
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTypedData: {
    // User needs to sign the typed data displayed on the device
    console.log("User needs to sign the typed data displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignDelegationAuthorization: {
    // User needs to sign the delegation authorization displayed on the device
    console.log(
      "User needs to sign the delegation authorization displayed on the device.",
    );
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.VerifySafeAddress: {
    // User needs to verify the Safe address displayed on the device
    console.log(
      "User needs to verify the Safe address displayed on the device.",
    );
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  case UserInteractionRequired.Web3ChecksOptIn: {
    // User needs to opt-in for web3 checks
    console.log("User needs to opt-in for web3 checks.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Ethereum Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/hyperliquid -->

# Hyperliquid Signer Kit

This module provides the implementation of the Ledger hyperliquid signer of the Device Management Kit. It enables interaction with the hyperliquid application on a Ledger device including:

- Signing a hyperliquid actions

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Sign Actions](#use-case-1-sign-actions)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Hyperliquid Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations.
The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units),
which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs.
The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-hyperliquid` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-hyperliquid
```

## 🔹 Initialisation

To initialise a Hyperliquid signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerHyperliquidBuilder`:

```typescript
const signerHyperliquid = new SignerHyperliquidBuilder({
  dmk,
  sessionId,
}).build();
```

## 🔹 Use Cases

The `SignerHyperliquidBuilder.build()` method will return a `SignerHyperliquid` instance that exposes 2 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Sign Actions

This method allows users to sign hyperliquid actions.

```typescript
const { observable, cancel } = signerHyperliquid.signActions(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the hyperliquid transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the hyperliquid app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Hyperliquid Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/icp -->

# Internet Computer Signer Kit

This module provides the implementation of the Ledger Internet Computer (ICP) signer of the Device Management Kit. It enables interaction with the Internet Computer application on a Ledger device including:

- Retrieving the ICP public key, account identifier and principal for a given derivation path
- Signing an Internet Computer transaction
- Signing an update call together with its read-state request (neuron management)
- Querying the device app configuration and version

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get Address](#use-case-1-get-address)
   - [Sign Transaction](#use-case-2-sign-transaction)
   - [Sign Update Call](#use-case-3-sign-update-call)
   - [Get App Configuration](#use-case-4-get-app-configuration)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Internet Computer Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-icp` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-icp
```

## 🔹 Initialisation

To initialise an ICP signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerIcpBuilder`:

```typescript
const signerIcp = new SignerIcpBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerIcpBuilder.build()` method will return a `SignerIcp` instance that exposes 4 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get Address

This method allows users to retrieve the ICP public key, account identifier and principal based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerIcp.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/223'/0'/0/0"`)
  - The derivation path used for the ICP address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the ICP app on the device (`true`) or not (`false`). Use when the app is already open.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Address = {
  publicKey: string; // hex-encoded secp256k1 public key
  accountId: string; // hex-encoded account identifier
  principal: string; // textual principal
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Sign Transaction

Securely sign an Internet Computer transaction on Ledger devices.

```typescript
const { observable, cancel } = signerIcp.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/223'/0'/0/0"`)
  - The derivation path used for the ICP address.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction bytes (CBOR request) to sign.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
      stake?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the ICP app on the device (`true`) or not (`false`). Use when the app is already open.

  - `stake`: An optional boolean. When `true`, signs a neuron-creation transfer (a governance-subaccount transfer) instead of a plain transfer. Defaults to `false`.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string; // hex-encoded 32-byte R value
  s: string; // hex-encoded 32-byte S value
  v: number; // recovery id
  der: string; // hex-encoded DER signature
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Update Call

Sign an Internet Computer update call together with its companion read-state request. Most neuron-management operations (dissolve, follow, split, hot-keys, maturity, …) are update calls to the NNS governance canister signed this way.

```typescript
const { observable, cancel } = signerIcp.signUpdateCall(
  derivationPath,
  callRequest,
  readStateRequest,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/223'/0'/0/0"`)
  - The derivation path used for the ICP address.

- `callRequest`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized update-call request bytes (CBOR envelope) to sign.

- `readStateRequest`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized read-state request bytes (CBOR envelope) signed alongside the call, used afterwards to poll the call's status.

- `options`

  - Optional

  - Type: `CommonOptions`

    ```typescript
    type CommonOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the ICP app on the device (`true`) or not (`false`). Use when the app is already open.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type UpdateCallSignature = {
  requestHash: string; // hex-encoded signed request digest
  requestSignature: { r: string; s: string }; // hex-encoded r‖s over the call
  readStateHash: string; // hex-encoded signed read-state digest
  readStateSignature: { r: string; s: string }; // hex-encoded r‖s over the read-state
  readStateBody: Uint8Array; // the read-state request that was signed
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Get App Configuration

This method allows the user to fetch the current app configuration.

```typescript
const { observable, cancel } = signerIcp.getAppConfiguration();
```

#### **Parameters**

None.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Version = {
  version: string; // "major.minor.patch"
  testMode: boolean;
  locked: boolean;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const { intermediateValue } = state;
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.None: {
    console.log("No user action needed.");
    break;
  }
  default:
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Internet Computer Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/polkadot -->

# Polkadot Signer Kit

This module provides the implementation of the Ledger polkadot signer of the Device Management Kit. It enables interaction with the polkadot application on a Ledger device including:

- Retrieving the polkadot address using a given derivation path
- Signing a polkadot transaction

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get Address](#use-case-1-get-address)
   - [Sign Transaction](#use-case-2-sign-transaction)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Polkadot Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-polkadot` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-polkadot
```

## 🔹 Initialisation

To initialise a Polkadot signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerPolkadotBuilder`:

```typescript
const signerPolkadot = new SignerPolkadotBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerPolkadotBuilder.build()` method will return a `SignerPolkadot` instance that exposes 2 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get Address

This method allows users to retrieve the polkadot address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerPolkadot.getAddress(
  derivationPath,
  ss58Prefix,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the polkadot address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `ss58Prefix`

  - **Required**
  - **Type:** `number` (e.g., `0` for Polkadot, `42` for Bittensor)
  - The SS58 address format prefix for the target network.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the polkadot app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  publicKey: Uint8Array;
  chainCode?: Uint8Array;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Sign Transaction

This method allows users to sign a polkadot transaction.

```typescript
const { observable, cancel } = signerPolkadot.signTransaction(
  derivationPath,
  blob,
  metadata,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the polkadot transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `blob`

  - **Required**
  - **Type:** `Uint8Array`
  - The SCALE-encoded transaction payload to be signed.

- `metadata`

  - **Required**
  - **Type:** `Uint8Array`
  - The metadata proof used for transaction clear signing (Ledger Polkadot generic app).

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the polkadot app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array;
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Polkadot Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/solana -->

---
title: "Solana Signer Kit"
category: reference
---

# Solana Signer Kit

This module provides the implementation of the Ledger Solana signer of the Device Management Kit. It enables interaction with the Solana application on a Ledger device including:

- Retrieving the Solana address using a given derivation path;
- Signing a Solana transaction;
- Signing an offchain message displayed on a Ledger device;
- Retrieving the app configuration;

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get Address](#use-case-1-get-address)
   - [Sign Transaction](#use-case-2-sign-transaction)
   - [Sign Message](#use-case-3-sign-message)
   - [Get App Configuration](#use-case-4-get-app-configuration)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Solana Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-solana` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-solana
```

## 🔹 Initialisation

To initialise a Solana signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerSolanaBuilder` along with the [Context Module](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/signer/context-module) by default developed by Ledger:

```typescript
const signerSolana = new SignerSolanaBuilder({
  dmk,
  sessionId,
  solanaRPCURL: "https://api.mainnet-beta.solana.com/",
}).build();
```

- **solanaRPCURL** _(optional)_ — Default Solana RPC endpoint for transaction inspection (SPL token resolution) and fetching a fresh `recentBlockhash` during delayed signing. Override per call with `SolanaTransactionOptionalConfig.solanaRPCURL`. In browser environments, use a CORS-enabled RPC URL.

## 🔹 Use Cases

The `SignerSolanaBuilder.build()` method will return a `SignerSolana` instance that exposes 4 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get Address

This method allows users to retrieve the Solana address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerSolana.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/501'/0'"`)
  - The derivation path used for the Solana address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressDAOutput = string; // base58-encoded Solana address
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Sign Transaction

Securely sign a Solana or SPL transaction using **Clear Signing** on Ledger devices.

```ts
const { observable, cancel } = signerSolana.signTransaction(
  derivationPath,
  transaction,
  transactionOptions,
);
```

---

### Parameters

**Required**

- **derivationPath** `string`\
  The derivation path used in the transaction.\
  See [Ledger’s guide](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- **transaction** `Uint8Array`\
  Serialized transaction bytes. Accepts both raw message bytes (`tx.serializeMessage()`) and the full wire-format transaction (`tx.serialize()`). When the full wire-format is provided, co-signer signatures are forwarded to Transaction Check automatically.

**Optional**

- **transactionOptions** `SolanaTransactionOptionalConfig`\
  Provides additional context for transaction signing.

  - **solanaRPCURL** `string` _(optional)_\
    Overrides the RPC URL from `SignerSolanaBuilder` for this call (inspection and delayed signing).

  - **transactionResolutionContext** `object` _(optional)_\
    Provides additional context for clear signing.

    - **mintAddress** `string`\
      Mint address of the SPL token, used for SPL basic clear signing. If omitted, the signer will attempt to resolve the token metadata automatically, if resolution fails, a degraded UI is shown on the device (`???` instead of the token symbol).

- **skipOpenApp** `boolean`\
  If `true`, skips opening the Solana app on the device.

---

### Returns

- `observable` That emits DeviceActionState updates, including the following details:

```ts
type SignTransactionDAOutput = Uint8Array; // raw signature (64 bytes)
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Internal Flow

Under the hood, this method subscribes to an\
`Observable<DeviceActionState<Uint8Array, SignTransactionDAError, IntermediateValue>>`.

#### DeviceActionState

Represents the lifecycle of a device action:

```ts
type DeviceActionState<Output, Error, IntermediateValue> =
  | { status: DeviceActionStatus.NotStarted }
  | { status: DeviceActionStatus.Pending; intermediateValue: IntermediateValue }
  | { status: DeviceActionStatus.Stopped }
  | { status: DeviceActionStatus.Completed; output: Output }
  | { status: DeviceActionStatus.Error; error: Error };

enum DeviceActionStatus {
  NotStarted = "not-started",
  Pending = "pending",
  Stopped = "stopped",
  Completed = "completed",
  Error = "error",
}
```

- **NotStarted** → Action hasn’t begun.
- **Pending** → Waiting for user confirmation on the device.\
  Includes an `intermediateValue` of type `IntermediateValue`.
- **Stopped** → Action was cancelled before completion.
- **Completed** → Provides the raw 64-byte Ed25519 signature (`Uint8Array`).
- **Error** → The device or signing operation failed (`SignTransactionDAError`).

---

### Example

```ts
const { observable } = dmkSigner.signTransaction(
  "m/44'/501'/0'/0'",
  serializedTx,
  {
    transactionResolutionContext: resolution,
  },
);

const subscription = observable.subscribe({
  next: (state) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        console.log("Waiting for user action...", state.intermediateValue);
        break;
      case DeviceActionStatus.Completed:
        console.log("Signature:", state.output);
        break;
      case DeviceActionStatus.Error:
        console.error("Error:", state.error);
        break;
    }
  },
  error: (err) => console.error("Observable error:", err),
  complete: () => console.log("Signing flow ended"),
});

// Later if needed:
// subscription.unsubscribe();
```

#### **Notes**

- Clear Signing only supports simple instructions like a single `transfer` or combos like `createAccount + fundAccount` or `createAccount + transfer`. If you are receiving `6808` error from device, most likely the instructions are not supported and blind signing is required.

---

### Use Case 3: Sign Message

Sign a Solana off-chain message on Ledger devices. Supports multiple signing
modes via `SignMessageVersion`:

- **V0** (default) — original [off-chain message](https://docs.anza.xyz/proposals/off-chain-message-signing) header with `appDomain` and signer fields. Supported on all firmware with off-chain signing. Falls back to Legacy on `6a81`.
- **V1** — simplified header per [sRFC 38](https://github.com/solana-foundation/SRFCs/discussions/3): no `appDomain`, no format byte. Use `signers` to bind the message to a specific application instead. Requires Solana device app version 1.14+. Falls back to V0 then Legacy on `6a81`.
- **Legacy** — compact header for backward compatibility with very old Solana app firmware. Current firmware will reject it.
- **Raw** — pass-through: the caller provides the fully formatted payload as a `Uint8Array` and the SDK sends it as-is with no header wrapping.

```typescript
const { observable, cancel } = signerSolana.signMessage(
  derivationPath,
  message,
  options,
);
```

---

### Parameters

**Required**

- **derivationPath** `string`
  The derivation path used for signing (e.g., `"44'/501'/0'"`).
  See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- **message** `string | Uint8Array`
  The message to sign. Pass a `string` for V0/V1/Legacy modes (UTF-8 encoded
  automatically). Pass a `Uint8Array` for Raw mode when you have an
  already-formatted payload.

**Optional**

- **options** `MessageOptions`

  - **version** `SignMessageVersion`
    Off-chain message signing mode. Defaults to `SignMessageVersion.V0`.

  - **appDomain** `string`
    V0 only: application domain included in the off-chain message header
    (UTF-8 encoded, padded/truncated to 32 bytes). Defaults to 32 zero bytes.
    Ignored for V1, Legacy, and Raw.

  - **signers** `Uint8Array[]`
    V1 only: additional required signers to include in the off-chain message header alongside the user's key. Per sRFC 38, this is the recommended replacement for the V0 `appDomain` field — pass the dApp's public key here to bind the message to a specific application. Signers are sorted and deduplicated automatically.
    Each entry must be a 32-byte Ed25519 public key. At most 254 additional signers are supported (1 slot is reserved for the user's key). Passing a signer with the wrong length or exceeding the limit returns an error before any device communication.
    Ignored for V0, Legacy, and Raw.

  - **skipOpenApp** `boolean`
    If `true`, skips opening the Solana app on the device.

```typescript
import { SignMessageVersion } from "@ledgerhq/device-signer-kit-solana";

type MessageOptions = {
  version?: SignMessageVersion;
  appDomain?: string; // V0 only
  signers?: Uint8Array[]; // V1 only
  skipOpenApp?: boolean;
};
```

#### Fallback Cascade

When the device rejects an off-chain message header with `6a81` (invalid data),
the SDK automatically retries with an older format:

| Starting Version | Fallback Path    |
| ---------------- | ---------------- |
| V1               | V1 → V0 → Legacy |
| V0               | V0 → Legacy      |
| Legacy / Raw     | No fallback      |

---

### Returns

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type SignMessageDAOutput = {
  signature: string; // base58-encoded signature envelope (V0/V1/Legacy) or raw base58 signature (Raw)
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Example

```typescript
import { SignMessageVersion } from "@ledgerhq/device-signer-kit-solana";

// V0 — sign with app domain
const { observable } = signerSolana.signMessage(
  "44'/501'/0'/0'",
  "Hello World",
  {
    version: SignMessageVersion.V0,
    appDomain: "my-app.com",
  },
);

observable.subscribe({
  next: (state) => {
    switch (state.status) {
      case DeviceActionStatus.Pending:
        console.log("Waiting for user action...", state.intermediateValue);
        break;
      case DeviceActionStatus.Completed:
        console.log("Signature:", state.output.signature);
        break;
      case DeviceActionStatus.Error:
        console.error("Error:", state.error);
        break;
    }
  },
  error: (err) => console.error("Observable error:", err),
  complete: () => console.log("Signing flow ended"),
});
```

#### V1 with Additional Signers

V1 removes `appDomain` (no central registry — anyone could spoof it). To bind a message to a specific application, add the dApp's public key as a required signer instead:

```typescript
// V1 — bind message to dApp via required signer (sRFC 38)
const { observable } = signerSolana.signMessage(
  "44'/501'/0'/0'",
  "Hello World",
  {
    version: SignMessageVersion.V1,
    signers: [dAppPubkeyBytes], // dApp's Ed25519 public key as Uint8Array(32)
  },
);
```

#### Raw Mode

In Raw mode, the caller is responsible for constructing the full off-chain
message payload. Pass it as a `Uint8Array`:

```typescript
const rawPayload = new Uint8Array([
  /* pre-built OCM bytes */
]);

const { observable } = signerSolana.signMessage("44'/501'/0'/0'", rawPayload, {
  version: SignMessageVersion.Raw,
});
```

#### **Notes**

- The output `signature` is a base58-encoded string. For V0/V1/Legacy modes it
  is a full envelope (signature count + signature + serialized off-chain
  message). For Raw mode it is the plain base58-encoded 64-byte Ed25519
  signature.

---

### Use Case 4: Get App Configuration

This method allows the user to fetch the current app configuration.

```typescript
const { observable, cancel } = signerSolana.getAppConfiguration();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type AppConfiguration = {
  blindSigningEnabled: boolean;
  pubKeyDisplayMode: PublicKeyDisplayMode;
  version: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation’s progress and status:

- **NotStarted**: The operation hasn’t started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTypedData: {
    // User needs to sign the typed data displayed on the device
    console.log("User needs to sign the typed data displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Solana Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/trx -->

# Tron Signer Kit

This module provides the implementation of the Ledger Tron signer of the Device Management Kit. It enables interaction with the Tron (TRX) application on a Ledger device including:

- Retrieving the Tron address using a given derivation path
- Signing a Tron transaction
- Signing a Tron transaction hash
- Signing a personal message
- Retrieving the app configuration
- Computing an ECDH shared secret with a peer public key

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Address](#use-case-2-get-address)
   - [Sign Transaction](#use-case-3-sign-transaction)
   - [Sign Transaction Hash](#use-case-4-sign-transaction-hash)
   - [Sign Personal Message](#use-case-5-sign-personal-message)
   - [Get ECDH Secret](#use-case-6-get-ecdh-secret)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Tron Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-tron` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-tron
```

## 🔹 Initialisation

To initialise a Tron signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerTrxBuilder`:

```typescript
const signerTrx = new SignerTrxBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerTrxBuilder.build()` method will return a `SignerTrx` instance that exposes 6 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

> **Note:** Tron uses the BIP44 coin type `195`, so derivation paths look like `"44'/195'/0'/0/0"`.

---

### Use Case 1: Get App Configuration

This method allows users to retrieve the app configuration from the Ledger device.

```typescript
const { observable, cancel } = signerTrx.getAppConfiguration();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type AppConfiguration = {
  version: string;
  versionN: number;
  allowData: boolean;
  allowContract: boolean;
  truncateAddress: boolean;
  signByHash: boolean;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Address

This method allows users to retrieve the Tron address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerTrx.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/195'/0'/0/0"`)
  - The derivation path used for the Tron address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Tron app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  publicKey: string; // hex-encoded public key
  address: string; // Base58 Tron address (e.g. "TWdnWBzFdBP1b8sqZ5RcFDbkV3sBmnxsYu")
  chainCode?: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Transaction

This method allows users to sign a Tron transaction.

```typescript
const { observable, cancel } = signerTrx.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/195'/0'/0/0"`)
  - The derivation path used for the Tron transaction.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized (protobuf) transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Tron app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array; // 65-byte signature
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign Transaction Hash

This method allows users to sign a raw Tron transaction hash. Signing a bare hash is a blind-signing operation, so use it with caution.

```typescript
const { observable, cancel } = signerTrx.signTransactionHash(
  derivationPath,
  transactionHash,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/195'/0'/0/0"`)
  - The derivation path used for the Tron transaction hash.

- `transactionHash`

  - **Required**
  - **Type:** `Uint8Array`
  - The 32-byte transaction hash to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Tron app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array; // 65-byte signature
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Sign Personal Message

This method allows users to sign a personal message (TRON's `signMessage` / TIP-191 flow).

```typescript
const { observable, cancel } = signerTrx.signPersonalMessage(
  derivationPath,
  message,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/195'/0'/0/0"`)
  - The derivation path used to sign the message.

- `message`

  - **Required**
  - **Type:** `string | Uint8Array`
  - The message to be signed, either as a UTF-8 string or as raw bytes.

- `options`

  - Optional

  - Type: `MessageOptions`

    ```typescript
    type MessageOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Tron app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = Uint8Array; // 65-byte signature
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 6: Get ECDH Secret

This method computes an ECDH shared secret between the device key (derived from the BIP32 path) and a peer's uncompressed secp256k1 public key. The operation is shown on the device for approval.

```typescript
const { observable, cancel } = signerTrx.getECDHSecret(
  derivationPath,
  publicKey,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/195'/0'/0/0"`)
  - The derivation path used to derive the device key.

- `publicKey`

  - **Required**
  - **Type:** `Uint8Array`
  - The peer's uncompressed secp256k1 public key (65 bytes, `0x04 || X || Y`).

- `options`

  - Optional

  - Type: `EcdhOptions`

    ```typescript
    type EcdhOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the Tron app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
// The 65-byte ECDH shared point (0x04 || X || Y).
type GetECDHSecretDAOutput = Uint8Array;
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Tron Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/xrp -->

# Xrp Signer Kit

This module provides the implementation of the Ledger xrp signer of the Device Management Kit. It enables interaction with the xrp application on a Ledger device including:

- Retrieving the xrp address using a given derivation path
- Signing a xrp transaction
- Retrieving the app configuration

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Address](#use-case-2-get-address)
   - [Sign Transaction](#use-case-3-sign-transaction)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Xrp Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-xrp` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-xrp
```

## 🔹 Initialisation

To initialise a Xrp signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerXrpBuilder`:

```typescript
const signerXrp = new SignerXrpBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerXrpBuilder.build()` method will return a `SignerXrp` instance that exposes 3 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get App Configuration

This method allows users to retrieve the app configuration from the Ledger device.

```typescript
const { observable, cancel } = signerXrp.getAppConfig(options);
```

#### **Parameters**

- `options`

  - Optional

  - Type: `AppConfigOptions`

    ```typescript
    type AppConfigOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the xrp app automatically (`true`) or not (`false`). Defaults to `false`.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAppConfigCommandResponse = {
  readonly version: string;
};
```

- `version`: The version of the XRP application installed on the device, formatted as `"major.minor.patch"` (e.g. `"2.5.2"`).

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Address

This method allows users to retrieve the xrp address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerXrp.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/144'/0'/0/0"`)
  - The derivation path used for the xrp address. At most 10 elements, as the XRP application rejects longer paths. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      returnChainCode?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`). Defaults to `false`.

  - `returnChainCode`: An optional boolean indicating whether the BIP32 chain code should be returned alongside the address (`true`) or not (`false`). Defaults to `false`.

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the xrp app automatically (`true`) or not (`false`). Defaults to `false`.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  /** Uncompressed public key, hex encoded. */
  publicKey: string;
  /** The XRP address, as returned by the application. */
  address: string;
  /** BIP32 chain code, hex encoded. Only set when `returnChainCode` was set. */
  chainCode?: string;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Sign Transaction

This method allows users to sign a xrp transaction.

```typescript
const { observable, cancel } = signerXrp.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the xrp transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the xrp app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Xrp Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/signers/zcash -->

# Zcash Signer Kit

This module provides the implementation of the Ledger zcash signer of the Device Management Kit. It enables interaction with the zcash application on a Ledger device including:

- Retrieving the zcash address using a given derivation path
- Retrieving a unified shielded address (Orchard receiver) using a given transparent derivation path
- Retrieving the zcash full viewing key (UFVK or Orchard FVK)
- Signing a zcash transaction
- Signing a message displayed on a Ledger device
- Retrieving the app configuration

## 🔹 Index

1. [How it works](#-how-it-works)
2. [Installation](#-installation)
3. [Initialisation](#-initialisation)
4. [Use Cases](#-use-cases)
   - [Get App Configuration](#use-case-1-get-app-configuration)
   - [Get Address](#use-case-2-get-address)
   - [Get Full Viewing Key](#use-case-3-get-full-viewing-key)
   - [Sign Transaction](#use-case-4-sign-transaction)
   - [Sign PCZT Transaction](#use-case-5-sign-pczt-transaction)
   - [Sign Message](#use-case-6-sign-message)
   - [Get Shielded Address](#use-case-7-get-shielded-address)
5. [Observable Behavior](#-observable-behavior)
6. [Example](#-example)

## 🔹 How it works

The Ledger Zcash Signer utilizes the advanced capabilities of the Ledger device to provide secure operations for end users. It takes advantage of the interface provided by the Device Management Kit to establish communication with the Ledger device and execute various operations. The communication with the Ledger device is performed using [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)s (Application Protocol Data Units), which are encapsulated within the `Command` object. These commands are then organized into tasks, allowing for the execution of complex operations with one or more APDUs. The tasks are further encapsulated within `DeviceAction` objects to handle different real-world scenarios. Finally, the Signer exposes dedicated and independent use cases that can be directly utilized by end users.

## 🔹 Installation

> **Note:** This module is not standalone; it depends on the [@ledgerhq/device-management-kit](https://github.com/LedgerHQ/device-sdk-ts/tree/develop/packages/device-management-kit) package, so you need to install it first.

To install the `device-signer-kit-zcash` package, run the following command:

```sh
npm install @ledgerhq/device-signer-kit-zcash
```

## 🔹 Initialisation

To initialise a Zcash signer instance, you need a Ledger Device Management Kit instance and the ID of the session of the connected device. Use the `SignerZcashBuilder`:

```typescript
const signerZcash = new SignerZcashBuilder({ dmk, sessionId }).build();
```

## 🔹 Use Cases

The `SignerZcashBuilder.build()` method will return a `SignerZcash` instance that exposes 5 dedicated methods, each of which calls an independent use case. Each use case will return an object that contains an observable and a method called `cancel`.

---

### Use Case 1: Get App Configuration

This method allows users to retrieve the app configuration from the Ledger device.

```typescript
const { observable, cancel } = signerZcash.getAppConfig();
```

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAppConfigCommandResponse = {
  version: string; // e.g. "3.5.0"
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 2: Get Address

This method allows users to retrieve the zcash address based on a given `derivationPath`.

```typescript
const { observable, cancel } = signerZcash.getAddress(derivationPath, options);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the zcash address. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the zcash app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetAddressCommandResponse = {
  publicKey: Uint8Array;
  chainCode?: Uint8Array;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 3: Get Full Viewing Key

This method allows users to retrieve the zcash full viewing key based on a given ZIP-32 account `derivationPath`.

```typescript
const { observable, cancel } = signerZcash.getFullViewingKey(
  derivationPath,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"32'/133'/0'"`)
  - The account-level ZIP-32 derivation path used for the zcash full viewing key.

- `options`

  - Optional

  - Type: `FullViewingKeyOptions`

    ```typescript
    type FullViewingKeyOptions = {
      mode?: "ufvk" | "orchardFvk";
      skipOpenApp?: boolean;
    };
    ```

  - `mode`: Optional export mode. Defaults to `"ufvk"`.
    - `"ufvk"` returns the Unified Full Viewing Key as a UTF-8 string.
    - `"orchardFvk"` returns the raw Orchard Full Viewing Key bytes (`Uint8Array`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the zcash app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetFullViewingKeyResult =
  | {
      mode: "ufvk";
      fullViewingKey: string;
    }
  | {
      mode: "orchardFvk";
      fullViewingKey: Uint8Array;
    };
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 4: Sign Transaction

This method allows users to sign a zcash transaction.

```typescript
const { observable, cancel } = signerZcash.signTransaction(
  derivationPath,
  transaction,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the zcash transaction. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `transaction`

  - **Required**
  - **Type:** `Uint8Array`
  - The serialized transaction to be signed.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the zcash app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 5: Sign PCZT Transaction

This method signs an Orchard **shielded** transaction expressed as a PCZT (Partially Constructed Zcash Transaction). The host (zcash-utils) builds the PCZT and passes the structured `PcztTransaction` to the signer, which streams the header, transparent inputs/outputs, and Orchard actions to the device. The device returns the raw per-action Orchard `spendAuthSig`s and per-input transparent signatures; the binding signature and final transaction assembly are computed host-side and never involve the device. The legacy transparent `signTransaction` path is unchanged.

```typescript
const { observable, cancel } = signerZcash.signPcztTransaction(
  transaction,
  options,
);
```

#### **Parameters**

- `transaction`

  - **Required**
  - **Type:** `PcztTransaction`
  - The structured PCZT to sign. Transparent sections are always streamed (count `0` when empty); `orchardBundle` may be `null` (treated as an empty Orchard bundle). All multi-byte integer fields are little-endian on the wire, except derivation-path components (big-endian `Bip32Path`).

    ```typescript
    type PcztTransaction = {
      global: PcztGlobal;
      transparentInputs: PcztTransparentInput[];
      transparentOutputs: PcztTransparentOutput[];
      orchardBundle: PcztOrchardBundle | null;
    };

    type PcztGlobal = {
      txVersion: number; // V5 = 5
      versionGroupId: number;
      consensusBranchId: number;
      fallbackLockTime: number | null; // Option<u32>; null = absent
      expiryHeight: number;
      coinType: number; // 133 mainnet, 1 testnet
      txModifiable: number;
    };

    type PcztBip32Derivation = {
      signingPath: string;
      pubkey: Uint8Array; // compressed secp256k1, 33 bytes
      seedFingerprint?: Uint8Array; // ZIP-32, 32 bytes
    };

    type PcztTransparentInput = {
      prevoutTxid: Uint8Array; // 32 bytes
      prevoutIndex: number;
      sequence: number | null; // Option<u32>; null = absent
      value: bigint; // zatoshis
      scriptPubKey: Uint8Array;
      sighashType: number; // must be SIGHASH_ALL (0x01)
      derivation: PcztBip32Derivation;
    };

    type PcztTransparentOutput = {
      value: bigint; // zatoshis
      scriptPubKey: Uint8Array;
      derivation?: PcztBip32Derivation | null; // entry count 0 or 1
    };

    type PcztOrchardBundle = {
      actions: PcztOrchardAction[];
      flags: number;
      valueBalance: bigint; // net value balance, zatoshis (signed)
      anchor: Uint8Array; // commitment-tree anchor, 32 bytes
    };
    ```

    Each `PcztOrchardAction` carries the spend and output halves of one Orchard action (value/nullifier/rk commitments, spent- and output-note fields, the host-supplied spend-auth randomizer `alpha`, the signing `signingPath`, and the randomized commitment value `rcv`). See the `PcztOrchardAction` type exported from `@ledgerhq/device-signer-kit-zcash` for the full field list.

- `options`

  - Optional

  - Type: `TransactionOptions`

    ```typescript
    type TransactionOptions = {
      skipOpenApp?: boolean;
    };
    ```

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the zcash app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates. The final output is:

```typescript
type SignPcztTransactionResult = {
  // one spendAuthSig per Orchard action, in action order
  orchard: Array<{ spendAuthSig: Uint8Array }>; // RedPallas sig, 64 bytes each
  // one signature per transparent input, in input order:
  // DER-encoded secp256k1 signature + trailing sighash_type byte (0x01)
  transparentInputSigs: Uint8Array[];
};
```

There is no `bindingSig` in the result — it is computed host-side from `bsk = Σ rcv`. On `Pending`, `requiredUserInteraction` is `UserInteractionRequired.SignTransaction`.

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 6: Sign Message

This method allows users to sign a text string that is displayed on Ledger devices.

```typescript
const { observable, cancel } = signerZcash.signMessage(derivationPath, message);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"m/44'/0'/0'/0/0"`)
  - The derivation path used for the zcash message. See [here](https://www.ledger.com/blog/understanding-crypto-addresses-and-derivation-paths) for more information.

- `message`

  - **Required**
  - **Type:** `string | Uint8Array`
  - The message to be signed, which will be displayed on the Ledger device.

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type Signature = {
  r: string;
  s: string;
  v?: number;
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

### Use Case 7: Get Shielded Address

This method allows users to retrieve a unified shielded address (single Orchard receiver) based on a transparent derivation path. The device uses the transparent path for account matching and on-device display; the returned unified address begins with `u1`.

```typescript
const { observable, cancel } = signerZcash.getShieldedAddress(
  derivationPath,
  options,
);
```

#### **Parameters**

- `derivationPath`

  - **Required**
  - **Type:** `string` (e.g., `"44'/133'/0'/0/0"`)
  - Transparent derivation path (BIP-44). The Orchard account path (`32'/coin/account'`) is derived from it automatically.

- `options`

  - Optional

  - Type: `AddressOptions`

    ```typescript
    type AddressOptions = {
      checkOnDevice?: boolean;
      skipOpenApp?: boolean;
    };
    ```

  - `checkOnDevice`: An optional boolean indicating whether user confirmation on the device is required (`true`) or not (`false`).

  - `skipOpenApp`: An optional boolean indicating whether to skip opening the zcash app automatically (`true`) or not (`false`).

#### **Returns**

- `observable` Emits DeviceActionState updates, including the following details:

```typescript
type GetShieldedAddressDAOutput = {
  readonly address: string; // unified address beginning with "u1"
};
```

- `cancel` A function to cancel the action on the Ledger device.

---

## 🔹 Observable Behavior

Each method returns an [Observable](https://rxjs.dev/guide/observable) emitting updates structured as [`DeviceActionState`](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/src/api/device-action/model/DeviceActionState.ts). These updates reflect the operation's progress and status:

- **NotStarted**: The operation hasn't started.
- **Pending**: The operation is in progress and may require user interaction.
- **Stopped**: The operation was canceled or stopped.
- **Completed**: The operation completed successfully, with results available.
- **Error**: An error occurred.

**Example Observable Subscription:**

```typescript
observable.subscribe({
  next: (state: DeviceActionState) => {
    switch (state.status) {
      case DeviceActionStatus.NotStarted: {
        console.log("The action is not started yet.");
        break;
      }
      case DeviceActionStatus.Pending: {
        const {
          intermediateValue: { requiredUserInteraction },
        } = state;
        // Access the intermediate value here, explained below
        console.log(
          "The action is pending and the intermediate value is: ",
          intermediateValue,
        );
        break;
      }
      case DeviceActionStatus.Stopped: {
        console.log("The action has been stopped.");
        break;
      }
      case DeviceActionStatus.Completed: {
        const { output } = state;
        // Access the output of the completed action here
        console.log("The action has been completed: ", output);
        break;
      }
      case DeviceActionStatus.Error: {
        const { error } = state;
        // Access the error here if occurred
        console.log("An error occurred during the action: ", error);
        break;
      }
    }
  },
});
```

**Intermediate Values in Pending Status:**

When the status is DeviceActionStatus.Pending, the state will include an `intermediateValue` object that provides useful information for interaction:

```typescript
const { requiredUserInteraction } = intermediateValue;

switch (requiredUserInteraction) {
  case UserInteractionRequired.VerifyAddress: {
    // User needs to verify the address displayed on the device
    console.log("User needs to verify the address displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignTransaction: {
    // User needs to sign the transaction displayed on the device
    console.log("User needs to sign the transaction displayed on the device.");
    break;
  }
  case UserInteractionRequired.SignPersonalMessage: {
    // User needs to sign the message displayed on the device
    console.log("User needs to sign the message displayed on the device.");
    break;
  }
  case UserInteractionRequired.None: {
    // No user action required
    console.log("No user action needed.");
    break;
  }
  case UserInteractionRequired.UnlockDevice: {
    // User needs to unlock the device
    console.log("The user needs to unlock the device.");
    break;
  }
  case UserInteractionRequired.ConfirmOpenApp: {
    // User needs to confirm on the device to open the app
    console.log("The user needs to confirm on the device to open the app.");
    break;
  }
  default:
    // Type guard to ensure all cases are handled
    const uncaughtUserInteraction: never = requiredUserInteraction;
    console.error("Unhandled user interaction case:", uncaughtUserInteraction);
}
```

## 🔹 Example

We encourage you to explore the Zcash Signer by trying it out in our online [sample application](https://app.devicesdk.ledger-test.com/). Experience how it works and see its capabilities in action. Of course, you will need a Ledger device connected.

---

<!-- https://developers.ledger.com/docs/device-interaction/dmk-ts/references/ts-doc -->

---
title: "TS Doc"
category: reference
---

# TS Doc

Device Management Kits References:

- [Device Management Kit]() - _Coming Soon..._
- [Device Signer Kit Ethereum]() - _Coming Soon..._

---

<!-- https://developers.ledger.com/docs/device-interaction/getting-started -->

# Documentation

Embedded: [YouTube video player](https://www.youtube-nocookie.com/embed/i-Q1ld2lG_4)

Here you will find all the documentation related to the Device Management Kit and the signers that come along with it.

## Glossary

Throughout the documentation we use the following acronyms:

- DMK: Device Management Kit
- DSK: Device Signer Kit

## Platforms Supported

You can find here the platforms supported by the DMK.

With the typescript DMK, you can use the following platforms:

- Web
- React Native
- Node.js

Check here the [TS DMK documentation](./dmk-ts).

With the mobile DMK, you can use the following platforms:

- Android
- iOS
- Kotlin Multiplatform (Android and iOS)

Check here the [KMP DMK documentation](./dmk-kmp).

## Legal notice

The Device Management Kit (DMK) is made available under an open source license and is free to use for development, testing, and integration purposes.

Please note that access to the DMK does not grant you any rights to access Ledger SAS backend services, nor any rights to use tokens, APIs, or infrastructure beyond what is explicitly allowed under the open source license. Access to Ledger SAS backend is strictly prohibited unless explicitly authorized by Ledger SAS.

Use of any token to gain access to Ledger SAS backend without a formal, written legal agreement is forbidden. Unauthorized use or access may lead to legal claims, including but not limited to injunctive relief, damages, or other remedies permitted under applicable law.

---

<!-- https://developers.ledger.com/docs/ledger-live/accounts/getting-started -->

---
title: Adding your blockchain to Ledger Wallet
category: explanation
---

# Adding your blockchain to Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

## Introduction

This guide walks you through the process of adding your blockchain to , giving millions of users the ability to manage your digital assets securely using Ledger's trusted signers.

&#x20;is Ledger's flagship application providing a unified interface for managing cryptocurrencies and digital assets across desktop (Windows, macOS) and mobile (iOS, Android). By integrating your blockchain, you give your community access to secure asset management, standardized UI components, and multi-platform support across all major operating systems.

> **Warning:** Do not start development without signing an agreement with our teams. Before building, [fill in this form](https://docs.google.com/forms/d/e/1FAIpQLScc_luftAe3Y9f7Y89aGjCa-z3XPOf1cVfIEeOZzhgx71MYbQ/viewform?usp=sharing\&ouid=107637591620972246516) and we will get back to you.

## Languages

The integration touches several layers of the Ledger Wallet stack. The table below shows the required skills for each development step.

| Development step                          | Required skills                                  |
| ----------------------------------------- | ------------------------------------------------ |
| Creation of new coin module               | TypeScript, RxJS                                 |
| Modification of live-common, LLD, and LLM | TypeScript, React Native                         |
| RPC node access                           | DevOps and server hosting/cloud                  |
| Data indexers                             | Backend data processing                          |
| Block explorer (if needed)                | Web framework (for example, Rails or a JS stack) |

## Setup

### Requirements

- [Node.js 18.x](https://nodejs.org/)
- [pnpm 8.x](https://pnpm.io/)
- Python 2.7 or 3.5+
- A C/C++ toolchain (see [node-gyp documentation](https://github.com/nodejs/node-gyp#installation))

### Development tools

- [eslint](https://github.com/eslint/eslint) — install the [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for in-editor feedback
- [prettier](https://github.com/prettier/prettier) — applied via an ESLint plugin
- [typescript](https://www.typescriptlang.org/) — verify it is working in your IDE before starting

### Hardware prerequisites

- A physical Ledger signer
- The MyCoin app installed on the signer

### Installation

1. Fork and clone the Ledger Wallet repository: [https://github.com/LedgerHQ/ledger-live](https://github.com/LedgerHQ/ledger-live)
2. `cd ledger-live`
3. Install dependencies: `pnpm i`

> **Caution:** The rest of this documentation is only available after signing in. To get access and start building, [fill in this form](https://docs.google.com/forms/d/e/1FAIpQLScc_luftAe3Y9f7Y89aGjCa-z3XPOf1cVfIEeOZzhgx71MYbQ/viewform?usp=sharing\&ouid=107637591620972246516) and we will get back to you.

## Sign in

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/explanation/architecture-decisions -->

# Architecture Decisions

This page explains the reasoning behind the Ledger Wallet architecture: why we adopted a feature-first structure, why we use the MVVM pattern, and how the codebase is evolving through migration.

---

## The Migration Journey

The Ledger Wallet codebase is undergoing a significant architectural evolution. Understanding the history helps make sense of the current state.

| Phase                          | Status              | Description                                                   |
| ------------------------------ | ------------------- | ------------------------------------------------------------- |
| **Legacy Code**                | Ongoing             | Pre-MVVM code in `apps/*/src/` — being progressively migrated |
| **MVVM Pattern**               | Standard (2+ years) | ViewModel pattern in `src/mvvm/` — used for new development   |
| **Feature-First Architecture** | In Progress         | New target: root-level `features/` folders                    |

The codebase currently contains three layers of code:

| Layer             | Location                        | Description                                                    |
| ----------------- | ------------------------------- | -------------------------------------------------------------- |
| **Legacy**        | `apps/*/src/` (outside `mvvm/`) | Pre-MVVM code, being progressively migrated                    |
| **MVVM**          | `apps/*/src/mvvm/`              | Code following the ViewModel pattern (2+ years of development) |
| **Feature-First** | Root `features/`                | New architecture target                                        |

This means:

- **New features** should be written in the [`features/`](https://github.com/LedgerHQ/ledger-live/tree/develop/features) folder at the monorepo root
- **MVVM code** in `src/mvvm/` follows the ViewModel pattern and will be progressively migrated to `features/`
- **Legacy code** predates MVVM and should be migrated when touched significantly
- **`libs/`** folder contains legacy shared libraries being progressively migrated into features

---

## Why Feature-First Architecture

The feature-first architecture is inspired by the C4 model and follows a deliberate philosophy:

- **Root level** contains everything connected to the exterior (apps, platform concerns)
- **One level deep** contains core business capabilities (features)
- **Two levels deep** contains feature-related business logic

### Design Goals

The architecture was designed to address specific pain points in the previous structure:

1. **Ease codebase discovery** — A clear, intuitive folder structure helps new contributors find what they need. Instead of navigating deep into platform-specific folders, features are visible at the root level.

2. **Highlight domain-specific code** — Domain-Driven Design principles make business logic explicit. Each feature encapsulates its own domain entities within its `data-layer/` subfolder.

3. **Balance folder depth** — The previous structure suffered from both deep nesting and flat file dumps. The new structure aims for a shallow, consistent depth across the codebase.

4. **Collocate synergizing files** — Related code (components, data-layer, tests) lives together within each feature, rather than being scattered across global folders.

5. **Unify mobile and desktop** — Instead of maintaining separate codebases for mobile and desktop, features use platform-specific file extensions (`.web.ts`, `.native.ts`) to keep code close together while respecting platform differences.

### Layer Responsibilities

| Layer           | Responsibility                                                                      |
| --------------- | ----------------------------------------------------------------------------------- |
| **`apps/`**     | Platform infrastructure — routing, state manager, observability. No business logic. |
| **`features/`** | Self-contained business features with high cohesion, low coupling                   |
| **`libs/`**     | Legacy shared libraries — being progressively migrated into features                |

The strict import boundaries between these layers enforce separation of concerns. Apps wire features together but should not contain business logic. This prevents circular dependencies and makes it possible to reason about each layer independently.

---

## Why MVVM

The MVVM (Model-View-ViewModel) pattern was adopted to address a specific problem: components that mix UI rendering with business logic (Redux selectors, API calls, state transformations) become difficult to test and maintain.

### Key Principles

1. **Separation of concerns** — UI components should be pure and receive data via props. All logic that connects to outer layers (store, network, etc.) lives in the ViewModel hook.

2. **Testability** — The View component can be tested in isolation with mock props, without needing to mock Redux, API calls, or any other external dependency. The ViewModel can be tested independently as a hook.

3. **Props injection** — The ViewModel hook result is spread as props to the View. This is a deliberate design choice: by injecting props rather than calling the hook inside the component body, you get a clear boundary between "what data to use" and "what to render."

### Benefits

| Benefit         | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **Testability** | View components can be tested with simple prop mocking           |
| **Reusability** | Views can be reused with different ViewModels                    |
| **Clarity**     | Clear separation between "what to render" and "what data to use" |
| **Debugging**   | Easier to isolate issues to either UI or logic                   |

MVVM is not used everywhere — simple presentational components, pure utility components, and components that only receive props from parents don't need it. The pattern is reserved for components that connect to Redux, make API calls, or contain complex business logic.

---

## See also

- [Architecture reference](../reference/architecture) — Complete folder structure, import rules, platform extensions
- [MVVM Pattern reference](../reference/mvvm-pattern) — Implementation details and when to use
- [How to Structure a Feature](../how-to/structure-a-feature) — Step-by-step guide for applying this architecture

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/explanation/testing-strategy -->

# Testing Strategy

This page explains the principles behind our testing approach, why we favor integration tests for UI validation, and the reasoning behind the custom test renderer.

---

## Testing Principles

Our testing strategy is built on three core principles:

### 1. Focus on your components

Never test external library components. It's not your responsibility to validate third-party behavior. Your tests should verify that _your_ code works correctly, not that React, Redux, or any library does what its own tests already verify.

### 2. Favor integration tests for UI

When testing UI features with many components, integration tests provide better coverage than unit tests. An integration test exercises the full feature flow — from user interaction to state changes to UI updates — which catches issues that unit tests miss.

This applies specifically to UI testing. Pure helper functions, Redux reducers, and isolated logic still benefit from focused unit tests. The integration-first approach is for feature-level UI validation, where rendering the full feature with real providers catches more real-world bugs than testing components in isolation.

### 3. Tests should be maintainable

Avoid testing implementation details that may change. If a test breaks every time you refactor internals without changing behavior, the test is too tightly coupled. Use queries based on user-visible behavior (`ByRole`, `ByText`) rather than internal structure (`ByTestId` as a last resort).

---

## Why a Custom Test Renderer

The Ledger Wallet apps depend on many providers: Redux, theming, i18n, feature flags, navigation, analytics, React Query, and more. Before the custom renderer existed, every test had to manually wrap components in a stack of providers:

```tsx
// Before: manual provider stacking
<Provider store={mockStore}>
  <FirebaseFeatureFlagsProvider getFeature={getFeature}>
    <NavigationContainer>
      <ThemeProvider theme={theme}>
        <I18nextProvider i18n={i18n}>
          <MyComponent />
        </I18nextProvider>
      </ThemeProvider>
    </NavigationContainer>
  </FirebaseFeatureFlagsProvider>
</Provider>
```

This created several problems:

- **Boilerplate in every test file** — The provider stack was duplicated across hundreds of test files.
- **Fragile mocks** — Tests mocked `useSelector`, `useTheme`, `useTranslation`, and other hooks individually. When provider implementations changed, many mocks broke simultaneously.
- **Incomplete test environments** — Tests often ran with only a subset of providers, hiding bugs that only appeared when all providers were present.

The custom renderer solves these problems by providing a single `render()` call that includes all providers with sensible defaults. Tests use the real Redux store, real theming, real i18n — and only override what they need via `overrideInitialState` or `initialState`.

### Key Benefits

| Benefit                        | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| **No provider mocking needed** | Redux, themes, analytics, i18n, feature flags, routing are all pre-configured |
| **No selector mocking**        | Use `overrideInitialState` or `initialState` to set up state                  |
| **Feature flags ready**        | Access feature flags via `FirebaseFeatureFlagsProvider`                       |
| **Routing included**           | `NavigationContainer` (Mobile) or `MemoryRouter` (Desktop)                    |
| **User events included**       | Access `user` from render result for realistic interactions                   |
| **Store access**               | Access `store` from render result to dispatch or read state                   |
| **Full RTL API**               | All `@testing-library` utilities are re-exported                              |

---

## Further Reading

These external resources provide additional context on the testing philosophy we follow:

- [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
- [Write fewer, longer tests](https://kentcdodds.com/blog/write-fewer-longer-tests)
- [Static vs Unit vs Integration vs E2E Testing](https://kentcdodds.com/blog/static-vs-unit-vs-integration-vs-e2e-tests)
- [Testing Overview - React](https://reactjs.org/docs/testing.html)
- [Stop mocking fetch](https://kentcdodds.com/blog/stop-mocking-fetch)

---

## See also

- [Testing reference](../reference/testing) — Tools, coverage targets, renderer API, query priority
- [How to Write Tests](../how-to/write-tests) — Step-by-step guide for writing tests
- [How to Use the Custom Renderer](../how-to/use-custom-renderer) — Practical usage guide

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/getting-started -->

# Contributing to Ledger Wallet

Welcome to the contributing guide for the [Ledger Wallet (formerly Ledger Live) monorepo](https://github.com/LedgerHQ/ledger-live). This documentation covers the architecture, coding conventions, and testing practices for both Ledger Wallet Desktop (LWD) and Ledger Wallet Mobile (LWM).

> **Warning:** **Migration in Progress**: The codebase is actively migrating to a feature-first architecture. New features and refactored code should follow the guidelines described here.

## Where to start

Depending on your task, follow the appropriate path:

| Scenario                    | Start here                                                 |
| --------------------------- | ---------------------------------------------------------- |
| **Creating a new feature**  | [How to Structure a Feature](./how-to/structure-a-feature) |
| **Working in MVVM code**    | [MVVM Pattern reference](./reference/mvvm-pattern)         |
| **Working in legacy code**  | Follow existing patterns, use MVVM for new components      |
| **Writing or fixing tests** | [How to Write Tests](./how-to/write-tests)                 |
| **Your first contribution** | Read the recommended path below                            |

### Recommended reading for new contributors

1. [**Architecture Decisions**](./explanation/architecture-decisions) — Understand why the codebase is structured the way it is
2. [**Architecture reference**](./reference/architecture) — Learn the folder structure and import rules
3. [**Do's and Don'ts**](./reference/component-patterns) — Review the 9 rules before writing code
4. [**Git Conventions**](./reference/git-conventions) — Branch naming and commit message format

---

## How-to Guides

Step-by-step instructions for common contributor tasks.

- [**How to Structure a Feature**](./how-to/structure-a-feature) — Create a new feature module or work within the existing architecture
- [**How to Write Tests**](./how-to/write-tests) — Write integration and unit tests, mock APIs, debug test failures
- [**How to Use the Custom Renderer**](./how-to/use-custom-renderer) — Render components and hooks with all providers in tests

## Reference

Lookup tables, rules, and specifications to consult while working.

- [**Architecture**](./reference/architecture) — Folder structure, import rules, platform-specific file extensions
- [**MVVM Pattern**](./reference/mvvm-pattern) — ViewModel pattern structure, implementation examples, when to use
- [**Do's and Don'ts**](./reference/component-patterns) — 9 numbered rules for components and naming (use in code reviews)
- [**Testing**](./reference/testing) — Testing tools, coverage targets, custom renderer API, query priority
- [**Git Conventions**](./reference/git-conventions) — Branch naming, commit message format, Gitmoji

## Explanation

Background and rationale behind our architectural and testing decisions.

- [**Architecture Decisions**](./explanation/architecture-decisions) — Why feature-first architecture, why MVVM, and the migration journey
- [**Testing Strategy**](./explanation/testing-strategy) — Testing principles and why we favor integration tests for UI

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/how-to/structure-a-feature -->

# How to Structure a Feature

This guide shows you how to organize your code depending on the scenario you are working in.

> **Warning:** **Migration in Progress**: The codebase contains legacy, MVVM, and feature-first code. Follow the guidance below based on your scenario.

## Choose your scenario

| Scenario                   | Action                                                                             |
| -------------------------- | ---------------------------------------------------------------------------------- |
| **Creating new features**  | Use the new `features/` folder structure ([see below](#create-a-new-feature))      |
| **Working in MVVM code**   | Follow MVVM patterns — see [MVVM Pattern reference](../reference/mvvm-pattern)     |
| **Working in legacy code** | Follow existing patterns, but use MVVM for new components to ease future migration |
| **Refactoring**            | Migrate code to the feature-first architecture when scope allows                   |

---

## Create a new feature

If you are creating a new feature, place it in the [`features/`](https://github.com/LedgerHQ/ledger-live/tree/develop/features) folder at the monorepo root.

### 1. Create the feature folder

```
features/
└─ {featureName}/
   ├─ components/
   ├─ screens/
   ├─ data-layer/
   ├─ routes/
   ├─ hooks/
   └─ utils/
```

| Subfolder     | Purpose                                                              |
| ------------- | -------------------------------------------------------------------- |
| `components/` | Reusable UI components within the feature                            |
| `screens/`    | Screen-level components (can have their own `components/` subfolder) |
| `data-layer/` | State management: entities, slices, selectors, actions, API          |
| `routes/`     | Platform-agnostic routing abstraction                                |
| `hooks/`      | Feature-specific custom hooks                                        |
| `utils/`      | Feature-specific utilities                                           |

### 2. Add platform-specific files

Use file extensions to target specific platforms within each feature folder:

| Extension     | Platform                     |
| ------------- | ---------------------------- |
| `.web.ts`     | Web and Desktop (Electron)   |
| `.native.ts`  | React Native (iOS + Android) |
| `.ios.ts`     | iOS only                     |
| `.android.ts` | Android only                 |
| No extension  | Shared across all platforms  |

For example:

```
components/
├─ userInfo.ts           // Shared logic
├─ userInfo.web.ts       // Web/Desktop UI
├─ userInfo.native.ts    // Mobile UI
└─ userInfo.test.ts      // Tests
```

> **Warning:** Test files (`*.test.ts`) should always be colocated with their source files.

### 3. Use the MVVM pattern for components

For components that connect to Redux, make API calls, or contain complex logic, create a dedicated ViewModel hook:

```
ComponentName/
├─ index.tsx                    # Exports the connected component
└─ useComponentNameViewModel.ts # Contains business logic
```

Inject the ViewModel result as props to the View — see the [MVVM Pattern reference](../reference/mvvm-pattern) for the full implementation pattern.

### 4. Respect import boundaries

Apps can import from features, but features should not import from apps. See the [Architecture reference](../reference/architecture#import-rules) for the full import rules.

---

## Work within existing MVVM code

If you are modifying code in `apps/*/src/mvvm/`, follow the existing ViewModel pattern. For any new components you add, use the [MVVM Pattern](../reference/mvvm-pattern) with the correct props-injection approach.

## Work within legacy code

If you are modifying legacy code in `apps/*/src/` (outside `mvvm/`), follow the existing patterns in that area. When adding new components, prefer the MVVM pattern to ease future migration.

## Refactor legacy code

When refactoring legacy code with sufficient scope, migrate it to the feature-first architecture in `features/`. Coordinate with Product for major feature reworks.

---

## See also

- [Architecture reference](../reference/architecture) — Full folder structure, import rules, platform extensions
- [MVVM Pattern reference](../reference/mvvm-pattern) — ViewModel implementation and when to use it
- [Do's and Don'ts](../reference/component-patterns) — 9 numbered rules for naming and structure
- [Architecture Decisions](../explanation/architecture-decisions) — Why we adopted this architecture

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/how-to/use-custom-renderer -->

# How to Use the Custom Test Renderer

This guide shows you how to use the custom render utilities provided by Ledger Wallet to test components and hooks with all necessary providers pre-configured.

> **Note:** Always prefer the custom render utilities over raw `@testing-library` render functions.

---

## How to render a component (Mobile)

Import from `@tests/test-renderer`:

```tsx
import { render, screen } from "@tests/test-renderer";
import { State } from "~/reducers/types";

const { user, store } = render(<MyComponent />, {
  overrideInitialState: (state: State) => ({
    ...state,
    accounts: {
      ...state.accounts,
      active: [mockAccount],
    },
  }),
});

// Use screen queries
expect(screen.getByText("Hello")).toBeTruthy();

// Simulate user interactions
await user.press(screen.getByText("Submit"));
```

## How to render a component (Desktop)

Import from `tests/testSetup`:

```tsx
import { render, screen } from "tests/testSetup";

const { user, store, i18n } = render(<MyComponent />, {
  initialState: {
    accounts: { active: [mockAccount] },
  },
  initialRoute: "/accounts", // Optional: set initial route
});

// Use screen queries
expect(screen.getByText("Hello")).toBeInTheDocument();

// Simulate user interactions
await user.click(screen.getByRole("button", { name: "Submit" }));
```

---

## How to render a hook

### Mobile

```tsx
import { renderHook } from "@tests/test-renderer";

const { result, store } = renderHook(() => useMyCustomHook(), {
  overrideInitialState: (state) => ({
    ...state,
    settings: { ...state.settings, theme: "dark" },
  }),
});

expect(result.current.value).toBe(expectedValue);
```

### Desktop

```tsx
import { renderHook } from "tests/testSetup";

const { result, store } = renderHook(() => useMyCustomHook(), {
  initialState: {
    settings: { theme: "dark" },
  },
});

expect(result.current.value).toBe(expectedValue);
```

---

## How to customize initial state

Use `overrideInitialState` (Mobile) or `initialState` (Desktop) to set up Redux state for your tests:

- **Mobile**: Pass a function that receives the full default state and returns the modified state. You must spread the existing state to avoid replacing reducer defaults.
- **Desktop**: Pass a partial state object that is merged into the default state.

```tsx
// Mobile - function-based override
render(<MyComponent />, {
  overrideInitialState: (state: State) => ({
    ...state,
    settings: { ...state.settings, theme: "dark" },
  }),
});

// Desktop - object-based override
render(<MyComponent />, {
  initialState: {
    settings: { theme: "dark" },
  },
});
```

---

## Before vs After: why use the custom renderer

### Before (manual provider setup)

> **Caution:** This approach requires manually wrapping components with many providers:

```tsx
import { render } from "@testing-library/react-native";
import { Provider } from "react-redux";
import { ThemeProvider } from "styled-components";
import { NavigationContainer } from "@react-navigation/native";
import { FirebaseFeatureFlagsProvider } from "~/components/FirebaseFeatureFlags";
// ... many more imports

const mockStore = createMockStore({ accounts: [mockAccount] });

render(
  <Provider store={mockStore}>
    <FirebaseFeatureFlagsProvider getFeature={getFeature}>
      <NavigationContainer>
        <ThemeProvider theme={theme}>
          <I18nextProvider i18n={i18n}>
            <MyComponent />
          </I18nextProvider>
        </ThemeProvider>
      </NavigationContainer>
    </FirebaseFeatureFlagsProvider>
  </Provider>
);
```

### After (using custom renderer)

> **Note:** The custom renderer handles all provider setup automatically:

```tsx
import { render, screen } from "@tests/test-renderer";

const { user, store } = render(<MyComponent />, {
  overrideInitialState: (state) => ({
    ...state,
    accounts: { ...state.accounts, active: [mockAccount] },
  }),
});
```

---

## Mocks you no longer need

When using the custom render utilities, remove these commonly unnecessary mocks:

```tsx
// ❌ No need to mock react-i18next - I18nextProvider is included
jest.mock("react-i18next", () => ({
  useTranslation: () => ({
    t: (key) => key,
  }),
}));

// ❌ No need to mock react-redux - Provider with real store is included
jest.mock("react-redux", () => ({
  useSelector: jest.fn(),
  useStore: jest.fn(() => ({})),
}));

// ❌ No need to mock theme-related hooks
jest.mock("~/hooks/useTheme", () => ({
  useTheme: () => ({ colors: { /* ... */ } }),
}));
```

---

## See also

- [How to Write Tests](./write-tests) — Integration tests, component tests, debugging tips
- [Testing reference](../reference/testing) — Full render function API, providers included, coverage targets
- [Testing Strategy](../explanation/testing-strategy) — Why we built the custom renderer

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/how-to/write-tests -->

# How to Write Tests

This guide shows you how to write and run tests in the Ledger Wallet monorepo. It covers integration tests, component tests, API mocking, debugging, and common patterns.

> **Warning:** When you fix an issue, always provide a test to ensure the same error does not
> occur again.

## Testing requirements

| Scenario                                   | Requirement                                                                      |
| ------------------------------------------ | -------------------------------------------------------------------------------- |
| **New features** in `features/` or `mvvm/` | Must include unit and integration tests                                          |
| **Bug fixes** in new architecture          | Must include a regression test covering the use case                             |
| **New components** in legacy code          | Use new arch patterns to ease future migration                                   |
| **Major feature reworks** in legacy code   | Consider full migration to new architecture with tests (coordinate with Product) |

---

## How to write an integration test

For features with many components, integration tests provide better coverage than unit tests. Use the [custom renderer](./use-custom-renderer) to avoid manual provider setup.

```tsx
// __integrations__/searchACoin.integration.test.tsx
import * as React from "react";
import {
  screen,
  waitForElementToBeRemoved,
} from "@testing-library/react-native";
import { render } from "@tests/test-renderer";
import { MarketPages } from "./shared";
import { State } from "~/reducers/types";

describe("Market integration test", () => {
  it("Should search for a coin and navigate to detail page", async () => {
    const { user } = render(<MarketPages />, {
      overrideInitialState: (state: State) => ({
        ...state,
        settings: {
          ...state.settings,
          featureFlags: { llmMarketNewArch: { enabled: true } },
        },
      }),
    });

    expect(await screen.findByText("Bitcoin (BTC)")).toBeOnTheScreen();
    expect(await screen.findByText("Ethereum (ETH)")).toBeOnTheScreen();

    const searchInput = await screen.findByTestId("search-box");
    await user.type(searchInput, "BTC");

    await waitForElementToBeRemoved(() => screen.queryByText("Ethereum (ETH)"));

    expect(await screen.findByText("Bitcoin (BTC)")).toBeOnTheScreen();
    await user.press(screen.getByText("Bitcoin (BTC)"));

    expect(await screen.findByText("Price Statistics")).toBeOnTheScreen();
  });
});
```

---

## How to write a component test

For generic components used across the application:

```tsx
import Button from "./Button";

describe("Button component", () => {
  it("should be disabled", () => {
    render(
      <Button disabled type="submit" name="hello" className="mySuperClass">
        Hello
      </Button>
    );
    expect(screen.getByRole("button")).toBeDisabled();
  });

  it("should dispatch onClick event", () => {
    const mockFn = jest.fn();
    render(<Button onClick={mockFn}>Hello</Button>);

    userEvent.click(screen.getByRole("button"));

    expect(mockFn).toHaveBeenCalledTimes(1);
  });
});
```

---

## How to mock APIs with MSW

Use Mock Service Worker (MSW) to mock API calls. Place mock data in `__mocks__/api/*` and register handlers in `__tests__/handlers`.

### Set up shared handlers

```tsx
// __tests__/handlers/market.ts
import { http, HttpResponse } from "msw";
import marketsMock from "@mocks/api/market/markets.json";
import supportedVsCurrenciesMock from "@mocks/api/market/supportedVsCurrencies.json";

const handlers = [
  http.get(
    "https://proxycg.api.live.ledger.com/api/v3/coins/:coin/market_chart",
    ({ params }) => {
      return HttpResponse.json(
        marketsMock.find(({ id }) => id === params.coin)
      );
    }
  ),
  http.get(
    "https://proxycg.api.live.ledger.com/api/v3/simple/supported_vs_currencies",
    () => {
      return HttpResponse.json(supportedVsCurrenciesMock);
    }
  ),
];

export default handlers;
```

### Override handlers for specific tests

For edge cases where the default response is not appropriate:

```tsx
import { server, http, HttpResponse } from "@tests/server";

describe("Market page", () => {
  it("should display coins from API", async () => {
    server.use(
      http.get("https://proxycg.api.live.ledger.com/api/v3/coins/markets", () =>
        HttpResponse.json({
          data: [{ name: "Bitcoin (BTC)" }, { name: "Ethereum (ETH)" }],
        })
      )
    );

    const { user } = render(<MarketPages />);

    expect(await screen.findByText("Bitcoin (BTC)")).toBeOnTheScreen();
    expect(await screen.findByText("Ethereum (ETH)")).toBeOnTheScreen();
  });
});
```

### Handle unhandled MSW requests

If your MSW handler is set up but the mock response is not used, the request may not have been intercepted because the test was stopped by Jest before the request was sent.

Make sure you use `waitFor` to assert the UI reflects the API response before the test ends:

```tsx
import { render, screen, waitFor } from "@tests/test-renderer";

render(<MyComponent />);

// Wait for the API response to be reflected in the UI
await waitFor(() => {
  expect(screen.getByText("Data from API")).toBeOnTheScreen();
});
```

> **Warning:** Always ensure your test waits for async operations to complete before assertions. This prevents race conditions where MSW is closed before the request is made.

---

## How to debug a failing test

### Use `screen.debug()`

```tsx
import { screen } from "@testing-library/react-native";

screen.debug();

// Debug a specific element
screen.debug(screen.getByText("test"));

// Increase the output limit (default is truncated)
screen.debug(undefined, 3000000);
```

**Resources:**

- [Debugging | Testing Library](https://testing-library.com/docs/dom-testing-library/api-debugging)
- [Testing Playground](https://testing-playground.com/) — Interactive tool for finding the right queries

### Print all available roles

To see all ARIA roles in your rendered component (useful for finding the right `ByRole` query):

```tsx
import { logRoles } from "@testing-library/dom";

const { container } = render(<MyComponent />);
logRoles(container);
```

---

## How to test element absence

Use `queryBy...` instead of `getBy...` when testing for non-existence.

> **Warning:** `getBy...` throws an error when the element doesn't exist. Use `queryBy...` instead, which returns `null` if no element is found.

```tsx
// ✅ Correct - queryBy returns null if not found
expect(screen.queryByRole("link", { name: /btc/i })).not.toBeInTheDocument();

// ❌ Wrong - getBy throws an error if not found
expect(screen.getByRole("link", { name: /btc/i })).not.toBeInTheDocument();
```

---

## How to force an initial state

You can customize the Redux state for your render call using `overrideInitialState`:

```tsx
const { user } = render(<MarketPages />, {
  overrideInitialState: (state: State) => ({
    ...state,
    settings: {
      ...state.settings,
      supportedCounterValues: SUPPORTED_CURRENCIES,
      featureFlags: { llmMarketNewArch: { enabled: true } },
    },
  }),
});
```

> **Note:** **Current Limitation:** Due to redux-actions, you need to spread the existing state when overriding specific parts. This prevents accidentally replacing the initial state of reducers.

---

## How to mock modules and functions

When a component calls a fetch or custom method that you don't need in your test, mock the module:

```tsx
jest.mock("./myModule", () => ({
  myFunction: jest.fn(() => "mocked value"),
}));
```

**Resources:**

- [ES6 Class Mocks - Jest](https://jestjs.io/docs/es6-class-mocks)

---

## How to run coverage

To generate a coverage report for Ledger Live Mobile:

```bash
pnpm mobile test:jest:coverage
```

The HTML report is available at:

```
apps/ledger-live-mobile/coverage/lcov-report/index.html
```

---

## See also

- [How to Use the Custom Renderer](./use-custom-renderer) — Render components with all providers pre-configured
- [Testing reference](../reference/testing) — Tools, coverage targets, renderer API, query priority
- [Testing Strategy](../explanation/testing-strategy) — Why we favor integration tests for UI and our testing principles

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/reference/architecture -->

# Architecture

Technical description of the Ledger Wallet monorepo folder structure, import rules, and platform-specific file conventions.

---

## Root Folder Structure

The monorepo is organized into the following areas:

| Folder      | Purpose                                                              |
| ----------- | -------------------------------------------------------------------- |
| `apps/`     | Platform-specific cross-cutting concerns                             |
| `features/` | Feature modules with high cohesion and low coupling                  |
| `libs/`     | Legacy shared libraries — being progressively migrated into features |

```
├─ apps/
│  ├─ ledger-live-desktop/
│  │  ├─ state-manager/
│  │  │  └─ configureStore.ts
│  │  └─ router/
│  │     └─ router.ts
│  └─ ledger-live-mobile/
│     ├─ state-manager/
│     │  └─ configureStore.ts
│     └─ router/
│        └─ router.ts
├─ features/
│  └─ {featureName}/
└─ libs/  // Legacy - being migrated into features
```

---

## Apps Folder

The `apps/` folder contains platform-specific cross-cutting concerns:

- **Observability** — Logging, monitoring, error tracking
- **Routing** — Platform-specific navigation (imports routes from features)
- **Analytics** — Platform-specific analytics utilities
- **State Manager** — Store configuration

> **Warning:** Apps should **not** contain business logic. They wire together features and provide platform infrastructure.

---

## Features Folder

Features are self-contained modules with **high cohesion** and **low coupling**.

### Feature Structure

```
features/
└─ posts/
   ├─ components/
   │  ├─ post.web.ts
   │  ├─ post.native.ts
   │  └─ post.test.ts
   ├─ screens/
   │  └─ components/
   │     ├─ posts.web.ts
   │     ├─ posts.native.ts
   │     └─ posts.test.ts
   ├─ data-layer/
   │  └─ entities/
   │     └─ post/
   │        ├─ postSchema.ts
   │        ├─ postSchema.test.ts
   │        ├─ postSelectors.ts
   │        ├─ postSelectors.test.ts
   │        ├─ postActions.ts
   │        ├─ postActions.test.ts
   │        ├─ postSlice.ts
   │        └─ postSlice.test.ts
   ├─ routes/
   │  └─ route.ts
   ├─ hooks/
   └─ utils/
```

### Feature Subfolders

| Subfolder     | Purpose                                                              |
| ------------- | -------------------------------------------------------------------- |
| `components/` | Reusable UI components within the feature                            |
| `screens/`    | Screen-level components (can have their own `components/` subfolder) |
| `data-layer/` | State management: entities, slices, selectors, actions, API          |
| `routes/`     | Platform-agnostic routing abstraction                                |
| `hooks/`      | Feature-specific custom hooks                                        |
| `utils/`      | Feature-specific utilities                                           |

---

## Platform-Specific Files

Use file extensions to target specific platforms:

| Extension     | Platform                     |
| ------------- | ---------------------------- |
| `.web.ts`     | Web and Desktop (Electron)   |
| `.native.ts`  | React Native (iOS + Android) |
| `.ios.ts`     | iOS only                     |
| `.android.ts` | Android only                 |
| No extension  | Shared across all platforms  |

### Example

```
components/
├─ userInfo.ts           // Shared logic
├─ userInfo.web.ts       // Web/Desktop UI
├─ userInfo.native.ts    // Mobile UI
└─ userInfo.test.ts      // Tests
```

> **Warning:** Test files (`*.test.ts`) should always be colocated with their source files.

---

## Import Rules

Strict import boundaries enforce the architectural layers.

### Forbidden Imports

> **Caution:** These import directions are **not allowed**:* `features/**` → `apps/**`

### Allowed Imports

> **Note:** These import directions are **allowed**:* `apps/**` → `features/**` (apps wire features together)
> * `features/{feature}/**` → `features/{feature}/**` (within the same feature)

### Import Flow Diagram

```
┌─────────────────────────────────────────────────────────┐
│                         apps/                           │
│              (can import from features)                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
               ┌─────────────────┐
               │    features/    │
               └─────────────────┘
```

---

## See also

- [How to Structure a Feature](../how-to/structure-a-feature) — Step-by-step guide for creating features
- [Component Patterns](./component-patterns) — Do's and Don'ts for naming and folder organization
- [Architecture Decisions](../explanation/architecture-decisions) — Why we adopted this folder structure

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/reference/component-patterns -->

# Do's and Don'ts

Component patterns and coding conventions with clear examples. Use the rule numbers to reference guidelines in code reviews (e.g. "please follow Rule 1").

## Quick Reference

| # | Rule                                                 | Summary                                   |
| - | ---------------------------------------------------- | ----------------------------------------- |
| 1 | [Screens/Components](#rule-1-screenscomponents)      | No nested `screens/` folders              |
| 2 | [List/Detail Pattern](#rule-2-listdetail-pattern)    | Use `List` and `Detail` suffixes          |
| 3 | [Index.tsx Convention](#rule-3-indextsx-convention)  | One folder per component with `index.tsx` |
| 4 | [Component Names](#rule-4-component-names)           | Avoid redundant context in names          |
| 5 | [Utils Files](#rule-5-utils-files)                   | Use `utils/` folder at shared level       |
| 6 | [Components Nesting](#rule-6-components-nesting)     | Keep nested components with parent        |
| 7 | [Constants](#rule-7-constants)                       | Colocate or use `utils/constants/`        |
| 8 | [Import Preferences](#rule-8-import-preferences)     | Favor relative imports and TS aliases     |
| 9 | [useViewModel Pattern](#rule-9-useviewmodel-pattern) | Inject ViewModel as props                 |

---

## Rule 1: Screens/Components

Folders inside `screens/` cannot have their own `screens/` subfolders. If a component is uniquely associated with a screen, place it in a `components/` subfolder inside that screen folder.

> **Note:** **Do:**```
> Market/
> ├─ components/
> │  └─ MarketRowItem/
> └─ screens/
>    ├─ MarketList/
>    │  └─ components/
>    │     └─ BottomSection/
>    └─ MarketDetail/
> ```

> **Caution:** **Don't:**```
> Market/
> └─ screens/
>    ├─ MarketList/
>    │  └─ screens/      // ❌ No nested screens
>    └─ MarketDetail/
> ```

---

## Rule 2: List/Detail Pattern

- Suffix list components with `List` (always singular)
- Suffix detail components with `Detail`

> **Note:** **Do:**```
> Market/
> └─ screens/
>    ├─ MarketList/
>    └─ MarketDetail/
> ```

> **Caution:** **Don't:**```
> Market/
> └─ screens/
>    ├─ ListOfMarketItem/    // ❌ Wrong naming
>    └─ MarketItemPage/      // ❌ Wrong naming
> ```

---

## Rule 3: Index.tsx Convention

Create a dedicated folder per component and name the main file `index.tsx`.

> **Note:** **Do:**```
> components/
> └─ MarketRowItem/
>    ├─ index.tsx
>    └─ useMarketRowItemViewModel.tsx
> ```

> **Caution:** **Don't:**```
> components/
> ├─ MarketRowItem.tsx              // ❌ No folder
> └─ useMarketRowItemViewModel.tsx  // ❌ Outside component folder
> ```

---

## Rule 4: Component Names

Avoid redundant context in component names. The folder structure provides context.

> **Note:** **Do:**```
> features/Deposit/screens/SelectNetwork/useSelectNetworkViewModel.tsx
> ```

> **Caution:** **Don't:**```
> features/Deposit/screens/DepositFlowSelectNetwork/useDepositFlowSelectNetworkViewModel.tsx
> // ❌ "DepositFlow" is redundant - we're already in Deposit feature
> ```

---

## Rule 5: Utils Files

Do not colocate utils as a single file. Use a `utils/` folder and place it at the top level of components that import it.

> **Note:** **Do:**```
> Market/
> ├─ screens/
> │  └─ MarketDetail/
> ├─ components/
> │  ├─ Header/
> │  └─ Footer/
> └─ utils/
>    └─ index.tsx  // Shared by MarketDetail, Header, Footer
> ```

> **Caution:** **Don't:**```
> Market/
> └─ components/
>    └─ Header/
>       ├─ index.tsx
>       └─ utils.tsx  // ❌ Utils as sibling file
> ```

---

## Rule 6: Components Nesting

If a component is not reused elsewhere, create it next to its parent. Do not flatten nested components.

> **Note:** **Do:**```
> MarketDetail/
> ├─ components/
> │  └─ Stats/
> │     ├─ Price/
> │     │  └─ index.tsx
> │     ├─ Supply/
> │     │  └─ index.tsx
> │     └─ index.tsx
> └─ index.tsx
> ```

> **Caution:** **Don't:**```
> MarketDetail/
> ├─ Stats/
> │  └─ index.tsx
> ├─ Price/           // ❌ Flattened - unclear hierarchy
> │  └─ index.tsx
> ├─ Supply/          // ❌ Flattened - unclear hierarchy
> │  └─ index.tsx
> └─ index.tsx
> ```

---

## Rule 7: Constants

Colocate constants with their component. If shared between components, declare them in `utils/constants/`.

> **Note:** **Do:**```
> utils/
> └─ constants/
>    └─ coins.ts  // Shared by MarketDetail, MarketList, SendFlow
> ```

> **Caution:** **Don't:**```
> MarketDetail/
> ├─ coins.ts         // ❌ Local constant
> └─ index.tsx
>
> MarketList/
> └─ index.tsx        // Imports from ../MarketDetail/coins ❌
> ```

---

## Rule 8: Import Preferences

- **Favor relative imports** when not moving more than one folder up
- **Favor TS aliases** over absolute imports
- Add TS aliases when it improves readability

> **Note:** **Do:**```typescript
> import MarketDetail from "LLM/features/Market/screens/MarketDetail";
> import MarketDetail from "../MarketDetail";
> import MarketDetail from "./MarketDetail";
> ```

> **Caution:** **Don't:**```typescript
> import MarketDetail from "src/features/Market/screens/MarketDetail"; // ❌ Absolute path
> import MarketDetail from "../../../MarketDetail"; // ❌ Too many levels
> import MarketDetail from "./MarketDetail/index.tsx"; // ❌ Explicit index
> ```

---

## Rule 9: useViewModel Pattern

Inject the ViewModel hook result as props to the View component. Do not call the ViewModel hook inside the component body.

> **Note:** **Do:**```tsx
> // index.tsx - Inject ViewModel as props
> const MarketDetail = () => <View {...useMarketDetailViewModel()} />;
>
> // View.tsx - Receives pre-computed props
> const View = ({ price, volume, onRefresh }: Props) => (
>   <Screen>
>     <Text>{price}</Text>
>     <Text>{volume}</Text>
>     <Button onPress={onRefresh}>Refresh</Button>
>   </Screen>
> );
> ```

> **Caution:** **Don't:**```tsx
> // ❌ Don't call ViewModel inside the View component
> const MarketDetail = () => {
>   const { price, volume, onRefresh } = useMarketDetailViewModel();
>
>   return (
>     <Screen>
>       <Text>{price}</Text>
>       <Text>{volume}</Text>
>       <Button onPress={onRefresh}>Refresh</Button>
>     </Screen>
>   );
> };
> ```

> **Warning:** **Why?** Separating the ViewModel call from the View makes testing easier. You can test the View with different props without mocking hooks, and test the ViewModel logic independently.

---

## See also

- [MVVM Pattern](./mvvm-pattern) — Full ViewModel implementation pattern
- [Architecture](./architecture) — Folder structure and import rules
- [How to Structure a Feature](../how-to/structure-a-feature) — Applying these rules when creating features

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/reference/git-conventions -->

# Git Conventions

Branch naming rules, commit message format, and Gitmoji conventions for the Ledger Wallet repository.

---

## Branch Naming

- Use **short, clear and descriptive names** that provide immediate context. For example: `feature/login` or `fix/navbar-overflow`.
- Use **hyphens** to separate words: `fix/login-issue` is preferred over `fix/LoginIssue` or `fix/login_issue`.
- Use only **lowercase alphanumeric characters** (a-z, 0-9) and hyphens.
- Use **prefixes** for organization:

| Prefix                | Purpose                                          |
| --------------------- | ------------------------------------------------ |
| `feature/` or `feat/` | Creating new features                            |
| `fix/`                | Addressing code bugs                             |
| `doc/`                | Updating, modifying, or correcting documentation |

- Add **ticket numbers** if your project uses an issue tracking system. If there is no ticket number, use `no-issue`.

**Example:** `feature/PROJ-123-footer-links`

---

## Commit Messages

### Format

The commit message is composed of:

1. The `doc`, `feature`, or `fix` prefix between parentheses
2. The related ticket number or `NO-ISSUE` between brackets
3. A short description

### Gitmoji

We recommend using [Gitmoji](https://gitmoji.dev/) to write commit messages.

| Emoji          | Usage                                |
| -------------- | ------------------------------------ |
| :tada:         | Begin a project                      |
| :construction: | Work in progress                     |
| :memo:         | Add or update documentation          |
| :pencil2:      | Fix a typo                           |
| :sparkles:     | Implement a new feature              |
| :bug:          | Fix a bug                            |
| :recycle:      | Refactor code                        |
| :wastebasket:  | Deprecated code needed to be removed |
| :mag:          | Improve SEO                          |

### Example

With Gitmoji and the naming convention, the commit looks like:

```
📝(doc) [NO-ISSUE]: DMK video presentation
```

---

## See also

- [How to Structure a Feature](../how-to/structure-a-feature) — Includes guidance on when to use `feature/` vs `fix/` branches

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/reference/mvvm-pattern -->

# MVVM Pattern

Technical description of the MVVM (Model-View-ViewModel) pattern used in Ledger Wallet to separate UI components from business logic.

---

## Pattern Structure

```
ComponentName/
├─ index.tsx                    # Exports the connected component
└─ useComponentNameViewModel.ts # Contains business logic
```

When a component connects to outer layers (network calls, store data), create a dedicated hook named `use{ComponentName}ViewModel`. The `ViewModel` suffix identifies hooks dedicated to a specific component that are not intended for reuse elsewhere.

---

## Implementation

### Correct Way

> **Note:** Inject the ViewModel hook result as props:

```tsx
// index.tsx
import { useMarketListViewModel } from "./useMarketListViewModel";

function View(props) {
  // Pure UI component - only renders based on props
  return (
    <div>
      <h1>{props.title}</h1>
      <ul>
        {props.items.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
      <button onClick={props.onRefresh}>Refresh</button>
    </div>
  );
}

// Connect View to ViewModel
const MarketList = () => <View {...useMarketListViewModel()} />;

export default MarketList;
```

```tsx
// useMarketListViewModel.ts
import { useSelector, useDispatch } from "react-redux";
import { useCallback } from "react";
import { selectMarketItems, fetchMarketData } from "../data-layer";

export function useMarketListViewModel() {
  const dispatch = useDispatch();
  const items = useSelector(selectMarketItems);
  const isLoading = useSelector(selectIsLoading);

  const onRefresh = useCallback(() => {
    dispatch(fetchMarketData());
  }, [dispatch]);

  return {
    title: "Market",
    items,
    isLoading,
    onRefresh,
  };
}
```

### Wrong Way

> **Caution:** Don't mix ViewModel logic directly in the component:

```tsx
// ❌ Wrong - mixing concerns
function MarketList() {
  const props = useMarketListViewModel();

  // Business logic mixed with UI
  if (props.isLoading) {
    return <Spinner />;
  }

  return <div>{props.data}</div>;
}

export default MarketList;
```

> **Warning:** **Why?** Separating the ViewModel call from the View makes testing easier. You can test the View with different props without mocking hooks, and test the ViewModel logic independently.

---

## When to Use

- Components that connect to Redux store
- Components that make API calls
- Components with complex business logic
- Screens and major feature components

## When NOT to Use

- Simple presentational components
- Components that only receive props from parents
- Pure utility components (buttons, inputs, etc.)

---

## See also

- [Component Patterns](./component-patterns) — Rule 9 covers the `useViewModel` injection pattern
- [How to Structure a Feature](../how-to/structure-a-feature) — How to set up a feature module with MVVM
- [Architecture Decisions](../explanation/architecture-decisions) — Why we use MVVM and its benefits

---

<!-- https://developers.ledger.com/docs/ledger-live/contributing/reference/testing -->

# Testing

Technical reference for testing tools, coverage targets, custom renderer API, and query priority in the Ledger Wallet monorepo.

---

## Testing Requirements

| Scenario                                   | Requirement                                                                      |
| ------------------------------------------ | -------------------------------------------------------------------------------- |
| **New features** in `features/` or `mvvm/` | Must include unit and integration tests                                          |
| **Bug fixes** in new architecture          | Must include a regression test covering the use case                             |
| **New components** in legacy code          | Use new arch patterns to ease future migration                                   |
| **Major feature reworks** in legacy code   | Consider full migration to new architecture with tests (coordinate with Product) |

---

## Testing Tools

| Tool                             | Purpose                                              | Documentation                                                                                  |
| -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Jest**                         | JavaScript test runner with DOM access via jsdom     | [Getting Started](https://jestjs.io/docs/getting-started)                                      |
| **React Testing Library**        | Test React components without implementation details | [Documentation](https://testing-library.com/docs/react-testing-library/intro/)                 |
| **React Native Testing Library** | Test React Native components (for LLM)               | [Documentation](https://callstack.github.io/react-native-testing-library/docs/getting-started) |
| **Mock Service Worker (MSW)**    | API mocking for network requests                     | [Documentation](https://mswjs.io/)                                                             |

---

## Query Priority

When writing tests, follow the query priority recommended by Testing Library:

- **React**: [About Queries](https://testing-library.com/docs/queries/about#priority)
- **React Native**: [How Should I Query](https://callstack.github.io/react-native-testing-library/docs/how-should-i-query)

> **Note:** Use `ByRole` queries when possible. If your component lacks aria attributes,
> consider adding them when it makes sense. Otherwise, use other queries
> following the priority guide.

---

## Coverage Targets

| Type                        | Target | Notes                                                                        |
| --------------------------- | ------ | ---------------------------------------------------------------------------- |
| **Features / User Stories** | >= 80% | Complex features with multiple conditions                                    |
| **Generic Components**      | >= 90% | Reusable components used in different contexts                               |
| **Helper Functions**        | 100%   | Pure functions like date formatting, number parsing                          |
| **Redux Actions/Reducers**  | 100%   | Well-documented at [Redux Testing](https://redux.js.org/usage/writing-tests) |

> **Note:** Do not focus solely on coverage scores. Use coverage as a tool to identify
> untested code paths.

---

## Custom Renderer API

### Mobile (ledger-live-mobile)

Import from `@tests/test-renderer`:

```typescript
import { render, screen, renderHook } from "@tests/test-renderer";
```

#### Available Render Functions

| Function                              | Use Case                             |
| ------------------------------------- | ------------------------------------ |
| `render`                              | Render components with all providers |
| `renderHook`                          | Test custom hooks in isolation       |
| `renderWithReactQuery`                | Components needing React Query       |
| `customRenderHookWithLiveAppProvider` | Hooks needing Live App context       |

#### Providers Included

- `Provider` (Redux)
- `FirebaseFeatureFlagsProvider` (Feature Flags)
- `NavigationContainer` (React Navigation routing)
- `CountervaluesProvider` / `CountervaluesMarketcapBridgedProvider`
- `StyleProvider` (theming)
- `I18nextProvider` (translations)
- `BottomSheetModalProvider`
- `QueuedDrawersContextProvider`
- `AnalyticsContextProvider`
- `QueryClientProvider` (when using `renderWithReactQuery`)

### Desktop (ledger-live-desktop)

Import from `tests/testSetup`:

```typescript
import { render, screen, renderHook, userEvent } from "tests/testSetup";
```

#### Available Render Functions

| Function                                | Use Case                             |
| --------------------------------------- | ------------------------------------ |
| `render`                                | Render components with all providers |
| `renderHook`                            | Test custom hooks in isolation       |
| `renderWithMockedCounterValuesProvider` | Components needing countervalues     |
| `renderHookWithLiveAppProvider`         | Hooks needing Live App context       |

#### Providers Included

- `QueryClientProvider` (React Query)
- `Provider` (Redux)
- `FirebaseFeatureFlagsProvider` (Feature Flags)
- `MemoryRouter` (React Router routing — supports `initialRoute` option)
- `CountervaluesProvider` / `CountervaluesMarketcapProvider`
- `I18nextProvider` (translations)
- `DrawerProvider`
- `DialogProvider`
- `StyleProvider` (theming)
- `ContextMenuWrapper`

---

## Modules That Don't Need Mocking

When using the custom renderer, the following modules are already provided:

| Module                                        | Why No Mock Needed                                        |
| --------------------------------------------- | --------------------------------------------------------- |
| `react-i18next` / `useTranslation`            | `I18nextProvider` is included with real i18n instance     |
| `react-redux` / `useSelector` / `useDispatch` | Real Redux `Provider` with configurable store             |
| `useTheme` / Theme hooks                      | `StyleProvider` is included                               |
| `useFeature` / Feature flags                  | `FirebaseFeatureFlagsProvider` is included                |
| Navigation hooks                              | `NavigationContainer` (Mobile) / `MemoryRouter` (Desktop) |
| `useAnalytics`                                | `AnalyticsContextProvider` is included (Mobile)           |

---

## Notes

- Always prefer the custom render utilities over raw `@testing-library` render
- Use `overrideInitialState` (Mobile) or `initialState` (Desktop) to customize Redux state
- Use `initialRoute` option (Desktop only) to set the starting route for navigation tests
- The `user` object returned provides realistic user interaction simulation
- The `store` object can be used to verify state changes after actions
- Feature flags can be customized via the `getFeature` function in the test setup files

---

## Internal Resources

> **Note:** The following internal resources are available to Ledger team members:* Testing Tools Setup
> * Testing Tips and Tricks
> * Warnings and Errors Policy

---

## See also

- [How to Write Tests](../how-to/write-tests) — Step-by-step guide for writing tests
- [How to Use the Custom Renderer](../how-to/use-custom-renderer) — Practical usage of render functions
- [Testing Strategy](../explanation/testing-strategy) — Why we test the way we do

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/beginner/live-app -->

---
title: Load a dApp in Discover Section of Ledger Wallet
catgory: tutorial
---

# Load a dApp in Discover Section of Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

## Write and load the manifest

To test and integrate the application, you first need to write your application Manifest file.
This file must contain some mandatory information, such as the app package names, the components, the permissions needed, the hardware and software features, etc.

```json copy
{
  "id": "lido",
  "name": "Lido",
  "url": "https://stake.lido.fi/?embed=true",
  "dapp": {
    "nanoApp": "Lido",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "bsc",
        "chainID": 56,
        "nodeURL": "https://bsc-dataseed.binance.org/"
      },
      {
        "currency": "polygon",
        "chainID": 137,
        "nodeURL": "https://polygon-mainnet.g.alchemy.com/v2/xxx"
      },
      {
        "currency": "arbitrum",
        "chainID": 42161,
        "nodeURL": "https://arb1.arbitrum.io/rpc"
      },
      {
        "currency": "optimism",
        "chainID": 10,
        "nodeURL": "https://mainnet.optimism.io"
      }
    ]
  },
  "homepageUrl": "https://lido.fi/",
  "icon": "https://cdn.live.ledger.com/icons/platform/lido.png",
  "platform": "all",
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["staking", "defi"],
  "currencies": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"],
  "content": {
    "shortDescription": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    },
    "description": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    }
  },
  "permissions": [],
  "domains": ["https://"]
}
```

## Load your Live App locally on desktop

To load your Live App locally, [unlock the Developer mode](../references/developer-mode) in  and [add a local app](../references/developer-mode#add-a-local-app).

This option will allow you to browse for local files and add a local app using a local manifest.
With it you can be autonomous in testing your application.
You’ll have to load your own manifest to make your application appear in the Discover section.

## Load your Live App locally on mobile (Android only)

Go to the **Settings** -> **Developer** section, and click on **Load Platform Manifest** you can copy your manifest here and load it.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/explanation/live-apps -->

# What are the Discover section and Live Apps

Ledger Wallet aims to be more than a keyholder— it’s a comprehensive platform crafted by Ledger.

It allows users to manage, transact, and nurture their digital assets securely. Both from Desktop and Mobile, it serves as a door to the broad crypto ecosystem. And this is where your apps and the Discover section comes into place.

![Discover section](/discover/discover-section.png)

Nested within the interface of , our Discover section offers a curated selection of apps, called Live Apps, to our audience. It provides the assurance to our user that those apps have been tested and can interact with their Ledger device. The curated apps are chosen by our business team.

All other Live Apps are accessible through a **search Bar** with automatic connection to your wallet, Clear Signing with signer security. This service is free for users and for partners

In short, Live Apps provide convenience and security for  users when interacting with web3 projects.

They are integrated in  using the dApp Browser or the  API (if more granualirty is required).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/getting-started -->

---
title: Adding a Live App to the Discover section
category: explanation
---

# Adding a Live App to the Discover section

A **Live App** is a third-party application that runs inside  and reaches the user's  through the Wallet API. The Discover section is where users find and launch them.

This page explains the two technical paths Ledger supports for building a Live App, when to choose each, and how the business and development tracks fit together.

## Business track: getting an invitation

Discover listings are invitation-only. To open the conversation, fill in the [partner intake form](https://docs.google.com/forms/d/e/1FAIpQLSd2e4BAfuZJOUYKhqcxMvMGNY12ShZ-UG5Lu0Se8AIVdlu2lA/viewform) and email **[discover@ledger.fr](mailto:discover@ledger.fr)**. Until Ledger confirms a slot, you can still develop and test against your own manifest in [Developer mode](./references/developer-mode).

## Two integration paths

Live Apps integrate with Ledger Wallet through one of two mechanisms. They are not interchangeable: each is suited to a different kind of application.

### dApp Browser (EVM-only)

The [dApp Browser](./integration/dapp-browser/dapp-customisation) hosts your existing web dApp inside a Ledger Wallet WebView and injects an EIP-1193 provider that signs through the Ledger device. You keep your current frontend and add a [manifest](./integration/dapp-browser/manifest) that tells Ledger Wallet how to load it.

### Wallet API (any chain)

The [Wallet API](./integration/wallet-api/introduction) gives a Live App typed access to accounts, currencies, messages, transactions, and storage on any supported chain: Bitcoin, Ethereum, Solana, Cosmos and many more (the full list of [families](./integration/wallet-api/appendix/families) covers 30+ chains). Live Apps embed the [`@ledgerhq/wallet-api-client`](https://github.com/LedgerHQ/wallet-api) and call methods such as `client.account.list()` directly, instead of going through a generic EVM provider.

### Choosing between them

| Question                                                                                     | Choose **dApp Browser** | Choose **Wallet API** |
| -------------------------------------------------------------------------------------------- | :---------------------: | :-------------------: |
| Is your dApp EVM-only?                                                                       |           yes           |           no          |
| Do you already have a working web dApp using EIP-1193?                                       |           yes           |        optional       |
| Do you need fine-grained API surface (specific signing flows, custom transactions, storage)? |            no           |          yes          |
| Are you targeting non-EVM chains (Bitcoin, Solana, Cosmos…) ?                                |            no           |          yes          |
| Required language/skills                                                                     |          JS/TS          |     React + JS/TS     |

If the answer is "yes" in both columns (EVM dApp wanting Wallet API granularity), pick the Wallet API.

## Development track

Whichever path you pick, the development sequence is the same:

1. **Make sure your app can talk to a Ledger device.** This is generally already the case for an existing dApp, but if it is not, use the [Device Management Kit](../../device-interaction/getting-started).
2. **Build the integration.** Either [customize your dApp for the Browser](./integration/dapp-browser/dapp-customisation) and [write a manifest](./integration/dapp-browser/manifest), or pull in the [Wallet API client](./integration/wallet-api/core/usage) (or the [React bindings](./integration/wallet-api/react/usage)) and call the modules you need.
3. **Add Clear Signing.** For EVM contracts, prefer [ERC-7730 metadata](../../clear-signing/overview); fall back to a [plugin](./integration/dapp-browser/plugin) only if your contract data does not fit. For non-EVM chains, talk to the Ledger team during your invitation conversation.
4. **Test locally with Developer mode.** Enable [Developer mode](./references/developer-mode) in Ledger Wallet and [load your manifest as a local app](./references/developer-mode#add-a-local-app). For Wallet API apps, the [Wallet API simulator](./integration/wallet-api/simulator/usage) lets you run the app in a browser without Ledger Wallet at all.

## Required skills

| Step                                     | Skills                                                                                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Wallet API integration                   | React + JavaScript/TypeScript                                                                                                               |
| dApp Browser integration                 | JavaScript/TypeScript                                                                                                                       |
| ERC-7730 Clear Signing                   | JSON authoring (no on-device code)                                                                                                          |
| Plugin (only when ERC-7730 isn't enough) | C, [Ledger OS](../../device-app/explanation/ledger-os/introduction), and the [Ethereum Plugin SDK](https://ethereum-plugin-sdk.ledger.com/) |

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/dapp-customisation -->

---
title: How to update your dApp for Ledger Wallet
catgory: how-to
---

# How to update your dApp for Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

This guide shows you how to adapt your dApp to detect  environment and optimize the user experience.

One of the most useful features of this dApp Browser is to be able to log-in automatically from a  Ethereum account, therefore obviating the step to manually "Connect a Wallet".

## Step 1: Detect Ledger Wallet connection

Check if your dApp is running in  by detecting the `isLedgerLive` boolean:

```javascript
// Check the injected provider
if (window.ethereum?.isLedgerLive) {
  // User is in <Glossary word='Ledger Wallet'></Glossary> - enable auto-connection
} else {
  // Show standard wallet connection options
}

// Or via EIP-6963
const providers = window.evmproviders;
const ledgerProvider = providers?.find(p => p.info.isLedgerLive);
```

## Step 2: Handle gas fees

Submit transactions with optional gas fees:

- **With gas fees set**:  uses your specified gas fees
- **Without gas fees set**:  shows low/medium/high gas fee options based on current estimates

## Step 3: Optimize user experience

### Handle disconnection properly

Test your logout/disconnect functionality:

- Users may be automatically logged back in via Ledger Wallet
- Or redirected to standard wallet provider selection

### Ensure network compatibility

Support these networks ( compatible):

- **Mainnets**: Ethereum, BSC, Arbitrum, Optimism, Base, Fantom, Polygon
- **Testnet**: Sepolia (requires [Developer mode](../../references/developer-mode) enabled)

### Remove third-party references

- Remove references to external services not in Ledger's ecosystem
- You can redirect to  Buy or Swap services

### Make it responsive

Ensure your dApp works on:

- Desktop screens
- Mobile screens

## What's next

After updating your dApp, you will need to:

- **[Write a manifest](./manifest.mdx)** - Create a manifest file containing your dApp's metadata, supported networks, permissions, and configuration settings to integrate it into Ledger Wallet's Discover section.
- **[Write a plugin](./plugin.mdx)** - Develop a plugin for Clear Signing if your dApp has complex smart contract interactions that need human-readable transaction details (requires Ledger approval and security audit).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/dapp-example -->

---
title: "DApp browser example: Wagmi wallet connection"
category: how-to
---

# DApp browser example: Wagmi wallet connection

This example shows how to build a React + Wagmi application and load it as a LiveApp in Ledger Wallet using the dApp browser. Use it as a starting point for any EVM-compatible dApp integration.

This application is a React-based web interface that allows users to connect their Ethereum wallets. It supports multiple wallet providers, including MetaMask, WalletConnect, Safe, and injected wallets. The app is built using React with TypeScript and leverages the Wagmi library for Ethereum wallet connections.

## Project Structure

The application follows this structure:

```
connect-wallet-example/
├── src/
│   ├── components/
│   │   ├── Account.tsx
│   │   ├── Connect.tsx
│   │   └── ConnectWallet.tsx
│   ├── App.tsx
│   ├── index.tsx
│   ├── wagmi.tsx
│   └── index.css
├── package.json
└── tsconfig.json
```

## Dependencies

The application relies on these dependencies:

- **React & React DOM**: UI framework
- **Wagmi**: Ethereum wallet connection hooks
- **Viem**: Low-level Ethereum interface
- **TanStack React Query**: Data fetching and caching
- **TypeScript**: Type safety
- **Vite**: Build tool and development server

## Package Management

The project uses **pnpm** as its package manager.

## Configuration

### Wagmi Configuration

The application configures Wagmi in the `wagmi.ts` file:

```typescript
import { http, createConfig } from "wagmi";
import { base, mainnet, optimism } from "wagmi/chains";
import { injected, metaMask, safe, walletConnect } from "wagmi/connectors";

const projectId = "3fbb6bba6f1de962d911bb5b5c9dba88";

export const config = createConfig({
  chains: [mainnet, optimism, base],
  connectors: [injected(), walletConnect({ projectId }), metaMask(), safe()],
  transports: {
    [mainnet.id]: http(),
    [optimism.id]: http(),
    [base.id]: http(),
  },
});
```

This configuration:

- Supports Ethereum Mainnet, Optimism, and Base chains
- Enables wallet connections via injected providers, WalletConnect, MetaMask, and Safe
- Configures HTTP transport for each chain

**Note:** The `projectId` is used for WalletConnect integration.

## Components

### App Component

The main App component sets up the Wagmi provider and React Query:

```typescript
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";

import { ConnectWallet } from "./components/ConnectWallet";
import { config } from "./wagmi";

const queryClient = new QueryClient();

export default function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectWallet />
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

### ConnectWallet Component

This component conditionally renders either the Connect or Account component based on the connection status:

```typescript
import { useAccount } from "wagmi";

import { Account } from "./Account";
import { Connect } from "./Connect";

export function ConnectWallet() {
  const { isConnected } = useAccount();
  return (
    <div className="container">{isConnected ? <Account /> : <Connect />}</div>
  );
}
```

### Connect Component

Displays buttons for all available wallet connectors:

```typescript
import * as React from "react";
import { Connector, useChainId, useConnect } from "wagmi";

export function Connect() {
  const chainId = useChainId();
  const { connectors, connect } = useConnect();

  return (
    <div className="buttons">
      {connectors.map((connector) => (
        <ConnectorButton
          key={connector.uid}
          connector={connector}
          onClick={() => connect({ connector, chainId })}
        />
      ))}
    </div>
  );
}

function ConnectorButton({
  connector,
  onClick,
}: {
  connector: Connector;
  onClick: () => void;
}) {
  const [ready, setReady] = React.useState(false);
  React.useEffect(() => {
    (async () => {
      const provider = await connector.getProvider();
      setReady(!!provider);
    })();
  }, [connector, setReady]);

  return (
    <button
      className="button"
      disabled={!ready}
      onClick={onClick}
      type="button"
    >
      {connector.name}
    </button>
  );
}
```

### Account Component

Displays connected account information and a disconnect button:

```typescript
import { useAccount, useDisconnect, useEnsAvatar, useEnsName } from "wagmi";

export function Account() {
  const { address, connector } = useAccount();
  const { disconnect } = useDisconnect();
  const { data: ensName } = useEnsName({ address });
  const { data: ensAvatar } = useEnsAvatar({ name: ensName! });

  const formattedAddress = formatAddress(address);

  return (
    <div className="row">
      <div className="inline">
        {ensAvatar ? (
          <img alt="ENS Avatar" className="avatar" src={ensAvatar} />
        ) : (
          <div className="avatar" />
        )}
        <div className="stack">
          {address && (
            <div className="text">
              {ensName ? `${ensName} (${formattedAddress})` : formattedAddress}
            </div>
          )}
          <div className="subtext">
            Connected to {connector?.name} Connector
          </div>
        </div>
      </div>
      <button className="button" onClick={() => disconnect()} type="button">
        Disconnect
      </button>
    </div>
  );
}

function formatAddress(address?: string) {
  if (!address) return null;
  return `${address.slice(0, 6)}…${address.slice(38, 42)}`;
}
```

## User Flow

1. **Initial State**: User is presented with wallet connection options
2. **Wallet Selection**: User clicks on their preferred wallet provider
3. **Wallet Connection**: The wallet provider's interface opens, allowing the user to connect
4. **Connected State**: Once connected, the UI switches to show account information
5. **Disconnection**: User can disconnect by clicking the "Disconnect" button

## Getting Started

### Prerequisites

- Node.js
- pnpm

### Installation

1. Set up the files as shown in the project structure

2. Install dependencies:

   ```bash
   pnpm install
   ```

3. Run the development server:

   ```bash
   pnpm dev
   ```

4. Open your browser to the URL shown in the terminal (typically [http://localhost:5173](http://localhost:5173))

## Load the app in Ledger Wallet

4. Create a manifest file

### Manifest file example

```json
{
  "$schema": "https://live-app-catalog.ledger.com/schema.json",
  "id": "WagmiExample",
  "name": "Wagmi Example",
  "private": false,
  "url": "http://localhost:5173/",
  "dapp": {
    "provider": "evm",
    "nanoApp": "Ethereum",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "ethereum_holesky",
        "chainID": 17000,
        "nodeURL": "https://ethereum-holesky-rpc.publicnode.com"
      }
    ]
  },
  "homepageUrl": "http://localhost:5173/",
  "platforms": ["ios", "android", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["staking", "defi"],
  "currencies": ["ethereum", "ethereum_holesky"],
    "content": {
    "shortDescription": {
      "en": "Connect your Ethereum wallet using Wagmi and WalletConnect."
    },
    "description": {
      "en": "Connect your Ethereum wallet using Wagmi and WalletConnect."
    }
  },
  "permissions": [],
  "domains": ["http://", "https://"],
  "visibility": "complete"
}
```

5. Go to , Settings, Developer, Add a Local app and add your manifest

## Related

- [Live app manifest reference](../../references/manifest) — full list of manifest fields and their defaults
- [DApp browser integration overview](../dapp-browser) — how the dApp browser loads and sandboxes LiveApps

**Next steps:** If your dApp needs to sign transactions (not just display addresses), see the [Wallet API](../wallet-api/getting-started) for signing, broadcasting, and account access.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/manifest -->

---
title: Write and load the manifest
catgory: how-to
---

# Write and load the manifest

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

If you have followed instructions on the previous page, you should now be ready to interact with the dApp directly from  interface to make sure all the basic features work as expected.

Your dApp will be run inside the  webview with an injected provider.

To test and integrate your application, you first need to write your application Manifest file.
This file must contain some mandatory information, such as the app package names, the components, the permissions needed, the hardware and software features, etc.

Check and if necessary edit your manifest file as described [below](#example-of-manifest-json-format-for-the-lido-application).

### Load your Live App locally on desktop

To load your Live App locally, [unlock the Developer mode](../../references/developer-mode/) in  and [add a local app](../../references/developer-mode#add-a-local-app).

### Load your Live App locally on mobile (Android only)

Go to the **Settings** -> **Developer** section, and click on **Load Platform Manifest** you can copy your manifest here and load it.

### Example of Manifest (JSON format) for the “Lido” application:

```json copy
{
  "id": "lido",
  "name": "Lido",
  "url": "https://stake.lido.fi/?embed=true",
  "dapp": {
    "nanoApp": "Lido",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "bsc",
        "chainID": 56,
        "nodeURL": "https://bsc-dataseed.binance.org/"
      },
      {
        "currency": "polygon",
        "chainID": 137,
        "nodeURL": "https://polygon-mainnet.g.alchemy.com/v2/xxx"
      },
      {
        "currency": "arbitrum",
        "chainID": 42161,
        "nodeURL": "https://arb1.arbitrum.io/rpc"
      },
      {
        "currency": "optimism",
        "chainID": 10,
        "nodeURL": "https://mainnet.optimism.io"
      }
    ]
  },
  "homepageUrl": "https://lido.fi/",
  "icon": "https://cdn.live.ledger.com/icons/platform/lido.png",
  "platform": "all",
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["staking", "defi"],
  "currencies": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"],
  "content": {
    "shortDescription": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    },
    "description": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    }
  },
  "permissions": [],
  "domains": ["https://"]
}
```

##### Here is the list of the mandatory fields required in your Manifest file:

| Field             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    | Type         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `id`              | The identification of your application. Must be in lowercase.                                                                                                                                                                                                                                                                                                                                                                                  | String       |
| `name`            | The name of your application ("Lido" in this example).                                                                                                                                                                                                                                                                                                                                                                                         | String       |
| `url`             | The url of your dApp, either running locally or at the production version                                                                                                                                                                                                                                                                                                                                                                      | String       |
| `dapp`            | `nanoApp` is [the plugin](../../../../device-app/explanation/plugin/) needed to clear sign your dApp, if your dApp doesn't require a plugin set the value to Ethereum `networks` is the list of networks supported by your dApp,  currently only support mainnet, BSC, arbitrum, optimism, base, fantom and Polygon, the nodeURL param will be set by Ledger in prod to use your node, for testing purposes, you can replace it with your own. | Object       |
| `homepageUrl`     | This for information only. It is is non-critial. For instance, "[https://lido.fi/](https://lido.fi/)".                                                                                                                                                                                                                                                                                                                                         | String       |
| `icon`            | A link to the icon displayed in the Discover Section of . Will be hosted on Ledger CDN before being released in production.                                                                                                                                                                                                                                                                                                                    | URL          |
| `platform`        | To set the platform (desktop, mobile, iOS, Android) on which your service is available. By default, you should set the value to "all".                                                                                                                                                                                                                                                                                                         | String       |
| `apiVersion`      | The API version. By default "^2.0.0".                                                                                                                                                                                                                                                                                                                                                                                                          | String       |
| `manifestVersion` | The manifest version. By default should be "2".                                                                                                                                                                                                                                                                                                                                                                                                | String       |
| `branch`          | The specific branch used by Ledger to deploy the changes. Can take the values stable `experimental`, `debug`, `soon`. By default, you should set it to `stable`. The value `soon` will mark your app as "Coming soon" and it won't be usable.                                                                                                                                                                                                  | String       |
| `categories`      | A JSON array of metadata information about your application. For instance: \["staking","defi" ]. You can add as many as you want. It is not used for the moment but will be used for filtering in the future.                                                                                                                                                                                                                                  | List(string) |
| `currencies`      | A JSON array of the currency/network being used by your application. For instance \["ethereum",”polygon”]. Leave blank if the App does not require any currency.                                                                                                                                                                                                                                                                               | List(string) |
| `content`         | A description of your service. It will be displayed on the entry card of your application.                                                                                                                                                                                                                                                                                                                                                     | L18n strings |
| `permissions`     | Leave empty for now.                                                                                                                                                                                                                                                                                                                                                                                                                           | List(string) |
| `domains`         | List of allowed domains to navigate to, if a domain doesn't match it will open in the default browser. By default \["http\://", "https\://"]                                                                                                                                                                                                                                                                                                   | List(string) |

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/migration -->

---
title: DApp Browser v3 migration
catgory: how-to
---

# DApp Browser v3 migration

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

We are in the process of deprecating the dApp Browser live-app v1 and v2.

Ledger Wallet will now support injecting a compatible provider in the webview.

## Deprecations

- [GitHub - LedgerHQ/iframe-provider](https://github.com/LedgerHQ/iframe-provider)
- [GitHub - LedgerHQ/eth-dapp-browser](https://github.com/LedgerHQ/eth-dapp-browser)
- `params` field in the manifest used by  (replaced by the `dapp` field)

## Changes

Ledger Wallet will now inject the needed provider in the WebView directly avoiding the need for an iframe like the `eth-dapp-browser`

The new provider is EIP 6963 compliant if there is a need for it but you can also use the injected `window.ethereum`

The provider exposes a boolean `provider.isLedgerLive` to inform when you are in the  environment, in that case we expect the dApp to auto connect using this provider, thus improving the user experience and avoid unnecessary clicks

Manifest for dApps can now use the `url` field directly instead of `params.dappUrl` and must use the `dapp` field instead of the `params` for the `provider`, `networks` and `nanoApp` fields

## Ledger Wallet supported versions

- Desktop: 2.79
- Mobile: Next release

## Manifest examples

```json
{
  "id": "metamask-test-dapp",
  "name": "Metamask Test dApp",
  "private": false,
  "url": "https://metamask.github.io/test-dapp/",
  "dapp": {
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "bsc",
        "chainID": 56,
        "nodeURL": "https://bsc-dataseed.binance.org/"
      },
      {
        "currency": "polygon",
        "chainID": 137,
        "nodeURL": "https://polygon-mainnet.g.alchemy.com/v2/[your-key]"
      },
      {
        "currency": "arbitrum",
        "chainID": 42161,
        "nodeURL": "https://arb1.arbitrum.io/rpc"
      },
      {
        "currency": "optimism",
        "chainID": 10,
        "nodeURL": "https://mainnet.optimism.io"
      }
    ]
  },
  "homepageUrl": "https://metamask.github.io/test-dapp/",
  "icon": "https://cdn.live.ledger.com/icons/platform/1inch.png",
  "platforms": ["android", "ios", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "1",
  "branch": "stable",
  "categories": ["tools"],
  "currencies": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"],
  "content": {
    "shortDescription": {
      "en": "Metamask Test dApp"
    },
    "description": {
      "en": "Metamask Test dApp"
    }
  },
  "permissions": [],
  "domains": ["https://"],
  "visibility": "complete"
}
```

```json
{
  "id": "1inch-local",
  "name": "1inch",
  "private": false,
  "url": "https://app.1inch.io/",
  "dapp": {
    "nanoApp": "1inch",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "bsc",
        "chainID": 56,
        "nodeURL": "https://bsc-dataseed.binance.org/"
      },
      {
        "currency": "polygon",
        "chainID": 137,
        "nodeURL": "https://polygon-mainnet.g.alchemy.com/v2/[your-key]"
      },
      {
        "currency": "arbitrum",
        "chainID": 42161,
        "nodeURL": "https://arb1.arbitrum.io/rpc"
      },
      {
        "currency": "optimism",
        "chainID": 10,
        "nodeURL": "https://mainnet.optimism.io"
      }
    ]
  },
  "homepageUrl": "https://1inch.io/",
  "icon": "https://cdn.live.ledger.com/icons/platform/1inch.png",
  "platforms": ["android", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "1",
  "branch": "stable",
  "categories": ["swap"],
  "currencies": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"],
  "content": {
    "shortDescription": {
      "en": "Exchange crypto via a Defi/DEX aggregator on Ethereum mainnet, BSC or Polygon"
    },
    "description": {
      "en": "Exchange crypto via a Defi/DEX aggregator on Ethereum mainnet, BSC or Polygon"
    }
  },
  "permissions": [],
  "domains": ["https://"],
  "visibility": "complete"
}
```

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/dapp-browser/plugin -->

---
title: Write a plugin for Clear Signing
category: how-to
---

# Write a plugin for Clear Signing

This page shows how to add a Ledger plugin to a dApp running in the Ledger Wallet dApp browser, so transactions on your contracts display human-readable details on the device instead of raw hex.

A Ledger plugin is a small C application installed alongside the [Ethereum device app](../../../../device-app/explanation/plugin/). When the user signs a transaction whose `to` address matches one of your plugin's registered contracts, the Ethereum app delegates the on-screen rendering to your plugin via a defined handler interface (`handle_init_contract`, `handle_provide_parameter`, `handle_finalize`, and others). Source: [`LedgerHQ/app-plugin-boilerplate`](https://github.com/LedgerHQ/app-plugin-boilerplate) and [`LedgerHQ/ethereum-plugin-sdk`](https://github.com/LedgerHQ/ethereum-plugin-sdk).

> **Note:** Before starting, check whether [ERC-7730](../../../clear-signing/overview) covers your contracts. ERC-7730 is metadata-only, requires no on-device code, and is the supported path for most use cases. Plugins are reserved for contracts whose data does not fit the ERC-7730 schema.

> **Warning:** Plugin development requires Ledger's prior approval. If your dApp does not already have a plugin slot agreed with Ledger, [request one](../../../../device-app/integration/how-to/plugin) before following this guide.

## Prerequisites

- Ledger has approved a plugin slot for your dApp.
- You have built a working plugin from [`app-plugin-boilerplate`](https://github.com/LedgerHQ/app-plugin-boilerplate) using the [Ethereum Plugin SDK](https://ethereum-plugin-sdk.ledger.com/), and your plugin passes the boilerplate's functional tests.
- Your Live App already loads in Ledger Wallet via a manifest. If not, start with [Write and load the manifest](./manifest).

## Steps

### 1. Build and submit your plugin

Follow the device-app guide [How to develop an Ethereum plugin](../../../../device-app/integration/how-to/plugin) for the full development flow:

1. Fork [`app-plugin-boilerplate`](https://github.com/LedgerHQ/app-plugin-boilerplate) and implement the SDK handlers for your contracts.
2. Add functional tests covering every transaction path your plugin parses. They are mandatory for submission.
3. Submit your plugin to Ledger's [submission process](../../../../device-app/submission-process/process). The plugin name you ship with is the value you will reference from the manifest in the next step.

### 2. Reference the plugin in your dApp manifest

Once Ledger has accepted your plugin, set its **exact name** as `dapp.nanoApp` in your [manifest](./manifest):

```json
{
  "id": "your-dapp-id",
  "name": "Your dApp",
  "url": "https://yourdapp.example",
  "dapp": {
    "nanoApp": "YourPluginName",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      }
    ]
  },
  "manifestVersion": "2",
  "apiVersion": "^2.0.0",
  "branch": "stable"
}
```

The `nanoApp` value must match the plugin name registered with Ledger character-for-character (capitalization included). Use `"Ethereum"` only if your dApp does not require a plugin.

See the [manifest reference](./manifest) for the full list of fields and an end-to-end example.

### 3. Test the integration end-to-end

1. Enable [Developer mode](../../references/developer-mode/) in Ledger Wallet.
2. Install the latest Ethereum app and your plugin on the device.
3. [Add your local app](../../references/developer-mode#add-a-local-app) using the manifest from step 2.
4. Sign a transaction on each contract path your plugin handles and confirm the device shows the expected fields.

If a transaction still displays raw hex, see [Common pitfalls](#common-pitfalls).

## Common pitfalls

- **Plugin not invoked.** The Ethereum app only delegates to a plugin when the recipient address is in the plugin's registered contract list. Double-check the `to` of the transaction matches one of the contracts declared in your plugin.
- **`nanoApp` name mismatch.** A typo or wrong case in `dapp.nanoApp` falls back silently to blind signing. Copy the name from the plugin repository's `Makefile`.
- **Wrong network.** A plugin only loads when the chain matches one of the entries in `dapp.networks`. Add the chain you are testing on (Ledger Wallet currently supports mainnet, BSC, Arbitrum, Optimism, Base, Fantom, and Polygon).
- **Old Ethereum app.** Plugins are pinned to a minimum Ethereum app version. Update the Ethereum app on the device if the plugin fails to load.
- **CI guidelines failing.** The `Guidelines_enforcer` workflow on the boilerplate runs Ledger's app guidelines; fix every reported rule before submitting (see [device-app development requirements](../../../../device-app/integration/requirements/development)).

## See also

- [How to develop an Ethereum plugin](../../../../device-app/integration/how-to/plugin): full plugin development flow and submission process.
- [Ethereum Plugin SDK](https://ethereum-plugin-sdk.ledger.com/): handler reference and architecture.
- [`app-plugin-boilerplate`](https://github.com/LedgerHQ/app-plugin-boilerplate): forkable starting point.
- [Clear signing with ERC-7730](../../../clear-signing/overview): the metadata-only alternative for simpler contracts.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/appendix/families -->

---
title: Cryptocurrency families
category: reference
---

# Cryptocurrency families

The Wallet API groups cryptocurrencies into families. All currencies in a family share the same transaction structure and API fields.

For the full Transaction type definitions for each family, see the [Wallet API Transaction types reference](../references/transaction-types).

## Supported cryptocurrency families

Please note that actual available cryptocurrency implementations depend on both the wallet and the app's permissions.

### `algorand`

The `algorand` family is used to interact with the Algorand cryptocurrency and its "assets".

### `bitcoin`

The `bitcoin` family is used to interact with Bitcoin and similar UTXO-based cryptocurrencies (for example, Dogecoin and Bitcoin Cash). UTXO-based; the transaction object includes `utxoStrategy` and `opReturnData` fields.

### `cardano`

The `cardano` family is used to interact with the Cardano cryptocurrency.

### `celo`

The `celo` family is used to interact with the Celo cryptocurrency.

### `cosmos`

The `cosmos` family is used to interact with Cosmos and other Tendermint cryptocurrencies.

### `crypto_org`

The `crypto_org` family is used to interact with the CRO cryptocurrency.

### `elrond`

The `elrond` family is used to interact with the MultiversX blockchain.

> **Note:** The API identifier remains `elrond` for backwards compatibility; this corresponds to the MultiversX blockchain (rebranded from Elrond in November 2022).

### `ethereum`

The `ethereum` family is used to interact with Ethereum and all EVM-based networks (for example, Polygon and BSC). EVM-based; supports EIP-1559 gas fields (`maxFeePerGas`, `maxPriorityFeePerGas`) and arbitrary `data` calldata.

### `filecoin`

The `filecoin` family is used to interact with the Filecoin cryptocurrency.

### `hedera`

The `hedera` family is used to interact with the Hedera cryptocurrency.

### `near`

The `near` family is used to interact with the NEAR cryptocurrency.

### `neo`

The `neo` family is used to interact with the Neo cryptocurrency.

### `polkadot`

The `polkadot` family is used to interact with the Polkadot cryptocurrency.

### `ripple`

The `ripple` family is used to interact with the XRP Ledger. Requires a `tag` (destination tag) field on transactions.

### `solana`

The `solana` family is used to interact with the Solana cryptocurrency.

### `stellar`

The `stellar` family is used to interact with the Stellar cryptocurrency. Supports a `memoType` and `memoValue` for destination tagging.

### `tezos`

The `tezos` family is used to interact with the Tezos cryptocurrency.

### `tron`

The `tron` family is used to interact with the Tron cryptocurrency.

## Related

- [Wallet API Transaction types reference](../references/transaction-types) — per-family transaction field definitions
- [Supported currencies](../references/currencies) — full list of supported currency identifiers

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/appendix/manifest -->

# Manifest

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

_If you want to know more about the Discover tab and the Live Apps in general, you can read this page : [Start here](https://developers.ledger.com/docs/live-app/start-here/)_

### What is a manifest ?

A Manifest is a config file that allows external applications and decentralized applications (dApps) to be integrated inside the  software as a Live app and interact with all provided features.

If you have followed instructions on the [How to create a Live app](../examples/live-app-creation/start) page, you should now be ready to interact with the dApp directly from  interface to make sure all the basic features work as expected.

### Manifest properties

To test and integrate your application, you first need to write your application Manifest file. This file must contain some mandatory information, such as the app package names, the components, the permissions needed, the hardware and software features, etc.

You don't have to fill in all the fields; we'll fill them in once your integration has been confirmed.

However, here are a few elements you'll need to fill in yourself and their descriptions :

_To be filled in by you_

| Properties                  | Descripton                                                                                                                   | Type          | Requirements                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------- |
| id                          | uniq id of your app                                                                                                          | string        | a-z \| 0-9 \|                                                                 |
| _author_                    | Name of your organisation                                                                                                    | string        | optional \| \*                                                                |
| _name_                      | Name of your live app (will be displayed and used to search your app inside the Discover section)                            | string        | \*                                                                            |
| _url_                       | Url of the live app homepage (users will be redirected to this link once they open your app)                                 | string (URL)  | \*                                                                            |
| _homepageUrl_               | Url of your organisation                                                                                                     | string (URL)  | optional \| \*                                                                |
| _supportUrl_                | Your support url                                                                                                             | string (URL)  | optional \| \*                                                                |
| _icon_                      | Icon URL (will be displayed inside the Discover section)                                                                     | string (URL)  | optional \| \*                                                                |
| platforms                   | Platform compatibility                                                                                                       | Array(enum)   | "ios", "android", "desktop"                                                   |
| apiVersion                  | Specific manifest schema version (leave it as [default](#default-values))                                                    | string        | \*                                                                            |
| manifestVersion             | Version supported by the app that the wallet needs to implement in order to support (leave it as [default](#default-values)) | enum          | 2                                                                             |
| categories                  | List of category related to your Live App ([example](#default-values))                                                       | Array(string) | items: min 1 → \*                                                             |
| currencies                  | currencies supported by your Live App                                                                                        | Array(string) | items: min 1 → \*                                                             |
| _content_                   | Descripton of your Live App (will be displayed inside the Discover section)                                                  | Object        | \{shortDescription: string, description: string, subtitle: string (optional)} |
| [permissions](#permissions) | List of permissions you will need in order to interact with wallet-api                                                       | enum          |                                                                               |
| _domains_                   | \_\_\_                                                                                                                       | Array(string) | optional \| \*                                                                |
| [dapp](#dapp)               | \_\_\_                                                                                                                       | Object        | (nanoApp: string, networks: Array (unique Object))                            |
| visibility                  | Visibility of your live app inside . (Leave it as [default](#default-values))                                                | string        | "complete", "searchable", "deep"                                              |

### DApp

_Your app uses the [dApp Browser](../../dapp-browser/dapp-customisation)_

| Params   | Type                  | Requirements                                       |
| -------- | --------------------- | -------------------------------------------------- |
| nanoApp  | string                | \*                                                 |
| networks | Array (unique Object) | (chainID: number, nodeURL: string, currency: enum) |

#### Permissions

Permissions that allow your app to interact with methods :

```javascript
"permissions": [

    // Account and currencies
    "account.list",
    "account.receive",
    "account.request",
    "currency.list",

    // Device permissions
    "device.close",
    "device.exchange",
    "device.transport",

    // Transaction
    "message.sign",
    "transaction.sign",
    "transaction.signAndBroadcast",

    // Wallet Info
    "wallet.capabilities",
    "wallet.info",
    "wallet.userId"

  ],

```

#### Default values

_Complete manifest.json file with default or examples values :_

```json
{
  "id": "ReplaceAppName",
  "name": "ReplaceAppName",
  "url": "http://localhost:3000",
  "params": {
    "exampleParam": "value"
  },
  "homepageUrl": "http://localhost:3000/",
  "platform": ["ios", "android", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["NFT", "Swap", "YourAppCategory"],
  "currencies": "*",
  "content": {
    "shortDescription": {
      "en": "Desc"
    },
    "description": {
      "en": "Desc"
    }
  },
  "permissions": [],
  "domains": ["http://", "https://"],
  "visibility": "complete"
}
```

## Manifest Overrides Guide

### Introduction to Overrides

In the context of app manifests, the **overrides** feature offers a powerful mechanism to create conditional modifications to your manifest. With this feature, you can specify different values for specific conditions, such as  versions (`llVersion`) and device (`platform`). This ensures a tailored experience across multiple versions and platforms without the need for separate manifest files.

### Structure of Overrides

Inside your manifest, you can include an `overrides` section to define conditions and their corresponding modifications. Here's how you can structure them:

1. **ledgerLiveVersion Overrides**: Allows you to define variations of the manifest specific to different  versions.

`Request: /api/v1/apps?llVersion=1.0.0`

```Example:
"overrides": [
  {
    "version": "1.0.0",
    "changes": {
      "name": "overridden manifest"
    }
  }
]
```

In this example, users with  version `1.0.0` will see the app name as "overridden manifest".

2. **Platform Overrides**: Enables you to tailor the manifest for specific platforms like iOS, Android, etc.

Request param:

- `/api/v1/apps?platform=ios`
- `/api/v1/apps?platform=android`

  ```Example:
  "overrides": [
    {
      "platform": "ios",
      "changes": {
        "name": "overridden for iOS"
      }
    },
    {
      "platform": "android",
      "changes": {
        "name": "overridden for Android"
      }
    }
  ]
  ```

  Depending on the user's device platform, they will see a different app name – "overridden for iOS" on Apple devices and "overridden for Android" on Android devices.

## Depth Limitation in Overrides

Only the first depth of fields can be overridden, meaning granular changes to nested properties are not supported directly. To override a field with nested properties, the entire field, including all nested properties, must be redefined.

For example, you cannot override just a nested `url`:

```
"overrides": [
 {
   "platform": "ios",
   "changes": {
     "params": {
       "url": "new-url"
     }
   }
 }
]
```

Instead, you need to redefine the entire `params` field:

```
"overrides": [
  {
    "platform": "ios",
    "changes": {
      "params": {
        "url": "new-url",
        "anotherField": "value",
        "yetAnotherField": "anotherValue"
      }
    }
  }
]
```

## Activating Overrides

Overrides are activated when the manifest is requested with specific parameters. Here are the supported parameters and how they activate the overrides:

1. **ledgerLiveVersion**: Activated by calling with the `llVersion` parameter.

   Will return all defaults manifests with the 1.0.0 overr if it exist:

   `http://localhost:3000/api/v1/apps?llVersion=1.0.0`

2. **Platform**: Activated by calling with the `platform` parameter. The `platforms` field inside the manifest will be replaced accordingly.

   Will return all defaults manifests and override for iOS and replace the `platforms` field in the manifest with `["ios"]` if it exist inside the manifest :

   `http://localhost:3000/api/v1/apps?platform=ios`

3. **Combining Parameters**: You can combine multiple parameters to activate multiple overrides.
   Apply overrides for both  version `1.0.0` and the `iOS` platform :
   `http://localhost:3000/api/v1/apps?llVersion=1.0.0&platform=ios`

## Priority in Overrides

In cases where both `ledgerLiveVersion` and `platform` might have overriding values for the same field, the priority is determined by their order in the manifest. Whichever is listed first takes precedence.

## Override Process for Specific Platform Requests

When a request specifies a platform, such as 'ios' (?platform=ios), the system performs an override process as follows:

`Request: ?platform=ios`

```
Manifest before override:
{
  "platforms": ["desktop", "android"],
  "overrides": [
    {
      "platform": "ios",
      "changes": {
        "visibility": "searchable"
      }
    }
  ]
}
```

It begins with the main manifest as the default.
Searches for any overrides within the manifest relevant to the requested platform (here "platform": "ios"), and applies them to the default fields.
Returns a manifest specific for the requested platform, in this case 'ios'.

```Resulting manifest.json:
{
    "platforms": ["ios"],
    "visibility": "searchable"
}
```

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/appendix/migration-guide -->

# Migrating from the Platform API

This guide aim to help migrating from the **Platform API** _(live-app-sdk)_ to the newer **Wallet-API**.

## Key Differences

Although they mostly serve the same purpose, there are many key differences that separate the Wallet-API from the
Platform API. Here is a list of those key differences:

1. **Introspective design:** Wallet-API was designed to be implemented on uneven wallets. Some wallets will implement
   all existing features, some won't. Live apps are now able to request a wallet's specific capabilities and adapt their
   UX based on those.
2. **Method permissions:** Wallet-API adds plenty of new features. Since they can be used freely by the live app, it
   made sense to restrict which app can use which method. Similarily to mobile apps and browser extensions, live apps now
   need to declare which methods they intend to use in their respective manifests.
3. **Currency permissions:** Most live apps will only focus on a few specific crypto currencies. To avoid exposing
   un-needed user account informations, live apps now have to declare in their manifests which currencies they intend to
   use.
4. **More coin family support:** Wallet-API implement more crypto currency families than the Platform API. Please
   refer to the doc to discover newly integrated crypto families.
5. **Unsollicited events:** Wallet-API enable live apps to subscribe to wallet events. This can be used to be notified
   of any emitted events from the wallet.

## Migrating the manifest

The manifest format hasn't been updated, however, some unused fields are now being used. Here is a list of the
required modifications:

### `apiVersion`

This field need to be set at version `^2.0.0` to ensure the connected wallet will expose the Wallet-API. If a lower
version is used, the Platform API will be exposed instead

```json
{
  ...
    "apiVersion": "^2.0.0",
}
```

### `currencies`

This field now specify which currencies will be used by the live app. From the point of view of the live app, the
wallet won't support crypto currencies that are not included in this list.

```json
{
  ...
    "currencies": [
  "ethereum",
  "bitcoin"
  ...
  ],
}
```

### `permissions`

This field now specify which methods can be used by the live app. Trying to use a method that wasn't declared in this
list will result in a permission error.

```json
{
  ...
    "permissions": [
  "currency.list",
  "account.list",
  "account.request",
  ...
  ],
}
```

## Migrating the live app

Live apps using the Platform API are using the `@ledgerhq/live-app-sdk` package. This package provided a vanilla JS
client instance that could be used to communicate with the connected wallet. We now provide **two packages** to
integrate the Wallet-API into your website:

### `@ledgerhq/wallet-api-client`

The minimal implementation is pretty similar to the `@ledgerhq/live-app-sdk`. This new package expose a vanilla JS
`WalletAPIClient` class. Please refer to [the core section](../core/getting-started) for more. Here are a few differences:

1. **Signing transactions:** The `broadcastSignedTransaction` endpoint was removed. There are now only two ways to
   sign a transaction, with **transaction.sign** or **transaction.signAndBroadcast**. The first one will trigger a
   signature flow and return a **signed transaction**, the second one will trigger a signature flow and broadcast the
   signed transaction in one go, returning the **transaction hash**.
2. **Transports:** Transport is an interface for a simple connector allowing the live app to connect to the wallet.
   `WindowMessageTransport` is still provided, but it now require the user to call `connect()` before it can be used.

### `@ledgerhq/wallet-api-client-react`

React typically makes it difficult to manage anything that is **instance based**. Doing so generally involve more
advanced concepts such as _reference management_ and can introduce a lot of **bugs and complexity**. Although some
developers might want to manage the integration themselves, we now offer a react wrapper library in order facilitate
Wallet-API integration in their website, we are now providing the `@ledgerhq/wallet-api-client-react` library. This
library is exposing both a provider and a set of react hooks, facilitating integration.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/appendix/transaction -->

# Transaction Type Reference

In the  API Core Client, the `Transaction` type is a crucial part of transaction management. This reference guide aims to provide an in-depth understanding of the structure of the `Transaction` type.

## Overview

The `Transaction` type is used to describe an unsigned transaction. It's an umbrella type that can represent transactions of various cryptocurrency families. For example, it could be an Ethereum transaction, a Bitcoin transaction, or others.

## Common Fields for All Transactions

Regardless of the specific cryptocurrency, all transactions share some common fields.

### Fields:

- `family` (string): The cryptocurrency family to which the transaction belongs. This could be 'ethereum', 'bitcoin', etc.
- `amount` (BigNumber): The amount of cryptocurrency to be sent in the transaction, represented in the smallest unit of the currency. For instance, in Bitcoin, an `amount` of 1 represents 0.00000001 BTC.
- `recipient` (string): The address of the recipient of the transaction.

## Cryptocurrency Specific Fields

In addition to the common fields, each cryptocurrency family might have additional fields specific to its network.

### Ethereum Transaction Example

For instance, an Ethereum transaction could have the following fields:

- `nonce` (number, optional): This is the number of transactions sent from the sender's address.
- `data` (Buffer, optional): Input data of the transaction. This is often used for contract interactions.
- `gasPrice` (BigNumber, optional): The price per gas in wei.
- `gasLimit` (BigNumber, optional): The maximum amount of gas provided for the transaction.
- `maxPriorityFeePerGas` (BigNumber, optional): Maximum fee per gas to be paid for a transaction to be included in a block.
- `maxFeePerGas` (BigNumber, optional): Maximum fee per gas willing to be paid for a transaction.

Here is how a typical Ethereum transaction might look:

```javascript
const ethereumTransaction = {
  family: "ethereum",
  amount: new BigNumber(100000000000000),
  recipient: "0xRecipientAddress",
  nonce: 2,
  data: Buffer.from("SomeDataInHex", "hex"),
  gasPrice: new BigNumber(20000000000),
  gasLimit: new BigNumber(21000),
};
```

## Raw Transactions

There are also raw representations of transactions, often used when serializing the transaction data. The common fields in raw transactions are similar to the regular transaction type but serialized into strings or other primitive types.

## TransactionSign and TransactionSignAndBroadcast Types

`TransactionSign` and `TransactionSignAndBroadcast` are types that define the parameters and the expected results for the respective functions, `sign` and `signAndBroadcast` in the  API Core Client's Transaction module.

### TransactionSign Type

#### Parameters:

- `accountId` (string, required): The ID of the account where the transaction will be made.
- `rawTransaction` (RawTransaction, required): The transaction object in a raw, serialized format specific to the cryptocurrency family.
- `options` (object, optional):
- `hwAppId` (string, optional): A signer application ID.
- `meta` (object, optional): Metadata for the transaction in the format `{ [key: string]: unknown }`.

#### Results:

- `signedTransactionHex` (string): The hexadecimal string representation of the signed transaction.

#### Type Definition:

```typescript
type TransactionSign = {
  params: {
    accountId: string;
    rawTransaction: RawTransaction;
    options?: {
      hwAppId?: string;
    };
    meta?: Record<string, unknown>;
  };
  result: {
    signedTransactionHex: string;
  };
};
```

### TransactionSignAndBroadcast Type

#### Parameters:

- `accountId` (string, required): The ID of the account where the transaction will be made.
- `rawTransaction` (RawTransaction, required): The transaction object in a raw, serialized format specific to the cryptocurrency family.
- `options` (object, optional):
- `hwAppId` (string, optional): A signer application ID.
- `meta` (object, optional): Metadata for the transaction in the format `{ [key: string]: unknown }`.

#### Results:

- `transactionHash` (string): The hash of the transaction once it's been broadcasted to the network.

#### Type Definition:

```typescript
type TransactionSignAndBroadcast = {
  params: {
    accountId: string;
    rawTransaction: RawTransaction;
    options?: {
      hwAppId?: string;
    };
    meta?: Record<string, unknown>;
  };
  result: {
    transactionHash: string;
  };
};
```

### Notes

- The `rawTransaction` parameter in both types expects the transaction object to be in a raw, serialized format, which is different from the regular `Transaction` object. You may need to convert your transaction object into this raw format before calling these functions.

- The `hwAppId` option can be used if you are interacting with a signer. It is an optional field, and is not required if you are not using a signer.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/appendix/working-with-ledger-live -->

# Working with Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

This page documents how to link the local packages of the wallet-api monorepo in order to work with  locally (or any other application using the Wallet-API) without having to deploy a new version to the npm registry.

## In the Wallet-API folder

First you want to start the dev server to have every packages built and ready to be used by the application but also to have the watcher in place whenever we make changes in the Wallet-API.

```sh
pnpm dev
```

## In the Ledger Wallet monorepo

> **Note:** Tip: Search for all places to modify with `"@ledgerhq/wallet-api`

### Step 1

Update all `package.json` file containing a wallet-api lib with the following version:\
`"@ledgerhq/wallet-api-<LIB>": "link:PATH_TO_WALLET_API/wallet-api/packages/<LIB>",`

For example with the client lib:\
`"@ledgerhq/wallet-api-client": "link:/Users/dave/Documents/Projects/wallet-api/packages/client"`

### Step 2

When you are done updating all `package.json` files, you can run `pnpm i` to update the dependencies with the local ones.

### Step 3

Then you can start developping as usual with `pmpm dev:lld` and any modification in the wallet-api sources will be reflected automatically.

### Step 4 (Optional)

You might also want to run `pnpm watch:common` to keep it up to date, as we have a lot of code shared in the common folder.

> **Warning:** Don't forget to revert the changes in `package.json` and `pnpm-lock.yaml`
> before committing

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/account -->

# Using the Account Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Account Module allows you to interact with the user's accounts. You can list accounts, request an account, and verify account addresses on a Ledger device through .

## Account Module Overview

Access the Account module via `walletApiClient.account`.

### Methods:

#### 1. List Accounts

Retrieve the list of accounts added by the user on the connected wallet. You can filter the accounts by currency IDs.

```javascript
walletApiClient.account.list(params?: { currencyIds?: string[] }): Promise<Account[]>
```

**Parameters**:

- `params` (optional): An object that may contain:
- `currencyIds` (optional): An array of strings specifying the currency IDs to filter accounts by.

**Returns**: A promise that resolves with an array of Account objects.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`account.list`

##### Example:

```javascript
async function listAccounts(walletApiClient) {
  try {
    const accounts = await walletApiClient.account.list();
    console.log("All Accounts:", accounts);

    const bitcoinAccounts = await walletApiClient.account.list({
      currencyIds: ["bitcoin"],
    });
    console.log("Bitcoin Accounts:", bitcoinAccounts);
  } catch (error) {
    console.error("Error listing accounts:", error);
  }
}
```

#### 2. Request Account

Prompt the user to select an account from the connected wallet. You can filter the accounts by currency IDs.

```javascript
walletApiClient.account.request(params?: { currencyIds?: string[] }): Promise<Account>
```

**Parameters**:

- `params` (optional): An object that may contain:
- `currencyIds` (optional): An array of strings specifying the currency IDs to filter accounts by. You can find currency IDs and token IDs in the [Ledger repository](https://github.com/LedgerHQ/ledger-live/blob/main/libs/ledgerjs/packages/cryptoassets/src/currencies.ts).

**Returns**: A promise that resolves with the selected Account object.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions) `account.request`

##### Example:

```javascript
async function requestAccount(walletApiClient) {
  try {
    const account = await walletApiClient.account.request({
      currencyIds: ["ethereum"],
    });
    console.log("Selected account:", account);
  } catch (error) {
    console.error("Error requesting account:", error);
  }
}
```

#### 3. Verify Account Address

Allows the user to verify an account's address on their Ledger device through .

```javascript
walletApiClient.account.receive(accountId: string): Promise<string>
```

**Parameters**:

- `accountId` (required): The ID of the account whose address needs to be verified.

**Returns**: A promise that resolves with the verified address as a string.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`account.receive`

##### Example:

```javascript
async function verifyAccountAddress(walletApiClient, accountId) {
  try {
    const address = await walletApiClient.account.receive(accountId);
    console.log("Verified address:", address);
  } catch (error) {
    console.error("Error verifying account address:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/bitcoin -->

# Using the Bitcoin Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Bitcoin Module allows you to interact with Bitcoin accounts. Specifically, you can retrieve the extended public key (xPub) of a Bitcoin account. This is useful for deriving Bitcoin addresses without revealing the private key.

## Bitcoin Module Overview

Access the Bitcoin module via `walletApiClient.bitcoin`.

### Methods:

#### 1. Get Extended Public Key (xPub)

Retrieve the extended public key (xPub) of a Bitcoin account. The xPub can be used to derive Bitcoin addresses without exposing the private key.

```javascript
walletApiClient.bitcoin.getXPub(accountId: string): Promise<string>
```

**Parameters**:

- `accountId` (required): The ID of the Bitcoin account for which the xPub is to be retrieved.

**Returns**: A promise that resolves with the xPub as a string.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`bitcoin.getXPub`

##### Example:

```javascript
async function getXPub(walletApiClient, accountId) {
  try {
    const xPub = await walletApiClient.bitcoin.getXPub(accountId);
    console.log("Extended Public Key (xPub):", xPub);
  } catch (error) {
    console.error("Error retrieving xPub:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/currency -->

# Using the Currency Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Currency Module enables interaction with various cryptocurrencies that are supported by the connected wallet. You can list the cryptocurrencies and apply filters by name or ticker.

## Currency Module Overview

Access the Currency module via `walletApiClient.currency`.

### Methods:

#### 1. List Cryptocurrencies

List the cryptocurrencies supported by the connected wallet. You can optionally provide filters by currency IDs.

```javascript
walletApiClient.currency.list(params?: { currencyIds?: string[] }): Promise<Currency[]>
```

**Parameters**:

- `params` (optional): An object which may contain:
- `currencyIds` (optional): An array of strings specifying the currency IDs to filter the cryptocurrencies.

**Returns**: A promise that resolves with an array of Currency objects.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`currency.list`

##### Example:

```javascript
async function listCurrencies(walletApiClient, currencyIds) {
  try {
    // List all supported cryptocurrencies
    const currencies = await walletApiClient.currency.list();
    console.log("Supported cryptocurrencies:", currencies);

    // Optionally, filter by currency IDs
    const filteredCurrencies = await walletApiClient.currency.list({
      currencyIds: currencyIds,
    });
    console.log("Filtered cryptocurrencies:", filteredCurrencies);
  } catch (error) {
    console.error("Error listing cryptocurrencies:", error);
  }
}
```

> **Note**: Filtering by currency IDs is marked as beta and may not be fully implemented yet.

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/custom -->

# Using the Custom Module in Wallet API Client

The Custom Module allows you to interact with any Custom Handler supported by the server.

## Custom Module Overview

> **Note:** We are still working on improving the type safety of custom modules

### Step 1

First, you need a Custom Module, you can import one from another lib or create it.

To create a Custom Module, you need to import and extend the CustomModule class.

You can add any method you want in your class and do any logic you need to.\
Use `this.request<ParamType, ReturnType>("custom.handler", param)` to call the Custom Handler methods supported by the server.

```javascript
import { CustomModule } from "@ledgerhq/wallet-api-client";

type CustomLogHandlersType = {
  "custom.log": (message: string) => Promise<{ res: "hello" }>;
};

class CustomLog extends CustomModule {
  log(message: string) {
    return this.request<
      Parameters<CustomLogHandlersType["custom.log"]>[0],
      ReturnType<CustomLogHandlersType["custom.log"]>
    >("custom.log", message);
  }
}
```

### Step 2

Go back to your transport declaration from your [Wallet API Configuration](../configuration).

You need to adapt the WalletAPIClient by passing a function that returns your custom handler.

> **Note:** You can use the `defaultLogger` export from the `@ledgerhq/wallet-api-client`
> if you weren't using the second parameter of the WalletAPIClient

```javascript
import { WalletAPIClient, defaultLogger } from "@ledgerhq/wallet-api-client";

const walletApiClient = new WalletAPIClient(
  transport,
  defaultLogger,
  (client) => {
    return new CustomLog(client);
  }
);
```

> **Note:** You can also use multiple Custom Module in an object.

```javascript
import { WalletAPIClient, defaultLogger } from "@ledgerhq/wallet-api-client";

const walletApiClient = new WalletAPIClient(
  transport,
  defaultLogger,
  (client) => {
    return {
      log: new CustomLog(client),
      log2: new CustomLog2(client),
      device: new CustomDevice(client),
    };
  }
);
```

### Step 3

Access the Custom Module via `walletApiClient.custom`.

```javascript
// Example using one module
const res = await walletApiClient.custom.log("test");
// Example using multiple modules
const res2 = await walletApiClient.custom.log.log("test");
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user.\
Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/device -->

# Using the Device Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Device Module provides methods for handling the physical device, including opening low-level transport and selecting a device in the connected wallet.

## Device Module Overview

Access the Device module via `walletApiClient.device`.

### Methods:

#### 1. Open Low-Level Transport

Open low-level transport in the connected wallet.

```javascript
walletApiClient.device.transport(params: DeviceTransport["params"]): Promise<HWTransport>
```

**Parameters**:

- `params`: An object containing the parameters for the transport.

**Returns**: A promise that resolves with an instance of Transport compatible with `@ledgerhq/hw-transport`.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`device.transport`

##### Example:

```javascript
async function openTransport(walletApiClient, params) {
  try {
    const transport = await walletApiClient.device.transport(params);
    console.log("Transport opened:", transport);
  } catch (error) {
    console.error("Error opening transport:", error);
  }
}
```

#### 2. Open Device

Open a device in the connected wallet.

```javascript
walletApiClient.device.open(params: DeviceOpen["params"]): Promise<HWTransport>
```

**Parameters**:

- `params`: An object containing the parameters to open the device.

**Returns**: A promise that resolves with an instance of Transport compatible with `@ledgerhq/hw-transport`.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`device.open`

##### Example:

```javascript
async function openDevice(walletApiClient, params) {
  try {
    const device = await walletApiClient.device.open(params);
    console.log("Device opened:", device);
  } catch (error) {
    console.error("Error opening device:", error);
  }
}
```

#### 3. Select Device

Select a device in the connected wallet.

```javascript
walletApiClient.device.select(params: DeviceSelect["params"]): Promise<DeviceSelect["result"]>
```

**Parameters**:

- `params`: An object containing the parameters to select and check the device.

**Returns**: A promise that resolves with a `deviceId` which can be used with the `device.open` method.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`device.select`

##### Example:

```javascript
async function selectDevice(walletApiClient, params) {
  try {
    const deviceId = await walletApiClient.device.select(params);
    console.log("Device selected, ID:", deviceId);
  } catch (error) {
    console.error("Error selecting device:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/exchange -->

# Using the Exchange Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Exchange Module facilitates various exchange operations such as starting the exchange process, completing swap, sell, and fund transactions using .

## Exchange Module Overview

Access the Exchange module via `walletApiClient.exchange`.

### Methods:

#### 1. Start Exchange

Start the exchange process by generating a nonce on Ledger device. This method is typically called before completing the exchange process.

```javascript
walletApiClient.exchange.start(exchangeType: 'SWAP' | 'SELL' | 'FUND'): Promise<{ transactionId: string }>
```

**Parameters**:

- `exchangeType` (required): A string specifying the type of exchange operation (`"SWAP"`, `"SELL"`, or `"FUND"`).

**Returns**: A promise that resolves with an object containing the `transactionId` which is used to complete the exchange process.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`exchange.start`

##### Example:

```javascript
async function startExchange(walletApiClient, exchangeType) {
  try {
    const { transactionId } = await walletApiClient.exchange.start(
      exchangeType
    );
    console.log("Transaction ID:", transactionId);
  } catch (error) {
    console.error("Error starting exchange:", error);
  }
}
```

#### 2. Complete Exchange

Complete an exchange process (swap, sell, or fund) by passing the exchange content and its signature.

```javascript
walletApiClient.exchange.complete(params: {
  provider: string,
  fromAccountId: string,
  rawTransaction: RawTransaction,
  hexBinaryPayload: string,
  hexSignature: string,
  feeStrategy: 'SLOW' | 'MEDIUM' | 'FAST',
  exchangeType: 'SWAP' | 'SELL' | 'FUND',
  toAccountId?: string,
  swapId?: string,
  rate?: number,
  tokenCurrency?: string,
}): Promise<{ transactionHash: string }>
```

**Parameters**: An object containing:

- `provider` (required): A string used to verify the signature.
- `fromAccountId` (required): Identifier of the account used as a source for the transaction.
- `rawTransaction` (required): A RawTransaction object containing the transaction details.
- `hexBinaryPayload` (required): Hexadecimal string representing the blueprint of the data that will be allowed for signing.
- `hexSignature` (required): Hexadecimal string ensuring the source of the payload.
- `feeStrategy` (required): A string representing the fee strategy (`"SLOW"`, `"MEDIUM"`, or `"FAST"`).
- `exchangeType` (required): A string specifying the type of exchange operation (`"SWAP"`, `"SELL"`, or `"FUND"`).
- `toAccountId` (optional): Identifier of the account used as a destination (required for `"SWAP"`).
- `swapId` (optional): Identifier of the backend swap used (required for `"SWAP"`).
- `rate` (optional): Swap rate used in the transaction (required for `"SWAP"`).
- `tokenCurrency` (optional): Swap tokenCurrency is used when we want point a new token, as id does not exists in wallet-api (optional for `"SWAP"` and `"FUND"`).

**Returns**: A promise that resolves with an object containing the `transactionHash` of the broadcasted transaction.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`exchange.complete`

##### Example:

```javascript
async function completeExchange(walletApiClient, exchangeParams) {
  try {
    const { transactionHash } = await walletApiClient.exchange.complete(
      exchangeParams
    );
    console.log("Transaction Hash:", transactionHash);
  } catch (error) {
    console.error("Error completing exchange:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/message -->

# Using the Message Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Message Module enables users to sign messages using . In the Ethereum context, the messages can be [EIP-191](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-191.md) or [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) messages.

## Message Module Overview

Access the Message module via `walletApiClient.message`.

### Methods:

#### 1. Sign Message

Allow the user to sign the provided message. This method is used to get a signature for a given message, which proves that the owner of the account has agreed to the message content.

```javascript
walletApiClient.message.sign(accountId: string, message: Buffer, meta?: Record<string, unknown>): Promise<Buffer>
```

**Parameters**:

- `accountId` (required): A string representing the  ID of the account that should be used to sign the message.
- `message` (required): A Buffer containing the message that should be signed.
- `meta` (optional): An object with additional data associated with the message.

**Returns**: A promise that resolves with a Buffer containing the signed message in hexadecimal format.

**Errors**: This method can throw an `RpcError` if an error occurs on the server-side.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`message.sign`

##### Example:

```javascript
async function signMessage(walletApiClient, accountId, message, meta) {
  try {
    const signedMessage = await walletApiClient.message.sign(
      accountId,
      message,
      meta
    );
    console.log("Signed Message (hex):", signedMessage.toString("hex"));
  } catch (error) {
    console.error("Error signing message:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/storage -->

# Using the Storage Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Storage Module provides a way to interact with Ledger Wallet's internal storage. You can store and retrieve data using key-value pairs.

## Storage Module Overview

Access the Storage module via `walletApiClient.storage`.

### Methods:

#### 1. Get Data

Retrieve data from Ledger Wallet's internal storage by specifying a key. You can also specify a store ID to retrieve data from a particular store.

```javascript
walletApiClient.storage.get(key: string, storeId?: string): Promise<string | undefined>
```

**Parameters**:

- `key` (required): A string representing the key of the data you want to retrieve.
- `storeId` (optional): A string representing the ID of the store from which you want to retrieve data.

**Returns**: A promise that resolves with the value as a string or `undefined` if the key does not exist.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`storage.get`

##### Example:

```javascript
async function getData(walletApiClient, key, storeId) {
  try {
    const value = await walletApiClient.storage.get(key, storeId);
    console.log("Retrieved Value:", value);
  } catch (error) {
    console.error("Error retrieving data:", error);
  }
}
```

#### 2. Set Data

Store data in Ledger Wallet's internal storage. You can specify a key and value, and optionally provide a store ID to store data in a specific store.

```javascript
walletApiClient.storage.set(key: string, value: string, storeId?: string): Promise<void>
```

**Parameters**:

- `key` (required): A string representing the key under which you want to store the data.
- `value` (required): A string representing the data you want to store.
- `storeId` (optional): A string representing the ID of the store where you want to store the data.

**Returns**: A promise that resolves when the data is successfully stored. There is no return value.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`storage.set`

##### Example:

```javascript
async function setData(walletApiClient, key, value, storeId) {
  try {
    await walletApiClient.storage.set(key, value, storeId);
    console.log("Data successfully stored.");
  } catch (error) {
    console.error("Error storing data:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/transaction -->

# Using the Transaction Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Transaction Module allows you to interact with user transactions. It enables you to let the user sign a transaction and also allows you to sign and broadcast a transaction through .

## Transaction Module Overview

Access the Transaction module via `walletApiClient.transaction`.

### Methods:

#### 1. Sign Transaction

Let the user sign a transaction without broadcasting it. This is useful if you want to sign a transaction for later use.

```javascript
walletApiClient.transaction.sign(
    accountId: string,
    transaction: Transaction,
    options?: TransactionSign["params"]["options"],
    meta?: Record<string, unknown>
): Promise<Buffer>
```

**Parameters**:

- `accountId` (required): The ID of the account where the transaction will be made.
- `transaction` (required): The [transaction object](../../appendix/transaction) in the currency family-specific format.
- `options` (optional): Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsign-type) for more information.
- `meta` (optional): Metadata for the transaction.

**Returns**: A promise that resolves with the raw signed transaction as a Buffer.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`transaction.sign`

##### Example:

```javascript
async function signTransaction(
  walletApiClient,
  accountId,
  transaction,
  options,
  meta
) {
  try {
    const signedTransaction = await walletApiClient.transaction.sign(
      accountId,
      transaction,
      options,
      meta
    );
    console.log("Signed transaction:", signedTransaction);
  } catch (error) {
    console.error("Error signing transaction:", error);
  }
}
```

#### 2. Sign and Broadcast Transaction

Let the user sign a transaction and broadcast it to the network.

```javascript
walletApiClient.transaction.signAndBroadcast(
    accountId: string,
    transaction: Transaction,
    options?: TransactionSignAndBroadcast["params"]["options"],
    meta?: Record<string, unknown>
): Promise<string>
```

**Parameters**:

- `accountId` (required): The ID of the account where the transaction will be made.
- `transaction` (required): The [transaction object](../../appendix/transaction) in the currency family-specific format.
- `options` (optional): Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsignandbroadcast-type) for more information.
- `meta` (optional): Metadata for the transaction.

**Returns**: A promise that resolves with the transaction hash as a string.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`transaction.signAndBroadcast`

##### Example:

```javascript
async function signAndBroadcastTransaction(
  walletApiClient,
  accountId,
  transaction,
  options,
  meta
) {
  try {
    const transactionHash = await walletApiClient.transaction.signAndBroadcast(
      accountId,
      transaction,
      options,
      meta
    );
    console.log("Transaction Hash:", transactionHash);
  } catch (error) {
    console.error("Error signing and broadcasting transaction:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/modules/wallet -->

# Using the Wallet Module in Wallet API Core Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Wallet Module allows you to interact with the user's wallet. This includes retrieving the user's ID, fetching wallet information, and listing the capabilities of the wallet.

## Wallet Module Overview

Access the Wallet module via `walletApiClient.wallet`.

### Methods:

#### 1. Get User ID

Retrieve the user ID of the connected wallet.

```javascript
walletApiClient.wallet.userId(): Promise<string>
```

- **Returns**: A promise that resolves with the user ID as a string.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`wallet.userId`

##### Example:

```javascript
async function getUserId(walletApiClient) {
  try {
    const userId = await walletApiClient.wallet.userId();
    console.log("User ID:", userId);
  } catch (error) {
    console.error("Error retrieving user ID:", error);
  }
}
```

#### 2. Get Wallet Info

Retrieve information about the connected wallet.

```javascript
walletApiClient.wallet.info(): Promise<WalletInfo["result"]>
```

**Returns**: A promise that resolves with an object containing information about the connected wallet.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`wallet.info`

##### Example:

```javascript
async function getWalletInfo(walletApiClient) {
  try {
    const walletInfo = await walletApiClient.wallet.info();
    console.log("Wallet Info:", walletInfo);
  } catch (error) {
    console.error("Error retrieving wallet info:", error);
  }
}
```

#### 3. List Wallet Capabilities

List the method IDs that are implemented by the wallet.

```javascript
walletApiClient.wallet.capabilities(): Promise<string[]>
```

- **Returns**: A promise that resolves with an array of strings representing the method IDs.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`wallet.capabilities`

##### Example:

```javascript
async function listWalletCapabilities(walletApiClient) {
  try {
    const capabilities = await walletApiClient.wallet.capabilities();
    console.log("Wallet Capabilities:", capabilities);
  } catch (error) {
    console.error("Error listing wallet capabilities:", error);
  }
}
```

## Handling Errors

Make sure to handle errors gracefully and provide appropriate feedback to the user. Additionally, always remember to disconnect the `WindowMessageTransport` when you're done interacting with the  API to free up resources.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/core/usage -->

# How to initialize and use the Ledger Wallet API

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

## Goal

Initialize the  API Core client, connect to a transport, and perform basic interactions (e.g., read accounts), then cleanly disconnect.

## Installation

You can use your favorite package manager to install `@ledgerhq/wallet-api-client`:

```sh npm2yarn
npm install @ledgerhq/wallet-api-client
```

## Step 1 - Initialize the transport

Set up the `WindowMessageTransport` (provided by `@ledgerhq/wallet-api-core` and re-exposed by `@ledgerhq/wallet-api-client`) to enable communication between your app and Ledger devices.

## Step 2 - Create and initialize the client

Use the transport to initialize `WalletAPIClient`.

```javascript
import {

  WalletAPIClient,
  WindowMessageTransport,
} from "@ledgerhq/wallet-api-client";

async function initializeWalletApiClient() {
  // 1) Connect the Window Message Transport
  const windowMessageTransport = new WindowMessageTransport();
  windowMessageTransport.connect();

  // 2) Initialize the Wallet API Client
  const walletApiClient = new WalletAPIClient(windowMessageTransport);

  // 3) Use the client (example: list accounts)
  // const accounts = await walletApiClient.account.getAccounts();

  // Your application logic here...

  // 4) Disconnect when done
  windowMessageTransport.disconnect();
}

// Execute the function
initializeWalletApiClient().catch((error) => console.error(error));
```

## Step 3 -  Disconnect when finished

Always close the communication channel by calling `disconnect` on the transport after your operations are complete.

## Outcome

You have a connected  API client and can call methods such as `account.getAccounts()` to interact with Ledger devices.

## Next steps

- Explore available methods in the API reference to retrieve accounts, request signatures, and perform transactions.
- Integrate error handling and UI flows for device connection states.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/live-app-creation/configuration -->

### 4. **Configuring the Wallet API**

To interact with , you'll need to configure the  API. The first step is to install the necessary packages, and then set up the appropriate configuration through a transport layer named "Transport". This transport layer will enable communication with the  API.

- **Installing Packages**:
  Install the necessary packages using npm:

  ```sh npm2yarn
  npm install @ledgerhq/wallet-api-client @ledgerhq/wallet-api-client-react
  ```

- **Creating Transport Provider**:
  Create a file named `TransportProvider.tsx`. This file will contain a component that utilizes the  API client to create a communication transport Higher Order Component (HOC).

  ```jsx
  // src/TransportProvider.tsx
  import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react";
  import {
    Transport,
    WindowMessageTransport,
  } from "@ledgerhq/wallet-api-client";

  function TransportProvider({ children }) {
    function getWalletAPITransport(): Transport {
      if (typeof window === "undefined") {
        return {
          onMessage: undefined,
          send: () => {},
        };
      }

      const transport = new WindowMessageTransport();
      transport.connect();
      return transport;
    }

    const transport = getWalletAPITransport();

    return (
      <WalletAPIProvider transport={transport}>{children}</WalletAPIProvider>
    );
  }

  export default TransportProvider;
  ```

- **Wrapping App with TransportProvider**:
  In your root file, wrap your `<App />` with the `TransportProvider`:

  ```jsx
  // src/index.tsx or src/index.js
  import React from 'react';
  import ReactDOM from 'react-dom';
  import App from './App';
  import TransportProvider from './TransportProvider';

  ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
    <React.StrictMode>
      <TransportProvider>
        <App />
      </TransportProvider>
    </React.StrictMode>
  );
  ```

With this setup, your entire application can access the  API and communicate with it via the `TransportProvider`.

### 5. **Setting Up The Simulator**

During the development and testing phases, the  API simulator can help you develop without requiring to run  in parallel.
You can modify your `TransportProvider.tsx` file to use the `getSimulatorTransport` function provided by the simulator library.

```jsx
// src/TransportProvider.tsx
import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react";
import {
  getSimulatorTransport,
  profiles,
} from "@ledgerhq/wallet-api-simulator";
import type { Transport } from "@ledgerhq/wallet-api-core";

function TransportProvider({ children }) {
  function getWalletAPITransport(): Transport {
    if (typeof window === "undefined") {
      return {
        onMessage: undefined,
        send: () => {},
      };
    }

    // Use Simulator transport
    const transport = getSimulatorTransport(profiles.STANDARD);

    return transport;
  }

  const transport = getWalletAPITransport();

  return (
    <WalletAPIProvider transport={transport}>{children}</WalletAPIProvider>
  );
}

export default TransportProvider;
```

> **Note:** For more informations regarding the simulator, please checkout out [the
> simulator subsection](../../simulator/introduction)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/live-app-creation/hooking-up -->

### 6. **Fetching Account Information**

With your environment set up, you can now start interacting with the  API. Create a new file under the `/hooks` directory named `useAccounts.tsx`. This file will house a custom hook to fetch user account information using the `useAccounts` hook provided by Ledger.

```jsx
// src/hooks/useAccounts.tsx
import { useAccounts } from "@ledgerhq/wallet-api-client-react";

function useUserAccounts() {
  const { accounts, loading, error } = useAccounts();

  return {
    accounts,
    loading,
    error,
  };
}

export default useUserAccounts;
```

Now, you can use this custom hook in your components to fetch and display user account information.

### 7. **Creating Transaction Signing Functionality**

Now that you can fetch account information, the next step is to facilitate transaction signing within your app. Create a new file under the `/hooks` directory named `useSignTransaction.tsx`. This file will contain a custom hook to sign transactions using the `useSignTransaction` hook provided by Ledger.

```jsx
// src/hooks/useSignTransaction.tsx
import {
  useSignTransaction,
  useRequestAccount,
} from "@ledgerhq/wallet-api-client-react";
import { useCallback, useState, useEffect } from "react";
import BigNumber from "bignumber.js";

function useTransactionSigner() {
  const { requestAccount, account } = useRequestAccount();
  const { signTransaction, pending, signature, error } = useSignTransaction();
  const [response, setResponse] = useState(null);

  useEffect(() => {
    requestAccount();
  }, [requestAccount]);

  const handleSignTransaction = useCallback(async () => {
    if (!account) return;

    const ethereumTransaction = {
      family: "ethereum",
      amount: new BigNumber(1000000000000000), // 0.001 ETH in wei
      recipient: "0xRecipientAddressHere",
      gasPrice: new BigNumber(20000000000), // 20 Gwei
      gasLimit: new BigNumber(21000),
      nonce: 0, // Replace with the correct nonce
    };

    try {
      const signature = await signTransaction(account.id, ethereumTransaction);
      setResponse(signature);
    } catch (e) {
      console.error(e);
    }
  }, [account, signTransaction]);

  return {
    handleSignTransaction,
    pending,
    response,
    error,
  };
}

export default useTransactionSigner;
```

### 8. **Building User Interface**

Now it's time to create the UI where users will interact with your app. Create a new file named `App.tsx` under the `/src` directory.

```jsx
// src/App.tsx
import React from "react";
import useUserAccounts from "./hooks/useAccounts";
import useTransactionSigner from "./hooks/useSignTransaction";

function App() {
  const { accounts, loading, error } = useUserAccounts();
  const {
    handleSignTransaction,
    pending,
    response,
    error: signError,
  } = useTransactionSigner();

  return (
    <>
      <h1>User's Crypto Accounts</h1>

      {loading ? (
        <p>Loading...</p>
      ) : error ? (
        <p>Error: {error.message}</p>
      ) : (
        <ul>
          {(accounts ?? []).map(({ id, name, address, currency, balance }) => (
            <li key={id}>
              <p>id: {id}</p>
              <p>name: {name}</p>
              <p>address: {address}</p>
              <p>currency: {currency}</p>
              {/* Make sure to parse BigNumber */}
              <p>balance: {balance.toString()}</p>
            </li>
          ))}
        </ul>
      )}

      <button onClick={handleSignTransaction} disabled={pending}>
        Sign Ethereum Transaction
      </button>

      {pending && <p>Signing...</p>}
      {signError && <p>Error: {signError.toString()}</p>}
      {response && (
        <p>Transaction signed successfully: {response.toString("hex")}</p>
      )}
    </>
  );
}

export default App;
```

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/live-app-creation/manifest -->

### 9. **Creating a Manifest File**

A manifest file is necessary to test your Live App inside . Create a `manifest.json` file at the root of your project. Here is a sample manifest you can use:

```json
{
  "$schema": "https://live-app-catalog.ledger.com/schema.json",
  "id": "SampleLiveApp",
  "name": "SampleLiveApp",
  "url": "http://localhost:3000/",
  "homepageUrl": "http://localhost:3000/",
  "platform": ["ios", "android", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["NFT", "Swap", "YourAppCategory"],
  "currencies": "*",
  "content": {
    "shortDescription": {
      "en": "Desc"
    },
    "description": {
      "en": "Desc"
    }
  },
  "permissions": [
    "account.list",
    "account.receive",
    "account.request",
    "currency.list",
    "message.sign",
    "transaction.sign",
    "transaction.signAndBroadcast",
    "wallet.capabilities",
    "wallet.info",
    "wallet.userId"
  ],
  "domains": ["http://", "https://"],
  "visibility": "complete"
}
```

> **Note:** For more informations regarding the setting up of a manifest, please refer to
> [the manifest page](../../appendix/manifest)

### 10. **Importing Manifest in Ledger Wallet**

Ensure  Desktop is installed on your computer. Enable Developer mode in  by navigating to **Settings** -> **About**, and clicking ten times on the  version. This will reveal a new **Developer** section in the settings menu.

- Enable **platform dev tools**.
- Click on **Browse** next to **Add a local app** and select the manifest you created.

Now you'll see a new row in the menu with the name of your Live App. You can now open and test your Live App within .

---

This concludes the step-by-step guide to developing a Live App for  from scratch.

Have any questions or suggestions for improvement? Leave an issue in our repo or reach out to us through our Discord.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/live-app-creation/start -->

# Building a Live App: A Step-by-Step Tutorial

### 1. Introduction

A Live App is a decentralized application (dApp) that interacts with , a software application used for managing crypto assets on . By creating a Live App, developers can provide users with seamless interactions with blockchain-based applications directly through . This tutorial will guide you through the process of building a Live App from scratch, utilizing the  API Client to facilitate interactions with the  environment.

### 2. Setting up the Development Environment

Before you begin building your Live App, we'll set up your development environment. This setup includes installing necessary tools and libraries that will assist in building, testing, and deploying your Live App.

#### Scaffold a Next.js app

First, scaffold a new Next.js app using the following command:

```sh
npx create-next-app my-app --typescript
```

This will create a new Next.js project called my-app with TypeScript support.

#### Node.js and npm:

Ensure that you have Node.js and npm (Node Package Manager) installed on your computer. If not, download and install the latest LTS version of Node.js from the official website, which includes npm.

#### Text Editor:

Use a text editor of your choice. Popular choices include Visual Studio Code, Sublime Text, or Atom.

#### Simulator:

Install the  API simulator for a mock environment to ease the development and testing phases. You can install the simulator library using npm:

```sh
npm install @ledgerhq/wallet-api-simulator
```

The simulator provides a mock environment with predefined responses for different Wallet API actions, allowing you to test your Live App without interacting with the real  application.

### 3. Creating the Project Structure

Now organize your project with a clear and manageable architecture. Here's a simple project structure to start with:

- /src: This directory contains all your TypeScript/JavaScript files.

- /components: This is where you’ll place your React components.

- /hooks: This will hold custom hooks, including those for
  interacting with the  API.

- /utils: Any utility functions or constant values can be stored here.

- /assets: Place images, icons, and other static files in this directory.

- App.tsx: This is the main file where your React application is bootstrapped.

- /public: This directory contains public assets like the index.html file.

- package.json: This file holds various metadata relevant to your project.

- tsconfig.json: This is your TypeScript configuration file if you're using TypeScript.

Now that your development environment is set up, and you have a basic project structure in place, you are ready to start building your Live App. In the next section, we'll delve into configuring the  API to establish a connection with .

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/test-live-app -->

---
title: Test a Live App with the Wallet API simulator
category: tutorial
---

# Test a Live App with the Wallet API simulator

In this tutorial you'll write a Jest test that uses the Wallet API simulator to verify that your Live App lists the user's accounts correctly. By the end you'll have a self-contained test that runs in CI without a Ledger device or Ledger Wallet running in the background.

## Prerequisites

- A Live App that uses [`@ledgerhq/wallet-api-client`](https://www.npmjs.com/package/@ledgerhq/wallet-api-client).
- Node.js 18+ and a package manager (npm, yarn, or pnpm).
- Jest installed in your project (`npm install --save-dev jest @types/jest ts-jest typescript`). Vitest works too: the assertions and import paths are the same.

## Steps

### Install the simulator

```sh npm2yarn
npm install --save-dev @ledgerhq/wallet-api-simulator
```

The simulator package re-exports a `Transport` you can plug straight into `WalletAPIClient`, plus a set of `profiles` that define which accounts, currencies, and permissions the simulated wallet exposes. The same package is used in the [usage guide](../simulator/usage) to develop locally in a browser.

### Write a first test

Create a `__tests__/account.test.ts` file:

```ts filename="__tests__/account.test.ts"
import { WalletAPIClient } from "@ledgerhq/wallet-api-client";
import {
  getSimulatorTransport,
  profiles,
} from "@ledgerhq/wallet-api-simulator";

describe("account.list", () => {
  it("returns the simulator's standard accounts", async () => {
    const transport = getSimulatorTransport(profiles.STANDARD);
    const client = new WalletAPIClient(transport);

    const accounts = await client.account.list();

    expect(accounts).toBeInstanceOf(Array);
    expect(accounts.map((a) => a.id)).toEqual([
      "account-btc-1",
      "account-eth-1",
    ]);
  });
});
```

The `profiles.STANDARD` profile ships with one Bitcoin and one Ethereum mock account. See [Simulator profiles](../simulator/profiles) for the full list. The test calls the same `client.account.list()` your Live App calls in production.

### Test that permissions are enforced

Live Apps can only call methods their manifest declares. The simulator lets you reproduce a permission rejection by overriding `permissions.methodIds` on a profile:

```ts filename="__tests__/permissions.test.ts"
import { WalletAPIClient } from "@ledgerhq/wallet-api-client";
import {
  getSimulatorTransport,
  profiles,
} from "@ledgerhq/wallet-api-simulator";

const profileWithNoPermissions = {
  ...profiles.STANDARD,
  permissions: {
    ...profiles.STANDARD.permissions,
    methodIds: [],
  },
};

it("rejects account.list when the method is not allowed", async () => {
  const transport = getSimulatorTransport(profileWithNoPermissions);
  const client = new WalletAPIClient(transport);

  await expect(client.account.list()).rejects.toThrow("permission");
});
```

This pattern mirrors the official [`simulator.spec.ts`](https://github.com/LedgerHQ/wallet-api/blob/main/packages/simulator/tests/simulator.spec.ts) suite. Copy from it when you need a working example for `bitcoin.getAddress`, `message.sign`, `transaction.sign`, `storage.get`/`storage.set`, and so on.

### Run the suite

```sh
npx jest
```

Both tests should pass. They make no network calls and need no Ledger device.

## What's next

- [Use Wallet API simulator to develop a Live App](../simulator/usage): run the simulator behind your Live App during local development.
- [Simulator profiles](../simulator/profiles): extend `profiles.STANDARD` with custom accounts and currencies, as shown in the simulator test suite.
- [Wallet API client usage](../core/usage): the API surface your tests will exercise.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/examples/use-live-app -->

# How to run your Live App locally in Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

Goal: Run a local Live App in  for development and testing.

## Prerequisites

- You have a dapp using wallet-api.
- A [Ledger Device](https://shop.ledger.com/pages/hardware-wallets-comparison) to access .
- &#x20;Desktop installed. Download from the [Ledger Wallet download page](https://www.ledger.com/ledger-live/download).

## 1. Create a manifest

A manifest is a .json file providing information about your Live App.

Create `manifest.json` at your project root:

```json
{
  "$schema": "https://live-app-catalog.ledger.com/schema.json",
  "id": "replace-app-name",
  "name": "ReplaceAppName",
  "url": "http://localhost:3000/",
  "homepageUrl": "http://localhost:3000/",
  "platform": ["ios", "android", "desktop"],
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["ReplaceCatagories"],
  "currencies": "*",
  "content": {
    "shortDescription": { "en": "Desc" },
    "description": { "en": "Desc" }
  },
  "permissions": [
    "account.list",
    "account.receive",
    "account.request",
    "currency.list",
    "message.sign",
    "transaction.sign",
    "transaction.signAndBroadcast",
    "wallet.capabilities",
    "wallet.info",
    "wallet.userId"
  ],
  "domains": ["http://", "https://"],
  "visibility": "complete"
}
```

> **Warning:** Ensure `url` points to your app (for local dev: `http://localhost:3000`).

> **Note:** For field details, see the [manifest reference](../../appendix/manifest/).

## 2. Enable Developer mode in Ledger Wallet

To add a local manifest and run a Live App not yet available in the catalog, enable Developer mode:

1. Settings → About
2. Click ten times on the  version

A new Developer section appears.

![developer-mode](./assets/3-1-developer-mode.png)

Turn on **Enable platform dev tools** to open the browser-like developer tools window.

![dev-tools](./assets/3-2-dev-tools.png)

## 3. Import your local manifest

In Developer settings, click **Browse** next to **Add a local app** and select the manifest from step 1.

![browse](./assets/3-3-browse.png)

A new row appears with your Live App name.

![local-app](./assets/3-4-local-app.png)

## 4. Open and test your Live App

- Ensure you have at least one Ethereum account created. See [Add your accounts](https://support.ledger.com/hc/en-us/articles/4404389482641-Add-your-accounts?docs=true).
- Click **Open** next to your local Live App in the developer menu.

![open-local-app](./assets/4-1-open-local-app.png)

Your Live App opens inside .

Tip: Click **Dev tools** to open a browser-like developer tools window.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/introduction -->

# Wallet API Client

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Wallet API Client integrates decentralized applications (dApps), called Live Apps, into . Live Apps use the  API to communicate with .

The library provides React hooks and utilities for crypto asset management apps, decentralized exchanges, and other blockchain projects. It also offers a framework-agnostic way to integrate Live Apps into .

> **Note:** **Migration from Platform SDK:** If you are migrating from Platform SDK,
> see the [migration guide](./appendix/migration-guide).

## Target audience

The Wallet API Client is for developers who build Live Apps to embed in . It enables communication between a Live App and the user's  through [Ledger Wallet](https://www.ledger.com/ledger-live).

The library does not yet support other use cases, such as web apps connected to Ledger signers through the [Ledger Extension](https://www.ledger.com/ledger-extension). We expect to support more use cases in the future.

## Overview

The Wallet API Client connects Live Apps, , and . Its modules, hooks, and utilities support account management, message signing, and transaction handling.

## Navigate the documentation

Use these sections to learn about the features and utilities available in the  API Client:

- **Getting started**: If you are new to the library, use the getting started guide for [Core](./core/getting-started) or [React](./react/getting-started) to install and set it up.

- **Configuration**: Learn how to integrate your application into  with the configuration guide for [Core](./core/configuration.mdx) or [React](./react/configuration).

- **Modules, hooks, and utilities**: Explore dedicated sections about account management, message signing, transaction handling, and other features. Each section explains the relevant parameters and uses.

- **Migration guide**: If you are migrating from Platform SDK, version 1 of this library, to the current Wallet API version, version 2, follow the [Migration Guide](./appendix/migration-guide).

- **Families**: See [Families](./appendix/families) for the supported blockchains and their features and capabilities.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useAccounts -->

# Using the `useAccounts` Hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

In this section, we will be looking at how to use the `useAccounts` hook to retrieve a list of available crypto asset accounts. This method is essential when you need to query information on user's account.

### Introduction to `useAccounts` Hook

The `useAccounts` hook is part of the `@ledgerhq/wallet-api-client-react` package. This hook allows you to fetch an array of crypto accounts of the user.

Each account object in the array contains essential information such as its type (e.g., `id`, `name`, `address`, `currency`, `balance`, `spendableBalance`, `blockHeight`, and `lastSyncDate`).

### Example

Here is an example that shows how to use the `useAccounts` hook inside a React component:

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`account.list`

```jsx
import React from "react";
import { useAccounts } from "@ledgerhq/wallet-api-client-react";

export default function App() {
  const { accounts, loading, error } = useAccounts();

  return (
    <>
      <h1>User's Crypto Accounts</h1>

      {loading ? (
        <p>Loading...</p>
      ) : error ? (
        <p>Error: {(error as Error).message}</p>
      ) : (
        <ul>
          {(accounts ?? []).map(({ id, name, address, currency, balance }) => (
            <li>
              <p>id: {id}</p>
              <p>name: {name}</p>
              <p>address: {address}</p>
              <p>currency: {currency}</p>
              {/* Make sure to parse BigNumber */}
              <p>balance: {balance.toString()}</p>
            </li>
          ))}
        </ul>
      )}
    </>
  );
}
```

In this example:

- We import the `useAccounts` hook from the `@ledgerhq/wallet-api-client-react` package.

- We use the hook to get the `accounts` array as well as loading and error state.

- If it's loading, show `Loading...` message

- Else if there's an error fetching accounts, show error message

- Lastly if accouts array is loaded, show the list of account info

### Understanding the Response

Here is an example of a partial response from the `useAccounts` hook:

```json
[
  {
    "id": "js:2:ethereum:0x0000000000000000000000000000000000000000:",
    "name": "Ethereum Account 1",
    "address": "0x0000000000000000000000000000000000000000",
    "currency": "ethereum",
    "balance": "10000000000000000000",
    "spendableBalance": "10000000000000000000",
    "blockHeight": 17484563,
    "lastSyncDate": "2023-06-15T10:02:36.611Z"
  },
  {
    "id": "js:2:ethereum:0x0000000000000000000000000000000000000000:+ethereum%2Ferc20%2Fusd__coin",
    "name": "USDC Account 1",
    "address": "0x0000000000000000000000000000000000000000",
    "currency": "ethereum/erc20/usd__coin",
    "balance": "100000000",
    "spendableBalance": "100000000",
    "blockHeight": 17484563,
    "lastSyncDate": "2023-06-15T10:02:37.992Z"
  },
  {
    "id": "js:2:polygon:0x0000000000000000000000000000000000000000:",
    "name": "Polygon Account 1",
    "address": "0x0000000000000000000000000000000000000000",
    "currency": "polygon",
    "balance": "10000000000000000000",
    "spendableBalance": "10000000000000000000",
    "blockHeight": 43935011,
    "lastSyncDate": "2023-06-15T10:02:37.682Z"
  }
]
```

Each object in the array represents an account and contains the following properties:

- `id` (string): The unique identifier of this account used internally by  software

- `name` (string): The account’s name set by the user.

- `address` (string): The "next" public address where a user should receive funds. In the context of Bitcoin, the address is "renewed" each time funds are received in order to allow some privacy. In other blockchains, the address might never change

- `currency` (string): The associated cryptocurrency id of the Account

- `balance` (BigNumber): The total amount of assets that this account holds

- `spendableBalance` (BigNumber): The amount of the balance that can be spent. Most of the time it will be equal to the balance, but this can vary in some blockchains

- `blockHeight` (number): Tracks the current blockchain block height

- `lastSyncData` (Date): The date of the last time a synchronization was performed. In other words, tracks how up-to-date the Account data is

### Manifest

```json filename="manifest.json"

{
  ...
  "currencies": ["bitcoin", "ethereum"], // for the example above we only asked "bitcoin", "ethereum"
 ...
  "permissions": [
    "account.list",
  ],
}
```

for more info about the Manifest click [here](/docs/ledger-live/discover/guides/wallet-api/appendix/manifest)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useCapabilities -->

# Using the `useCapabilities` Hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The `useCapabilities` hook is part of the `@ledgerhq/wallet-api-client-react` package (current version: 1.4.x). It lets you fetch the list of Wallet API methods your Live App is allowed to call for the connected user, so you can check what you can do with the user's account before calling a method that might be rejected.

> **Note:** Package versions change frequently. Check the [npm page](https://www.npmjs.com/package/@ledgerhq/wallet-api-client-react) for the latest release before pinning a version in your Live App.

## Sample code

Here is an example that shows how to use the `useCapabilities` hook inside a React component:

**Required permission:** [`wallet.capabilities`](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)

```jsx
import { useState } from "react";
import { useCapabilities } from "@ledgerhq/wallet-api-client-react";

function App() {
  const { capabilities } = useCapabilities();

  return (
    <>
      <h1>Capabilities</h1>
      <button onClick={() => {console.log(capabilities)}}> log Capabilities </button>
    </>
  );
}

export default App;
```

In this example:

- We import the `useCapabilities` hook from the `@ledgerhq/wallet-api-client-react` package.

- We use the hook to get the `capabilities` array.

- When the button is clicked, it log the list of capabilities.

## Understanding the response

Here is an example of a partial response from the `useCapabilities` hook:

```json
[
  'account.list', 
  'account.receive', 
  'account.request', 
  'bitcoin.getXPub', 
  'currency.list', 
  'device.close', 
  'device.exchange', 
  'device.transport', 
  'exchange.complete', 
  'exchange.start', 
  'message.sign', 
  'storage.get', 
  'storage.set', 
  'transaction.sign', 
  'transaction.signAndBroadcast', 
  'wallet.capabilities', 
  'wallet.info', 
  'wallet.userId'
]
```

Each string in the array represents a capability.
They are composed in two part `group.method` :

- `group`: Specifies in which area does the permission belong.

```
wallet, currency, account, exchange, bitcoin, device, transaction, storage, message, account
```

- `method`: Specifies the method that you can call with this specific user.

## Other fields

```jsx
  const capabilitiesHook = useCapabilities();
```

`loading` : Loading state of capabilities field

```jsx
  if (capabilitiesHook.loading){
    ...
  };
```

`error` : State of the request

```jsx
  if (capabilitiesHook.error){
    ...
  };
```

`updateData` : Function that update the updateData

```jsx
  capabilitiesHook.updateData();
```

`updatedAt` : Last update of capabilities

## Related hooks

- [`useAccounts`](./useAccounts): list the user's accounts once you've confirmed `account.list` is available
- [`useWalletInfo`](./useWalletInfo): check the wallet version and tracking settings
- [`useUserId`](./useUserId): fetch the user ID if `wallet.userId` is available

## Related

- [Manifest permissions reference](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions): declare the permissions your Live App requests

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useCurrencies -->

# Using the `useCurrencies` Hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

In this section, we will be looking at how to use the `useCurrencies` hook to retrieve a list of available cryptocurrencies and tokens. This method is essential when you need to get information on the various currencies supported by  API.

### Introduction to `useCurrencies` Hook

The `useCurrencies` hook is part of the `@ledgerhq/wallet-api-client-react` package. This hook allows you to fetch an array of supported cryptocurrencies and tokens.

Each currency object in the array contains essential information such as its type (e.g., `CryptoCurrency` or `TokenCurrency`, `id`, `ticker`, `name`, `family`, `color`, and `decimals`).

For tokens, additional properties like `standard` and `contract` are included.

### Handling Large Datasets

As of the latest data, the `useCurrencies` hook returns an array with up to 7501 elements when unfiltered. Due to the size of this dataset, it is essential to handle this data efficiently.

You might not want to render all elements on the UI simultaneously, as it could affect the performance. Instead, you can implement pagination, virtualisation or selectively display the data based on user input.

In addition, you can filter the currencies accessible by setting the `"currencies"` property inside your manifest. See the families subsection for more information about currencies filtering.

### Sample Code

Here is an example that shows how to use the `useCurrencies` hook inside a React component:

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`currency.list`

```jsx
import React, { useState } from "react";
import { useCurrencies } from "@ledgerhq/wallet-api-client-react";

function App() {
  const { currencies } = useCurrencies();
  const [response, setResponse] = useState(undefined);

  const handleCurrencies = () => {
    setResponse(currencies?.map((currency) => <p>{currency.name}</p>));
  };

  return (
    <>
      <h1>Supported Currencies</h1>
      <button onClick={handleCurrencies}>Show Currencies</button>
      <div>{response}</div>
    </>
  );
}

export default App;
```

In this example:

- We import the `useCurrencies` hook from the `@ledgerhq/wallet-api-client-react` package.

- We use the hook to get the `currencies` array.

- We define a `handleCurrencies` function that updates the state with a list of currency names.

- When the button is clicked, it displays the list of supported currencies.

### Understanding the Response

Here is an example of a partial response from the `useCurrencies` hook:

```json
[
  {
    "type": "CryptoCurrency",
    "id": "bitcoin",
    "ticker": "BTC",
    "name": "Bitcoin",
    "family": "bitcoin",
    "color": "#ffae35",
    "decimals": 8
  },
  {
    "type": "TokenCurrency",
    "standard": "ERC20",
    "id": "ethereum/erc20/gods_unchained",
    "ticker": "GODS",
    "contract": "0xccC8cb5229B0ac8069C51fd58367Fd1e622aFD97",
    "name": "Gods Unchained",
    "parent": "ethereum",
    "color": "#0ebdcd",
    "decimals": 18
  }
]
```

Each object in the array represents a cryptocurrency or token and contains the following properties:

- `type`: Specifies whether the currency is a base cryptocurrency like Bitcoin or Ethereum (`CryptoCurrency`) or a token like an ERC20 token (`TokenCurrency`).

- `id`: A unique identifier for the currency.

- `ticker`: The ticker symbol of the currency.

- `name`: The full name of the currency.

- `family`: The blockchain family the currency belongs to, such as `bitcoin` or `ethereum`.

- `color`: A color code usually associated with the currency for branding.

- `decimals`: The number of decimals the smallest unit of this currency can be divided into.

For tokens (`TokenCurrency`), there are additional properties:

- `standard`: Indicates the token standard (only`ERC20` this is in fact a bug as multiple standards should be represented. We advise not to rely on this property for now).

- `contract`: The smart contract address for the token.

- `parent`: Specifies the parent blockchain of the token.

Keep in mind that the actual response from the `useCurrencies` hook might be extensive, especially if you set the `"currencies" `property of your manifest to `"*"`.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useRequestAccount -->

# Using the `useRequestAccount` hook

The `useRequestAccount` hook is part of the  API Client for React. It is used to request an account from . When the hook is called, the user will be prompted to select the desired account.

### Introduction

The `useRequestAccount` hook facilitates requesting access to a user’s account. On component mount, the user will be prompted to select an account from .

### Usage

1. Import the necessary dependencies and hooks from the  API Client.

2. Use the `useRequestAccount` hook in your component.

3. Call the `requestAccount` function within a `useEffect` to prompt the user to select an account when the component mounts.

### Example

Here is an example of how to use the `useRequestAccount` hook within a simple React application:

[**Required permission**:](../../appendix/manifest#permissions)
`account.request`

```javascript
import React, { useEffect, useState } from "react";
import { useRequestAccount } from "@ledgerhq/wallet-api-client-react";

function App() {
  // Use the useRequestAccount hook
  const { requestAccount, account } = useRequestAccount();
  // State to store the response
  const [response, setResponse] = useState(null);

  // Prompt the user to select an account on component mount
  useEffect(() => {
    requestAccount();
  }, [requestAccount]);

  // If needed you can filter the accounts by currency as follow
  useEffect(() => {
    const request = async () => {
      await requestAccount({ currencyIds: ["currency_id"] });
    };

    request();
  }, [requestAccount]);

  // Trigger a re-render after the user selects an account to handle the account response
  useEffect(() => {
    if (account) {
      setResponse(`${account.address} : ${account.id}`);
    }
  }, [account]);

  return (
    <div>
      <h1>Test Live App - Wallet API</h1>
      <div className="card">
        {response ? (
          <p>Selected Account: {response}</p>
        ) : (
          <p>Selecting account...</p>
        )}
      </div>
    </div>
  );
}

export default App;
```

### Parameters

The `requestAccount` accepts an object with a currencyIds property as parameter.

- `currencyIds`: An array of currencyIds.

### Return Value

The `useRequestAccount` hook returns an object with the following properties:

- `requestAccount`: A function to trigger the account selection prompt.
- `account`: The selected account object. It will be `null` until the user selects an account.

The account object typically contains the following properties:

- `id`: A string representing the account ID.
- `address`: A string representing the account address.

### Handling Responses

After invoking `requestAccount`, you can keep track of the `account` object to determine if the user has selected an account. Once selected, the `account` object will populate with the relevant account information.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useSignAndBroadcastTransaction -->

# Using the `useSignAndBroadcastTransaction` Hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The `useSignAndBroadcastTransaction` hook is part of the  API Client for React. It allows the user to sign a transaction and immediately broadcast it to the network using the connected wallet. This documentation provides a detailed explanation of how to use this hook in your application.

### Introduction

`useSignAndBroadcastTransaction` returns an object with a function to sign and broadcast transactions, along with the state of the process. This is useful when you want to both sign a transaction and send it to the network in a single step.

### Usage

1. Import the required dependencies and hooks from the  API Client.

2. Use the `useSignAndBroadcastTransaction` hook in your component.

3. Call the `signAndBroadcastTransaction` function with the appropriate parameters.

### Example

Below is an example demonstrating how to use the `useSignAndBroadcastTransaction` hook to sign and broadcast an Ethereum transaction.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`transaction.signAndBroadcast`

```jsx
import React, { useEffect, useState, useCallback } from "react";
import {
  useSignAndBroadcastTransaction,
  useRequestAccount,
} from "@ledgerhq/wallet-api-client-react";
import BigNumber from "bignumber.js";

function App() {
  const { requestAccount, account } = useRequestAccount();
  const { signAndBroadcastTransaction, pending, transactionHash, error } =
    useSignAndBroadcastTransaction();

  useEffect(() => {
    requestAccount();
  }, [requestAccount]);

  const handleSignAndBroadcastTransaction = useCallback(async () => {
    if (!account) return;

    const ethereumTransaction = {
      family: "ethereum",
      amount: new BigNumber(1000000000000000), // 0.001 ETH in wei
      recipient: "0xRecipientAddressHere",
      gasPrice: new BigNumber(20000000000), // 20 Gwei
      gasLimit: new BigNumber(21000),
      nonce: 0, // Replace with the correct nonce
    };

    try {
      await signAndBroadcastTransaction(account.id, ethereumTransaction);
    } catch (e) {
      console.error(e);
    }
  }, [account, signAndBroadcastTransaction]);

  return (
    <>
      <h1>Test Live App - Wallet API</h1>
      <div className="card">
        <button onClick={handleSignAndBroadcastTransaction} disabled={pending}>
          Sign and Broadcast Ethereum Transaction
        </button>

        {pending && <p>Broadcasting...</p>}
        {error && <p>Error: {error.toString()}</p>}
        {transactionHash && (
          <p>Transaction broadcasted successfully: {transactionHash}</p>
        )}
      </div>
    </>
  );
}

export default App;
```

### Parameters

The `signAndBroadcastTransaction` function takes three parameters:

- `accountId`: The ID of the account you want to sign the transaction with.
- `transaction`: The transaction object in the currency family-specific format.
- `options` (optional): Extra parameters that may be required by certain blockchain implementations.

In the example above, `accountId` is obtained through the `useRequestAccount` hook, and `transaction` is an object representing an Ethereum transaction.

### Return Value

The `useSignAndBroadcastTransaction` hook returns an object with the following properties:

- `signAndBroadcastTransaction`: Function to call for signing and broadcasting a transaction.
- `pending`: Boolean indicating if the process is ongoing.
- `transactionHash`: The hash of the transaction once it's successfully broadcasted.
- `error`: An error object if the process failed.

### Error Handling

If an error occurs during the signing and broadcasting process, the \`

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useSignMessage -->

# Using the `useSignMessage` hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The `useSignMessage` hook is part of the  API Client for React. It allows the application to request the user to sign a message with their .

### Introduction

The `useSignMessage` hook facilitates the process of signing a message using a user's .

### Usage

1. Import the necessary dependencies and hooks from the  API Client.

2. Use the `useSignMessage` hook in your component.

3. Call the `signMessage` function with the account ID and the message to be signed.

### Example

Here's an example of how to use the `useSignMessage` hook within a simple React application:

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`message.sign`

```javascript
import React, { useEffect, useState } from "react";
import {

  useRequestAccount,
  useSignMessage,
} from "@ledgerhq/wallet-api-client-react";

function App() {
  const { requestAccount, account } = useRequestAccount();
  const { signMessage, signature } = useSignMessage();

  // Prompt the user to select an account on component mount
  useEffect(() => {
    requestAccount();
  }, [requestAccount]);

  const handleSignMessage = async () => {
    if (!account) return;
    await signMessage(account.id, Buffer.from("Hello, Ledger!"));
  };

  return (
    <div>
      <h1>Test Live App - Wallet API</h1>
      <div className="card">
        <button onClick={handleSignMessage}>Sign Message</button>
        {signature && (
          <div>
            <h3>Signed Message:</h3>
            <p>{signature}</p>
          </div>
        )}
      </div>
    </div>
  );
}

export default App;
```

### Parameters

The `signMessage` function takes the following parameters:

- `accountId`: A string representing the account ID, typically obtained through the `useRequestAccount` hook.
- `message`: A string representing the message to be signed.

### Return Value

The `signMessage` function returns a promise that resolves to a string, representing the signed message.

### Handling Responses

Once the `signMessage` function is called, it will trigger the  interface for the user to confirm the signing. After confirmation, the promise will resolve with the signed message. You should handle this asynchronously and update the UI accordingly.

### Errors

If an error occurs during the message signing, such as the user declining to sign the message, the promise will be rejected. It is good practice to catch and handle these errors appropriately.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useSignTransaction -->

# Using the `useSignTransaction` hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The `useSignTransaction` hook is part of the  API Client for React. It allows the user to sign a transaction without broadcasting it using the connected wallet. This documentation provides a detailed explanation of how to use this hook in your application.

### Introduction

`useSignTransaction` returns an object with a function to sign transactions, along with the state of the signature process. This is useful when you want to sign a transaction programmatically without sending it to the network.

### Usage

1. Import the required dependencies and hooks from the  API Client.

2. Use the `useSignTransaction` hook in your component.

3. Call the `signTransaction` function with the appropriate parameters.

### Example

Below is an example demonstrating how to use the `useSignTransaction` hook to sign an Ethereum transaction.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`transaction.sign`

```jsx
import React, { useEffect, useState, useCallback } from "react";
import {
  useSignTransaction,
  useRequestAccount,
} from "@ledgerhq/wallet-api-client-react";
import BigNumber from "bignumber.js";

function App() {
  const { requestAccount, account } = useRequestAccount();
  const { signTransaction, pending, signature, error } = useSignTransaction();

  const [response, setResponse] = useState(null);

  useEffect(() => {
    requestAccount();
  }, [requestAccount]);

  const handleSignTransaction = useCallback(async () => {
    if (!account) return;

    const ethereumTransaction = {
      family: "ethereum",
      amount: new BigNumber(1000000000000000), // 0.001 ETH in wei
      recipient: "0xRecipientAddressHere",
      gasPrice: new BigNumber(20000000000), // 20 Gwei
      gasLimit: new BigNumber(21000),
      nonce: 0, // Replace with the correct nonce
    };

    try {
      const signature = await signTransaction(account.id, ethereumTransaction);
      setResponse(signature);
    } catch (e) {
      console.error(e);
    }
  }, [account, signTransaction]);

  return (
    <>
      <h1>Test Live App - Wallet API</h1>
      <div className="card">
        <button onClick={handleSignTransaction} disabled={pending}>
          Sign Ethereum Transaction
        </button>

        {pending && <p>Signing...</p>}
        {error && <p>Error: {error.toString()}</p>}
        {response && (
          <p>Transaction signed successfully: {response.toString("hex")}</p>
        )}
      </div>
    </>
  );
}

export default App;
```

### Parameters

The `signTransaction` function takes three parameters:

- `accountId`: The ID of the account you want to sign the transaction with.
- `transaction`: The [transaction object](../../appendix/transaction) in the currency family-specific format.
- `options` (optional): Extra parameters that may be required by certain blockchain implementations.

In the example above, `accountId` is obtained through the `useRequestAccount` hook, and `transaction` is an object representing an Ethereum transaction.

### Return Value

The `useSignTransaction` hook returns an object with the following properties:

- `signTransaction`: Function to call for signing a transaction.
- `pending`: Boolean indicating if the signing process is ongoing.
- `signature`: The raw signed transaction as a Buffer, if successful.
- `error`: An error object if the signing process failed.

### Error Handling

If an error occurs during the signing process, the `error` property will be set with the error information

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useUserId -->

# Using the `useUserId` Hook

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The `useUserId` hook is part of the  API Client for React. It allows the user to fetch the User ID associated with the connected wallet. This documentation provides a detailed explanation of how to use this hook in your application.

### Introduction

`useUserId` returns an object with the User ID, the time at which the data was updated, a loading state, any error that occurred during the fetching process, and a function to manually update the data.

### Usage

1. Import the required dependencies and hooks from the  API Client.

2. Use the `useUserId` hook in your component.

3. Optionally, call the `updateData` function to manually update the User ID.

### Example

Below is an example demonstrating how to use the `useUserId` hook to fetch and display the User ID.

[**Required permission**:](https://developers.ledger.com/docs/ledger-live/discover/guides/wallet-api/appendix/manifest#permissions)
`wallet.userId`

```jsx
import React, { useEffect } from "react";
import { useUserId } from "@ledgerhq/wallet-api-client-react";

function App() {
  const { userId, updatedAt, error, loading, updateData } = useUserId();

  useEffect(() => {
    updateData();
  }, [updateData]);

  return (
    <div>
      <h1>Fetch User ID</h1>

      {loading && <p>Loading...</p>}
      {error && <p>Error: {error.toString()}</p>}
      {userId && (
        <div>
          <p>User ID: {userId}</p>
          <p>Last Updated At: {updatedAt?.toLocaleString()}</p>
        </div>
      )}

      <button onClick={updateData} disabled={loading}>
        Refresh User ID
      </button>
    </div>
  );
}

export default App;
```

### Return Value

The `useUserId` hook returns an object with the following properties:

- `userId`: The User ID as a string or `null` if not fetched.
- `updatedAt`: A `Date` object representing the last time the data was updated or `null` if not updated.
- `loading`: A boolean indicating if the fetching process is ongoing.
- `error`: An error object if the fetching process failed.
- `updateData`: A function that can be called to manually refresh the User ID.

### Manual Updating

The `updateData` function allows you to manually trigger the fetching process. This might be useful if you need to re-fetch the User ID due to some user interaction or event in your application.

### Error Handling

If an error occurs during the fetching process, the `error` property will be set with the error information. It's good practice to always check this property and handle errors accordingly in your UI.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/hooks/useWalletInfo -->

# Using the `useWalletInfo` Hook

The `useWalletInfo` hook is part of the  API Client for React. It allows you to fetch the wallet information associated with the connected wallet. This documentation provides a detailed explanation of how to use this hook in your application.

### Introduction

`useWalletInfo` returns an object containing the wallet information, the time at which the data was updated, a loading state, any error that occurred during the fetching process, and a function to manually update the data.

### Usage

1. Import the required dependencies and hooks from the  API Client.

2. Use the `useWalletInfo` hook in your component.

3. Optionally, call the `updateData` function to manually update the wallet information.

### Example

Below is an example demonstrating how to use the `useWalletInfo` hook to fetch and display the wallet information.

[**Required permission**:](https://developers.ledger.com/docs/discover/wallet-api/appendix/manifest#permissions)
`wallet.info`

```jsx
import React, { useEffect } from "react";
import { useWalletInfo } from "@ledgerhq/wallet-api-client-react";

function App() {
  const { walletInfo, updatedAt, error, loading, updateData } = useWalletInfo();

  useEffect(() => {
    updateData();
  }, [updateData]);

  return (
    <div>
      <h1>Fetch Wallet Info</h1>

      {loading && <p>Loading...</p>}
      {error && <p>Error: {error.toString()}</p>}
      {walletInfo && (
        <div>
          <p>Wallet Info: {JSON.stringify(walletInfo)}</p>
          <p>Last Updated At: {updatedAt?.toLocaleString()}</p>
        </div>
      )}

      <button onClick={updateData} disabled={loading}>
        Refresh Wallet Info
      </button>
    </div>
  );
}

export default App;
```

### Return Value

The `useWalletInfo` hook returns an object with the following properties:

- `walletInfo`: The wallet information object or `null` if not fetched.
- `updatedAt`: A `Date` object representing the last time the data was updated or `null` if not updated.
- `loading`: A boolean indicating if the fetching process is ongoing.
- `error`: An error object if the fetching process failed.
- `updateData`: A function that can be called to manually update the wallet information.

#### Structure of the `walletInfo` Object

The `walletInfo` object contains the following properties:

- `tracking`: A boolean indicating whether tracking is enabled or disabled.
- `wallet`: An object containing the following properties:
- `name`: A string representing the name of the wallet.
- `version`: A string representing the version of the wallet.

Example of a `walletInfo` object:

```json
{
  "tracking": true,
  "wallet": {
    "name": "My Wallet",
    "version": "1.0.0"
  }
}
```

### Manual Updating

The `updateData` function allows you to manually trigger the fetching process. This might be useful if you need to re-fetch the wallet information due to some user interaction or event in your application.

### Error Handling

If an error occurs during the fetching process, the `error` property will be set with the error information. It's good practice to always check this property and handle errors accordingly in your UI.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/react/usage -->

# Use the Wallet API in a React app

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

This guide shows how to integrate the  API in a React app: install the packages, configure the transport, wrap your app, and optionally test with the simulator.

## Prerequisites

- A React app (client-side)
- Node.js and a package manager (npm, yarn or pnpm)

## Install packages

Install the base client:

```sh npm2yarn
npm install @ledgerhq/wallet-api-client
```

Install the React helper package with hooks:

```sh npm2yarn
npm install @ledgerhq/wallet-api-client-react
```

Optional: install the simulator for server-side testing:

```sh npm2yarn
npm install @ledgerhq/wallet-api-simulator
```

Note: the simulator currently works only in server-side environments because it depends on `process`.

## Configure the transport

Create a transport provider to enable communication with the  API. Add a `TransportProvider.tsx` component that uses the Wallet API client to establish a window message transport (SSR-safe).

```jsx
import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react";
import { Transport, WindowMessageTransport } from "@ledgerhq/wallet-api-client";

function TransportProvider({ children }) {
  function getWalletAPITransport(): Transport {
    if (typeof window === "undefined") {
      return {
        onMessage: undefined,
        send: () => {},
      };
    }

    const transport = new WindowMessageTransport();
    transport.connect();
    return transport;
  }

  const transport = getWalletAPITransport();

  return (
    <WalletAPIProvider transport={transport}>{children}</WalletAPIProvider>
  );
}

export default TransportProvider;
```

### How it works

- Import the client React provider and transport types from the  API packages.
- Create `TransportProvider` to render its children inside `WalletAPIProvider`.
- Use `getWalletAPITransport` to supply a transport: during SSR, return a no-op transport; in the browser, use `WindowMessageTransport` and call `connect()`.
- `WindowMessageTransport` communicates with the  API via window messages.
- `WalletAPIProvider` receives the transport so the rest of the app (its `{children}`) can access the API.

## Wrap your app

Wrap your root `<App />` component with the `TransportProvider`:

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import TransportProvider from './TransportProvider';

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <TransportProvider>
      <App />
    </TransportProvider>
  </React.StrictMode>
);
```

With this setup, your app can access the  API via the `WalletAPIProvider` context.

## Test with the simulator (optional)

To test without connecting to the  App directly, use `@ledgerhq/wallet-api-simulator` in a server-side environment.

```sh npm2yarn
npm install @ledgerhq/wallet-api-simulator
```

Remember: it currently only functions server-side due to a dependency on `process`.

## Next steps

- Make your Live App ready to be registered by creating your manifest.
- Learn how to create your manifest: [how to create your manifest](../examples/use-live-app)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/diagrams -->

---
title: Server diagrams
category: reference
---

# Server diagrams

These diagrams give a visual overview of how `WalletAPIServer` brokers communication between a Live App and a wallet. Read them alongside the [server reference](./reference) and the [RpcNode reference](./extras/rpc-node).

> **Note:** The diagrams come from this [introductory slideshow](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4) and have been adapted to be readable on their own.

## 1. Direct wallet–app interaction

![Live App and wallet exchanging ad-hoc messages without an RPC layer, showing the lack of structure that motivates the Wallet API](./assets/diagram-request-handlers-1-light.png)

Without a JSON-RPC layer, every Live App and every wallet would need ad-hoc message contracts. The Wallet API exists to replace this with a structured, capability-based bridge.

## 2. Processing requests with requestHandlers

![The WalletAPIServer routing an incoming JSON-RPC request to the matching requestHandler before returning a response](./assets/diagram-request-handlers-2-light.png)

When the Live App sends a request, the server looks up [`requestHandlers`](./reference#requesthandlers) by method ID, runs the matching handler with the parsed parameters and `walletContext`, then writes the result back to the transport.

## 3. Asking the wallet for data or actions with walletHandlers

![A requestHandler delegating to a walletHandler, which performs an action on the wallet side and returns a result back through the server](./assets/diagram-wallet-handlers-1-light.png)

Most request handlers cannot fulfil a request alone: they need wallet-side capabilities such as prompting the user, signing, or reading accounts. They delegate to [`walletHandlers`](./reference#wallethandlers), which the wallet implements.

## 4. Bidirectional transport

![The Transport object carrying serialized JSON-RPC messages in both directions between the Live App and the wallet via send and onMessage](./assets/diagram-transport-1-light.png)

The [`transport`](./reference#transport) carries strings in both directions: the Live App's `send` becomes the server's `onMessage`, and vice versa. The transport itself is implementation-specific (postMessage, WebSocket, IPC).

## 5. Data and permissions flowing into walletContext

![Accounts, currencies, configuration, and permissions being injected into walletContext from setter calls on the wallet side](./assets/diagram-permissions-1-light.png)

The wallet pushes accounts, currencies, configuration, and permissions into the server using the matching setters. The server combines them into [`walletContext`](./reference#walletcontext), the read-only view that request handlers consume. Permissions filter both what handlers a Live App can call and what currencies and accounts they can see.

## See also

- [Server reference](./reference): full list of properties, methods, and the constructor signature.
- [RpcNode](./extras/rpc-node): the abstract class that handles JSON-RPC framing and error translation.
- [Server slideshow](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4): the original Excalidraw deck.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/extras/rpc-node -->

---
title: RpcNode
category: reference
---

# RpcNode

`WalletAPIServer` extends the abstract class `RpcNode`, which implements the JSON-RPC 2.0 plumbing shared between the server and the client. Knowing what `RpcNode` provides is useful when you implement a custom transport or read stack traces.

Class diagram overview

![Class diagram showing RpcNode with its transport, requestHandlers, and ongoingRequests properties, and the request/notify/handleMessage flow into onRequest](../assets/server-rpc-node-classdiagram.png)

## Type parameters

```ts
abstract class RpcNode<TSHandlers, TCHandlers>
```

| Parameter    | Meaning                                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `TSHandlers` | The handlers exposed to the **other side** for this node. For the server, these are the [request handlers](../reference#requesthandlers). |
| `TCHandlers` | The handlers available on the **other side**, used to type the `request` / `notify` calls this node emits.                                |

## Properties

| Property          | Visibility | Set via                 | Purpose                                                                                                |
| ----------------- | ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `transport`       | private    | constructor             | The [transport](../reference#transport) used to read and write JSON-RPC messages.                      |
| `requestHandlers` | protected  | constructor             | The handlers that fulfil incoming requests.                                                            |
| `ongoingRequests` | private    | populated by `_request` | Pending request promises keyed by request ID. The resolver is called when a matching response arrives. |

The constructor sets `transport.onMessage` to its own `handleMessage` so any incoming string is routed through `RpcNode`.

## Methods

### Public

```ts
request<K>(method: K, params: P): Promise<R | undefined>
notify<K>(method: K, params: P): void
```

| Method    | Use it to                                                | Notes                                                                                                                                                                                                                       |
| --------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request` | Send a JSON-RPC **request** and `await` the response.    | Generates a UUID v4 for the request `id`, stores a resolver in `ongoingRequests`, sends `{ jsonrpc: "2.0", id, method, params }` over the transport, and resolves with the response's `result` (or rejects with the error). |
| `notify`  | Send a JSON-RPC **notification** (no response expected). | No `id` is generated; the receiver does not reply.                                                                                                                                                                          |

### Internal flow

| Method              | Visibility          | Role                                                                                                                                                                         |
| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `handleMessage`     | private             | Routes an incoming message to `handleRpcRequest` (when it has a `method`) or `handleRpcResponse` (when it has a `result`/`error`).                                           |
| `handleRpcRequest`  | private             | Calls `onRequest(request)`, builds the response, and writes it to the transport. Translates exceptions into `RpcError`s (see below).                                         |
| `handleRpcResponse` | private             | Looks up the resolver in `ongoingRequests` by ID and resolves it. Throws if no matching request is found.                                                                    |
| `onRequest`         | abstract, protected | Subclasses must implement this. `WalletAPIServer.onRequest` looks up `requestHandlers[method]`, checks the [permissions](../reference#permissions), and invokes the handler. |

## Error handling

`RpcNode` translates thrown exceptions into JSON-RPC error responses with the following codes (defined in [`packages/core/src/JSONRPC/types.ts`](https://github.com/LedgerHQ/wallet-api/blob/main/packages/core/src/JSONRPC/types.ts)):

| Code     | Name               | Raised when                                                                                                                   |
| -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `-32700` | `PARSE_ERROR`      | Invalid JSON received.                                                                                                        |
| `-32600` | `INVALID_REQUEST`  | Message is not a valid JSON-RPC request.                                                                                      |
| `-32601` | `METHOD_NOT_FOUND` | `requestHandlers` has no entry for the method ID.                                                                             |
| `-32602` | `INVALID_PARAMS`   | Zod validation of `params` fails (`error.flatten()` is attached as `data`).                                                   |
| `-32603` | `INTERNAL_ERROR`   | Internal JSON-RPC error.                                                                                                      |
| `-32000` | `SERVER_ERROR`     | A `ServerError` (for example the wallet not implementing a handler) was thrown. The original error data is wrapped in `data`. |

On the requesting side, `_request` re-hydrates these errors: `SERVER_ERROR`s with code `UNKNOWN_ERROR` are deserialized via `@ledgerhq/errors` and rejected as the original error class; everything else is rejected as a `RpcError`.

## RPC request and response types

```ts filename="packages/core/src/JSONRPC/types.ts"
type RpcRequest<MParam = string, TParam = unknown> = {
  jsonrpc: "2.0";
  method: MParam;
  params?: TParam;
  id?: string | number | null;
};

type RpcResponse<TResult = unknown, TErrorData = unknown> =
  | { jsonrpc: "2.0"; id: string | number | null; result?: TResult }
  | { jsonrpc: "2.0"; id: string | number | null; error: RpcResponseError<TErrorData> };
```

A request without an `id` is a notification: no response is sent.

## See also

- [Server reference](../reference): `requestHandlers`, `walletHandlers`, and permissions.
- [`RpcNode` source](https://github.com/LedgerHQ/wallet-api/blob/main/packages/core/src/JSONRPC/RpcNode.ts).
- [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/extras/rxjs -->

---
title: RxJS operators used in Wallet API Server
category: reference
---

# RxJS operators used in Wallet API Server

`WalletAPIServer` uses [RxJS 7](https://rxjs.dev/) to handle the stream of messages coming in from . This page is a quick reference for the specific operators and subjects the server relies on. If you are new to RxJS, start with the [official RxJS guide](https://rxjs.dev/guide/overview) before reading further.

## `map`

[`map`](https://rxjs.dev/api/operators/map) transforms each value emitted by an observable before passing it downstream. The server uses it to normalise or reshape incoming message payloads.

## `Observable`

An [`Observable`](https://rxjs.dev/guide/observable) is a lazy push-based data producer. The server models the incoming message stream as an observable so consumers can react to each message without polling.

## `BehaviorSubject`

A [`BehaviorSubject`](https://rxjs.dev/api/BehaviorSubject) is a subject that requires an initial value and immediately emits the current value to any new subscriber. The server uses it to hold stateful permission lists (such as allowed currencies) so that late subscribers always receive the latest snapshot.

```js
import { BehaviorSubject } from "rxjs";

const subject = new BehaviorSubject(123);

// Two subscribers receive the initial value immediately.
subject.subscribe(console.log); // 123
subject.subscribe(console.log); // 123

// Both receive the new value when it changes.
subject.next(456); // 456, 456

// A new subscriber receives the latest value (456), not the initial one.
subject.subscribe(console.log); // 456

subject.next(789); // 789, 789, 789

// Output sequence: 123, 123, 456, 456, 456, 789, 789, 789
```

## `combineLatest`

[`combineLatest`](https://rxjs.dev/api/index/function/combineLatest) emits a combined value whenever any of its source observables emits, pairing each emission with the most recent value from every other source. The server uses it to compute the list of currencies a dApp is permitted to access, re-evaluating whenever either the full currency list or the dApp's declared permissions change:

```js
const allowedCurrencies$ = new BehaviorSubject([]);

combineLatest(
  [this.allCurrencies$, this.permissions.currencyIds$],
  matchCurrencies
).subscribe(allowedCurrencies$);
```

Here `matchCurrencies` is the projection function that filters `allCurrencies$` to those the dApp has declared. `allowedCurrencies$` emits an empty array immediately (from the `BehaviorSubject` initial value), then re-emits any time either source changes.

## `firstValueFrom`

[`firstValueFrom`](https://rxjs.dev/api/index/function/firstValueFrom) converts an observable to a promise by subscribing, waiting for the first emission, and then unsubscribing. The server uses it when a one-shot value is needed from a stream without keeping the subscription open.

```js
import { firstValueFrom } from "rxjs";

const value = await firstValueFrom(someObservable$);
```

## Related

- [Wallet API Server introduction](../introduction) — architecture overview and constructor reference
- [RxJS official documentation](https://rxjs.dev/) — full operator catalogue

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/account -->

---
title: Account handlers
category: reference
---

# Account handlers

The account handlers let a Live App list the user's accounts, prompt the user to pick one, and let the user verify a receive address on their Ledger device.

## Method IDs

| Method ID         | Direction         | Wallet handler required? | Purpose                                              |
| ----------------- | ----------------- | :----------------------: | ---------------------------------------------------- |
| `account.list`    | Live App → Wallet |            yes           | List the user's accounts, optionally filtered.       |
| `account.request` | Live App → Wallet |            yes           | Prompt the user to select an account.                |
| `account.receive` | Live App → Wallet |            yes           | Display an address on-device for the user to verify. |

If the wallet does not register the matching wallet handler, the server throws an `RpcError` with code `SERVER_ERROR` (`-32000`) wrapping a `not implemented by wallet` server error.

## `account.list`

Returns every account the user has added in the wallet, optionally filtered by currency.

### Parameters

| Parameter     | Type       | Required | Notes                                                                                                   |
| ------------- | ---------- | :------: | ------------------------------------------------------------------------------------------------------- |
| `currencyIds` | `string[]` |    no    | Filter by currency ID (for example `["bitcoin", "ethereum"]`). When omitted, all accounts are returned. |

### Result

```ts
{
  rawAccounts: RawAccount[]
}
```

The `rawAccounts` are the [serialized Account objects](../reference#allaccounts).

## `account.request`

Prompts the user to select an account in the wallet UI.

### Parameters

| Parameter             | Type       | Required | Notes                                                                                                                                  |
| --------------------- | ---------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------- |
| `currencyIds`         | `string[]` |    no    | Restrict the picker to these currencies.                                                                                               |
| `showAccountFilter`   | `boolean`  |    no    | Show the account filter UI.                                                                                                            |
| `drawerConfiguration` | `object`   |    no    | Controls the drawer UI: `assets.{filter, leftElement, rightElement}` and `networks.{leftElement, rightElement}`, all optional strings. |
| `useCase`             | `string`   |    no    | Tags the request with a use case (for example `"swap"`).                                                                               |
| `uiUseCase`           | `string`   |    no    | UI variant to render.                                                                                                                  |

When the wallet handler is invoked, the server also forwards a derived flag `areCurrenciesFiltered` (`true` when `currencyIds` is non-empty).

### Result

```ts
{
  rawAccount: RawAccount
}
```

## `account.receive`

Displays an account address on the Ledger device so the user can verify it. Use this before sharing the address with a counterparty.

### Parameters

| Parameter       | Type     | Required | Notes                                                                                                           |
| --------------- | -------- | :------: | --------------------------------------------------------------------------------------------------------------- |
| `accountId`     | `string` |    yes   | ID of the account whose address to display.                                                                     |
| `tokenCurrency` | `string` |    no    | Token currency ID, when the account holds tokens whose receive address differs from the parent account address. |

### Result

```ts
{
  address: string
}
```

The returned address is the one the user confirmed on-device.

## See also

- [Account module (client)](../../core/modules/account): the client-side counterpart.
- [Server reference, `allAccounts$`](../reference#allaccounts): shape of the `RawAccount` returned by these handlers.
- [`account` handler source](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/internalHandlers/account.ts) and [schemas](https://github.com/LedgerHQ/wallet-api/tree/main/packages/core/src/spec/types).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/bitcoin -->

## overview

The Bitcoin handler allows the server to interact with Bitcoin accounts.\
Specifically, you can retrieve the extended public key (xPub) of a Bitcoin account.\
This is useful for deriving Bitcoin addresses without revealing the private key.

## request handlers:

### "bitcoin.getXPub" - Get Extended Public Key (xPub)

| parameter (in req.params) | required? | note                                                                 |
| ------------------------- | --------- | -------------------------------------------------------------------- |
| _accountId_               | ✅         | The ID of the Bitcoin account for which the xPub is to be retrieved. |

| walletHandler used | note                                                     |
| ------------------ | -------------------------------------------------------- |
| _bitcoin.getXPub_  | Should retrieve the xPub of a particular bitcoin account |

- Gets the xPub of a bitcoin account with _bitcoin.getXPub_ walletHandler
- **Returns**: A promise that resolves with the xPub as a string.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/currency -->

## overview

The Currency handlers enables interaction with various cryptocurrencies that are supported by the connected wallet.\
The server can list the cryptocurrencies and apply filters by name or ticker.

## request handlers:

### "currency.list" - List Cryptocurrencies

| parameter (in req.params) | required? | note                                                                            |
| ------------------------- | --------- | ------------------------------------------------------------------------------- |
| _currencyIds_             | ❌         | An array of strings specifying the currency IDs to filter the cryptocurrencies. |

- Start with all currencies (available in [context.currencies](../wallet-api-server#walletcontextcurrencies))
- Filter those against the parameter _currencyIds_
- **Returns**: A promise that resolves with an array of Currency objects.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/device -->

---
title: Device handlers
category: reference
---

# Device handlers

The device handlers provide methods for handling the physical device, including opening low-level transport and selecting a device in the connected wallet.

## Request handlers

### "device.close" — Close Device

Closes a transport connection, releasing the BLE or USB lock on the device.

| Parameter (in req.params) | Required? | Note                     |
| ------------------------- | --------- | ------------------------ |
| _transportId_             | ✅         | A device's transport ID. |

| Wallet handler used |
| ------------------- |
| _device.close_      |

- **Returns**: A promise that resolves with the transport ID.

### "device.exchange" — Send a raw APDU command

Sends an APDU hex string to the device and returns the raw hex response. Use this to communicate directly with the device at the transport level.

| Parameter (in req.params) | Required? | Note                                        |
| ------------------------- | --------- | ------------------------------------------- |
| _transportId_             | ✅         | The transport ID returned by `device.open`. |
| _apduHex_                 | ✅         | Raw APDU command in hexadecimal format.     |

| Wallet handler used |
| ------------------- |
| _device.exchange_   |

- **Returns**: A promise that resolves with `responseHex` — the raw hex response from the device.

### "device.open" — Open Device

Opens a device in the connected wallet.

| Parameter | Required? | Note                                                    |
| --------- | --------- | ------------------------------------------------------- |
| _filters_ | ✅         | An object containing the parameters to open the device. |

| Wallet handler used |
| ------------------- |
| _device.open_       |

- **Returns**: A promise that resolves with a `transportId`.

### "device.select": Select Device

Selects a device in the connected wallet.

| Parameter | Required? | Note                                                                |
| --------- | --------- | ------------------------------------------------------------------- |
| _params_  | ✅         | An object containing the parameters to select and check the device. |

| Wallet handler used |
| ------------------- |
| _device.select_     |

- **Returns**: A promise that resolves with a `deviceId`, which you can use with the `device.open` method.

### "device.transport": Open Low-Level Transport

Opens low-level transport in the connected wallet.

| Parameter  | Required? | Note                                 |
| ---------- | --------- | ------------------------------------ |
| _deviceId_ | ✅         | The device ID to open transport for. |
| _appName_  | ✅         | The app to open on the device.       |

| Wallet handler used |
| ------------------- |
| _device.transport_  |

- **Returns**: A promise that resolves with an instance of Transport compatible with `@ledgerhq/hw-transport`.

## Related

- [Exchange handlers](./exchange)
- [Wallet API server reference](../usage)
- [Transport compatibility](../../../transport)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/exchange -->

---
title: Exchange handlers
category: reference
---

# Exchange handlers

The exchange handlers manage swap, sell, and fund operations through Ledger Wallet.

## Request handlers

### "exchange.start": Start Exchange

Call this before `exchange.complete` to generate a nonce for the transaction. The returned `transactionId` is required by the completion step.

| Parameter (in req.params) | Required? | Note                                              |
| ------------------------- | --------- | ------------------------------------------------- |
| _exchangeType_            | ✅         | Type of exchange: `"SWAP"`, `"SELL"`, or `"FUND"` |

| Wallet handler used |
| ------------------- |
| _exchange.start_    |

- **Returns**: A promise that resolves with an object containing the `transactionId`, which is used to complete the exchange process.

### "exchange.complete": Complete Exchange

Complete an exchange process (swap, sell, or fund) by passing the exchange content and its signature. The optional parameters `toAccountId`, `swapId`, and `rate` are required when `exchangeType` is `"SWAP"`. The `tokenCurrency` parameter applies to `"SWAP"` and `"FUND"`.

| Parameter (in req.params) | Required? | Note                                                                                                          |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| _provider_                | ✅         | A string used to verify the signature.                                                                        |
| _fromAccountId_           | ✅         | Identifier of the account used as a source for the transaction.                                               |
| _rawTransaction_          | ✅         | A RawTransaction object containing the transaction details.                                                   |
| _hexBinaryPayload_        | ✅         | Hexadecimal string representing the blueprint of the data that will be allowed for signing.                   |
| _hexSignature_            | ✅         | Hexadecimal string ensuring the source of the payload.                                                        |
| _feeStrategy_             | ✅         | A string representing the fee strategy: `"SLOW"`, `"MEDIUM"`, or `"FAST"`.                                    |
| _exchangeType_            | ✅         | A string specifying the type of exchange operation: `"SWAP"`, `"SELL"`, or `"FUND"`.                          |
| _toAccountId_             | ❌         | Identifier of the account used as a destination (required for `"SWAP"`).                                      |
| _swapId_                  | ❌         | Identifier of the backend swap used (required for `"SWAP"`).                                                  |
| _rate_                    | ❌         | Swap rate used in the transaction (required for `"SWAP"`).                                                    |
| _tokenCurrency_           | ❌         | Used when pointing to a token whose ID does not exist in the Wallet API (optional for `"SWAP"` and `"FUND"`). |

| Wallet handler used |
| ------------------- |
| _exchange.complete_ |

- **Returns**: A promise that resolves with an object containing the `transactionHash` of the broadcasted transaction.

## Related

- [Exchange flow overview](../../../exchange)
- [Device handlers](./device)
- [Wallet API server usage guide](../usage)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/message -->

---
title: Message handlers
category: reference
---

# Message handlers

The message handlers let a Live App ask the user to sign an arbitrary message (for example an [EIP-191](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-191.md) personal sign or an [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) typed-data message) using one of the wallet's accounts.

To sign a transaction instead, use the [transaction handlers](./transaction).

## Method IDs

| Method ID      | Direction         | Wallet handler required? | Purpose                                         |
| -------------- | ----------------- | :----------------------: | ----------------------------------------------- |
| `message.sign` | Live App → Wallet |            yes           | Sign a message with the selected account's key. |

## `message.sign`

The Live App passes the message as a hex string. The server decodes it to a `Buffer` before forwarding to the wallet's `message.sign` handler. The result is encoded back to hex on the wire.

### Parameters

| Parameter    | Type     | Required | Notes                                                                                                                                        |
| ------------ | -------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`  | `string` |    yes   | ID of the account whose key signs the message.                                                                                               |
| `hexMessage` | `string` |    yes   | Hex-encoded message to sign.                                                                                                                 |
| `options`    | `object` |    no    | Wallet-specific options. Currently: `hwAppId?: string`, `dependencies?: string[]`.                                                           |
| `meta`       | `object` |    no    | Free-form metadata, typed as `Record<string, unknown>`. Forwarded as-is to the wallet handler; useful for context such as the dApp identity. |

### Result

```ts
{
  hexSignedMessage: string
}
```

The signed message is hex-encoded.

### Errors

| Condition                                         | Error                                                                |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| `accountId` or `hexMessage` missing or wrong type | `RpcError` with code `INVALID_PARAMS` (`-32602`).                    |
| Wallet does not implement `message.sign`          | `RpcError` with code `SERVER_ERROR` (`-32000`).                      |
| The user rejects the request on-device            | The error thrown by the wallet handler is forwarded to the Live App. |

## See also

- [Transaction handlers](./transaction): for signing transactions instead of arbitrary messages.
- [Message module (client)](../../core/modules/message): the client-side counterpart.
- [`message.sign` source](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/internalHandlers/message.ts) and [`MessageSign` schema](https://github.com/LedgerHQ/wallet-api/blob/main/packages/core/src/spec/types/MessageSign.ts).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/storage -->

---
title: Storage handlers
category: reference
---

# Storage handlers

The storage handlers expose Ledger Wallet's per-app key-value store to a Live App. Data is namespaced by application so two Live Apps cannot read or overwrite each other's keys without an explicit `storeId`.

## Method IDs

| Method ID     | Direction         | Purpose                                  |
| ------------- | ----------------- | ---------------------------------------- |
| `storage.set` | Live App → Wallet | Store a string value under a given key.  |
| `storage.get` | Live App → Wallet | Retrieve a string value for a given key. |

Both methods require the wallet to implement the matching `walletHandler` (`storage.set` / `storage.get`). If the wallet does not, the server throws an `RpcError` with code `SERVER_ERROR` (`-32000`) wrapping a `not implemented by wallet` server error.

## `storage.set`

Stores a string value under the given key. The default store is the calling app's `appId` from [`walletContext.config`](../reference#walletcontextconfig); pass `storeId` to write into a specific store.

### Parameters

| Parameter | Type     | Required | Notes                                                                                                           |
| --------- | -------- | :------: | --------------------------------------------------------------------------------------------------------------- |
| `key`     | `string` |    yes   | Key under which to store the value.                                                                             |
| `value`   | `string` |    yes   | Value to store. The store only accepts strings; serialize objects yourself (for example with `JSON.stringify`). |
| `storeId` | `string` |    no    | Store to write into. Defaults to `context.config.appId`.                                                        |

### Result

Resolves with `undefined` (the schema is `z.void().optional()`).

### Errors

| Condition                               | Error                                                                                   |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| `key` or `value` missing or wrong type  | `RpcError` with code `INVALID_PARAMS` (`-32602`).                                       |
| Wallet does not implement `storage.set` | `RpcError` with code `SERVER_ERROR` (`-32000`), data wraps `not implemented by wallet`. |

## `storage.get`

Retrieves the value previously stored under `key`. Returns `undefined` if the key does not exist.

### Parameters

| Parameter | Type                    | Required | Notes                                                   |
| --------- | ----------------------- | :------: | ------------------------------------------------------- |
| `key`     | `string` (min length 1) |    yes   | Key to read.                                            |
| `storeId` | `string` (min length 1) |    no    | Store to read from. Defaults to `context.config.appId`. |

### Result

Resolves with `{ value: string | undefined }`. The value is `undefined` when the key has never been set in the targeted store.

### Errors

| Condition                               | Error                                             |
| --------------------------------------- | ------------------------------------------------- |
| `key` missing, empty, or wrong type     | `RpcError` with code `INVALID_PARAMS` (`-32602`). |
| Wallet does not implement `storage.get` | `RpcError` with code `SERVER_ERROR` (`-32000`).   |

## See also

- [Storage module (client)](../../core/modules/storage): the client-side counterpart used by Live Apps.
- [Server reference](../reference): `walletContext.config`, permissions, and how handlers are wired in.
- [`storage.set` source](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/internalHandlers/storage.ts) and [`StorageSet` / `StorageGet` schemas](https://github.com/LedgerHQ/wallet-api/blob/main/packages/core/src/spec/types/StorageSet.ts).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/transaction -->

## overview

The Transaction handlers allows the server to interact with user transactions.
It enables the server to let the user sign a transaction and also allows the server to sign and broadcast a transaction through .

## request handlers:

### "transaction.sign" - Sign Transaction

Let the user sign a transaction without broadcasting it. This is useful if you want to sign a transaction for later use.

| parameter (in req.params) | required? | note                                                                                                                                               |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`               | ✅         | The ID of the account where the transaction will be made.                                                                                          |
| `rawTransaction`          | ✅         | The raw [transaction object](../../appendix/transaction) in the currency family-specific format.                                                   |
| `options`                 | ❌         | Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsign-type) for more information. |
| `meta`                    | ❌         | Metadata for the transaction.                                                                                                                      |
|                           |           |                                                                                                                                                    |

| walletHandler used | note |
| ------------------ | ---- |
| _transaction.sign_ |      |

- **Returns**: A promise that resolves with the raw signed transaction as a Buffer.

### "transaction.signAndBroadcast" - Sign and Broadcast Transaction

Let the user sign a transaction and broadcast it to the network.

| parameter (in req.params) | required? | note                                                                                                                                               |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`               | ✅         | The ID of the account where the transaction will be made.                                                                                          |
| `rawTransaction`          | ✅         | The raw [transaction object](../../appendix/transaction) in the currency family-specific format.                                                   |
| `options`                 | ❌         | Extra parameters that might be needed for the transaction. See [references](../../appendix/transaction#transactionsign-type) for more information. |
| `meta`                    | ❌         | Metadata for the transaction.                                                                                                                      |

| walletHandler used             | note |
| ------------------------------ | ---- |
| _transaction.signAndBroadcast_ |      |

- **Returns**: A promise that resolves with the transaction hash as a string.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/handlers/wallet -->

---
title: Wallet handlers
category: reference
---

# Wallet handlers

The wallet handlers expose information about the connected wallet itself: which methods it supports, the user identifier, and a name/version pair. All three are served by the server and never delegate to the wallet, so a wallet implementation does not need to register matching `walletHandlers`.

## Method IDs

| Method ID             | Direction         | Purpose                                                              |
| --------------------- | ----------------- | -------------------------------------------------------------------- |
| `wallet.capabilities` | Live App → Wallet | List the method IDs available on this wallet (built-ins + handlers). |
| `wallet.userId`       | Live App → Wallet | Get the user identifier configured on the wallet.                    |
| `wallet.info`         | Live App → Wallet | Get the wallet name, version, and tracking flag.                     |

## `wallet.capabilities`

Lists every JSON-RPC method the wallet exposes. The server merges:

- the IDs of every `walletHandler` registered on the server, and
- five built-ins that always work without a wallet handler: `account.list`, `currency.list`, `wallet.capabilities`, `wallet.info`, `wallet.userId`.

### Parameters

None.

### Result

```ts
{
  methodIds: string[]
}
```

## `wallet.userId`

Returns the user ID stored in [`walletContext.config`](../reference#walletcontextconfig). The value is set when the server is constructed with `config.userId`.

### Parameters

None.

### Result

```ts
{
  userId: string
}
```

## `wallet.info`

Returns the wallet metadata stored in [`walletContext.config`](../reference#walletcontextconfig).

### Parameters

None.

### Result

```ts
{
  tracking: boolean,
  wallet: {
    name: string,
    version: string,
  }
}
```

`tracking` reflects whether the wallet has consented to analytics; `wallet.name` and `wallet.version` are set from `config.wallet` at server construction.

## See also

- [Wallet module (client)](../../core/modules/wallet): the client-side counterpart.
- [Server reference](../reference): how `walletContext.config` is populated.
- [`wallet` handler source](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/internalHandlers/wallet.ts) and [`WalletCapabilities` / `WalletInfo` / `WalletUserId` schemas](https://github.com/LedgerHQ/wallet-api/tree/main/packages/core/src/spec/types).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/introduction -->

# Wallet API Server

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Wallet API Server is a bi-directional JSON‑RPC 2.0 server that bridges a dApp (or service) with a Wallet (e.g., ) over a trusted channel. It provides a structured way to exchange requests/responses and notifications while enforcing capability-based permissions.

## Why use a server?

- Separation of concerns: your application logic stays in your process; the Wallet handles sensitive operations (accounts, signatures, device flows).
- Trust and permissions: the server formalizes capability requests and enforces what the dApp is allowed to do.
- Transport-agnostic RPC: JSON‑RPC 2.0 allows clear contracts and consistent error handling across transports (e.g., window\.postMessage, WebSocket).

## When to use it?

- You need a secure, permissioned bridge to a wallet () from a dApp or integration.
- You want a consistent RPC contract across environments and transports.
- You prefer capability-based access over ad‑hoc messaging.

## Where to start?

- [Visual introduction](./diagrams)
- [API reference](./reference)
- [Constructor overview](./reference#constructor)
- [React hook](./react-hook) (optional, useful if using react)
- [Example using constructor](./usage-examples/with-constructor)
- [Example within Ledger Wallet](./usage-examples/within-ledger-live)

## External resources

- Source code: [https://github.com/LedgerHQ/wallet-api/tree/main/packages/server](https://github.com/LedgerHQ/wallet-api/tree/main/packages/server)
- Main file: [https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/WalletAPIServer.ts](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/WalletAPIServer.ts)
- Wallet API README: [https://github.com/LedgerHQ/wallet-api/blob/main/README.md](https://github.com/LedgerHQ/wallet-api/blob/main/README.md)
- Spec: [https://github.com/LedgerHQ/wallet-api/blob/main/spec/server/README.md](https://github.com/LedgerHQ/wallet-api/blob/main/spec/server/README.md)
- Package: @ledgerhq/wallet-api-server

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/react-hook -->

> **Key takeaway:**  ☞   The renaming of "Ledger Live" to "Ledger Wallet" and\
>      "wallet" (in the hardware sense) to "signer" is still in progress.\
>      This page may contain legacy references that will be updated.

## useWalletAPIServer

[source code](https://github.com/LedgerHQ/wallet-api/blob/main/packages/server/src/react.ts)

For convenience in a react environment, the hook `useWalletAPIServer`, is available.

It is used to setup a WalletAPIServer

> **Note:** [It is how the  API Servers are created in ledger
> live](../usage-examples/within-ledger-live)

```js filename="packages/server/src/WalletAPIServer.ts"

export function useWalletAPIServer({
  transport,
  config,
  logger,
  accounts,
  currencies,
  permission,
  customHandlers,
}){...}

```

| Parameter (destructured from single object) | required? | note                                                                            |
| ------------------------------------------- | --------- | ------------------------------------------------------------------------------- |
| _transport_                                 | ✅         | sets the [transport](../wallet-api-server#transport)                            |
| _config_                                    | ✅         | sets the [walletContext.config](../wallet-api-server#walletcontextconfig) value |
| _logger_                                    | ❌         | (optional) sets the logger                                                      |
| _accounts_                                  | ✅         | sets the [accounts](../wallet-api-server#allaccounts)                           |
| _currencies_                                | ✅         | sets the [currencies](../wallet-api-server#allcurrencies)                       |
| _permissions_                               | ✅         | sets the [permissions](../wallet-api-server#permissions)                        |
| _customHandlers_                            | ❌         | (optional) sets [customHandlers](../wallet-api-server#walletcontextconfig)      |

Once instantiated, it

- Sets custom handlers, in all cases (even if no custom handlers are sent from LLC),
  it will be called to set the [requestHandlers](../wallet-api-server#requesthandlers)
- Sets config, permissions, currencies and accounts.

Then, it returns:

```ts
return {
  server,
  onMessage,
};
```

`server` is our walletAPIServer instance.\
`onMessage`, which will allow _APP -> SERVER_ communication.

> **Note:** Note that WalletAPIServer is instantiated as a ref
> [useRef](https://react.dev/reference/react/useRef) we actually return
> `server: server.current`

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/reference -->

## properties

### allAccounts$

Represents all available wallet accounts

`Account` is a slightly modified subject of the Account type used by the  platform

details of the Account type

```js
export type Account = {
  /**
   * The unique identifier of this account used internally by <Glossary word='Ledger Wallet'></Glossary> software
   */
  id: string;
  /**
   * The account’s name set by the user.
   */
  name: string;
  /**
   * The "next" public address where a user should receive funds. In the context of Bitcoin, the address is "renewed" each time funds are received in order to allow some privacy. In other blockchains, the address might never change
   */
  address: string;
  /**
   * The associated cryptocurrency id of the Account
   */
  currency: string;
  /**
   * The total amount of assets that this account holds
   */
  balance: BigNumber;
  /**
   * The amount of the balance that can be spent. Most of the time it will be equal to the balance, but this can vary in some blockchains
   */
  spendableBalance: BigNumber;
  /**
   * Tracks the current blockchain block height
   */
  blockHeight: number | undefined;
  /**
   * The date of the last time a synchronization was performed. In other words, tracks how up-to-date the Account data is
   */
  lastSyncDate: Date;
}; 
```

| Created via | name            |
| ----------- | --------------- |
| _setter_    | **setAccounts** |

### allCurrencies$

All available currencies that supported by the wallet.

details of the Currency type

```js
type Currency = {
    type: "CryptoCurrency";
    name: string;
    id: string;
    color: string;
    ticker: string;
    decimals: number;
    family: "bitcoin" | "ethereum" | "algorand" | "crypto_org" | "ripple" | "cosmos" | "celo" | ... 10 more ... | "solana";
}

```

| Created via | name              |
| ----------- | ----------------- |
| _setter_    | **setCurrencies** |

---

### permissions

Permissions are a set of two lists:

1. The first restricting the [currencies](./wallet-api-server#allcurrencies) that can be used,
2. The second restricting the [requestHandlers](./wallet-api-server#requesthandlers) method that can be used,
   this list also restricts the calls that the [sendMessage](./wallet-api-server#sendmessage) method can make

| Created via | name               |
| ----------- | ------------------ |
| _setter_    | **setPermissions** |

#### permissions.currencyIds$

- a list of currencies ids an application can interact with

```js filename="example"
permissions.currencyIds$ = ["ethereum", "bitcoin"];
```

- ℹ️ it is possible to allow all currencies available in [allCurrencies](./wallet-api-server#allcurrencies) by setting this value to `["**"]`

```js filename="example with glob"
permissions.currencies$ = ["**"],
```

#### permissions.methodIds$

- a list of methods a live app can call, corresponds to a [requestHandler's name](./wallet-api-server#requesthandlers)
- this list is also checked against when _SERVER -> APP_ communication is done (in [sendMessage](./wallet-api-server#sendmessage))

```js filename="example"
permissions.methodIds$ = [
  "account.request",
  "currency.list",
  "account.list",
  "transaction.signAndBroadcast",
  "transaction.sign",
  "message.sign",
  "account.receive",
  "wallet.capabilities",
  "storage.set",
  "storage.get",
  "wallet.userId",
  "wallet.info",
  "bitcoin.getXPub",
  "exchange.start",
  "exchange.complete",
];
```

---

### walletContext

#### walletContext.currencies$

The allowed currencies:

[allCurrencies](./wallet-api-server#allcurrencies) filtered against the currencies listed in [permissions.currencyIds](./wallet-api-server#permissionscurrencyids)

| Created via  | name | note                                                                                                                                                           |
| ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _observable_ |      | set in constructor, updates anytime `allAccounts` or `allowedCurrencies` changes, more info on how it does this using rxjs [here](./extras/rxjs#combinelatest) |

#### walletContext.accounts$

The allowed accounts:

[allAccounts](./wallet-api-server#allaccounts) filtered against the allowedCurrencies computed above

| Created via  | name | note                                                                                                                                                                         |
| ------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _observable_ |      | set in constructor, updates anytime `allAccounts` or `walletContext.allowedCurrencies` changes, more info on how it does this using rxjs [here](./extras/rxjs#combinelatest) |

#### walletContext.config

An object of this form

```js
ServerConfig = {
  userId: string; // used in internal handler wallet.userID
  tracking: boolean;
  appId: string; // used in internal handler storage.ts, to store data in this fashion: object[app.id]
  wallet: { // used in internal handler wallet.info
    name: string;
    version: string;
  };
};
```

| Created via   | name          |
| ------------- | ------------- |
| _constructor_ | **config**    |
| _setter_      | **setConfig** |

---

### transport

A transport protocol used to communicate with an application

Show diagram

![diagram](./assets/diagram-transport-1-light.png)

```js
type Transport = {
  // A function to handle messages coming from the application
  onMessage: MessageHandler

  // A function to send messages to the application
  send(message: string): void;
};

```

| Created via   | name          |
| ------------- | ------------- |
| _constructor_ | **transport** |

---

### requestHandlers

Show diagram

![diagram](./assets/diagram-request-handlers-2-light.png)

More on RpcRequest [here](./extras/rpc-node#rpc-requests).

A handler is a function of type `RPCHandler`

```js filename="packages/server/src/types.ts"
 type RPCHandler<TResult, TParam = unknown> = (
  request: RpcRequest<string, TParam>,
  context: WalletContext,
  handlers: Partial<WalletHandlers>,
) => Promisable<TResult>;

```

requestHandlers is an object of this type, mapping method ids (handlers name) to their RPCHandlers:

```js
{
 'handlerName': RPCHandler,
 'handlerName2': RPCHandler,
 'handlerName3': RPCHandler,
 ...
}
```

A default set of handlers will always be present, those are the `internalHandlers`.

> **Note:** You can find a comprehensive list of those internalHandlers
> [here](./handlers/account).

Additionally, you can pass `customHandlers` to the constructor.

To put it simply: `requestHandlers = internalHandlers + customHandlers {:js}`

| Created via   | name                  |
| ------------- | --------------------- |
| _constructor_ | **customHandlers**    |
| _setter_      | **setCustomHandlers** |

---

### walletHandlers

Show diagram

![diagram](./assets/diagram-wallet-handlers-1-light.png)

wallets using the wallet-api-server must implements this spec:
[https://github.com/LedgerHQ/wallet-api/blob/main/spec/rpc/README.md](https://github.com/LedgerHQ/wallet-api/blob/main/spec/rpc/README.md)

those functions will allow requestHandlers to interact with the wallet
most requestHandlers use one or more walletHandlers internally, to request / send data to the wallet
on top of that, request handlers will use permissions set above to filter out what's show / operated on (allowed accounts, allowed currencies)

| Created via | name            | note                                                    |
| ----------- | --------------- | ------------------------------------------------------- |
| _setter_    | **setHandler**  |                                                         |
| _setter_    | **setHandlers** | _sets in bulk, overriding all existing wallet handlers_ |

## methods

### handleMessage

A function to handle messages coming from the application

Used in conjonction with the transport property.

the `server.transport.onMessage` value is set to this function.

Parse json to either a [rpcRequest](./extras/rpc-node#rpc-requests) or rpcResponse object

Will then call `handleRpcRequest`

### handleRpcRequest

calls .onrequest, then creates an `RpcResponse` with the result and sends that
response back to the application (using `this.transport.send`)

### onRequest

call the appropriate [requestHandler](./wallet-api-server#requesthandlers) for that request

1. check if method exists by looking up [requestHandlers](./wallet-api-server#requesthandlers)
2. check if [permissions](./wallet-api-server#permissionsmethodids) allows for it to be called
3. calls it, with the following parameters :

- request ([RpcRequest](./extras/rpc-node#rpc-requests))
- [walletContext](./wallet-api-server#walletcontext)
- [walletHandlers](./wallet-api-server#wallethandlers)

### sendMessage

1. checks if it can send a message to the server by checking permissions.
2. then calls [notify](./wallet-api-server#notify)

## constructor

```js filename="packages/server/src/WalletAPIServer.ts"
class WalletAPIServer{
  constructor(
    transport: Transport,
    config: ServerConfig,
    logger = defaultLogger,
    customHandlers: CustomHandlers = {},
  ) {...}
}

```

| Parameter        | required? | note                                                                           |
| ---------------- | --------- | ------------------------------------------------------------------------------ |
| _transport_      | ✅         | sets the [transport](./wallet-api-server#transport)                            |
| _config_         | ✅         | sets the [walletContext.config](./wallet-api-server#walletcontextconfig) value |
| _logger_         | ❌         | (optional) sets the logger                                                     |
| _customHandlers_ | ❌         | (optional) sets [customHandlers](./wallet-api-server#walletcontextconfig)      |

> **Note:** It is how a WalletAPIServer is created in the example
> [here](./usage-examples/with-constructor)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/usage-examples/with-constructor -->

## Example usage of the walletAPIServer

Here's how you can instantiate a new `WalletAPIServer` using its [constructor](../wallet-api-server#constructor)

### instantiation

```ts {21}
const transport: Transport = {
  onMessage: undefined,
  send: (message: string) => {
    if (wapiView) {
      wapiView.webContents.postMessage("message", message);
    }
  },
};

const config = {
  appId: "fake-manifest-id", // should be the real manifest id, used in the storage handler code
  wallet: {
    name: "browserview-wallet",
    version: "0.1.0",
  },
  tracking: false,
  userId: "fake",
};

const wapiServer = new WalletAPIServer(transport, config);
```

two required arguments are passed, [transport](../wallet-api-server#transport) and [config](../wallet-api-server#walletcontextconfig).

### setup accounts, currencies and permissions via setters

```ts
wapiServer.setAccounts(accounts);
wapiServer.setCurrencies(currencies);
wapiServer.setPermissions({
  currencyIds: ["**"],
  methodIds: ["account.list", "account.receive", "account.request"],
});
```

Call setters to set the [accounts](../wallet-api-server#allaccounts),
[currencies](../wallet-api-server#allcurrencies),
and [permissions](../wallet-api-server#permissions)

### set wallet handlers

```ts
    wapiServer.setHandler("account.request", async ({ accounts$, currencies$ }) => {
      return new Promise((resolve, reject) => {
        uiAccountRequest({
          accounts$,
          currencies: currencies.map({id} => id),
          onSuccess: (account: AccountLike, parentAccount: Account | undefined) => {
            resolve(accountToWalletAPIAccount(account, parentAccount));
          },
          onCancel: () => {
            reject(new Error("Canceled by user"));
          },
        });
      });
    })

```

Set a [walletHandler](../wallet-api-server#wallethandlers) to handle
actions that would request an account from the wallet.

### wire up transport

```ts {3}
import { ipcMain } from "electron";
ipcMain.on("walletAPI:postMessage", (_, data) => {
  transport.onMessage?.(data);
});
```

Set up the transport's `onMessage` value, which will allow _APP -> SERVER_ communication.

More on transport [here](../wallet-api-server#transport).

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/server/usage-examples/within-ledger-live -->

> **Key takeaway:**  ☞   The renaming of "Ledger Live" to "Ledger Wallet" and\
>      "wallet" (in the hardware sense) to "signer" is still in progress.\
>      This page may contain legacy references that will be updated.

## Usage of the walletAPIServer in Ledger Wallet

The react hook [useWalletAPIServer](../wallet-api-server/react-hook)
is used within [Ledger Wallet](https://github.com/LedgerHQ/ledger-live/)
to create a walletAPIServer

It is used in _ledger-live-common_ here
**ledger-live-common/src/wallet-api/react.ts**\
In this file, a walletAPIServer
is created, and exposed through another hook (also called
`useWalletAPIServer`)

This (LLC hook) is in turn used in both
[LLD](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-desktop/src/renderer/components/Web3AppWebview/WalletAPIWebview.tsx#L10)
and [LLM](https://github.com/LedgerHQ/ledger-live/blob/43aeb2a1c650c6231c14149b74e4a42135b15766/apps/ledger-live-mobile/src/components/Web3AppWebview/helpers.ts#L8)

## useWebview()

### useWebView() gets called

Both LLD and LLM, when creating live apps, use the hook `useWebView`,
with the main arguments being:

- [manifest](../../appendix/manifest)
- [customHandlers](../wallet-api-server#requesthandlers)
- webviewRef

```ts filename="apps/ledger-live-desktop/src/renderer/components/Web3AppWebview/WalletAPIWebview.tsx"
const WalletAPIWebview => {
  ({ manifest customHandlers} ) => {
    const { webviewRef } = useWebviewState();

    useWebView({ manifest, customHandlers}, webviewRef);
    return <webview />
  }
};
```

### Prepares transport

Will allow communication with the webview.

```ts filename="simplified"
const webviewHook =  {
  return {
    postMessage: (message) => {
        webviewRef.current.contentWindow?.postMessage(message);
    },
  };
};
```

### Prepares uiHooks

They will allow walletHandlers to trigger ui actions

more on uiHooks

uiHooks are created in useWebView and sent to LLC useWalletAPIServer
`uiHook` is an object that maps a method like `"account.request"` to an action in LLD / LLM
here's a list of actions it triggers in LLD:

- opening a drawer to select an account, start an exchange process
- opening modals to sign transactions, messages, start an exchange process, connect a device
- store data / update account data
- display toaster

### LLC useWalletAPIServer() gets called

The goal of LLC's `useWalletAPIServer` is simply to call the walletAPIServer hook (also called `useWalletAPIServer`)

Before doing so it:

- Extracts [permissions](../wallet-api-server#permissions) From the manifest

- Converts accounts sent from [useWebView](./within-ledger-live#usewebview) (coming from redux store) to [a format readable by walletAPIServer](../wallet-api-server#allaccounts)

- Fetches and filters currencies (coming from `libs/ledger-live-common/src/currencies/helpers.ts` `listCurrencies`)

- Converts filtered currencies to a format readable by wallet-api-server. More on that format [here](../wallet-api-server/react-hook#currencies)

- Creates a [transport](../wallet-api-server#transport)

```js
function useTransport(postMessage: (message: string) => void | undefined): Transport {
  return useMemo(() => {
    return {
      onMessage: undefined,
      send: postMessage, // will allow WALLETAPISERVER -> LIVEAPP communication (via postMessage)
    };
  }, [postMessage]);
}

  const transport = useTransport(webviewHook.postMessage);
```

### walletAPIServer gets instantiated

via the react hook [useWalletAPIServer](../wallet-api-server/react-hook)

### post-instantiation transport setup

walletAPIServer sends back its `onMessage` callback, the webview will use
it to send message to it.

```ts {1,12-13, 20}
const { onMessage } = useWalletAPIServer({
  manifest,
  accounts,
  config,
  webviewHook,
  uiHook,
  customHandlers,
});

const handleMessage = useCallback(
  (event: Electron.IpcMessageEvent) => {
    if (event.channel === "webviewToParent") {
      onMessage(event.args[0]);
    }
  },
  [onMessage]
);

useEffect(() => {
  webviewRef.current.addEventListener("ipc-message", handleMessage);
}, [handleMessage, onLoad]);
```

### post-instantiation setup of wallet handlers

[server.setHandler](../wallet-api-server#wallethandlers) is called
to setup  Wallet/UI/Store callbacks.

Simplified example of setHandler() call

```js filename="libs/ledger-live-common/src/wallet-api/react.ts"
    server.setHandler("account.request", async ({ accounts$, currencies$ }) => {
      const currencies = await firstValueFrom(currencies$);
      return new Promise((resolve, reject) => {
        let currencyList = currencyList = allCurrenciesAndTokens.filter(({ id }) => currencyIds.includes(id));
        uiAccountRequest({
          accounts$,
          currencies: currencyList,
          onSuccess: (account: AccountLike, parentAccount: Account | undefined) => {
            resolve(accountToWalletAPIAccount(account, parentAccount));
          },
          onCancel: () => {
            reject(new Error("Canceled by user"));
          },
        });
      });
    });
  }, [manifest, server, tracking, uiAccountRequest]);
```

those handlers are saved in the property `WalletAPIServer.walletHandlers`

To recap:

- `WalletAPIServer.walletHandlers` -> callbacks defined in LLC, trigger modals / drawers / update redux store, etc.
- `WalletAPIServer.requestHandlers` -> internalHandlers + customHandlers, can call `walletHandlers` inside of them

```mermaid
flowchart TD
    A{LLD/LLM useWebView} -->|
    SENDS:

    manifest
    accounts
    uiHooks: so server can trigger LL ui
    webviewHook: so server can communicate TO the webview
    customHandlers
    | B{LLC useWalletAPIServer}
    B --> |
      GETS BACK:

      onMessage: so webview can communicate TO server
    |A
```

```mermaid
flowchart TD
    A{LLC useWalletAPIServer} -->|
    SENDS:

    transport: so server can communicate TO webview
    accounts
    currencies
    permissions
    customHandlers
    | B{wallet-api-server useWalletAPIServer}
    B --> |
      GETS BACK:

      server: WalletAPIServer, a RPC Node
      onMessage: so webview can communicate TO server
    |A
```

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/simulator/introduction -->

# Wallet API Simulator

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Simulator is a tool provided by Ledger that allows developers to test their application without interacting with the real  application.

It provides a mock environment with a set of predefined responses for different Wallet API actions.
This enables you to develop and test your application safely.

## Target audience

This documentation and the Wallet API library are dedicated to developers building Live Apps that are intended to be embedded within a wallet implementing the Wallet API Server like [Ledger Wallet](https://www.ledger.com/ledger-live).

## Overview

The  API Simulator library empowers you to:

- **Easily develop your Live App in the browser**: Establish a fake connection to the Simulator acting as a wallet implementing the  API Server, like  would do.

- **Test in more ways**: The simulator facilitate writing E2E, integration or unit tests, by allowing mocking any data used.

- **Simulate errors that are hard to reproduce**: Just like you can write tests for the good path, you should also test your error handling code.

## Navigating the documentation

This documentation is structured to provide you with a clear understanding of the various features and utilities available in the  API Simulator library.

- **Usage**: Start with the [Usage](./usage.mdx) section. It guides you through installation and configuration, and how to add the simulator to your Live App.

- **Profiles**: Learn about the various [Profiles](./profiles.mdx) we export for use with the simulator, as well as utilities to customize the profiles.

We're thrilled to have you on board and excited to see the innovative Live Apps you build.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/simulator/profiles -->

# Understanding the Simulator Profiles

The Simulator provides different profiles. These profiles are predefined sets of responses for various API actions.
For now, we recommend that you use `profiles.STANDARD` which includes a set of mock accounts, mock currencies, and method handlers.

## Mock Accounts and Currencies

The Simulator is set up with a predefined list of mock accounts and currencies. Here’s a brief overview of the mock accounts and currencies used within the simulator:

## Mock Accounts

```json
[
  {
    "id": "account-btc-1",
    "name": "Bitcoin 1",
    "address": "address",
    "currency": "bitcoin",
    "balance": "42",
    "spendableBalance": "42",
    "blockHeight": 1,
    "lastSyncDate": "1995-12-17T03:24:00"
  },
  {
    "id": "account-eth-1",
    "name": "Ethereum 1",
    "address": "address",
    "currency": "ethereum",
    "balance": "42",
    "spendableBalance": "42",
    "blockHeight": 1,
    "lastSyncDate": "1995-12-17T03:24:00"
  }
]
```

## Mock Currencies

```json
[
  {
    "type": "CryptoCurrency",
    "id": "bitcoin",
    "ticker": "BTC",
    "name": "Bitcoin",
    "family": "bitcoin",
    "color": "#ffae35",
    "decimals": 8
  },
  {
    "type": "CryptoCurrency",
    "id": "ethereum",
    "ticker": "ETH",
    "name": "Ethereum",
    "family": "ethereum",
    "color": "#0ebdcd",
    "decimals": 18
  }
]
```

These mock accounts and currencies are used to emulate a realistic  environment. You can interact with these accounts and currencies through the API without affecting any real-world assets.

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/integration/wallet-api/simulator/usage -->

# Use Wallet API Simulator to develop a Live App

## Overview

This guide shows how to use the `@ledgerhq/wallet-api-simulator` to develop and test your Live App from any browser, without launching it inside .

Outcome:

- Install the Simulator
- Configure your app to connect to the Simulator via `TransportProvider`
- Run your Live App in a browser

## Prerequisites

- A React app (or similar) where you can wrap a root component
- Access to your `TransportProvider.tsx` (or equivalent) and root file
- Node.js with npm, yarn, or pnpm

## Installation

Install the base package with your preferred package manager:

```sh npm2yarn
npm install @ledgerhq/wallet-api-simulator
```

## Step 1 — Launch Live App from Browser

One of the benefits of using the Simulator is that it allows developers to launch their Live App from any browser, without the need to launch it from within . This greatly simplifies development and testing by removing the dependency on the  application.

## Step 2 — Connect to the Simulator

Modify your `TransportProvider.tsx` to use the Simulator transport. Use the `getSimulatorTransport` function with a predefined profile (e.g., `profiles.STANDARD`).

```jsx
import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react";
import {
  getSimulatorTransport,
  profiles,
} from "@ledgerhq/wallet-api-simulator";
import type { Transport } from "@ledgerhq/wallet-api-core";

function TransportProvider({ children }) {
  function getWalletAPITransport(): Transport {
    if (typeof window === "undefined") {
      return {
        onMessage: undefined,
        send: () => {},
      };
    }

    // Use Simulator transport
    const transport = getSimulatorTransport(profiles.STANDARD);

    return transport;
  }

  const transport = getWalletAPITransport();

  return (
    <WalletAPIProvider transport={transport}>{children}</WalletAPIProvider>
  );
}

export default TransportProvider;
```

What’s happening:

- We import the necessary components and types from the  API packages.
- `TransportProvider` renders its children inside `WalletAPIProvider`.
- `getWalletAPITransport` returns a transport for the provider. If `window` is not available (SSR), it returns an empty transport.
- When `window` is available, it uses `getSimulatorTransport(profiles.STANDARD)` to communicate with the  API via the Simulator.

## Step 3 — Wrap your application

Wrap your root `<App />` with `TransportProvider`:

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import TransportProvider from './TransportProvider';

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <TransportProvider>
      <App />
    </TransportProvider>
  </React.StrictMode>
);
```

With this setup, the entire application can access the  API through the Simulator.

## Next steps

You are now almost ready to use the Wallet API's functionalities. The last step is to make your Live App ready to be registered by creating your manifest. Learn how to create your manifest: [how to create your manifest](../examples/use-live-app)

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/references/developer-mode -->

# Enabling the developer mode

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

To activate the Developer mode in , go to the **Settings/About** section, and click ten times on the  version.

This will make the Developer tab appear.

![screenshot of the Developer tab](/discover/developer_mode_tab.png "Developer tab")

Note : this feature is available only for  version 2.32 and above.

This new section will give you access to the following content :

- **Allow debug apps** : Display and allow opening debug tagged platform apps.
- **Allow experimental apps** : Display and allow opening experimental tagged platform apps.
- **Set the catalog provider** : Switch between multiple platform apps sources (Production of Staging).
- **Enable platform dev tools** : Enable opening platform apps dev tools window.
- **Add a local app** : Browse local files and add a local app using a local manifest.

We’ll dive into each section to describe how they work.

## Allow debug apps

This setting, when enabled, will display and allow opening “debug” tagged platform apps.
The first debug tagged platform app you will now see appear in the Discover section will be the Debugger. This app has been designed by Ledger to specifically allow you to test the API and understand how it works.

## Allow experimental apps

This setting, when enabled, will display and allow opening “experimental” tagged platform apps.
As long as an application hasn’t been reviewed and approved by Ledger, it can only remain experimental.

## Set the catalog provider

The catalog provider is a variable used to define the list of applications being displayed in the discover section. Ledger uses two lists of applications, those in staging (currently being tested), and those in production (validated already, and usually available to all our users).

## Enable Platform dev tools

This setting will enable opening the platform apps dev tools window, which can become handy when debugging your application.

![screenshot of the Platform dev tools](/discover/platform_dev_tools.png "Developer tools window")

## Adding a Local App to Ledger Wallet

You can add a local app to  by importing a local manifest file. This allows you to independently test your application before it's officially available. Follow these steps to enable Developer Mode and import your manifest:

### 1. Install Ledger Wallet Desktop

Ensure that  Desktop is installed on your computer. If you haven’t installed it yet, download it from the [official Ledger website](https://www.ledger.com/ledger-live). You will also need a Ledger device to access .

### 2. Enable Developer Mode

To enable Developer Mode in , follow the steps described in the section above in this document.

Once activated, a **Developer** section will appear in the settings menu.

### 3. Enable Developer Tools

In the Developer section, turn on **Enable platform dev tools**. This will provide access to developer tools, allowing you to inspect and debug your app.

### 4. Import Your Manifest File

- In the Developer section, locate the **Add a local app** option.
- Click **Browse** and select the manifest file you created earlier.

After importing, your app will appear in the menu under its designated name.

## Loading manifest on mobile phone with localhost

To successfully load a manifest on a mobile phone using localhost, follow the steps below:

### Method 1:

**Step 1: Retrieve Your Local IP Address**
To access your local IP address, open your terminal and run the following command:

- If you have a UNIX-based development machine, run:
  ```sh
  ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}'
  ```
- If you have a Windows machine, run:
  ```sh
  ipconfig
  ```

**Step 2: Update the Manifest**
Locate your manifest file and replace all occurrences of `localhost` with the IP address retrieved in Step 1. This step ensures that your mobile phone can resolve the correct endpoint when accessing the manifest.

**Step 3: Network Configuration**
Ensure that both your mobile phone (e.g., your phone) and your development machine (e.g., your laptop) are connected to the same Wi-Fi network. Note the following:

- Devices must be on the same frequency band. For example, if you have a 2.4 GHz network and a 5 GHz network, both devices must connect to the same frequency.

**Step 4: Load the Manifest**
With the updated manifest and correct network configuration:

1. Open your mobile phone's browser or app that loads the manifest.
2. Navigate to the manifest's URL, replacing `localhost` with the IP address you used in the manifest file.

   **Example:** If your IP address is `192.168.1.10` and the manifest URL was `http://localhost:3000`, update it to `http://192.168.1.10:3000`.

**Make sure your `domains` field includes `http://` otherwise the connection will fail**

If you encounter issues, verify the devices' network connection and ensure no firewall or router settings are blocking access.

Some tools may cache previous configurations. Restart your development environment or mobile phone if changes do not take effect immediately.

### Method 2:

1. Use a service such as **NGROK** or **LocalTunnel**.
2. Obtain a URL from your service of choice.
3. Replace all occurrences of `localhost` in the manifest file with the obtained URL from the service of your choice.
4. Load the manifest.

## Disabling the developer mode

If you want to disable the developer mode, you will need to uninstall and reinstall .

---

<!-- https://developers.ledger.com/docs/ledger-live/discover/references/manifest -->

---
title: Live app manifest reference
category: reference
---

# Live app manifest

## Example for the “Lido” application:

```json copy
{
  "id": "lido",
  "name": "Lido",
  "url": "https://stake.lido.fi/?embed=true",
  "dapp": {
    "nanoApp": "Lido",
    "networks": [
      {
        "currency": "ethereum",
        "chainID": 1,
        "nodeURL": "https://eth-dapps.api.live.ledger.com"
      },
      {
        "currency": "bsc",
        "chainID": 56,
        "nodeURL": "https://bsc-dataseed.binance.org/"
      },
      {
        "currency": "polygon",
        "chainID": 137,
        "nodeURL": "https://polygon-mainnet.g.alchemy.com/v2/xxx"
      },
      {
        "currency": "arbitrum",
        "chainID": 42161,
        "nodeURL": "https://arb1.arbitrum.io/rpc"
      },
      {
        "currency": "optimism",
        "chainID": 10,
        "nodeURL": "https://mainnet.optimism.io"
      }
    ]
  },
  "homepageUrl": "https://lido.fi/",
  "icon": "https://cdn.live.ledger.com/icons/platform/lido.png",
  "platform": "all",
  "apiVersion": "^2.0.0",
  "manifestVersion": "2",
  "branch": "stable",
  "categories": ["staking", "defi"],
  "currencies": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"],
  "content": {
    "shortDescription": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    },
    "description": {
      "en": "Stake your ETH with Lido to earn daily staking rewards."
    }
  },
  "permissions": [],
  "domains": ["https://"]
}
```

## List of the mandatory fields required in the Manifest file

| Field             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          | Type         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `id`              | The identification of your application. Must be in lowercase.                                                                                                                                                                                                                                                                                                                                                                                        | String       |
| `name`            | The name of your application ("Lido" in this example).                                                                                                                                                                                                                                                                                                                                                                                               | String       |
| `url`             | The url of your dApp, either running locally or at the production version                                                                                                                                                                                                                                                                                                                                                                            | String       |
| `dapp`            | `nanoApp` is [the plugin](../../../device-app/explanation/plugin/) needed to clear sign your dApp, if your dApp doesn't require a plugin set the value to Ethereum `networks` is the list of networks supported by your dApp,  currently supports mainnet, BSC, Arbitrum, Optimism, Base, Fantom, and Polygon. In production, Ledger overrides `nodeURL` with the approved node for your dApp. Use your own endpoint during development and testing. | Object       |
| `homepageUrl`     | For information only. Not required for the app to load. For instance, "[https://lido.fi/](https://lido.fi/)".                                                                                                                                                                                                                                                                                                                                        | String       |
| `icon`            | A link to the icon displayed in the Discover Section of . Will be hosted on Ledger CDN before being released in production.                                                                                                                                                                                                                                                                                                                          | URL          |
| `platform`        | To set the platform (desktop, mobile, iOS, Android) on which your service is available. By default, you should set the value to "all".                                                                                                                                                                                                                                                                                                               | String       |
| `apiVersion`      | The API version. By default "^2.0.0".                                                                                                                                                                                                                                                                                                                                                                                                                | String       |
| `manifestVersion` | The manifest version. By default should be "2".                                                                                                                                                                                                                                                                                                                                                                                                      | String       |
| `branch`          | The specific branch used by Ledger to deploy the changes. Can take the values stable `experimental`, `debug`, `soon`. By default, you should set it to `stable`. The value `soon` will mark your app as "Coming soon" and it won't be usable.                                                                                                                                                                                                        | String       |
| `categories`      | A JSON array of metadata information about your application. For instance: \["staking","defi" ]. You can add as many as you want. It is not used for the moment but will be used for filtering in the future.                                                                                                                                                                                                                                        | List(string) |
| `currencies`      | A JSON array of the currency/network being used by your application. For instance \["ethereum",”polygon”]. Leave blank if the App does not require any currency.                                                                                                                                                                                                                                                                                     | List(string) |
| `content`         | A description of your service. It will be displayed on the entry card of your application.                                                                                                                                                                                                                                                                                                                                                           | L18n strings |
| `permissions`     | Leave empty for now.                                                                                                                                                                                                                                                                                                                                                                                                                                 | List(string) |
| `domains`         | List of allowed domains to navigate to, if a domain doesn't match it will open in the default browser. By default \["http\://", "https\://"]                                                                                                                                                                                                                                                                                                         | List(string) |

## Related

- [Load a local app in developer mode](./developer-mode) — how to add and test a manifest locally before publishing
- [DApp browser integration guide](../integration/dapp-browser) — full walkthrough for embedding a dApp in Ledger Wallet
- [Live app catalog schema](https://live-app-catalog.ledger.com/schema.json) — JSON schema reference for manifest validation

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy/architecture -->

# Overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The integration process ensures a seamless flow of data between , Ledger Backend, and the provider's systems. Providers are expected to implement specific endpoints and adhere to the following workflow to support the Buy feature in .

## Workflow Diagram

```mermaid
sequenceDiagram
    participant User
    participant LedgerLive as Ledger Wallet
    participant LedgerBackend as Ledger Backend
    participant ProviderBackend as Provider Backend
    participant ProviderWidget as Provider Widget App
    participant ExchangeSDK as Exchange SDK

    %% Step 1: Open Buy App
    User->>LedgerLive: Open Buy App
    LedgerLive->>LedgerBackend: [GET] /providers
    LedgerBackend->>ProviderBackend: [GET] /capabilities (Cached)
    ProviderBackend-->>LedgerBackend: Return capabilities data
    LedgerBackend->>ProviderBackend: [GET] /crypto-currencies (Cached)
    ProviderBackend-->>LedgerBackend: Return supported crypto assets
    LedgerBackend-->>LedgerLive: Return providers list and capabilities

    %% Step 2: User Input and Validation
    User->>LedgerLive: Select crypto, fiat, amount
    LedgerLive-->>User: Validate input using cached /capabilities
    User->>LedgerLive: Proceed with valid input
    LedgerLive-->>User: Display countries and payment methods based on /capabilities
    User->>LedgerLive: Select country and payment method
    
    %% Step 3: Select Provider and Get Quotes
    LedgerLive->>LedgerBackend: [GET] /onRamp Find eligible providers
    LedgerBackend->>ProviderBackend: [GET] /quotes
    ProviderBackend-->>LedgerBackend: Return quotes
    LedgerBackend-->>LedgerLive: Return providers and quotes
    User->>LedgerLive: Choose provider

    %% Step 4: Redirect to Provider Widget
    LedgerLive->>ProviderWidget: Redirect with parameters (LiveApp URL)
    User->>ProviderWidget: KYC process, if required, and landing in step transaction in provider widget.
```

### Step 1: Open Buy App

Action: The user opens the Buy App in .

Ledger Wallet:

- Fetches capabilities data from the Ledger Backend, which caches responses from the provider's [/capabilities](./redoc-api#operation/getCapabilities) endpoint.

- Fetches supported cryptocurrencies from the Ledger Backend, which caches responses from the provider's [/crypto-currencies](./redoc-api#operation/getCryptoCurrencies) endpoint.

### Step 2: User Input and Validation

User Interaction: The user selects the cryptocurrency, fiat currency, and the amount they wish to buy.

User Interaction: The user selects their country and preferred payment method (e.g., PayPal, bank transfer).

Validation Process:  validates user input.
Validation is performed using cached data from [/capabilities](./redoc-api#operation/getCapabilities), ensuring the user's input aligns with provider-supported limitations (e.g., minimum/maximum amounts, supported countries).

If the input is invalid,  displays an error message to the user.

### Step 3: Get Quotes and Select Provider

User Interaction: User request quote.

Backend Process: Ledger Backend identifies eligible providers based on the user's input.

For each eligible provider, the Ledger Backend sends a \[GET] [/quotes](./redoc-api#operation/getQuote) request to the provider backend to retrieve pricing details (e.g., the amount of fiat currency the user will receive after fees).

The provider backend returns quotes, which are aggregated by the Ledger Backend and displayed in .

User Decision: The user selects a provider from the list of quotes.

### Step 4: Redirect to Provider Widget

Action: Once a provider is selected,  redirects the user to the provider's widget.

Redirection Details: The redirection includes required parameters as specified in the [LiveApp URL documentation](../buy/providers-liveapp), such as the selected cryptocurrency, fiat currency, amount, and user-specific details.

The user lands on the provider widget to complete the transaction details.

### Step 5: Initiate Transaction

Provider Widget Interaction: The user finishes the transaction in the provider widget and providers sends funds to user wallet.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy/providers-backend -->

# Backend

## Endpoints needed for Buy

In order to communicate with Ledger’s backend, you must provide standardised APIs for Ledger's Buy aggregator services to call.

> **Note:** You will find all the information regarding the Buy endpoints [here](./redoc-api).

There are 4 endpoints needed for the Buy integration:

- To get the list of available fiat, country, payment, method and amount: [/capabilities](./redoc-api#operation/getCapabilities).
- To get the list of available crypto-currencies: [/crypto-currenciess](./redoc-api#operation/getCrypto-currencies).
- To get the crypto amount that the user should expect -after all fees are deducted - as a payment for the given fiat amount: [/quotes](./redoc-api#operation/getQuote).
- To get the URL of the on-ramp widget to which the user will be redirected. [/buy-redirect](./redoc-api#operation/buy-redirect).

### Ledger IDs mapping

To comply with our integration policies, the LedgerId format must be used (by your `/crypto-currencies` endpoint) and accepted (by your `/quote` endpoint and widgetURL) to accurately identify tokens and coins.

You can refer to [this API](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name) to obtain ledger IDs. You can use the `search` parameter to find a specific coin or token. For instance, to search for USDT, you can use this [request](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name\&search=USDT). The API returns paginated results: to access the next pages, include `cursor=<value of the "X-Ledger-Next" header>` in your request. Further information is available in the response headers.

Example: let's say your support AAVE on Ethereum mainnet. The LedgerID for AAVE on Ethereum is `ethereum/erc20/aave` (as we can see [here](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name\&search=AAVE)). This means:

- Your `/crypto-currencies` endpoint must include `ethereum/erc20/aave` in its response (along with the other coins/tokens you support), so we know that you support AAVE on Ethereum.
- Your `/quote` endpoint must accept `ethereum/erc20/aave` as a value for the `to` parameter.
- Your widgetURL must accept `ethereum/erc20/aave` as a value for the `to` parameter.

[//]: # "Info needed to be exchange with the provider, but not out loud publicly"

[//]: # "**IP address checking** "

[//]: # "Additionally, we also need a way to know if a user will be able to perform a coin swap given his IP."

[//]: # "Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user’s IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected."

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy/providers-how-to-test -->

---
title: Test your Buy integration
category: how-to
description: How to test your Buy provider integration in Ledger Wallet before releasing to production.
---

# How to test your Buy integration

> **Key takeaway:** ☞   The transition from "Ledger Live" to "Ledger Wallet" and from "wallet" (for the hardware product) to "signer" is still in progress. This page may contain legacy terms that will be updated.

This guide shows you how to test your Buy provider integration in . Complete this final step before deploying your Buy widget to Ledger Wallet's production environment.

Test these three flows on desktop, iOS, and Android:

1. New user flow (registration)
2. Returning user flow (sign-in)
3. **Buy again** flow, which appears on the initial Buy screen in  after you initiate a purchase

## Before you start

Complete these steps before running the flows below:

- [Backend integration guide](./providers-liveapp-technical-requirements) — server-side integration
- [LiveApp guide](./providers-liveapp) — building and publishing the LiveApp
- [Load a manifest in developer mode](../../../discover/references/developer-mode) — how to add a local app

## Prerequisites for testing

- **Technical integration**: Complete the backend and LiveApp integration steps linked above.
- **Accounts in Ledger Wallet**: To start and complete a purchase, you need accounts in , such as Bitcoin or Ethereum accounts. You need a Ledger signer to set up these accounts.
- **Authentication and payment methods**: Use your own KYC-verified account and payment methods to run real transactions in your widget.

## Test in your own environment

Test your LiveApp in different environments to check how it works in . Ledger Wallet uses a manifest, which is a JSON configuration file, to load an embedded LiveApp with specific parameters.

Set these two manifest attributes to switch the widget environment, such as to localhost or staging:

- `providerTestId`: Specifies the provider to test. After you set this value, the Buy/Sell section displays only that provider. Contact Ledger if you do not know your provider ID.
- `providerTestBaseUrl`: Sets the base URL for the environment, such as `http://localhost:3000/buy` or `https://provider.staging`.

After you add these attributes,  replaces the LiveApp's base URL with the specified `providerTestBaseUrl`.

**Example:**

Original LiveApp URL loaded in Ledger Wallet:

```
https://yourwidget.com?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop
```

LiveApp URL after you load the `buy-sell-ui` manifest locally with `"providerTestId"` and `"providerTestBaseUrl"`:

```
http://providerTestBaseUrl?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop
```

Your test environment must accept the query string parameters that  generates for your widget. You cannot modify these parameters with `providerTestBaseUrl` because Ledger Wallet's backend generates some of them. This behavior lets you test the actual flow in your local environment.

To test the flow:

1. Obtain the manifest from Ledger. Before loading it in , add the `"providerTestId"` and `"providerTestBaseUrl"` attributes described above. Follow [Add a local app](https://developers.ledger.com/docs/ledger-live/discover/references/developer-mode) to load the manifest.
2. Open the **Buy/Sell** section. The list of available providers displays only the provider specified by `"providerTestId"`.
3. Select the provider.  opens the URL specified by `"providerTestBaseUrl"`.

## Test in pre-production

You must also test in **Ledger Wallet's pre-production environment**, which uses your production keys and endpoints. Run real transactions to test the integration under real-world conditions.

Ledger will provide a manifest that connects the **Buy/Sell** section to the pre-production environment. Load this manifest in  without modifying it. This configuration directs users to your widget's actual URL.

## What to test

### UX requirements

- **Non-editable wallet address**: Confirm that the review page shows the wallet address before the user completes the transaction and that the address is not editable.
- **Persistent session**: Confirm that users remain signed in to your widget after closing and reopening either the widget or .
- **Dark and light modes**: Confirm that your widget automatically adjusts its layout, if available, to match the user's selected theme in .
- **Automatic payment method selection**: Confirm that the widget automatically selects the payment method that the user chose in .
- **Responsive LiveApp**: Confirm that your widget adjusts its layout to fit mobile screens.

### Authentication and account creation

- **New account creation**: Complete the full account creation process in your widget within . Confirm that each step works, including KYC steps that use the device's camera or file upload feature.
- **Sign-in**: Confirm that you can sign in to and out of your widget within . The session must persist so that users do not need to sign in each time they open the widget.

### Transactions

- **Quote accuracy**: Confirm that the quotes shown in  match those in your widget, including all fees.
- **Buy transaction**: Perform real transactions using as many supported blockchains as possible, along with various fiat currencies and payment methods. Confirm each transaction and verify on-chain that the funds reach the expected  address.
- **Buy again transaction**: After you initiate a purchase in  with your provider, confirm that the **Buy again with** button appears on the initial Buy screen and that the flow works as expected.

## Next steps

After you complete the tests, share your results with Ledger. We will evaluate each potential issue, prioritize it, and implement the appropriate fixes.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Buy Integration](../buy) section, you need to modify your LiveApp to recognize the parameters we are passing to you, with some particularities compared to the version found in the Discover section.

Your LiveApp must:

- Respond to specific LiveApp URLs to adapt to the flow inside .
- Follow specific flow/UX requirements:

![Buy transaction flow](/exchange/buy-liveapp-flow.png)

## LiveApp URL

The LiveApp needs to respond to a URL with certain parameters. LiveApp URLs are used to open your LiveApp with the quote values that the user has already entered in .

- `accountAddress`: Destination address to deposit the crypto.
- `cryptoCurrency`: The cryptocurrency that the user wants to buy. It will contain the [LedgerID](https://developers.ledger.com/docs/ledger-live/exchange/buy/providers-backend#ledger-ids-mapping) value to identify the crypto.
- `fiatCurrency`: The fiat currency that the user wants to spend.
- `fiatAmount`: The fiat amount that the user wants to spend.
- `cryptoAmount`: The crypto amount that the user wants to buy.
- `mode`: `buy` or `sell`. In this case, always `buy`. It's required that you share the same base widget URL for both usages.
- `paymentMethod`: The preferred payment method of the user.
- `bankResidency` (optional): The bank residency of the user.
- `buySessionid`: ID used by Ledger to track transactions and their completion statuses.
- `language`: The language preference of the user set in .
- `theme`: The theme preference of the user set in .
- `platform`: The platform used by the user (mobile/desktop).

**Example**:

```
https://buy.provider.widget.com?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionid]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permissions

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contain at least the following [permissions](../../../../docs/discover/wallet-api/appendix/manifest#permissions) request:

```json
"permissions": [
  "currency.list",
  "account.list",
  "account.receive"
]
```

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy/redoc-api -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/buy -->

---
title: Buy integration overview
category: explanation
---

# Buy integration overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Buy integration lets users purchase crypto assets with fiat currency directly inside , without leaving the wallet. As a Buy provider, you supply the quoting, payment processing, and order fulfilment; Ledger supplies the secure, device-verified receive address and the embedded LiveApp experience.

To become a native Buy provider, you need to deliver three things:

1. **Backend API**: adapt your existing API to the Ledger Buy API specification so that Ledger's backend can request quotes and forward orders to your service.
2. **LiveApp**: a web application that loads inside  and gives users a buy flow. It receives the quote the user entered in the wallet as query parameters, so the user lands directly on a pre-filled checkout. You also need to write or update your LiveApp manifest and follow Ledger's UX requirements.
3. **Testing and submission**: test the full integration end-to-end using Developer Mode in , then submit your API and manifest for Ledger review.

> **Note:** Each step can be worked on in parallel. The integration only goes live once all three have passed review.

## What to read next

- [Architecture](buy/architecture) — flow overview showing how the components interact
- [Backend](buy/providers-backend) — the API endpoints your service must expose
- [LiveApp](buy/providers-liveapp) — LiveApp URL format, manifest requirements, and UX guidelines
- [Test & Submit](buy/providers-test-and-submit) — how to test end-to-end with Developer Mode and submit for review

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/fund-card/code-examples -->

---
title: Card fund code examples
category: reference
---

# Card fund code examples

This page shows how to implement the payload-signing routine described in [Payload & Signature](./providers-backend#payload--signature). Each example signs a payload with your Card fund provider private key using ES256 over the secp256k1 curve, then base64Url-encodes the result to produce the `signature` field your response must include.

The three examples below are equivalent implementations in Java, Python, and TypeScript. Pick the one that matches your backend stack; the signing steps are the same in each case.

> **Note:** Each snippet expects a `response` protobuf message (or an already-encoded payload) and your provider's private key. Replace the placeholder key path or value with the location of your own key.

## Cross-references

- [Backend](./providers-backend): the endpoints that consume this signature, and the payload format it signs
- [API reference](../redoc-api): full request and response schemas for the Card endpoints

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/fund-card/providers-backend -->

# Backend

## Endpoints needed for Card

In order to communicate with Ledger’s backend, you must provide standardised APIs for Ledger's CARD aggregator services to call.

> **Note:** You will find all the information regarding the CARD endpoints [here](../redoc-api), as well as additional details on some endpoints below.

You need to implement following endpoint for the card: - To create a signed fund binary payload: [/sell](../redoc-api#operation/postSell).

Additional Details: POST /sell

Example request payload:

```json copy
{
  "quoteId": "string",
  "amount": "string",
  "refundAddress": "string",
  "fromCryptoCurrency": "string",
  "payloadCryptoCurrency": "string",
  "nonce": "number"
}
```

An example response from the your backend to the Ledger backend

```json copy
{
  "sellId": "SELL-ID-165940",
  "payinAddress": "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48",
  "createdAt": "2030-05-26T14:13:39",
  "providerFees": "0.0001",
  "referralFees": "0.0001",
  "payoutNetworkFees": "0.0002",
  "providerSig": {
    "payload": "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==",
    "signature": "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs="
  }
}
```

Your Protobuf message should have the following structure:

```go copy
message NewFundResponse {
  string   user_id = 1;                
  string   account_name = 2;           
  string   in_currency = 3;            
  bytes    in_amount = 4;              
  string   in_address = 5;             
  bytes    device_transaction_id = 6;
  string   in_extra_id = 7;            // memo
}
```

`in_amount` amount must be in the lowest unit of the coin, encoded into a 16 bytes array in big endian.

- 1 **BTC** would be `0x5F5E100` (100000000 in hexadecimal). The smallest unit is a **satoshi** which is `10^-8` **BTC**.
  So multiply 1 **BTC** by `10^8` → `0x5F5E100`.
  And `0x5F5E100` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x05, 0xF5, 0xE1, 0x00]`.
- 2 **ETH** would be `0x1BC16D674EC80000` (or 2000000000000000000). The smallest unit is a **wei** which is `10^-18` **ETH**.
  So multiply 2 **ETH** by `10^18` → `0x1BC16D674EC80000`.
  And `0x1BC16D674EC80000` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x1B, 0xC1, 0x6D, 0x67, 0x4E, 0xC8, 0x00, 0x00]`.

## Real-time Status Updates:

To ensure effective communication with Ledger's backend, you are required to implement a webhook [/transaction/\{sellId}/status](../redoc-api#operation/statusUpdate) update mechanism. This should notify Ledger in real-time whenever there is a change in the status of a transaction.
Ledger will provide a webhook URL for status updates, partners can then send updates by calling this provided endpoint.

Additional Details: POST /transaction/\{sellId}/status
Explanation of the different output `status`:

- `FINISHED`: Trade has been completed successfully (user has received payout transaction).
- `EXPIRED`: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
- `ON_HOLD`: Trade has been put on hold (eg: for KYC reasons). User must contact support.
- `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction)
- `TRANSFER_IN_COMPLETED`: Transfer in completed and waiting for transfer out to be sent.
- `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
- `UNKNOWN`: Trade is in unknown state. User must contact support.

Additionally, if your backend needs to know the transaction status from our system (e.g., whether the transaction was approved or rejected by the user’s device), we provide an optional endpoint [/transaction/\{sellId}/status](../redoc-api#operation/getStatusUpdate).

[//]: # "Info needed to be exchange with the provider, but not out loud publicly"

[//]: # "**IP address checking** "

[//]: # "Additionally, we also need a way to know if a user will be able to perform a coin sell given his IP."

[//]: # "Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user’s IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected."

## Payload & Signature

Here is a little diagram to explain how the `payload` and the `signature` are generated:

![Payload and Payload Signature generation diagram](/exchange/payload-signature-generation-sell.png)

- `payload`: the trade parameters are assembled in a [protobuf](https://developers.google.com/protocol-buffers) message. This message is [binary encoded](https://developers.google.com/protocol-buffers/docs/encoding) to produce a Byte Array. This Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), resulting `payload` field.
- `signature`: The payload is signed using [ES256](https://ldapwiki.com/wiki/Wiki.jsp?page=ES256) provider's private key, generating a Byte Array. This Signature Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), producing the Signature field. ([more details](#jws-signature)).

If you need help with the signing process, please refer to our code [examples](code-examples.mdx).

### Generate Private/Public Key

1. **Private Key**:
   Use the following command to generate the private key:

   ```bash
   openssl ecparam -name secp256k1 -genkey -noout -out sample-priv-key-secp256k1.pem
   ```

2. **Public Key**:
   Derive the public key from the private key using the command:
   ```bash
   openssl ec -in sample-priv-key-secp256k1.pem -pubout > sample-pub-key-secp256k1.pem
   ```

### Verify Key Information

To inspect the contents of the private key file:

```bash
openssl ec -text -in sample-priv-key-secp256k1.pem
```

Repeat this process for both the **production** and **test** environments to generate two distinct key pairs.

### Signature usage

- Payload and Signature\
  From the provider to . The payload is a protobuf message containing the trade data. It is generated by the provider and sent to .

```go copy
type Payload struct {
  user_id,
  account_name,
  in_currency,
  in_amount,
  in_address,
  device_transaction_id,
  in_extra_id
}
R, S := Sign(payload, privKey)
```

- Validate\
  Exchange app checks and validates the payload (signature and content).

```go copy
// Compare nonce in payload
Verify((R, S), payload, pubKey)
```

- Display\
  Exchange app requests approval to the user by displaying the operation summary on screen.

```c copy
Validate?
Send currency_from amount_to_provider
Receive currency_to amount_to_wallet
```

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/fund-card/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Card Integration](../../card) page, you need to modify your LiveApp with some specific adjustments compared to the one found in the Discover section.

Your LiveApp must:

- Use the Ledger's [exchangeSDK](https://github.com/LedgerHQ/exchange-sdk), in addition to the Wallet API.
- Have a modified, slightly more complex, Manifest file.
- Follow specific flow/ux requirements.

## Ledger Exchange Services Kit

To learn how to create (or embed if already existing) your user interface for the card, please follow the [Discover documentation](../../discover/getting-started).

Your LiveApp will interact with , through the [ExchangeSDK](https://github.com/LedgerHQ/exchange-sdk), with the corresponding method.

You will need to set up the SDK with your `providerId` attributed upon request by Ledger.

```js copy
const exchangeSDK = new ExchangeSDK("yourProviderId");
```

### CARD method

This method will need you to provide the following parameters:

- `orderId`: The id coming from your system.
- `fromAccountId`: User's Ledger account id.
- `fromAmount`: Amount that will be sold.
- `customFeeConfig`: Custom fee configuration in case the strategy is of type `CUSTOM`. The key-value object is encoded in URI parameter.

```js copy
exchangeSDK.fund({
  orderId: "123abc",
  fromAccountId: "97f06be9-6fb2-5da3-be71-4e762ed6e115",
  fromAmount: BigNumber,
  type: "card",
  feeStrategy?: `SLOW`, `MEDIUM`, `FAST` or `CUSTOM`,
  customFeeConfig?: { [key: string]: BigNumber }, (optional, required for `CUSTOM` feeStrategy):
});
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permission

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contains at least those permissions request:

```json copy
"permissions": [
  "account.list",
  "currency.list",
  "custom.exchange.start",
  "custom.exchange.complete",
  "custom.exchange.error",
]
```

## Tracking Events

The ExchangeSDK includes tracking capabilities for fund card operations.

### Page View

**Trigger:** Page viewed

| Property | Type   | Required | Description | Example          |
| -------- | ------ | -------- | ----------- | ---------------- |
| `page`   | string | yes      | Page name   | `"introduction"` |

```js copy
exchangeSDK.tracking.trackPage("introduction", {
  some: "param",
});
```

### Event: button\_clicked

**Trigger:** Button clicked

| Property | Type   | Required | Description | Example          |
| -------- | ------ | -------- | ----------- | ---------------- |
| `button` | string | yes      | Button name | `"login"`        |
| `page`   | string | yes      | Page name   | `"introduction"` |
| `flow`   | string | yes      | Flow name   | `"cl_card"`      |

```js copy
exchangeSDK.tracking.trackEvent("button_clicked", {
  button: "login",
  page: "introduction",
  flow: "cl_card",
});
```

### Event: cardorder\_initiated

**Trigger:** Card order initiated

| Property   | Type   | Required | Description                | Example                     |
| ---------- | ------ | -------- | -------------------------- | --------------------------- |
| `cardType` | string | yes      | Type of card being ordered | `"virtual"` or `"physical"` |

```js copy
exchangeSDK.tracking.trackEvent("cardorder_initiated", {
  cardType: "virtual", // or "physical"
});
```

### Event: topup\_initiated

**Trigger:** Top up initiated

| Property       | Type   | Required | Description                      | Example |
| -------------- | ------ | -------- | -------------------------------- | ------- |
| `currencyFrom` | string | yes      | Currency used to fund the top-up | `"GBP"` |

```js copy
exchangeSDK.tracking.trackEvent("topup_initiated", {
  currencyFrom: "GBP",
});
```

### Event: topup\_completed

**Trigger:** Top up completed

| Property       | Type   | Required | Description                      | Example |
| -------------- | ------ | -------- | -------------------------------- | ------- |
| `currencyFrom` | string | yes      | Currency used to fund the top-up | `"GBP"` |

```js copy
exchangeSDK.tracking.trackEvent("topup_completed", {
  currencyFrom: "GBP",
});
```

### Event: withdraw

**Trigger:** Withdraw initiated

| Property       | Type   | Required | Description                               | Example                               |
| -------------- | ------ | -------- | ----------------------------------------- | ------------------------------------- |
| `currencyFrom` | string | yes      | Crypto being withdrawn in LedgerID format | `"ethereum/erc20/usd_tether__erc20_"` |
| `currencyTo`   | string | yes      | Fiat being withdrawn                      | `"GBP"`                               |

```js copy
exchangeSDK.tracking.trackEvent("withdraw", {
  currencyFrom: "ethereum/erc20/usd_tether__erc20_",
  currencyTo: "GBP",
});
```

### Event: delegation\_completed

**Trigger:** On delegation completion

| Property   | Type    | Required | Description              | Example           |
| ---------- | ------- | -------- | ------------------------ | ----------------- |
| `limit`    | boolean | yes      | Whether there is a limit | `true` or `false` |
| `currency` | string  | yes      | Currency for delegation  | `"GBP"`           |

```js copy
exchangeSDK.tracking.trackEvent("delegation_completed", {
  limit: true, // or false
  currency: "GBP",
});
```

## Key Generation for Production and Test Environments

To ensure secure communication, you must generate two sets of keys: one for the production environment and one for the test environment. Follow the steps below to generate these keys:

# Testing with the Development Key

After submitting [your keys](./providers-backend#generate-privatepublic-key) to us and once the CAL team has successfully integrated them, you can proceed to test your integration in .

### Steps to Test in Ledger Wallet

1. Open the **Settings** menu in .
2. Navigate to the **Developer** tab.
3. Locate the setting labeled **Exchange in Test Partner Mode**.
4. Enable this setting to activate the test environment.

![Payload and Payload Signature generation diagram](/exchange/exchange-dev-mode.png)

With this mode enabled, you can verify the functionality of your keys and ensure everything is working as expected in the test environment.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/fund-card/providers-test-and-submit -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/onchain-card/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Card Integration](../../card) page, you need to modify your LiveApp with some specific adjustments compared to the one found in the Discover section.

Your LiveApp must:

- Use the Ledger's [exchangeSDK](https://github.com/LedgerHQ/exchange-sdk), in addition to the Wallet API.
- Have a modified, slightly more complex, Manifest file.
- Follow specific flow/ux requirements.

## Ledger Exchange Wallet API

To learn how to create (or embed if already existing) your user interface for the card, please follow the [Discover documentation](../../discover/getting-started).

Your LiveApp will interact with , through the [ExchangeSDK](https://github.com/LedgerHQ/exchange-sdk), with the corresponding method.

You will need to set up the SDK with your `providerId` attributed upon request by Ledger.

```js copy
const exchangeSDK = new ExchangeSDK("yourProviderId");
```

### CARD method

This method will need you to provide the following parameters:

- `orderId`: The id coming from your system.
- `userAccountId`: User's Ledger uuid4 account id.
- `smartContractAddress`: The address of the onchain smart contract
- `approval.amount`: Max amount for approval, if not set, unlimited approval will be triggered
- `rawTx`: Raw transaction to sign and broadcast

```js copy
exchangeSDK.tokenApproval({
  orderId: "123abc",
  userAccountId: "97f06be9-6fb2-5da3-be71-4e762ed6e115",
  smartContractAddress: "12345",
  approval: {
    amount: new BigNumber(1),
  },
  rawTx: "abcd1234",
});
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permission

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contains at least those permissions request:

```json copy
"permissions": [
  "account.list",
  "currency.list",
  "custom.exchange.start",
  "custom.exchange.complete",
  "custom.exchange.error",
]
```

## Key Generation for Production and Test Environments

To ensure secure communication, you must generate two sets of keys: one for the production environment and one for the test environment. Follow the steps below to generate these keys:

# Testing with the Development Key

After submitting [your keys](/docs/ledger-live/exchange/card/providers-backend#generate-privatepublic-key) to us and once the CAL team has successfully integrated them, you can proceed to test your integration in .

### Steps to Test in Ledger Wallet

1. Open the **Settings** menu in .
2. Navigate to the **Developer** tab.
3. Locate the setting labeled **Exchange in Test Partner Mode**.
4. Enable this setting to activate the test environment.

![Payload and Payload Signature generation diagram](/exchange/exchange-dev-mode.png)

With this mode enabled, you can verify the functionality of your keys and ensure everything is working as expected in the test environment.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/onchain-card/providers-test-and-submit -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/redoc-api -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/sell-card/code-examples -->

---
title: Card sell code examples
category: reference
---

# Card sell code examples

This page shows how to implement the payload-signing routine described in [Payload & Signature](./providers-backend#payload--signature). Each example signs a payload with your Card sell provider private key using ES256 over the secp256k1 curve, then base64Url-encodes the result to produce the `signature` field your `/sell` response must include.

The three examples below are equivalent implementations in Java, Python, and TypeScript. Pick the one that matches your backend stack; the signing steps are the same in each case.

> **Note:** Each snippet expects a `response` protobuf message (or an already-encoded payload) and your provider's private key. Replace the placeholder key path or value with the location of your own key.

## Cross-references

- [Backend](./providers-backend): the endpoints that consume this signature, and the payload format it signs
- [API reference](../redoc-api): full request and response schemas for the Card endpoints

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/sell-card/providers-backend -->

# Backend

## Endpoints needed for Card

In order to communicate with Ledger’s backend, you must provide standardised APIs for Ledger's CARD aggregator services to call.

> **Note:** You will find all the information regarding the CARD endpoints [here](../redoc-api), as well as additional details on
> some endpoints below.

You need to implement following endpoint for the card: - To create a signed fund binary payload: [/sell](../redoc-api#operation/postSell).

Additional Details: POST /sell

Example request payload:

```json copy
{
  "quoteId": "string",
  "amount": "string",
  "refundAddress": "string",
  "fromCryptoCurrency": "string",
  "toFiatCurrency": "string",
  "payloadCryptoCurrency": "string",
  "nonce": "number"
}
```

An example response from the your backend to the Ledger backend

```json copy
{
  "sellId": "SELL-ID-165940",
  "payinAddress": "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48",
  "createdAt": "2030-05-26T14:13:39",
  "providerFees": "0.0001",
  "referralFees": "0.0001",
  "payoutNetworkFees": "0.0002",
  "providerSig": {
    "payload": "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==",
    "signature": "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs="
  }
}
```

Your Protobuf message should have the following structure:

```go copy
syntax = "proto3";
package ledger_sell;

// (coefficient) * 10^(- exponent)
message UDecimal {
    bytes  coefficient = 1;
    uint32 exponent = 2;
}

message NewSellResponse {
    string   trader_email = 1;
    string   in_currency = 2;
    bytes    in_amount = 3;
    string   in_address = 4;
    string   out_currency = 5;
    UDecimal out_amount = 6;
    bytes    device_transaction_id = 7;
    string   in_extra_id = 8;            // memo
}
```

`in_amount` amount must be in the lowest unit of the coin, encoded into a 16 bytes array in big endian.

- 1 **BTC** would be `0x5F5E100` (100000000 in hexadecimal). The smallest unit is a **satoshi** which is `10^-8` **BTC**.
  So multiply 1 **BTC** by `10^8` → `0x5F5E100`.
  And `0x5F5E100` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x05, 0xF5, 0xE1, 0x00]`.
- 2 **ETH** would be `0x1BC16D674EC80000` (or 2000000000000000000). The smallest unit is a **wei** which is `10^-18` **ETH**.
  So multiply 2 **ETH** by `10^18` → `0x1BC16D674EC80000`.
  And `0x1BC16D674EC80000` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x1B, 0xC1, 0x6D, 0x67, 0x4E, 0xC8, 0x00, 0x00]`.

## Real-time Status Updates:

To ensure effective communication with Ledger's backend, you are required to implement a webhook [/transaction/\{sellId}/status](../redoc-api#operation/statusUpdate) update mechanism. This should notify Ledger real-time whenever there is a change in the status of a transaction. Ledger will provide partners with the necessary webhook URL or address to which the status updates should be sent.

Additional Details: POST /transaction/\{sellId}/status
Explanation of the different output `status`:

- `FINISHED`: Trade has been completed successfully (user has received payout transaction).
- `EXPIRED`: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
- `ON_HOLD`: Trade has been put on hold (eg: for KYC reasons). User must contact support.
- `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction)
- `TRANSFER_IN_COMPLETED`: Transfer in completed and waiting for transfer out to be sent.
- `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
- `UNKNOWN`: Trade is in unknown state. User must contact support.

Additionally, if your backend needs to know the transaction status from our system (e.g., whether the transaction was approved or rejected by the user’s device), we provide an optional endpoint [/transaction/\{sellId}/status](../redoc-api#operation/getStatusUpdate)

[//]: # "Info needed to be exchange with the provider, but not out loud publicly"

[//]: # "**IP address checking** "

[//]: # "Additionally, we also need a way to know if a user will be able to perform a coin sell given his IP."

[//]: # "Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user’s IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected."

## Payload & Signature

Here is a little diagram to explain how the `payload` and the `signature` are generated:

![Payload and Payload Signature generation diagram](/exchange/payload-signature-generation-sell.png)

- `payload`: the trade parameters are assembled in a [protobuf](https://developers.google.com/protocol-buffers) message. This message is [binary encoded](https://developers.google.com/protocol-buffers/docs/encoding) to produce a Byte Array. This Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), resulting `payload` field.
- `signature`: The payload is signed using [ES256](https://ldapwiki.com/wiki/Wiki.jsp?page=ES256) provider's private key, generating a Byte Array. This Signature Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), producing the Signature field. ([more details](#jws-signature)).

If you need help with the signing process, please refer to our code [examples](code-examples.mdx).

### Generate Private/Public Key

1. **Private Key**:
   Use the following command to generate the private key:

   ```bash
   openssl ecparam -name secp256k1 -genkey -noout -out sample-priv-key-secp256k1.pem
   ```

2. **Public Key**:
   Derive the public key from the private key using the command:
   ```bash
   openssl ec -in sample-priv-key-secp256k1.pem -pubout > sample-pub-key-secp256k1.pem
   ```

### Verify Key Information

To inspect the contents of the private key file:

```bash
openssl ec -text -in sample-priv-key-secp256k1.pem
```

Repeat this process for both the **production** and **test** environments to generate two distinct key pairs.

### Signature usage

- Payload and Signature\
  From the provider to . The payload is a protobuf message containing the trade data. It is generated by the provider and sent to .

```go copy
type Payload struct {
  trader_email,
  in_currency,
  in_amount,
  in_address,
  out_currency,
  out_amount,
  device_transaction_id,
  in_extra_id
}
R, S := Sign(payload, privKey)
```

- Validate\
  Exchange app checks and validates the payload (signature and content).

```go copy
// Compare nonce in payload
Verify((R, S), payload, pubKey)
```

- Display\
  Exchange app requests approval to the user by displaying the operation summary on screen.

```c copy
Validate?
Send currency_from amount_to_provider
Receive currency_to amount_to_wallet
```

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/sell-card/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Card Integration](../../card) page, you need to modify your LiveApp with some specific adjustments compared to the one found in the Discover section.

Your LiveApp must:

- Use the Ledger's [exchangeSDK](https://github.com/LedgerHQ/exchange-sdk), in addition to the Wallet API.
- Have a modified, slightly more complex, Manifest file.
- Follow specific flow/ux requirements.

## Ledger Exchange Services Kit

To learn how to create (or embed if already existing) your user interface for the card, please follow the [Discover documentation](../../discover/getting-started).

Your LiveApp will interact with , through the [ExchangeSDK](https://github.com/LedgerHQ/exchange-sdk), with the corresponding method.

You will need to set up the SDK with your `providerId` attributed upon request by Ledger.

```js copy
const exchangeSDK = new ExchangeSDK("yourProviderId");
```

### CARD method

This method will need you to provide the following parameters:

- `quoteId`: The id coming from your system.
- `fromAccountId`: User's Ledger account id.
- `fromAmount`: Amount that will be sold.
- `toFiat`: Fiat currency that the user wants to be paid with using provider id.
- `rate`: The crypto/fiat rate.

```js copy
exchangeSDK.sell({
  quoteId: "123abc",
  fromAccountId: "97f06be9-6fb2-5da3-be71-4e762ed6e115", // <Glossary word='Ledger Wallet'></Glossary> uuid4 account (can be a BTC account)
  fromAmount: new BigNumber(1),
  toFiat: "EUR", // provider fiat id
  rate: 66564, // crypto/fiat rate [BTC/EUR]
  type: "card",
});
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permission

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contains at least those permissions request:

```json copy
"permissions": [
  "account.list",
  "currency.list",
  "custom.exchange.start",
  "custom.exchange.complete",
  "custom.exchange.error",
]
```

## Key Generation for Production and Test Environments

To ensure secure communication, you must generate two sets of keys: one for the production environment and one for the test environment. Follow the steps below to generate these keys:

# Testing with the Development Key

After submitting [your keys](/docs/ledger-live/exchange/card/providers-backend#generate-privatepublic-key) to us and once the CAL team has successfully integrated them, you can proceed to test your integration in .

### Steps to Test in Ledger Wallet

1. Open the **Settings** menu in .
2. Navigate to the **Developer** tab.
3. Locate the setting labeled **Exchange in Test Partner Mode**.
4. Enable this setting to activate the test environment.

![Payload and Payload Signature generation diagram](/exchange/exchange-dev-mode.png)

With this mode enabled, you can verify the functionality of your keys and ensure everything is working as expected in the test environment.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card/sell-card/providers-test-and-submit -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/card -->

---
title: Card integration overview
category: explanation
---

# Card integration overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Card integration lets users buy crypto with a debit or credit card directly inside . As a Card provider, you handle the payment processing and order fulfilment; Ledger supplies the secure, device-verified receive address and the embedded LiveApp experience.

To become a native Card provider, you need to deliver three things:

1. **Backend API**: adapt your API to the Ledger Card specification. Each order is secured with a cryptographic payload and signature: your backend generates a structured payload, signs it with your private key, and sends both to Ledger. You must also share your public key with Ledger so signatures can be verified, and keep your private key secure.
2. **LiveApp**: a web application that loads inside . It uses the Ledger Exchange Wallet API in addition to the standard Wallet API to handle card purchase flows and transaction signing on the device. You also need to write or update your manifest and follow Ledger's UX requirements.
3. **Testing and submission**: test the full integration end-to-end using Developer Mode in , then submit your API, manifest, and public key for Ledger review.

> **Note:** Each component can be worked on in parallel. The integration only goes live once all three have passed review.

## What to read next

- [Backend](card/providers-backend) — the API endpoint, payload format, signature scheme, and key-pair requirements
- [LiveApp](card/providers-liveapp) — LiveApp URL format, manifest requirements, Exchange Wallet API usage, and UX guidelines
- [Test & Submit](card/providers-test-and-submit) — how to test end-to-end with Developer Mode and submit for review
- [Code examples](card/code-examples) — payload generation and encoding examples in multiple languages

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/earn/clear-signing -->

---
title: Clear sign your Earn smart contracts
category: how-to
---

# Clear sign your Earn smart contracts

Earn Live Apps must clear sign every smart-contract interaction they trigger: staking, unstaking, claiming rewards, delegating. This page shows how to do it with [ERC-7730](../../../clear-signing/overview), the metadata-only standard supported by Ledger Wallet.

> **Note:** Clear signing is a release blocker for Earn. A Live App with even one un-clear-signed call will not be approved.

## Prerequisites

- Your contract is deployed on an EVM-compatible mainnet (the [JSON Builder](../../../clear-signing/for-dapps/json-builder) tool currently targets Ethereum mainnet only).
- You have the contract **address** and **ABI**.
- You can open a pull request to [`ethereum/clear-signing-erc7730-registry`](https://github.com/ethereum/clear-signing-erc7730-registry), the public ERC-7730 registry that wallets fetch from.

## Steps

### Pick the right approach

Use the [ERC-7730 JSON Builder](../../../clear-signing/for-dapps/json-builder) when your contract is on Ethereum mainnet and uses standard function signatures. It produces a valid metadata file in a few minutes. For multi-chain deployments, EIP-712 messages, nested tuples, or reusable includes, write the metadata file [manually](../../../clear-signing/for-dapps/manual-implementation) instead. The full step-by-step walkthrough is on [How to add Clear Signing to your dApp](../../../clear-signing/for-dapps/get-started).

### Describe each function in metadata

For every function your Earn Live App calls, declare it under `display.formats`. The example below is taken from Lido's published [`calldata-stETH.json`](https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/registry/lido/calldata-stETH.json) and shows the `submit(address)` function used to stake ETH:

```json
{
  "$schema": "../../specs/erc7730-v2.schema.json",
  "context": {
    "$id": "stETH",
    "contract": {
      "deployments": [
        { "chainId": 1, "address": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84" }
      ]
    }
  },
  "metadata": {
    "owner": "Lido DAO",
    "info": { "url": "https://lido.fi" },
    "contractName": "stETH"
  },
  "display": {
    "formats": {
      "submit(address _referral)": {
        "intent": "Stake ETH",
        "fields": [
          { "label": "Amount to stake", "format": "amount", "path": "@.value" },
          { "label": "Referral",       "path": "#._referral", "visible": "never" }
        ]
      }
    }
  }
}
```

The same file should also describe `approve`, `transfer`, and any unstake / claim / delegate functions your Live App invokes. Every function the user signs needs an entry.

### Validate the file

Check that your metadata follows the schema before you submit, using the [ERC-7730 validator](../../../clear-signing/for-dapps/validate-submit). A failing schema check means wallets cannot use the file.

### Submit to the registry

Open a pull request to [`ethereum/clear-signing-erc7730-registry`](https://github.com/ethereum/clear-signing-erc7730-registry) under `registry/<your-protocol>/`. Once the pull request is merged, Ledger Wallet (and other ERC-7730-compatible wallets) automatically fetches the file when users sign one of the listed transactions, with no app release needed. Detailed submission rules are on [Validate and submit your metadata](../../../clear-signing/for-dapps/validate-submit).

## Non-EVM chains

ERC-7730 currently covers EVM-compatible chains only. If your Earn Live App stakes on a non-EVM chain (for example Cosmos, Solana, Cardano, Polkadot), get in touch with your Ledger contact during the integration review. Clear signing on those chains is handled outside this registry.

## Common pitfalls

- **`localhost:` links in the file.** A local validator URL has no place in a registry submission; remove it before opening the pull request.
- **Spelling mistakes in `intent` or `label`.** They appear verbatim on the device screen, so misspellings ship straight to users.
- **Forgotten functions.** If you ship a flow with five contract calls, the registry file must describe all five. Anything missing falls back to blind signing.

## See also

- [Clear signing overview](../../../clear-signing/overview): what ERC-7730 is and how it works.
- [How to add Clear Signing to your dApp](../../../clear-signing/for-dapps/get-started): step-by-step guide.
- [Manual implementation](../../../clear-signing/for-dapps/manual-implementation): for multi-chain or EIP-712 cases.
- [`ethereum/clear-signing-erc7730-registry`](https://github.com/ethereum/clear-signing-erc7730-registry): registry of published metadata files (Lido, Kiln, Swell, P2P, Figment, Ethena, and others useful for Earn).

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/earn/earn-dashboard -->

---
title: Earn dashboard integration
category: how-to
---

# Earn dashboard integration

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Earn section in  shows users their active staking positions. For each account used for staking, it displays:

- **Staked amount**: total assets delegated or locked in the account.
- **Rewards %**: the net APY (Annual Percentage Yield) for the position.
- **Rewards earned**: cumulative rewards to date, including any that have been claimed.

To populate these fields, 's backend queries your service through standardised APIs described on this page.

![Earn section screenshot](/exchange/screen-ledger-wallet-earn-dashboard.png)

## Required endpoints

Your service must expose an API that, for each account used for staking, returns the data listed above. Depending on your protocol, this data may need to be broken down by validator address and/or pool ID, and include a rewards breakdown for specified time windows (for example, last 24 hours, last 7 days).

> **Note:** The full endpoint specifications, request/response schemas, and example payloads are in the [Earn API reference](./redoc-api).

## Connection details to share with Ledger

Once your API is ready, provide Ledger with:

| Detail         | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------ |
| Base URL       | The root URL of your API (e.g. `https://api.yourprotocol.com`)                             |
| Authentication | Any token, header, or credential required to call the API                                  |
| Refresh rate   | How quickly positions and rewards reflect on-chain state                                   |
| Rate limit     | Your API's rate limit; the desired target is unlimited                                     |
| Health codes   | HTTP status codes that indicate the API is up (e.g. 200, 404) vs. down (e.g. 500, timeout) |

## Related

- [Earn integration overview](../earn) — the three components required for an Earn integration
- [Earn API reference](./redoc-api) — full endpoint specifications
- [LiveApp](./liveapp) — the frontend component of the Earn integration
- [Clear Signing](./clear-signing) — the mandatory security component

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/earn/liveapp -->

---
title: Earn provider LiveApp
category: how-to
---

# How to prepare an Earn provider LiveApp

> **Key takeaway:** ☞   The transition from "Ledger Live" to "Ledger Wallet" and from "wallet" (for the hardware product) to "signer" is still in progress. This page may contain legacy terms that will be updated.

This guide shows you how to prepare an Earn provider LiveApp for Ledger Wallet. A LiveApp is your dapp, or web application, running in Ledger Wallet's embedded browser.

Users can access a LiveApp that offers staking services from these sections of :

- **Accounts**, where users can view their accounts and stake available assets
- **Discover**, where users can explore a curated catalog of dapps
- **Earn**, where users can track staking positions and stake additional assets from eligible accounts

## Create your LiveApp

There are two ways to integrate your dapp into Ledger Wallet:

1. **dAppBrowser (EVM only)**: Create a manifest that points to the dAppBrowser to integrate your dapp into .
2. **The  API**: Use this JavaScript library to interact with  signers, such as to sign a transaction, and access information from the connected , such as the wallet address.

Follow the [Discover documentation](../../discover/getting-started) to create a user interface for  or embed an existing one.

## Meet the LiveApp UX requirements

Your LiveApp must meet these UX requirements:

- Connect the user's wallet automatically when they open your LiveApp.
- Do not allow users to sign in through other wallets.
- Use a responsive design that displays correctly on all devices.
- Do not request unlimited token approvals. Request approval only for the number of tokens required to stake or unstake.
- Use trusted names, such as ENS names.
- After a successful transaction, such as staking, unstaking, delegation, or claiming rewards, display a confirmation page with the transaction hash so that users can check its status.
- When applicable, show the staking method, such as native or liquid staking, and the names of the validators to which the assets are delegated.

The Ledger team will review and validate your LiveApp's user flow against these requirements.

> **Note:** If users receive a liquid or non-liquid token that represents the staking
> position, inform Ledger of the token's name and address.

## Support direct navigation with URL parameters

Implement URL parameters so that  can direct users to the correct LiveApp page for actions such as staking or unstaking.

When  opens one of these URLs, route the user to the screen that matches the specified parameters. Each parameter must correspond to a specific action.

Use these URL parameters:

| Parameter           | Type        | Example             | Description                                                                                                        |
| ------------------- | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `action`            | string      | `stake`             | Specifies the action to be performed: `stake`, `unstake`, `manage`, or `claim_rewards`.                            |
| `accountAddress`    | hex address | `0xABC…`            | The address of the user executing the action.                                                                      |
| `accountId`         | string      | `js:2:ethereum:0x…` | The ID of the user's account in .                                                                                  |
| `cryptoCurrency`    | string      | `ETH`               | The crypto asset involved in the action.                                                                           |
| `network`           | string      | `arbitrum`          | The blockchain (network) where the action takes place.                                                             |
| `language`          | string      | `en`                | The language preference of the user set in .                                                                       |
| `theme`             | string      | `dark`              | The theme preference of the user set in .                                                                          |
| `fix_parameters`    | boolean     | `true`              | When `true`, restricts users from changing the network, coins, and connected address within your LiveApp frontend. |
| `validator_address` | string      | `0xVAL…`            | If needed, the validator address related to the `action`.                                                          |

**Example:**

```
https://earn.provider.widget.com?[accountAddress]=0x…&[cryptoCurrency]=ETH&[network]=arbitrum&[action]=unstake&[language]=en&[theme]=dark&[fix_parameters]=true
```

Configure your app to recognize these parameters and route users directly to the relevant screens. If a parameter is missing or invalid, provide a fallback, such as the default home or dashboard screen.

## Update the manifest

If your LiveApp interacts with third-party smart contracts that you do not own and that already support Clear Signing, update your manifest to specify the dependency.

For example, if your LiveApp interacts with EigenLayer smart contracts that already support Clear Signing and are used by other LiveApps, include the following in your LiveApp manifest:

```json
"dependencies": [
  "eigenlayer"
]
```

> **Note:** Verify the correct field name (`dependency` vs `dependencies`) against the [manifest schema](https://live-app-catalog.ledger.com/schema.json) before submitting. List the identifiers of third-party protocols whose clear-signed contracts your LiveApp calls.

Contact the Ledger team to confirm whether a third-party smart contract already supports Clear Signing and which value to use for it in your manifest.

## Next steps

After you prepare the Earn provider LiveApp, continue with the relevant documentation:

- [Discover documentation](../../discover/getting-started) for building and embedding a LiveApp
- [Live app manifest reference](../../discover/references/manifest) for the full manifest field reference
- [UX review process](../../discover/integration/liveapp/ux-review) for Ledger team review requirements

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/earn/redoc-api -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/earn -->

---
title: Earn integration overview
category: explanation
---

# Earn integration overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

&#x20;users can stake their crypto assets to earn rewards.

To integrate an Earn application into , three components are required and must all be delivered together before your integration can go live:

1. **A LiveApp** — a web application loaded within  that lets users interact with your protocol. It communicates with the connected Ledger signer to request transaction signatures and reads account information (addresses, balances) through the Wallet API.
2. **Clear Signing** — instead of presenting users with raw, unreadable blockchain data (blind signing), Clear Signing displays a human-readable summary of each transaction on the Ledger device's Secure Screen. This is a mandatory security requirement for Earn integrations.
3. **Earn dashboard integration** — the Earn section in  lets users track their staking positions (APY, accrued rewards, and more). Your service must expose the API endpoints that feed this dashboard so users can see their positions without leaving the wallet.

> **Note:** Each component can be developed in parallel. For example, you can work on Clear Signing while your LiveApp is still in progress. However, all three components must be fully developed and tested before your Earn integration can be deployed to .

## What to read next

- [LiveApp](earn/liveapp) — LiveApp specifics for Earn integrations
- [Clear Signing](earn/clear-signing) — how to clear-sign your smart contracts
- [Earn Dashboard](earn/earn-dashboard) — how to expose your staking data to the Earn dashboard

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/glossary -->

---
title: Glossary
category: reference
---

# Glossary

A reference of the terms used across the Exchange section (Swap, Buy, Sell, Earn, Card). Definitions match the vocabulary used in the Ledger device-side [Exchange application](https://github.com/LedgerHQ/app-exchange) and the partner-facing flow documentation.

Terms are listed alphabetically.

### Account

A  address on a cryptocurrency network. A user can have several accounts on the same blockchain (for example several Ethereum addresses).

### CAL: Crypto Asset List

The Ledger-maintained, HSM-signed list of currencies the device-side Exchange application can display. The CAL is what lets the device verify that the FROM and TO assets in a transaction proposal really are the assets the user expects.

### Coin

The native currency on a blockchain. Identified with `"type": "coin"`. For example, on Ethereum only `ETH` has type `coin`; everything else is a token.

### Coin application

The Ledger device app that handles a specific blockchain (Bitcoin app, Ethereum app, …). The Exchange application drives two coin applications during a swap: one for the **FROM** asset and one for the **TO** asset.

```json
[
  { "id": "ETH",  "type": "coin",  "blockchain": "ethereum", "chainId": 1 },
  {
    "id": "USDC",
    "type": "token",
    "blockchain": "ethereum",
    "chainId": 1,
    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
]
```

### Exchange application

The device-side application that orchestrates Swap and Sell. It receives the partner's signed transaction proposal from Ledger Wallet, validates it against the CAL, drives the FROM and TO coin applications, and shows the final review screen to the user.

### Fixed quote

A quote whose rate is guaranteed for a defined window (at least 60 seconds). The user receives exactly the amount displayed if they accept within that window. Compare with [Floating quote](#floating-quote).

### Floating quote

A quote whose rate is not guaranteed. The user can receive less than the displayed amount according to market fluctuations, but is protected by a maximum slippage value defined by the partner. Compare with [Fixed quote](#fixed-quote).

### KYC: Know Your Customer

Identity-verification process some partners require before letting a user trade. See [Registration policy](#registration-policy).

### Ledger fee

Fee taken by Ledger as part of a swap. Subtracted from the partner's swap rate output when computing the receiving amount.

### LiveApp

A third-party application that runs inside Ledger Wallet through the dApp browser or the Wallet API. Each Exchange flow (Swap, Buy, Sell, Earn, Card) is implemented by one or more partner LiveApps.

### Partner

A third-party service integrated with Ledger Wallet to provide a Buy, Sell, Swap, Earn, or Card flow. In the Exchange application's vocabulary, also called the **Trade Partner**.

### Partner fee

Fee taken by the partner as part of a swap. Subtracted from the partner's swap rate output when computing the receiving amount.

### `payinNetworkFees`

The network (gas) fee paid by the user to send the FROM crypto from their Ledger account to the partner. Not included in the receiving amount displayed in the quote, but shown separately above it.

### Provider

Synonym for partner used in the Buy / Sell / Card flows (`providers-backend.mdx`, `providers-liveapp.mdx`).

### Quote

A trade offer returned by a partner for a given input amount and currency pair. Includes the receiving amount, exchange rate, fee breakdown, and whether the rate is fixed or floating. The Exchange flow is built around displaying and accepting quotes.

### Receiving amount

The amount the user will receive in the TO currency, after all fees are applied. Computed as:

```text
receivingAmount = swapRateOutput × (1 − ledgerFee − partnerFee) − withdrawalFee
```

`payinNetworkFees` are not included.

### Registration policy

Whether a partner requires the user to register / complete KYC before trading. Displayed on each quote card as **Needed** or **Not needed**.

### Signed transaction proposal

A transaction proposal sent by the trade partner, signed with the partner's private key. Ledger Wallet forwards it to the Exchange application, which verifies the signature against the partner's public key registered with Ledger.

### Slippage

The maximum acceptable difference between the quoted rate and the executed rate on a floating quote. Set by the partner and surfaced to the user.

### Swap rate output

The rate provided by the partner for a swap, before any fee deduction. The receiving amount is derived from it.

### Token

A non-native asset on a blockchain. Identified with `"type": "token"` and a `contract` field. For example, USDC on Ethereum:

```json
{
  "id": "USDC",
  "type": "token",
  "blockchain": "ethereum",
  "chainId": 1,
  "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
```

### Trade Partner

The actor that proposes a trade offer to the Ledger Wallet user. Equivalent to **partner** / **provider**. The partner's offer must be displayed faithfully on the device screen by the Exchange application.

### Withdrawal fee

Fee paid by the user to cover the gas needed to move the TO crypto from the partner's wallet back to the user. Subtracted when computing the receiving amount.

## See also

- [Swap flow](./swap/flow): where most of these terms appear in context.
- [Quote display](./swap/flow/quote): fee composition and quote sorting.
- [`LedgerHQ/app-exchange`](https://github.com/LedgerHQ/app-exchange): source of truth for the device-side Exchange application vocabulary.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/architecture -->

# Sell integration architecture

> **Key takeaway:** ☞   The transition from "Ledger Live" to "Ledger Wallet" and from "wallet" (for the hardware product) to "signer" is still in progress. This page may contain legacy terms that will be updated.

The Sell integration exchanges data between , Ledger Backend, and the provider's systems. To support the Sell feature in , providers implement specific endpoints and follow the workflow described below.

## Workflow diagram

```mermaid
sequenceDiagram
    participant User
    participant LedgerLive as Ledger Wallet
    participant LedgerBackend as Ledger Backend
    participant ProviderBackend as Provider Backend
    participant ProviderWidget as Provider Widget App
    participant ExchangeSDK as Exchange SDK

    %% Step 1: Open Sell App
    User->>LedgerLive: Open Sell App
    LedgerLive->>LedgerBackend: [GET] /providers
    LedgerBackend->>ProviderBackend: [GET] /capabilities (Cached)
    ProviderBackend-->>LedgerBackend: Return capabilities data
    LedgerBackend->>ProviderBackend: [GET] /crypto-currencies (Cached)
    ProviderBackend-->>LedgerBackend: Return supported crypto assets
    LedgerBackend-->>LedgerLive: Return providers list and capabilities

    %% Step 2: User Input and Validation
    User->>LedgerLive: Select crypto, fiat, amount
    LedgerLive-->>User: Validate input using cached /capabilities
    User->>LedgerLive: Proceed with valid input
    LedgerLive-->>User: Display countries and payment methods based on /capabilities
    User->>LedgerLive: Select country and payment method
    
    %% Step 3: Select Provider and Get Quotes
    LedgerLive->>LedgerBackend: [GET] /offRamp Find eligible providers
    LedgerBackend->>ProviderBackend: [GET] /quotes
    ProviderBackend-->>LedgerBackend: Return quotes
    LedgerBackend-->>LedgerLive: Return providers and quotes
    User->>LedgerLive: Choose provider

    %% Step 4: Redirect to Provider Widget
    LedgerLive->>ProviderWidget: Redirect with parameters (LiveApp URL)
    User->>ProviderWidget: KYC process, if required, and landing in step transaction in provider widget.
    ProviderWidget->>ExchangeSDK: Initiate exchangeSdk
    ProviderWidget->>ExchangeSDK: Call exchangeSdk.sell

    %% Step 5: Initiate Transaction
    ExchangeSDK->>LedgerLive: Initiate transaction
    LedgerLive-->>ExchangeSDK: Return nonce
    ExchangeSDK->>LedgerBackend: [POST] /remit
    LedgerBackend->>ProviderBackend: [POST] /sell (Request signed payload)
    ProviderBackend-->>LedgerBackend: Return signed payload
    LedgerBackend-->>ExchangeSDK: Return signed payload
    ExchangeSDK-->>LedgerLive: Device transaction approval
    User->>LedgerLive: Approve transaction on device (approve/reject)

    %% Step 6: Finalizing the Transaction
    LedgerLive->>ExchangeSDK: Inform transaction rejected or approved. Provides transactionId if approved
    ExchangeSDK->>ProviderWidget: Transmit transaction info
    ProviderWidget->>ProviderBackend: Transmit transaction status and init webhooks
    ProviderBackend->>LedgerBackend: [POST] /webhook - Update transaction status

```

### Opening the Sell app

Action: The user opens the Sell app in .

&#x20;fetches capability data from Ledger Backend, which caches responses from the provider's [/capabilities](./redoc-api#operation/getCapabilities) endpoint. It also fetches the supported crypto assets from Ledger Backend, which caches responses from the provider's [/crypto-currencies](./redoc-api#operation/getCryptoCurrencies) endpoint.

### User input and validation

User interaction: The user selects the crypto asset, fiat currency, and amount to sell.

The user then selects their country and preferred payment method, such as PayPal or a bank transfer.

Validation process:  validates the input against cached data from [/capabilities](./redoc-api#operation/getCapabilities). The data includes provider limits, such as minimum and maximum amounts and supported countries.

If the input is invalid,  displays an error message to the user.

### Quotes and provider selection

User interaction: The user requests a quote.

Backend process: Ledger Backend identifies eligible providers based on the user's input.

For each eligible provider, Ledger Backend sends a \[GET] [/quotes](./redoc-api#operation/getQuote) request to the provider backend. The response contains pricing details, such as the fiat amount the user will receive after fees.

Ledger Backend aggregates the returned quotes and displays them in .

User decision: The user selects a provider from the list of quotes.

### Redirect to the provider widget

Action: After the user selects a provider,  redirects them to the provider's widget.

Redirection details: The redirect includes the parameters specified in the [LiveApp URL documentation](../sell/providers-liveapp), such as the selected crypto asset, fiat currency, amount, and user details.

The user completes the transaction details in the provider widget.

### Transaction initiation

Provider widget interaction: The provider widget starts the transaction by calling the `exchangeSdk.sell` method. This call triggers Ledger Backend to initiate the transaction.

Backend process: Ledger Backend sends a \[POST] [/sell](./redoc-api#operation/postSell) request to the provider backend for a signed transaction payload.

The provider backend processes the request and returns the signed payload. Ledger Backend then passes the payload to the Exchange SDK.

Signer approval: The Exchange SDK prompts the Ledger signer to approve or reject the transaction.

The user approves or rejects the transaction on their Ledger signer.

### Transaction finalization

After approval: When the transaction is approved, the `exchangeSdk.sell` promise sends the result to the provider widget. The result includes a `transactionId` for an approved transaction.

The provider widget then sends the final transaction status to the provider backend. If the user approved the transaction, the provider backend initiates webhooks.

If the user rejects the transaction, the provider is also notified.

### Real-time updates

The provider backend sends real-time transaction status updates to Ledger Backend through the `[POST] /webhook/status` endpoint.

Ledger Backend updates the transaction status in  so that the user can track its progress and completion.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/code-examples -->

---
title: Sell code examples
category: reference
---

# Sell code examples

This page shows how to implement the payload-signing routine described in [Payload & Signature](./providers-backend#payload--signature). Each example signs a payload with your Sell provider private key using ES256 over the secp256k1 curve, then base64Url-encodes the result to produce the `signature` field your `/sell` response must include.

The three examples below are equivalent implementations in Java, Python, and TypeScript. Pick the one that matches your backend stack; the signing steps are the same in each case.

> **Note:** Each snippet expects a `response` protobuf message (or an already-encoded payload) and your provider's private key. Replace the placeholder key path or value with the location of your own key.

## Cross-references

- [Backend](./providers-backend): the endpoints that consume this signature, and the payload format it signs
- [API reference](./redoc-api): full request and response schemas for the Sell endpoints

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/providers-backend -->

# Backend

## Endpoints needed for Sell

In order to communicate with Ledger’s backend, you must provide standardised APIs for Ledger's Sell aggregator services to call.

> **Note:** You will find all the information regarding the Sell endpoints [here](./redoc-api), as well as additional details on
> some endpoints below.

There are 5 endpoints needed for the Sell integration:

- To get the list of available fiat, country, payment, method and amount: [/capabilities](./redoc-api#operation/getCapabilities).
- To get the list of available crypto-currencies: [/crypto-currencies](./redoc-api#operation/getCryptoCurrencies).
- To get the fiat amount that the user should expect -after all fees are deducted - as a payment for the given crypto amount: [/quotes](./redoc-api#operation/getQuote).
- To get the URL of the off-ramp widget to which the user will be redirected. [/sell-redirect](./redoc-api#operation/sell-redirect).
- To create a signed sell binary payload: [/sell](./redoc-api#operation/postSell).

Additional Details: POST /sell

Example request payload:

```json copy
{
  "quoteId": "string",
  "amount": "string",
  "refundAddress": "string",
  "fromCryptoCurrency": "string",
  "toFiatCurrency": "string",
  "payloadCryptoCurrency": "string",
  "nonce": "number"
}
```

An example response from the your backend to the Ledger backend

```json copy
{
  "sellId": "SELL-ID-165940",
  "payinAddress": "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48",
  "createdAt": "2030-05-26T14:13:39",
  "providerFees": "0.0001",
  "referralFees": "0.0001",
  "payoutNetworkFees": "0.0002",
  "providerSig": {
    "payload": "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==",
    "signature": "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs="
  }
}
```

Your Protobuf message should have the following structure:

```go copy
syntax = "proto3";
package ledger_sell;

// (coefficient) * 10^(- exponent)
message UDecimal {
    bytes  coefficient = 1;
    uint32 exponent = 2;
}

message NewSellResponse {
    string   trader_email = 1;
    string   in_currency = 2;
    bytes    in_amount = 3;
    string   in_address = 4;
    string   out_currency = 5;
    UDecimal out_amount = 6;
    bytes    device_transaction_id = 7;
    string   in_extra_id = 8;            // memo
}
```

`in_amount` amount must be in the lowest unit of the coin, encoded into a 16 bytes array in big endian.

- 1 **BTC** would be `0x5F5E100` (100000000 in hexadecimal). The smallest unit is a **satoshi** which is `10^-8` **BTC**.
  So multiply 1 **BTC** by `10^8` → `0x5F5E100`.
  And `0x5F5E100` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x05, 0xF5, 0xE1, 0x00]`.
- 2 **ETH** would be `0x1BC16D674EC80000` (or 2000000000000000000). The smallest unit is a **wei** which is `10^-18` **ETH**.
  So multiply 2 **ETH** by `10^18` → `0x1BC16D674EC80000`.
  And `0x1BC16D674EC80000` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x1B, 0xC1, 0x6D, 0x67, 0x4E, 0xC8, 0x00, 0x00]`.

### Ledger IDs mapping

To comply with our integration policies, the LedgerId format must be used (by your `/crypto-currencies` and `/capabilities` endpoints) and accepted (by your `/quote` endpoint and widgetURL) to accurately identify tokens and coins.

You can refer to [this API](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name) to obtain Ledger IDs. You can use the `search` parameter to find a specific coin or token. For instance, to search for USDT, you can use this [request](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name\&search=USDT). The API returns paginated results: to access the next pages, include `cursor=<value of the "X-Ledger-Next" header>` in your request. Further information is available in the response headers.

Example: let's say your support AAVE on Ethereum mainnet. The LedgerID for AAVE on Ethereum is `ethereum/erc20/aave` (as we can see [here](https://crypto-assets-service.api.ledger.com/v1/currencies?output=id,name,ticker,contract_address,blockchain_name\&search=AAVE)). This means:

- Your `/crypto-currencies` endpoint must include `ethereum/erc20/aave` in its response (along with the other coins/tokens you support), so we know that you support AAVE on Ethereum.
- Your `/capabilities` endpoint must include `ethereum/erc20/aave` in its response (along with the other coins/tokens you support).
- Your `/quote` endpoint must accept `ethereum/erc20/aave` as a value for the `from` parameter.
- Your widgetURL must accept `ethereum/erc20/aave` as a value for the `from` parameter.

## Real-time Status Updates:

To ensure effective communication with Ledger's backend, you are required to implement a webhook [/transaction/\{sellId}/status](./redoc-api#operation/statusUpdate) update mechanism. This should notify Ledger in real-time whenever there is a change in the status of a transaction.
Ledger will provide a webhook URL for status updates, partners can then send updates by calling this provided endpoint.

Additional Details: POST /transaction/\{sellId}/status
Explanation of the different output `status`:

- `FINISHED`: Trade has been completed successfully (user has received payout transaction).
- `EXPIRED`: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
- `ON_HOLD`: Trade has been put on hold (eg: for KYC reasons). User must contact support.
- `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction)
- `TRANSFER_IN_COMPLETED`: Transfer in completed and waiting for transfer out to be sent.
- `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
- `UNKNOWN`: Trade is in unknown state. User must contact support.

Additionally, if your backend needs to know the transaction status from our system (e.g., whether the transaction was approved or rejected by the user’s device), we provide an optional endpoint [/transaction/\{sellId}/status](./redoc-api#operation/getStatusUpdate)

> **Note:** Webhooks must be sent only **after** your Front-End has called the Sell method of the Exchange SDK. Sending a webhook beforehand will result in an error 404 (transaction not found), as the Sell ID included the webhook payload won't be recognized by Ledger at that point.

[//]: # "Info needed to be exchange with the provider, but not out loud publicly"

[//]: # "**IP address checking** "

[//]: # "Additionally, we also need a way to know if a user will be able to perform a coin sell given his IP."

[//]: # "Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user’s IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected."

## Payload & Signature

Here is a little diagram to explain how the `payload` and the `signature` are generated:

![Payload and Payload Signature generation diagram](/exchange/payload-signature-generation-sell.png)

- `payload`: the trade parameters are assembled in a [protobuf](https://developers.google.com/protocol-buffers) message. This message is [binary encoded](https://developers.google.com/protocol-buffers/docs/encoding) to produce a Byte Array. This Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), resulting `payload` field.
- `signature`: The payload is signed using [ES256](https://ldapwiki.com/wiki/Wiki.jsp?page=ES256) provider's private key, generating a Byte Array. This Signature Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), producing the Signature field. ([more details](#jws-signature)).

If you need help with the signing process, please refer to our code [examples](code-examples.mdx).

### Generate Private/Public Key

1. **Private Key**:
   Use the following command to generate the private key:

   ```bash
   openssl ecparam -name secp256k1 -genkey -noout -out sample-priv-key-secp256k1.pem
   ```

2. **Public Key**:
   Derive the public key from the private key using the command:
   ```bash
   openssl ec -in sample-priv-key-secp256k1.pem -pubout > sample-pub-key-secp256k1.pem
   ```

### Verify Key Information

To inspect the contents of the private key file:

```bash
openssl ec -text -in sample-priv-key-secp256k1.pem
```

Repeat this process for both the **production** and **test** environments to generate two distinct key pairs.

### Signature usage

- Payload and Signature\
  From the provider to . The payload is a protobuf message containing the trade data. It is generated by the provider and sent to .

```go copy
type Payload struct {
  trader_email,
  in_currency,
  in_amount,
  in_address,
  out_currency,
  out_amount,
  device_transaction_id,
}
R, S := Sign(payload, privKey)
```

- Validate\
  Exchange app checks and validates the payload (signature and content).

```go copy
// Compare nonce in payload
Verify((R, S), payload, pubKey)
```

- Display\
  Exchange app requests approval to the user by displaying the operation summary on screen.

```c copy
Validate?
Send currency_from amount_to_provider
Receive currency_to amount_to_wallet
```

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Sell Integration](../sell) page, you need to modify your LiveApp with some particularities compared to the one that can be found in the Discover section.

Your LiveApp must:

- Use the [Ledger Exchange Services Kit](https://github.com/LedgerHQ/exchange-sdk), in addition to the Wallet API.
- Respond to specific LiveApp URL parameters in order to adapt to the flow inside .
- Have a modified, slightly more complex, Manifest file.
- Follow specific flow/ux requirements.

## Ledger Exchange Services Kit

To learn how to create (or embed if already existing) your user interface for the sell, please follow the [Discover documentation](../../discover/getting-started).

Your LiveApp will interact with , through the [ExchangeSDK](https://github.com/LedgerHQ/exchange-sdk), with the corresponding method.

You will need to set up the SDK with your `providerId` attributed upon request by Ledger.

```js copy
const exchangeSDK = new ExchangeSDK("yourProviderId");
```

### SELL method

This method will need you to provide the following parameters:

- `quoteId`: The id coming from your system and [forwarded to your LiveApp](./providers-liveapp) as a query parameter.
- `fromAccountId`: User's Ledger account id, [previously given to the LiveApp](./providers-liveapp) as a query parameter.
- `fromAmount`: Amount that will be sold.
- `toFiat`: Fiat currency that the user wants to be paid with using provider id.
- `rate`: The crypto/fiat rate.

```js copy
exchangeSDK.sell({
  quoteId: "123abc",
  fromAccountId: "97f06be9-6fb2-5da3-be71-4e762ed6e115", // <Glossary word='Ledger Wallet'></Glossary> uuid4 account (can be a BTC account)
  fromAmount: new BigNumber(1),
  toFiat: "EUR", // provider fiat id
  rate: 66564, // crypto/fiat rate [BTC/EUR]
  type: "SELL",
});
```

## LiveApp URL

The LiveApp needs to respond to a URL with some parameters. LiveApp URLs are used to open your LiveApp with the quote values that the user already entered in .

The LiveApp URL format is already fixed and will depend on the information you provided inside your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) (ex: `ledgerlive://discover/sellprovidername`).

- `accountId`: User’s selected account id, where the crypto he wants to sell is stored.
- `cryptoCurrency`: The crypto currency that the user wants to sell. It will contain the [LedgerID](https://developers.ledger.com/docs/ledger-live/exchange/sell/providers-backend#ledger-ids-mapping) value to identify the crypto.
- `fiatCurrency`: The fiat currency that the user wants to be paid with.
- `cryptoAmount`: The crypto amount that the user wants to sell.
- `paymentMethod`: The preferred payment method for the user.
- `mode`: `buy` or `sell`. In this case always sell. Required you share the same base widget url for both usages.
- `bankResidency`: User's Country Code (ALPHA-2)
- `ledgerTransactionId`: ID used by Ledger to track transactions and their completion statuses.
- `customParameters`: Used to include additional URL-encoded key-value parameters in the widget URL.For example: `widgetid%3D247312%26ledgerlive%3Dtrue`.

**Example**:

```
https://sell.provider.widget.com?[accountId]=ua11-…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[cryptoAmount]=0.04
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permission

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contains at least those permissions request:

```json copy
"permissions": [
  "account.list",
  "currency.list",
  "custom.exchange.start",
  "custom.exchange.complete",
  "custom.exchange.error",
]
```

## Key Generation for Production and Test Environments

To ensure secure communication, you must generate two sets of keys: one for the production environment and one for the test environment. Follow the steps below to generate these keys:

# Testing with the Development Key

After submitting [your keys](/docs/ledger-live/exchange/sell/providers-backend#generate-privatepublic-key) to us and once the CAL team has successfully integrated them, you can proceed to test your integration in .

### Steps to Test in Ledger Wallet

1. Open the **Settings** menu in .
2. Navigate to the **Developer** tab.
3. Locate the setting labeled **Exchange in Test Partner Mode**.
4. Enable this setting to activate the test environment.

![Payload and Payload Signature generation diagram](/exchange/exchange-dev-mode.png)

With this mode enabled, you can verify the functionality of your keys and ensure everything is working as expected in the test environment.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/providers-test-and-submit -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell/redoc-api -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/sell -->

---
title: Sell integration overview
category: explanation
---

# Sell integration overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Sell integration lets users sell crypto assets for fiat currency directly inside . As a Sell provider, you handle the order, payout, and compliance; Ledger handles the secure transaction signing on the user's device and the embedded LiveApp experience.

To become a native Sell provider, you need to deliver three things:

1. **Backend API**: adapt your API to the Ledger Sell specification. Each sell order is secured with a cryptographic payload and signature: your backend generates a structured binary payload, signs it with your private key, and sends both to Ledger. You must also share your public key with Ledger so signatures can be verified.
2. **LiveApp**: a web application that loads inside . It uses the Ledger Exchange Services Kit alongside the Wallet API to initiate and track sell orders. The LiveApp receives the quote the user entered in the wallet as query parameters, so the user lands directly on a pre-filled sell flow. You also need to write or update your manifest and follow Ledger's UX requirements.
3. **Testing and submission**: test the full integration end-to-end using Developer Mode in , then submit your API, manifest, and public key for Ledger review.

> **Note:** Each component can be worked on in parallel. The integration only goes live once all three have passed review.

## What to read next

- [Architecture](sell/architecture) — flow overview showing how the components interact
- [Backend](sell/providers-backend) — the API endpoints, payload format, signature scheme, and key-pair requirements
- [LiveApp](sell/providers-liveapp) — LiveApp URL format, manifest requirements, Exchange Services Kit usage, and UX guidelines
- [Test & Submit](sell/providers-test-and-submit) — how to test end-to-end with Developer Mode and submit for review
- [Code examples](sell/code-examples) — payload generation and encoding examples in multiple languages

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/detailed-technical-flows -->

---
title: Detailed Technical Flows
category: reference
---

# Detailed Technical Flows

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

## Overview diagram

This is a [C4 diagram](https://c4model.com/) that describes an overview of the exchange during the swap process.

![Swap C4 diagram](/exchange/swap-light-C4.png)

> **Note:** Although the provider's LiveApp is embedded inside , we describe it
> as running in a separate environment because it is sandboxed.

## Detailed transaction flow

Explanations about each step below the diagram.

![Swap transaction flow](/exchange/detailed-flow-2.png)

1. &#x20;opens the provider's LiveApp through a [deeplink](./providers-liveapp#deeplink). Example:

```
ledgerlive://discover/swapprovidername?quoteId=CC14E626-CF1B-4EDA-AF5E-766FFD5A3457&
fromAddress=bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq&
toAddress=0xb794f5ea0ba39494ce839613fffba74279579268&
fromAddressId=AF1A7BD4-6A9A-4491-A540-98B1C7AD2407&
toAddressId=6EA9F270-91C5-4832-9A44-2713F9A6F6F0
```

The `quoteId` sent is the one coming from a previous request to the `/quote` endpoint of the Provider's backend. This id is linked to the `fromCurrency` and `toCurrency` wanted by the user.

2. The provider's LiveApp starts Ledger's swap process through a call to ExchangeSDK method call: `swap`.

3. After asking the user to start the process, Ledger's Swap Service will call the Provider's backend to generate and sign the `payload`. The backend will also returns a `swapId`, for [status tracking purpose](#check-swap-status-flow).

4. The Provider's backend will generate the payload with Ledger's currency id. This part is important as Ledger's device only knows Ledger's referential currency.

5. The Provider's backend will sign the payload with its private key. The public part must be previously sent to Ledger and must use secp256k1 curve.

6. As soon as the user signs the transaction within his Ledger's device,  will broadcast the transaction.

7. The `transactionId` is returned in the response of the `swap` method, called by the LiveApp.

8. The LiveApp should call back  with a deeplink. Example: `ledgerlive://swap?status=COMPLETED&swapId=123`

## Display quote information to user

![Quote information flow](/exchange/detailed-flow-1.png)

[Details on the quote API needed](./redoc-api#operation/postQuote).

## Check swap status flow

![Check swap status flow](/exchange/detailed-flow-3.png)

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/device-flow -->

---
title: Device transaction approval 
category: reference
---

# Device transaction approval

**Input**:  The user clicks on the “swap” button.

**Output**: The swap method from ExchangeSDK is called. During this call, the partner's service will be called to build and sign the binary payload.

This payload contains the informations for the swap to be performed including:

- **Payin\_address**: the partner address to receive payment
- **Refund\_address**: the client address to receive back the payment funds in case the provider is not able to execute the swap for some unpredictable reason
- **Payout\_address**: the client address to receive the money resulting from a successful swap
- **Currency\_from**: set to value of payloadCurrencyFrom from the /swap API request
- **Currency\_to**: set to value of payloadCurrencyTo from the /swap API request
- **Amount\_to\_provider**: the amount of currency\_from that the provider expects to receive from the client
- **Amount\_to\_wallet**: the amount of currency\_to that the provider agrees to send to the client in exchange from amount\_to\_provider. This amount must also include the network fees that the provider will pay to send the crypto to the user.
- **Device\_transaction\_id**: the swap transaction nonce provided by the client at initialization (must be set to value of nonce from the API request)

More detail [here](../integration/providers-backend/#payload--signature).

## Transaction approval flow

1. The user is asked first to unlock their Ledger device to access
2. The user is asked then to open the app exchange on their Ledger device
3. The user is redirected to the Confirmation drawer with information sent from the partner payload
4. The user checks if the information displayed on the Ledger device is the same as in the drawer
5. The user approves the transaction on his Ledger device. Transactions are broadcasted on the  blockchain.
6. The partner receives the amount and performs the swap

| Confirmation modal                                              | Device display                                                        |
| --------------------------------------------------------------- | --------------------------------------------------------------------- |
| Swap: Amount of tokens to send (Initial amount)                 | Send: Amount of tokens to send (Initial amount)                       |
| Receive: Amount of destination token credited (Credited amount) | Get estimated: Amount of destination token credited (Credited amount) |
| Provider: name of the partner                                   |                                                                       |
| Network fees: Network fees from Ledger account to partner       | Fees: Network fees from Ledger account to partner                     |
| Source: source account name                                     |                                                                       |
| Destination: Destination account name                           |                                                                       |

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/edge-cases -->

---
title: Edge cases
category: reference
---

# Edge cases

The standard happy-path of a swap is described in [Quote display and user preferences](./quote) and [Transaction status](./transaction-status). This page lists the edge cases a partner integration must handle, with the contracts each side is expected to honour.

For the meaning of terms used here (`payinNetworkFees`, fixed/floating quote, OnHold, …) see the [Exchange glossary](../../glossary).

## Refund: transaction cannot complete

The user has sent the FROM crypto to the partner but the swap can no longer be completed (for example the destination side fails). The partner sends the funds back to the user's source address.

| Behaviour           | Detail                                                                                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Funds returned      | Partner refunds the FROM crypto, minus `payinNetworkFees`.                                                                                                        |
| User-visible status | Maps to **Refunded** in [transaction status](./transaction-status#status), final and not retried.                                                                 |
| Partner guidance    | Refuse swaps where the input amount does not cover `payinNetworkFees` at least twice over, otherwise the refund will arrive with a near-zero or negative balance. |

## OnHold: extra information needed from the user

The partner has received the funds but cannot complete the swap until the user provides additional information (for example a KYC step triggered by the amount or destination). The funds are not at risk; they are paused on the partner's side.

| Behaviour        | Detail                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| Display          | Ledger Wallet shows the transaction as **OnHold** in the [history tab](./transaction-status#status).      |
| Action           | The user must contact the partner's support, using the **Swap ID** the partner returned at swap creation. |
| Partner guidance | Surface the contact channel on the partner's status page so it is one click away from the Swap ID.        |

## Quote unavailability

Before showing a quote, Ledger Wallet calls the partner's quote endpoint. The endpoint must reply with one of the [Region / Token / Amount checks](./quote#output) so the right error message is surfaced. Specifically:

- **Region NOT AVAILABLE**: the user's region is unsupported by this partner.
- **Token NOT AVAILABLE**: the FROM/TO pair is unsupported.
- **Amount TOO LOW** / **TOO HIGH**: the input amount is outside the partner's bounds.

If the partner does not reply within **5 seconds**, the partner's quote is dropped from the result list. The user can either trigger a new quote or wait for another partner.

## Fixed quote expiry

A **fixed** quote must be guaranteed for at least 60 seconds. If the user takes longer than the partner's window to confirm on the device, the quote becomes invalid and Ledger Wallet returns the user to the quote selection step. The partner must then return a fresh quote, and never silently re-rate at acceptance time.

## Floating quote slippage

A **floating** quote is not guaranteed. The user can receive less than the displayed amount according to market fluctuations, but the partner must enforce a maximum slippage so the executed rate cannot drift arbitrarily far. Surface this maximum slippage in the partner's UI so the user knows the worst-case receiving amount before signing.

## Single sign-on across Buy and Swap

If the same partner is integrated in both Buy and Swap (or other Exchange flows), a user who logs in for Buy is expected to remain logged in for Swap during the session window the partner sets, and vice versa. Asking the user to log in twice in the same Ledger Wallet session is an integration bug.

## See also

- [Quote display and user preferences](./quote): how quotes are computed and displayed.
- [Transaction status](./transaction-status): definitive list of status values (Pending, OnHold, Expired, Finished, Refunded).
- [Exchange glossary](../../glossary): term definitions used on this page.
- [`LedgerHQ/app-exchange`](https://github.com/LedgerHQ/app-exchange): device-side Exchange application.
- [`LedgerHQ/dale`](https://github.com/LedgerHQ/dale): translates Exchange APDUs/RAPDUs to plain text for diagnosing failed swaps.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/partner-live-app -->

---
title: Partner LiveApp
category: reference
---

# Partner LiveApp

When the user selects a quote among partners and clicks on the exchange to access the selected partner’s app, the user is redirected to the LiveApp (embedded partner web app). The LiveApp is displayed in the LL browser as a webview.

## Partner LiveApp flow

![Transaction flow](/exchange/partner-flow.png)

### Summary screen before login

The user is first redirected to a summary screen to check their transaction information.

Following information is displayed:

- **Swap**: The input amount in cryptocurrency to swap
- **Receive**: The output amount in cryptocurrency to receive
- **Slippage** (only valid for floating rates): The acceptable slippage up to which a refund is requested. Slippage can either be fixed by the partner and/or set by the user
- **Fee**: The breakdown of the transaction (withdrawal fee, partner fee, Ledger fee)
- **To account**: The account name on which the user will receive the cryptocurrency
- **Account address**: The address of the account on which the user will receive cryptocurrency

The user cannot change their choice on this page. For any change, they need to come back to the  swap app.

To make sure the user has the last up to date quote, a timer must be set to update the quote at least every 10 seconds.

### Login screen

The login is on the summary screen. It allows the user to log in with email, password or OTP depending on the partner policy. If the user is already logged in, this step is passed.

The login page is on the partner LiveApp side only, and not handled by Ledger.

### KYC screen

If a KYC is needed and the user has not performed it yet, the KYC onboarding must be included in the partner LiveApp.

The KYC process is on the partner LiveApp side only, and not handled by Ledger.

### Summary screen after login

After the user completes login and KYC, they are redirected to the summary screen with an updated quote.

## UX

### Design

The design choices belong to the partner but some guidelines need to be followed to make sure that the UX is clear for the user.

As such, a design guideline can be found [here](https://www.figma.com/proto/hx4Sxd5WRuTls5gM0hft76/LIVE-APP-%2F-Swap-provider%27s-flow?page-id=3865%3A60210\&node-id=3867-69274\&viewport=4418%2C3010%2C1\&scaling=scale-down\&starting-point-node-id=3867%3A72294).

### Navigation

The partner provides navigation inside their app, so users can navigate from one page to another. We recommend the partners have clear Call-To-Action buttons:

- To go back to the previous page
- To validate a screen and go forth in the process

Users can leave a partner LiveApp by clicking on the “X” button in the navigation bar. This action:

- Closes the partner LiveApp
- Brings the user back to the swap page with
  - Last source and destination accounts
  - Last source amount

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/quote -->

---
title: Quote display and user preferences
category: reference
---

# Quote display and user preferences

## Input

To chose a swap service, the user selects:

1. A source cryptocurrency and a source [account](../glossary)
2. An amount from the source account to swap
3. The destination cryptocurrency and the destination account

## Output

According to the input amount, the partner's API is called to get a quote and check several conditions:

- Region  (AVAILABLE / NOT AVAILABLE)
- Token (AVAILABLE / NOT AVAILABLE)
- Amount (TOO LOW / TOO HIGH)

If all of the above conditions are validated, the partners are displayed in  with the following information. Between several CEX offers, `amountFrom` and network fee being the same, quotes are sorted by `amount to`, the first "best value" quote being the one offering the greatest `Receiving amount`:

1. Network fees to send crypto to partners  - payinNetworkFees
2. Partner quote
   - **a.** Partner image
   - **b.** Partner name
   - **c.** Registration policy of the partner : Needed / Not needed
   - **d.** Exchange rate of the current swap, after all fees are applied: ex : 1 ETH = 0.0549919 BTC
   - **e.** Fixed or Floating: When it is fixed, the quote is guaranteed. The user must accept the quote within a certain amount of time (the quote must be guaranteed for at least 60 seconds). When it is floating, the quote is not guaranteed. The user can receive less than the quote according to the market fluctuation but should be protected against a maximum slippage defined by the partner
   - **f.** Receiving amount: ex = want to Swap 0.04301 ETH, receiving 0.0023652 BTC

   - **g.** time out = 5s. partner must reply in less that 5s, otherwise the quote is not displayed in the quote results. The user needs to trigger a quote again, or wait for timeout

## User Preferences

The user can use filters and and change the network fee strategy to find the swap service fit to their need and preferences.

### Fees

The user can change network fees according to the speed of the transaction:

- Slow
- Medium
- Fast

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow/transaction-status -->

---
title: Transaction status
category: reference
---

# Transaction status

As a swap is done with a centralized entity, some part of the swap is done off-chain.
As such, the user must be able to follow the status of the swap to avoid having them in a situation where they do not know what is happening with their transaction. Therefore, the user can follow the status on the transaction in an history tab on Ledger.

## History tab

The history tab contains the swap transactions for a given  instance.

The following information is displayed to the user:

- Date of Swap and time
- Partner name
- Source account
- Destination account
- Amount of destination token credited
- Amount of source token deducted
- Swap status

By clicking on a given swap, more information is displayed:

- **Provider**: Link to the provider’s website
- **Swap ID**: This information is generated by the service provider and sent back to Ledger backend at the swap creation. This ID must be used by the user if they need to contact the service provider's support.
- **Status**: Detail of Status in the next section.
- **Date**: Date of the Transaction
- **From**: Name of the source account
- **Initial amount**: Amount of token sent
- **Origin address**: Address of the source account
- **To**: Name of the destination account
- **Credited amount**: Amount of destination token credited
- **Provider address**: Destination address of the provider

An url will be made available to the user to get more information about the swap transaction.
You should provide this url to Ledger, accepting the following query parameters:

- **swapId**: Swap ID

## Status

Users can check the status of the swap transaction in the history tab.  backend calls the service provider with the Swap ID to get the status for each transaction (until the transaction is “FINISHED”).

The statuses are:

1. non final

- **Pending**: Transaction is ongoing
- **OnHold**: Provider has received funds but funds on transaction hold on provider’s side

2. final (can’t be changed)

- **Expired**: User’s transaction has failed. funds stay in their wallet
- **Finished**: Transaction completed and fund sent
- **Refunded**: Funds are back in user’s wallet

You can add more detailed statuses (KYC, swap withdrawal failure, network congestion, refund failure, etc) by providing a mapping of your status along with the two status above.

## Workflow for transaction status between Ledger and the service provider

While the transaction is performed, Ledger polls the service provider for status updates. Initially, the transaction is pending. The goal is to have the same status as above for clarity.

![Transaction flow](/exchange/transaction-status.jpg)

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/flow -->

# Swap: CEX integrated as a LiveApp

Our goal is to offer the best swap experience for our users in , by providing competitive quotes and security.

To offer our centralize exchange partners the best time-to-market and and our users the best swap experience, we have built an hybrid solution:

- Native swap marketplace: An aggregator in  listing our partners depending on the region, token coverage and prices.
- Partner Web app: A LiveApp experience (embedded web app) where users interact with the partner web app in , once they want to finalize the swap. The transaction is performed with ExchangeSDK.

This section of the documentation explains how the swap feature is displayed to the user in  and how your web app is integrated into this hybrid solution.

## Full transaction flow

![Transaction flow](/exchange/live-app-flow.png)

- **[Quote display and user preferences](./flow/quote)**
- **[Partner LiveApp](./flow/partner-live-app)**
- **[Device transaction approval](./flow/device-flow)**
- **[Transaction status](./flow/transaction-status)**
- **[Edge Cases](./flow/edge-cases)**
- **[Detailled Technical Flows](./flow/detailed-technical-flows)**

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/providers-backend -->

# Backend

## Endpoints needed for Swap

In order to communicate with Ledger's backend, you must provide standardised APIs for Ledger's SWAP aggregator services to call.

> **Note:** You will find all the information regarding the SWAP endpoints [here](./redoc-api), as well as additional details on some endpoints below.

There are 5 main endpoints needed for the swap:

- To get the list of available currencies: [/currencies](./redoc-api#operation/getCurrencies).
- To get the list of tradable pairs: [/pairs](./redoc-api#operation/getPairs).
- To query a rate: [/quote](./redoc-api#operation/postQuote).
- To create a signed swap binary payload as Fixed trade method [/swap/fixed](./redoc-api#operation/postSwapFixed).
- To create a signed swap binary payload as Float trade method [/swap/float](./redoc-api#operation/postSwapFloat).
- To query a swap status: [/status](./redoc-api#operation/getStatus).
- To push real-time transaction status updates to Ledger: [/webhook/\{swapId}/status](./redoc-api#operation/statusUpdate).

Additional Details: GET /pairs

This endpoint is not required if all permutations returned by [/currencies](./redoc-api#operation/getCurrencies) are supported.

**Fixed quote**: The quote price is guaranteed until execution (or until end of quote validity period).

**Float quote**: The quote price is indicative only, real price is computed at execution time.

Additional Details: POST /quote

All fees are expressed in output currency. For example, during a ETH to USDT on ethereum swap, the fees are expressed in USDT on ethereum.

Some requirements about the **/quote** endpoint:

- The quote must work without user auth. It can require a Ledger auth.
- The quote must be valid long enough (at least a few minutes).

Additional Details: POST /swap

Your Protobuf message should have the following structure:

```go copy
syntax = "proto3";
package ledger_swap;

message NewTransactionResponse {
    string    payin_address = 1;
    string    payin_extra_id = 2;
    string    refund_address = 3;
    string    refund_extra_id = 4;
    string    payout_address = 5;
    string    payout_extra_id = 6;
    string    currency_from = 7;
    string    currency_to = 8;
    bytes     amount_to_provider = 9;
    bytes     amount_to_wallet = 10;
    string    device_transaction_id = 11; // Legacy nonce, no need to give a value
    bytes     device_transaction_id_ng = 12; // nonce
}
```

Explanation of each fields:

- `payin_address`: provider address to receive payment
- `payin_extra_id`: eventual memo for the payment (stellar payment, for instance)
- `refund_address`: client address to receive back the payment funds in case the provider is not able to execute the swap for some unpredictable reasons
- `refund_extra_id`: eventual memo for the payment (stellar payment, for instance)
- `payout_address`: client address to receive the money resulting from a successful swap
- `payout_extra_id`: eventual memo for the payment (stellar payment, for instance)
- `currency_from`: must be set to value of `payloadCurrencyFrom` from the [/swap API request](#post-swap)
- `currency_to`: must be set to value of `payloadCurrencyTo` from the [/swap API request](#post-swap)
- `amount_to_provider`: amount of `currency_from` that the provider expects to receive from client
- `amount_to_wallet`: amount of `currency_to` that the provider agrees to send to the client in exchange from `amount_to_provider`. This amount must also include the network fees that the provider will pay to send the crypto to the user.
- `device_transaction_id`: swap transaction nonce provided by client at initialization (must be set to value of `nonce` from the API request) - this is a legacy property, only used by historical parter
- `device_transaction_id_ng`: swap transaction nonce provided by client at initialization (must be set to value of `nonce` from the API request)

Amounts must be in the lowest unit of the coin, encoded into a 16 bytes array in big endian.

- 1 **BTC** would be `0x5F5E100` (100000000 in hexadecimal). The smallest unit is a **satoshi** which is `10^-8` **BTC**.
  So multiply 1 **BTC** by `10^8` → `0x5F5E100`.
  And `0x5F5E100` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x05, 0xF5, 0xE1, 0x00]`.
- 2 **ETH** would be `0x1BC16D674EC80000` (or 2000000000000000000). The smallest unit is a **wei** which is `10^-18` **ETH**.
  So multiply 2 **ETH** by `10^18` → `0x1BC16D674EC80000`.
  And `0x1BC16D674EC80000` encoded into a 16 bytes array in big endian is `[0x00, ... 0x00, 0x1B, 0xC1, 0x6D, 0x67, 0x4E, 0xC8, 0x00, 0x00]`.

You also should ensure the following fields length limitations :

```
ledger_swap.NewTransactionResponse.payin_address max_size:63;
ledger_swap.NewTransactionResponse.payin_extra_id max_size:81;
ledger_swap.NewTransactionResponse.refund_address max_size:63;
ledger_swap.NewTransactionResponse.refund_extra_id max_size:20;
ledger_swap.NewTransactionResponse.payout_address max_size:63;
ledger_swap.NewTransactionResponse.payout_extra_id max_size:20;
ledger_swap.NewTransactionResponse.currency_from max_size:10;
ledger_swap.NewTransactionResponse.currency_to max_size:10;
ledger_swap.NewTransactionResponse.amount_to_provider max_size:16;
ledger_swap.NewTransactionResponse.amount_to_wallet max_size:16;
ledger_swap.NewTransactionResponse.device_transaction_id max_size:11;
ledger_swap.NewTransactionResponse.device_transaction_id_ng max_size:32;
```

Additional Details: GET /status
Explanation of the different output `status`:

- `FINISHED`: Trade has been completed successfully (user has received payout transaction).
- `EXPIRED`: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
- `ON_HOLD`: Trade has been put on hold (eg: for KYC reasons). User must contact support.
- `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction)
- `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
- `UNKNOWN`: Trade is in unknown state. User must contact support.

## Real-time Status Updates

To keep the user's transaction history up to date in real-time, Ledger hosts a webhook endpoint [/webhook/\{swapId}/status](./redoc-api#operation/statusUpdate) that you call whenever the status of a transaction changes. This endpoint is provided and hosted by Ledger: Ledger gives you the base URL and the `x-api-key` shared secret used to authenticate your calls.

Additional Details: POST /webhook/\{swapId}/status

**Authentication**: every call must include your provider-specific `x-api-key` header. A missing or invalid key is rejected with `401`. The same `401` is returned for an unknown or unsupported provider, so the response cannot be used to discover which providers exist.

**Asynchronous processing**: a `200` response means the update was authenticated, validated and **queued** (the body is `message: queued`); it does not mean the update has already been persisted. Ledger applies it shortly after, and only while the swap is still in a non-final status.

**`providerStatus`**: send your own transaction status string, typically the same value your [GET /status](./redoc-api#operation/getStatus) endpoint returns. Ledger translates it with the same per-provider mapping it uses when polling your `/status` endpoint, so it resolves to one of the internal states below. A value Ledger cannot map is rejected with `422` and nothing is persisted (an unrecognized status never regresses a live swap).

Internal states a `providerStatus` can resolve to:

- `FINISHED`: Trade has been completed successfully (user has received payout transaction).
- `EXPIRED`: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
- `ON_HOLD`: Trade has been put on hold (eg: for KYC reasons). User must contact support.
- `PENDING`: Trade is in progress (provider is waiting to receive payin transaction, or user is waiting to receive payout transaction).
- `REFUNDED`: Trade has been cancelled, refund transaction has been successfully received by user.
- `UNKNOWN`: Trade is in unknown state. User must contact support.

Request body fields:

- `providerId` (required): your provider id; used to authenticate the call and to select the status mapping. It must match the provider that owns the swap.
- `providerStatus` (required): your transaction status string (see above).
- `amount` (required): final amount delivered to the user, in the output currency. Required because once a webhook finalizes a swap it leaves the polling set, so a missing amount would never be backfilled.
- `providerFees` (optional): fees paid to the provider, converted to the output currency.
- `networkFees` (optional): referral / extra fee, converted to the output currency.
- `payinTransactionId` (optional): on-chain payin transaction hash.
- `transactionHash` (optional): on-chain payout transaction hash.

Error responses use a flat shape (an `error` field, plus `transactionId` on `404`):

- `401` `unauthorized`: missing or invalid `x-api-key`, or an unknown / unsupported provider.
- `404` `transaction not found`: no swap matches the `swapId` / `providerId` (the `swapId` is echoed back in `transactionId`).
- `405` `transaction can no longer be updated`: the swap is already in a final status.
- `422` `unknown status`: `providerStatus` could not be mapped; nothing is persisted.
- `500` `internal error`: an unexpected failure occurred.

> **Note:** Ledger also polls your [GET /status](./redoc-api#operation/getStatus) endpoint as a fallback mechanism. However, calling the webhook is strongly recommended for faster, real-time updates to the user's transaction history.

[//]: # "Info needed to be exchange with the provider, but not out loud publicly"

[//]: # "**IP address checking** "

[//]: # "Additionally, we also need a way to know if a user will be able to perform a coin swap given his IP."

[//]: # "Our back-end can adapt to how you decide to do this, but we recommend you use a dedicated endpoint. Our back-end will send the user's IP address to that endpoint, without logging it. In response, your endpoint should tell us if the trade is accepted or rejected."

## Payload & Signature

Here is a little diagram to explain how the `payload` and the `signature` are generated:

![Payload and Payload Signature generation diagram](/exchange/payload-signature-generation-swap.png)

- `payload`: the trade parameters are assembled in a [protobuf](https://developers.google.com/protocol-buffers) message. This message is [binary encoded](https://developers.google.com/protocol-buffers/docs/encoding) to produce a Byte Array. This Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), resulting `payload` field.
- `signature`: The payload is signed using [ES256](https://ldapwiki.com/wiki/Wiki.jsp?page=ES256) provider's private key, generating a Byte Array. This Signature Byte Array is then [base64Url encoded](https://en.wikipedia.org/wiki/Base64), producing the Signature field. ([more details](#jws-signature)).

### Signature usage

- Payload and Signature\
  From the provider to . The payload is a protobuf message containing the trade data. It is generated by the provider and sent to .

```go copy
type Payload struct {
  payin_address,      // address (of provider)
  refund_address,     // address (of customer)
  payout_address,     // address (of customer)
  currency_from,      // currency name (to provider)
  currency_to,
  amount_to_provider, // amount (to provider)
  amount_to_wallet,   // amount (to customer)
  device_transaction_id,
  device_transaction_id_ng,
  …
}
R, S := Sign(payload, privKey)
```

- Validate\
  Exchange app checks and validates the payload (signature and content).

```go copy
// Compare nonce in payload
Verify((R, S), payload, pubKey)
```

- Display\
  Exchange app requests approval to the user by displaying the operation summary on screen.

```c copy
Validate?
Send currency_from amount_to_provider
Receive currency_to amount_to_wallet
```

## Error Codes Reference

REGION\_RESTRICTED\_ERROR

- HTTP status code 451
- Endpoints: `/quote`, `/swap`
- Description: When the user's IP address is in a restricted region.

FROM\_CURRENCY\_MINIMUM\_AMOUNT\_ERROR

- HTTP status code 400
- Endpoints: `/quote`
- Context: \{ minSwapAmount: string }
- Description: When the amount to swap is below the minimum amount.
- Response

TO\_CURRENCY\_MAXIMUM\_AMOUNT\_ERROR

- HTTP status code 400
- Endpoints: `/quote`
- Context: \{ maxSwapAmount: string }
- Description: When the amount to swap is above the maximum amount.

SWAP\_PAIR\_NOT\_FOUND\_ERROR

- HTTP status code 404
- Endpoints: `/quote`
- Description: When the pair is not found.

CURRENCY\_REGION\_RESTRICTED\_ERROR

- HTTP status code 451
- Endpoints: `/quote`
- Description: When the currency is in a restricted region.

NO\_DEPOSIT\_WALLET\_ERROR

- HTTP status code 400
- Endpoints: `/swap`
- Description: When the deposit wallet is not available.

CURRENCY\_FROM\_NOT\_FOUND\_ERROR

- HTTP status code 404
- Endpoints: `/swap`
- Description: When the currency from is not found.

CURRENCY\_TO\_NOT\_FOUND\_ERROR

- HTTP status code 404
- Endpoints: `/swap`
- Description: When the currency to is not found.

SWAP\_QUOTE\_NOT\_FOUND\_ERROR

- HTTP status code 404
- Endpoints: `/swap`
- Description: When the swap quote is not found.

TRANSACTION\_NOT\_FOUND

- HTTP status code 404
- Endpoints: `/status`, `/webhook/{swapId}/status`
- Description: When the transaction is not found. The current backend returns a not-found response.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/providers-currencies -->

---
title: Supported currencies
category: reference
---

# Supported currencies

This page lists the blockchains that Ledger's Swap integration supports as of this writing. Use it to confirm a currency is available before referencing it in a `/quote` or `/swap` request against the [Swap backend API](./providers-backend).

> **Note:** This list evolves as new blockchains are integrated into . If a currency you need is missing, check with your Ledger integration contact before assuming it is unsupported.

## Blockchain supported

- bitcoin
- bitcoin\_cash
- bitcoin\_gold
- bsc
- dash
- digibyte
- dogecoin
- ethereum
- litecoin
- polkadot
- polygon
- qtum
- ripple
- solana
- stellar
- tezos
- zcash
- zencash

## Cross-references

- [Swap integration overview](../swap): the full set of deliverables for a Swap provider
- [Backend](./providers-backend): the `/currencies` and `/pairs` endpoints that must reflect the currencies you support
- [API reference](./redoc-api): full request and response schemas for every Swap endpoint

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/providers-liveapp -->

# Provider's LiveApp

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As explained in the [Swap Integration](../swap) page, you need to modify your LiveApp with some particularities compared to the one that can be found in the Discover section.

Your LiveApp must:

- Use the [Ledger Exchange Services Kit](https://github.com/LedgerHQ/exchange-sdk), in addition to the Wallet API.
- Respond to specific LiveApp URLs in order to adapt to the flow inside .
- Have a modified, slightly more complex, Manifest file.
- Follow specifics flow/ux requirements.

## Ledger Exchange Services Kit

To learn how to create (or embed if already existing) your user interface for the swap, please follow the [Discover documentation](../../discover/getting-started).

Your LiveApp will interact with , through the [ExchangeSDK](https://github.com/LedgerHQ/exchange-sdk), with the corresponding method.

You will need to set up the SDK with your `providerId` attributed upon request by Ledger.

```js copy
const exchangeSDK = new ExchangeSDK("yourProviderId");
```

### SWAP Method

This method will need you to provide the following parameters:

- `quoteId`: the id coming from your system and [forwarded to your LiveApp](./providers-liveapp) as a query parameter
- `fromAccountId`: user's account id, [previously given to the LiveApp](./providers-liveapp) as a query parameter
- `toAccountId`: user's account id, [previously given to the LiveApp](./providers-liveapp) as a query parameter
- `fromAmount`: amount that will be sent from `fromAddressId` to `payinAddress`
- `feeStrategy`: `SLOW`, `MEDIUM`, `FAST` or `CUSTOM`.
- `rate`: rate differences in the pair, [previously given to the LiveApp](./providers-liveapp) as a query parameter

```js copy
exchangeSDK.swap({
  quoteId: "1234",
  fromAccountId: "07AB5930-C73A-433F-A2FA-920640AF3A02",
  toAccountId: "76A239EB-1C2A-4237-B942-CA87472106EB",
  fromAmount: "12.3",
  feeStrategy: "SLOW",
  rate: 0.7555,
});
```

## LiveApp URL

The LiveApp needs to respond to an URL with some parameters. LiveApp URLs are used to open your LiveApp with the quote values that the user already entered in .

The LiveApp URL format is already fixed and will depend on the information you provided inside your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) (ex: `ledgerlive://discover/swapprovidername`).

- `quoteId`: The id retrieved by Ledger's backend during a quote request.
- `fromAmount`: The amount of currency.
- `fromAccountId`: The user's account id in  repository.
- `toAccountId`: The user's account id in  repository.
- `rate`: the rate differences in the pair.
- `feeStrategy`: `SLOW`, `MEDIUM`, `FAST` or `CUSTOM`.
- `initFeeTotalValue`: initial transaction total fee.
- `customFeeConfig`(optional, required for `CUSTOM` feeStrategy): Custom fee configuration in case the strategy is of type `CUSTOM`. The key-value object is encoded in URI parameter.
- `ledger-transaction-id`: id used by ledger to track transactions and their completion statuses.
- `fiatCurrencyId`: The fiat currency id used as reference for the quote.
- `theme`: The theme used in .
- `displayLanguage`: The language used in .

**Example**:

```
ledgerlive://discover/swapprovidername?quoteId=1234&fromAmount=0.09&fromAccountId=82f48c06-6170-536e-a21b-56b30b02b58d&toAccountId=c0c4493e-fc4b-50b6-b1a0-566f1a751521&rate=79.09405555555555555556&feeStrategy=CUSTOM&initFeeTotalValue=878198522989412&customFeeConfig=%7B%22maxFeePerGas%22%3A%2212000000000%22%2C%22maxPriorityFeePerGas%22%3A%221000000000%22%2C%22userGasLimit%22%3Anull%2C%22gasLimit%22%3A%2221000%22%7D
```

> **Note:** Ledger needs to know how to send referral information through the widget.

## Manifest Permission

Your [LiveApp manifest](../../../../docs/discover/wallet-api/appendix/manifest) should contains at least those permissions request:

```json copy
"permissions": [
  "account.list",
  "currency.list",
  "custom.exchange.start",
  "custom.exchange.complete",
  "custom.exchange.error",
]
```

## Flow/UX requirements

Please refer to the [Flow Breakdown](./flow) section for more information.

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/providers-test-and-submit -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap/redoc-api -->



---

<!-- https://developers.ledger.com/docs/ledger-live/exchange/swap -->

---
title: Swap integration overview
category: explanation
---

# Swap integration overview

> **Key takeaway:** ☞   The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

The Swap integration lets users exchange one crypto asset for another directly inside . As a Swap provider, you handle the quoting, route finding, and order execution; Ledger handles the device-verified transaction signing and the embedded exchange experience.

> **Note:** Non-KYC exchanges that do not need a custom UI can use a pure API integration and skip the LiveApp step entirely. If this applies to you, sections 1 (Backend) and 3 (Test & Submit) are what you need.

To become a native Swap provider, you need to deliver up to three things:

1. **Backend API**: adapt your API to the Ledger Swap specification. Each swap is secured with a cryptographic payload and signature: your backend generates a structured binary payload, signs it with your private key, and sends both to Ledger. You must also share your public key with Ledger so signatures can be verified.
2. **LiveApp** _(optional for non-KYC pure-API providers)_: a web application that loads inside . It uses the Ledger Exchange Services Kit alongside the Wallet API to display your swap UI and initiate transactions. The LiveApp receives the quote the user entered in the wallet as query parameters. You also need to write or update your manifest and follow Ledger's UX requirements.
3. **Testing and submission**: test the full integration end-to-end using Developer Mode in , then submit your API, manifest (if applicable), and public key for Ledger review.

## What to read next

- [Backend](swap/providers-backend) — the API endpoints, payload format, signature scheme, and key-pair requirements
- [LiveApp](swap/providers-liveapp) — LiveApp URL format, manifest requirements, Exchange Services Kit usage, and UX guidelines
- [Test & Submit](swap/providers-test-and-submit) — how to test end-to-end with Developer Mode and submit for review
- [Flow breakdown](swap/flow) — UX flows, advanced scenarios, and architecture diagrams
- [Supported currencies](swap/providers-currencies) — the list of currencies available for swapping

---

<!-- https://developers.ledger.com/docs/ledger-live/exchange -->

# Get your exchange services in Ledger Wallet

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

As a centralized exchange, it is possible to integrate your Swap/Sell/Buy/Fund services into  as a native function of , thus offering security, ease and accessibility to millions of users!

With this integration, your services will appear directly under the corresponding section (Buy/Sell, Swap, Card) of .

![Ledger Wallet screenshot](/exchange/screen-ledger-wallet-native-integration.png)

To see if this integration is a good fit for your service, please get in touch with Ledger beforehand.

> **Note:** There are two types of integration: - Autonomous first step integration: your
> LiveApp is accessible through the “Discover” section. For this integration,
> you can skip the API integration and refer to the [Discover](/docs/discover)
> section instead. - Main flow: your LiveApp can be integrated natively to
> . Better exposition but with additional API integration. More
> details in this section.

- **[Swap Integration](/docs/exchange/swap)** — />![]("/blockchain-cover.jpg")
- **[Sell Integration](/docs/exchange/sell)** — />![]("/blockchain-cover.jpg")
- **[Buy Integration](/docs/exchange/buy)** — />![]("/blockchain-cover.jpg")
- **[Earn Integration](/docs/exchange/earn)** — />![]("/blockchain-cover.jpg")
- **[Card Integration](/docs/exchange/card/sell-card)** — />![]("/blockchain-cover.jpg")

---

<!-- https://developers.ledger.com/docs/ledger-live/introduction -->

---
title: Ledger Wallet integrations
category: explanation
---

# Ledger Wallet integrations

> **Key takeaway:** ☞ The renaming of "Ledger Live" to "Ledger Wallet" and "wallet" (in the hardware sense) to "signer" is still in progress. This page may contain legacy references that will be updated.

&#x20;is the companion application through which users manage accounts, exchange assets, and interact with third-party services, all secured by their Ledger device. This section of the documentation gathers every path available to integrate a project with . Which path applies to you depends on what you are integrating and how deeply it needs to sit inside the wallet.

## Choosing an integration path

If you provide a **blockchain or a coin** and want users to hold, send, and receive it from the "Accounts" section of , you need an **Accounts integration**. This is the deepest form of integration: it requires a Ledger device application, a coin module in the  monorepo, and a signed agreement with Ledger before development starts, because it involves shipping code that runs on the device itself.

If you provide an **application or a service** that users should be able to open from within , such as a dApp, a Live App, or any tool that needs read or write access to the user's accounts, you need a **Discover integration** using the dApp Browser or the Wallet API. This path does not require a Ledger device application: your app runs as a web application loaded inside  and communicates with the user's accounts through the Wallet API.

If you are an **exchange, on-ramp, or card provider** and want to offer swap, sell, buy, or card services directly inside , you need an **Exchange provider integration**. This path combines a backend that implements Ledger's exchange specification with, in most cases, a Live App for the user-facing flow.

## What to read next

- [Accounts or Blockchain integration](./accounts/getting-started): add a blockchain or coin to the Accounts section; [fill in this form](https://docs.google.com/forms/d/e/1FAIpQLScc_luftAe3Y9f7Y89aGjCa-z3XPOf1cVfIEeOZzhgx71MYbQ/viewform?usp=sharing\&ouid=107637591620972246516) to start. Do not begin development before signing an agreement with our teams.
- [Discover integration](./discover/getting-started): integrate a Live App or dApp using the Wallet API
- [Exchange provider integration](./exchange): integrate swap, sell, buy, or card services

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/api-reference -->

---
title: API reference
category: reference
---

# API reference

This page describes the public API of Ledger Wallet Provider: `initializeLedgerProvider` from `@ledgerhq/ledger-wallet-provider`, and `LedgerEIP1193Provider` from `@ledgerhq/ledger-wallet-provider-evm`.

---

## `initializeLedgerProvider(options)`

Initializes the Ledger Wallet Provider and injects the UI components into the DOM. Registers blockchain providers for each factory you pass in `blockchainProviderFactories` that is also enabled in your partner dApp configuration (`dAppIdentifier`): EVM factory + Ethereum enabled → [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) / [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193); Solana factory + Solana enabled → [Wallet Standard](https://github.com/wallet-standard/wallet-standard). Without factories, no chain provider is registered. For chain-specific connect and signing examples, see [EVM](./blockchains/evm) and [Solana](./blockchains/solana).

**Signature**

```ts
function initializeLedgerProvider(
  options: InitializeLedgerProviderOptions
): () => void

type BlockchainFamily = 'ethereum' | 'solana'

type BlockchainProviderFactoryRegistration = {
  family: BlockchainFamily
  create: (core: CoreFacade, config: BlockchainConfig) => BlockchainProvider
}

type InitializeLedgerProviderOptions = {
  // Core
  apiKey?: string;
  dAppIdentifier?: string;
  loggerLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug';
  environment?: 'staging' | 'production';
  dmkConfig?: DeviceModuleOptions;
  blockchainProviderFactories?: BlockchainProviderFactoryRegistration[];

  // UI
  target?: HTMLElement;
  hideButton?: boolean;
  floatingButtonPosition?:
    | 'bottom-right'
    | 'bottom-left'
    | 'bottom-center'
    | 'top-right'
    | 'top-left'
    | 'top-center'
    | 'middle-right';
  floatingButtonTarget?: HTMLElement | string;
  walletTransactionFeatures?: Array<
    'send' | 'receive' | 'swap' | 'buy' | 'earn' | 'sell'
  >;
  transactionConfirmationNotification?: 'tooltip' | 'toast';

  // Development
  devConfig?: {
    stub?: {
      base?: boolean;
      account?: boolean;
      balance?: boolean;
      device?: boolean;
      web3Provider?: boolean;
      solanaProvider?: boolean;
      transactionHistory?: boolean;
    };
  };
};
```

See [Configuration](./configuration) for the full `options` reference with defaults and examples.

**Returns** a cleanup function. Call it to remove the UI components from the DOM and to unregister any providers that were registered for your partner configuration (for example the EVM `eip6963:requestProvider` listener and/or the Solana Wallet Standard wallet).

```ts
const cleanup = initializeLedgerProvider({ /* options */ })

// When unmounting (e.g. route change, app teardown):
cleanup()
```

> **Note:** If the browser does not support Web HID or Web Bluetooth, `initializeLedgerProvider` returns a no-op function without registering the provider or mounting any UI. See [Requirements](./requirements).

---

## `LedgerEIP1193Provider`

Implements the [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) Ethereum Provider JavaScript API for Ledger hardware signers. Import it from `@ledgerhq/ledger-wallet-provider-evm` (it is no longer re-exported from `@ledgerhq/ledger-wallet-provider`).

You obtain an instance via the `eip6963:announceProvider` event (see [EVM](./blockchains/evm)):

```ts
window.addEventListener('eip6963:announceProvider', (event: CustomEvent) => {
  const { provider } = event.detail // LedgerEIP1193Provider
})
window.dispatchEvent(new Event('eip6963:requestProvider'))
```

### Methods

#### `request(args): Promise<unknown>`

```ts
request({ method, params }: RequestArguments): Promise<unknown>
```

Makes a JSON-RPC request to the provider. For signing and account-selection methods, the provider queues the request while the Ledger UI is open and executes it when the UI closes. Rejects with a `ProviderRpcError` on failure.

For the full list of supported methods, see [Supported methods](#supported-methods).

#### `on(eventName, listener): this`

```ts
on<TEvent extends keyof ProviderEvent>(
  eventName: TEvent,
  listener: (args: ProviderEvent[TEvent]) => void,
): this
```

Registers an event listener. Returns `this` for chaining.

#### `removeListener(eventName, listener): this`

```ts
removeListener<TEvent extends keyof ProviderEvent>(
  eventName: TEvent,
  listener: (args: ProviderEvent[TEvent]) => void,
): this
```

Removes a previously registered listener. Returns `this` for chaining.

#### `isConnected(): boolean`

```ts
isConnected(): boolean
```

Returns `true` if the provider has a connected account.

#### `disconnect(code?, message?, data?): Promise<void>`

```ts
disconnect(code?: number, message?: string, data?: unknown): Promise<void>
```

Disconnects the provider, clears the selected account and chain, and fires a `disconnect` event. The `code` parameter follows the [CloseEvent status code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code) convention (default: `1000`).

---

### Supported methods

**Handled locally by the provider**

| Method                       | Description                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `eth_requestAccounts`        | Opens the Ledger UI for signer and account selection; returns the selected address |
| `eth_accounts`               | Returns the currently selected account address                                     |
| `eth_chainId`                | Returns the current chain ID as a hex string                                       |
| `eth_sendTransaction`        | Signs and broadcasts a transaction                                                 |
| `eth_signTransaction`        | Signs a transaction without broadcasting                                           |
| `eth_signRawTransaction`     | Signs a raw transaction                                                            |
| `eth_sendRawTransaction`     | Signs and broadcasts a raw transaction                                             |
| `eth_sign`                   | Signs a message                                                                    |
| `personal_sign`              | Signs a personal message ([EIP-191](https://eips.ethereum.org/EIPS/eip-191))       |
| `eth_signTypedData`          | Signs typed structured data ([EIP-712](https://eips.ethereum.org/EIPS/eip-712))    |
| `eth_signTypedData_v4`       | Signs typed structured data v4 (EIP-712)                                           |
| `wallet_switchEthereumChain` | Switches to a supported chain ID                                                   |

**Forwarded to node RPC**

| Method            | Description                         |
| ----------------- | ----------------------------------- |
| `eth_blockNumber` | Returns the current block number    |
| `eth_getBalance`  | Returns the balance of an address   |
| `eth_getCode`     | Returns the code at a given address |
| `eth_estimateGas` | Estimates gas for a transaction     |
| `eth_call`        | Executes a read-only call           |

### Events

| Event             | Payload type                      | Fires when                            |
| ----------------- | --------------------------------- | ------------------------------------- |
| `accountsChanged` | `string[]`                        | The selected account changes          |
| `chainChanged`    | `string` (hex chain ID)           | The active chain changes              |
| `connect`         | `{ chainId: string }`             | The provider connects with an account |
| `disconnect`      | `ProviderRpcError`                | The provider disconnects              |
| `message`         | `{ type: string; data: unknown }` | The provider emits a message          |

### Error codes

`request()` rejects with a `ProviderRpcError` whose `code` is one of the following:

| Code     | Name                  | When it occurs                                                                |
| -------- | --------------------- | ----------------------------------------------------------------------------- |
| `4001`   | `UserRejectedRequest` | User rejected the request or closed the modal                                 |
| `4100`   | `Unauthorized`        | Provider not connected, no account selected, or address mismatch              |
| `4200`   | `UnsupportedMethod`   | Method is not in the supported list                                           |
| `4900`   | `Disconnected`        | Provider is disconnected when a method that requires a connection is called   |
| `4901`   | `ChainDisconnected`   | Requested chain is not in the supported chain list                            |
| `-32602` | `InvalidParams`       | Invalid parameters (e.g. malformed typed data)                                |
| `-32603` | `InternalError`       | Internal error (e.g. provider busy, broadcast failed, blind signing disabled) |

---

## See also

- [Get started](./get-started) — install and initialize the provider
- [EVM](./blockchains/evm) — EIP-6963 discovery and EIP-1193 signing how-to
- [Solana](./blockchains/solana) — Wallet Standard connect and signing how-to
- [Configuration](./configuration) — full `initializeLedgerProvider` options reference
- [Requirements](./requirements) — browser and platform requirements
- [EIP-1193 specification](https://eips.ethereum.org/EIPS/eip-1193)
- [EIP-6963 specification](https://eips.ethereum.org/EIPS/eip-6963)

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/blockchains/evm -->

---
title: EVM with EIP-6963 and EIP-1193
category: how-to
---

# EVM with EIP-6963 and EIP-1193

This guide shows how to connect to Ledger Wallet Provider from an EVM dApp and sign messages or transactions through [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) discovery and the [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) provider API.

Ledger Wallet Provider registers an EIP-1193 provider when you call `initializeLedgerProvider` with the EVM factory **and** Ethereum is enabled in your partner dApp configuration (`dAppIdentifier`).

> **Note:** Complete [Get started](../get-started) first so `initializeLedgerProvider` runs in the browser (use a dynamic import in SSR frameworks). Install `@ledgerhq/ledger-wallet-provider-evm`, pass `createEvmBlockchainProvider`, and confirm with Ledger that Ethereum is enabled for your dApp. Then follow this page for EIP-6963 discovery and signing.

## Prerequisites

```bash
npm install @ledgerhq/ledger-wallet-provider @ledgerhq/ledger-wallet-provider-evm
```

Initialize once at application startup (see [Get started](../get-started) and [Configuration](../configuration)):

```ts
import { initializeLedgerProvider } from '@ledgerhq/ledger-wallet-provider'
import { createEvmBlockchainProvider } from '@ledgerhq/ledger-wallet-provider-evm'
import '@ledgerhq/ledger-wallet-provider/styles.css'

const cleanup = initializeLedgerProvider({
  dAppIdentifier: 'my-dapp',
  apiKey: 'your-api-key',
  blockchainProviderFactories: [
    { family: 'ethereum', create: createEvmBlockchainProvider },
  ],
})

// Call cleanup() when your app unmounts to unregister the EVM provider too.
```

## Supported methods

After connection, use `provider.request({ method, params })`. Methods handled locally by Ledger include:

| Method                                       | Purpose                                            |
| -------------------------------------------- | -------------------------------------------------- |
| `eth_requestAccounts`                        | Open the Ledger UI and return the selected address |
| `eth_accounts`                               | Return the currently selected account              |
| `eth_chainId`                                | Return the current chain ID (hex)                  |
| `personal_sign` / `eth_sign`                 | Sign a message                                     |
| `eth_signTypedData` / `eth_signTypedData_v4` | Sign EIP-712 typed data                            |
| `eth_signTransaction`                        | Sign a transaction without broadcasting            |
| `eth_sendTransaction`                        | Sign and broadcast a transaction                   |
| `wallet_switchEthereumChain`                 | Switch to a supported chain ID                     |

Read methods such as `eth_call` and `eth_getBalance` are forwarded to the node RPC. See [API reference](../api-reference) for the full list, events, and error codes.

## Discover and connect

Listen for EIP-6963 announcements, then request accounts:

```ts
import type { EIP6963ProviderDetail } from '@ledgerhq/ledger-wallet-provider-evm'

let provider: EIP6963ProviderDetail['provider'] | undefined

window.addEventListener('eip6963:announceProvider', ((event: CustomEvent<EIP6963ProviderDetail>) => {
  const { provider: announced, info } = event.detail
  if (info.name.toLowerCase().includes('ledger')) {
    provider = announced
  }
}) as EventListener)

window.dispatchEvent(new Event('eip6963:requestProvider'))

if (!provider) {
  throw new Error('Ledger EVM provider not found. Call initializeLedgerProvider first.')
}

const accounts = await provider.request({
  method: 'eth_requestAccounts',
  params: [],
}) as string[]

const account = accounts[0]
```

> **Note:** **Registration:** A family is registered only when you pass its factory **and** it is enabled in your dApp config. EVM factory + Ethereum enabled → EIP-6963 / EIP-1193. Solana factory + Solana enabled → Wallet Standard. Both → both surfaces from the same `initializeLedgerProvider` call. Account pickers are filtered by the requesting family (`eth_requestAccounts` only lists EVM-compatible accounts).

## Sign a message

```ts
const signature = await provider.request({
  method: 'personal_sign',
  params: ['Hello from my EVM dApp', account],
})
```

For EIP-712 typed data, use `eth_signTypedData_v4` with your typed-data payload. Signing opens the Ledger Wallet Provider UI so the user can confirm on their device.

## Sign a transaction

```ts
const signedTx = await provider.request({
  method: 'eth_signTransaction',
  params: [
    {
      from: account,
      to: '0x…',
      value: '0x0',
      // gas, data, chainId, …
    },
  ],
})

// `signedTx` is the signed raw transaction (you broadcast yourself if needed)
```

## Sign and send a transaction

```ts
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [
    {
      from: account,
      to: '0x…',
      value: '0x0',
    },
  ],
})
```

## Switch chain

```ts
await provider.request({
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: '0x1' }], // Ethereum mainnet
})
```

## Cleanup

Call the function returned by `initializeLedgerProvider` when your application unmounts. Cleanup removes the Ledger UI and unregisters any providers that were registered for your partner configuration.

```ts
const cleanup = initializeLedgerProvider({ /* options */ })

// Later:
cleanup()
```

## Troubleshooting

**The `eip6963:announceProvider` event never fires.**
Confirm `initializeLedgerProvider` ran in the browser before dispatching `eip6963:requestProvider`, that you passed `createEvmBlockchainProvider`, and that Ethereum is enabled for your `dAppIdentifier`. On unsupported platforms (no Web HID / Web Bluetooth), initialization is a no-op and no provider is registered — see [Requirements](../requirements).

**`request()` rejects with error code `4100` ("Unauthorized").**
Call `eth_requestAccounts` first, or the user disconnected. Request accounts again to reopen the Ledger UI.

**`request()` rejects with error code `-32603` and message "Ledger Provider is busy".**
Blocking requests (connect / sign) are handled one at a time. Wait for the current Ledger UI flow to finish before starting another.

## See also

- [Get started](../get-started) — install family packages and pass `blockchainProviderFactories`
- [Solana](./solana) — Wallet Standard connect and signing
- [Configuration](../configuration) — init options
- [API reference](../api-reference) — full EIP-1193 methods, events, and errors
- [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) / [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963)

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/blockchains/solana -->

---
title: Solana with Wallet Standard
category: how-to
---

# Solana with Wallet Standard

This guide shows how to connect to Ledger Wallet Provider from a Solana dApp and sign messages or transactions through the [Wallet Standard](https://github.com/wallet-standard/wallet-standard).

Ledger Wallet Provider registers a Solana Wallet Standard wallet when you call `initializeLedgerProvider` with the Solana factory **and** Solana is enabled in your partner dApp configuration (`dAppIdentifier`).

> **Note:** Complete [Get started](../get-started) first so `initializeLedgerProvider` runs in the browser (use a dynamic import in SSR frameworks). Install `@ledgerhq/ledger-wallet-provider-solana`, pass `createSolanaBlockchainProvider`, and confirm with Ledger that Solana is enabled for your dApp. Then follow this page for Wallet Standard discovery and signing.

## Prerequisites

```bash
npm install @ledgerhq/ledger-wallet-provider @ledgerhq/ledger-wallet-provider-solana
```

Initialize once at application startup (see [Get started](../get-started) and [Configuration](../configuration)):

```ts
import { initializeLedgerProvider } from '@ledgerhq/ledger-wallet-provider'
import { createSolanaBlockchainProvider } from '@ledgerhq/ledger-wallet-provider-solana'
import '@ledgerhq/ledger-wallet-provider/styles.css'

const cleanup = initializeLedgerProvider({
  dAppIdentifier: 'my-dapp',
  apiKey: 'your-api-key',
  blockchainProviderFactories: [
    { family: 'solana', create: createSolanaBlockchainProvider },
  ],
})

// Call cleanup() when your app unmounts to unregister the Solana wallet too.
```

Optional Solana packages for discovery and React hooks:

```bash
npm install @wallet-standard/app
# React helpers (optional):
npm install @solana/react @wallet-standard/react
```

Libraries such as `@solana/wallet-adapter` also discover Wallet Standard wallets with no extra Ledger wiring.

## Supported features

After connection, the Ledger Solana wallet exposes:

| Feature                                    | Purpose                                            |
| ------------------------------------------ | -------------------------------------------------- |
| `standard:connect` / `standard:disconnect` | Connect and disconnect accounts                    |
| `standard:events`                          | Listen for account / feature changes               |
| `solana:signMessage`                       | Sign an off-chain message (ed25519)                |
| `solana:signTransaction`                   | Sign a serialized transaction without broadcasting |
| `solana:signAndSendTransaction`            | Sign and submit a transaction                      |

Supported transaction versions: `legacy` and `0` (versioned).

## Discover and connect

List Wallet Standard wallets and connect to Ledger:

```ts
import { getWallets } from '@wallet-standard/app'

const { get } = getWallets()

function findLedgerWallet() {
  return get().find((wallet) =>
    wallet.chains.some((chain) => chain.startsWith('solana:')) &&
    wallet.name.toLowerCase().includes('ledger'),
  )
}

const wallet = findLedgerWallet()
if (!wallet) {
  throw new Error('Ledger Solana wallet not found. Call initializeLedgerProvider first.')
}

const connect = wallet.features['standard:connect']
if (!connect) {
  throw new Error('Wallet does not support standard:connect')
}

const { accounts } = await connect.connect()
const account = accounts[0]
```

With React, `@solana/react` / `@wallet-standard/react` helpers (`useConnect`, `useSelectedWalletAccount`, …) wrap the same Wallet Standard APIs.

> **Note:** **Registration:** A family is registered only when you pass its factory **and** it is enabled in your dApp config. Solana factory + Solana enabled → Wallet Standard. EVM factory + Ethereum enabled → EIP-6963 / EIP-1193. Both → both surfaces from the same `initializeLedgerProvider` call. Account pickers are filtered by the requesting family (Solana connect only lists Solana-compatible accounts).

## Sign a message

```ts
const signMessageFeature = wallet.features['solana:signMessage']
if (!signMessageFeature) {
  throw new Error('Wallet does not support solana:signMessage')
}

const message = new TextEncoder().encode('Hello from my Solana dApp')

const [result] = await signMessageFeature.signMessage({
  account,
  message,
})

// result.signedMessage — bytes that were signed
// result.signature — ed25519 signature bytes
```

React equivalent with `@solana/react`:

```tsx
import { useSignMessage } from '@solana/react'

const signMessage = useSignMessage(account)

const { signature } = await signMessage({
  message: new TextEncoder().encode('Hello from my Solana dApp'),
})
```

Signing opens the Ledger Wallet Provider UI so the user can confirm on their device.

## Sign a transaction

Build and serialize a Solana transaction with your preferred toolkit (`@solana/kit`, `@solana/web3.js`, …), then pass the serialized bytes:

```ts
const signTransactionFeature = wallet.features['solana:signTransaction']
if (!signTransactionFeature) {
  throw new Error('Wallet does not support solana:signTransaction')
}

// `serializedTransaction` is a Uint8Array (wire format)
const [signed] = await signTransactionFeature.signTransaction({
  account,
  transaction: serializedTransaction,
  chain: 'solana:mainnet', // or solana:devnet / solana:testnet
})

// signed.signedTransaction — signed wire bytes (you broadcast yourself)
```

## Sign and send a transaction

```ts
const signAndSendFeature = wallet.features['solana:signAndSendTransaction']
if (!signAndSendFeature) {
  throw new Error('Wallet does not support solana:signAndSendTransaction')
}

const [sent] = await signAndSendFeature.signAndSendTransaction({
  account,
  transaction: serializedTransaction,
  chain: 'solana:mainnet',
  options: { skipPreflight: false },
})

// sent.signature — base58 transaction signature
```

## Cleanup

Call the function returned by `initializeLedgerProvider` when your application unmounts. Cleanup removes the Ledger UI and unregisters any providers that were registered for your partner configuration.

```ts
const cleanup = initializeLedgerProvider({ /* options */ })

// Later:
cleanup()
```

## Troubleshooting

**Ledger does not appear in the wallet list.**
Confirm `initializeLedgerProvider` ran in the browser before you query wallets, that you passed `createSolanaBlockchainProvider`, and that Solana is enabled for your `dAppIdentifier`. On unsupported platforms (no Web HID / Web Bluetooth), initialization is a no-op and no Solana wallet is registered — see [Requirements](../requirements).

**Connect returns no accounts.**
The user cancelled the flow, or no Solana account is available on the device for the requested cluster. Retry `standard:connect` after the user finishes onboarding in the Ledger UI.

**Signing fails while another flow is open.**
Blocking requests (connect / sign) are handled one at a time. Wait for the current Ledger UI flow to finish before starting another.

## See also

- [Get started](../get-started) — install family packages and pass `blockchainProviderFactories`
- [EVM](./evm) — EIP-6963 discovery and EIP-1193 signing
- [Configuration](../configuration) — init options, including `blockchainProviderFactories`
- [API reference](../api-reference) — `initializeLedgerProvider` and EVM EIP-1193 surface
- [Wallet Standard](https://github.com/wallet-standard/wallet-standard) — discovery protocol specification

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/configuration -->

---
title: Configuration
category: reference
---

# Configuration

This page describes all available configuration options for `initializeLedgerProvider`. See [Get started](./get-started) for usage and [API reference](./api-reference) for the function signature.

## Configuration options

```typescript
{
  // Core options
  apiKey?: string;                                    // Your Ledger API key
  dAppIdentifier?: string;                            // Your dApp identifier
  loggerLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug';  // Log verbosity (default: 'info')
  environment?: 'staging' | 'production';             // Target Ledger backend environment
  dmkConfig?: DeviceModuleOptions;                    // Device Management Kit configuration (optional)
  blockchainProviderFactories?: BlockchainProviderFactoryRegistration[]; // Family factories to register (required for EVM / Solana)

  // UI options
  target?: HTMLElement;                               // Where to mount the UI (default: document.body)
  hideButton?: boolean;                               // Hide the floating button entirely (default: false)
  floatingButtonPosition?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center' | 'middle-right';  // Position of the floating button (default: 'bottom-right')
  floatingButtonTarget?: HTMLElement | string;        // Element or CSS selector to anchor the floating button to
  walletTransactionFeatures?: Array<'send' | 'receive' | 'swap' | 'buy' | 'earn' | 'sell'>;  // Wallet action CTAs to display
  transactionConfirmationNotification?: 'tooltip' | 'toast';  // How TX confirmation is shown (default: 'tooltip')

  // Development options
  devConfig?: {
    stub?: {
      base?: boolean;              // Enable base stub mode (default: false)
      account?: boolean;           // Stub account operations (default: false)
      balance?: boolean;           // Stub account balances (default: false)
      device?: boolean;            // Stub signer interactions (default: false)
      web3Provider?: boolean;      // Stub Web3 provider responses (default: false)
      solanaProvider?: boolean;    // Stub Solana provider responses (default: false)
      transactionHistory?: boolean; // Stub transaction history (default: false)
    };
  };
}
```

All options are optional. Pass `blockchainProviderFactories` for any chain provider to load.

## Parameter details

### `apiKey`

Your Ledger API key. Required for production use.

### `dAppIdentifier`

Your dApp identifier. This lets Ledger validate the integration and enable remote services.

### `blockchainProviderFactories`

Host-supplied factories that create blockchain providers. Required for any family to load — the UI package never imports family packages itself.

Install the family package, import its factory, and register it against the family it serves:

```ts
import { initializeLedgerProvider } from "@ledgerhq/ledger-wallet-provider";
import { createEvmBlockchainProvider } from "@ledgerhq/ledger-wallet-provider-evm";
import { createSolanaBlockchainProvider } from "@ledgerhq/ledger-wallet-provider-solana";

initializeLedgerProvider({
  dAppIdentifier: "my-dapp",
  apiKey: "your-api-key",
  blockchainProviderFactories: [
    { family: "ethereum", create: createEvmBlockchainProvider },
    { family: "solana", create: createSolanaBlockchainProvider },
  ],
});
```

| Family     | Package                                   | Factory                          |
| ---------- | ----------------------------------------- | -------------------------------- |
| `ethereum` | `@ledgerhq/ledger-wallet-provider-evm`    | `createEvmBlockchainProvider`    |
| `solana`   | `@ledgerhq/ledger-wallet-provider-solana` | `createSolanaBlockchainProvider` |

A factory is skipped when that family is not enabled in your partner dApp configuration. If you omit `blockchainProviderFactories` (or pass an empty array), no EVM or Solana provider is registered.

### `loggerLevel`

Log verbosity. Accepted values: `'fatal'`, `'error'`, `'warn'`, `'info'`, `'debug'`. Default is `'info'`.

### `environment`

Target Ledger backend environment. Accepted values: `'staging'`, `'production'`.

### `target`

Target element to mount the Ledger Wallet Provider UI. Defaults to `document.body`.

### `hideButton`

Hides the floating Ledger button entirely. Defaults to `false`.

When set to `true`, the floating button is not rendered on screen or inside a `floatingButtonTarget`. The Ledger UI (modal, side panel) is still mounted and any providers you registered via `blockchainProviderFactories` are still announced — this is useful when you want to drive the flow exclusively from your own UI (for example through the [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) provider).

```javascript
initializeLedgerProvider({
  hideButton: true,
  // ...
});
```

> **Note:** When `hideButton` is `true`, `floatingButtonPosition` and `floatingButtonTarget` have no effect.

### `floatingButtonPosition`

Controls where the floating Ledger button appears on screen. Default is `'bottom-right'`.

Available positions: `'bottom-right'`, `'bottom-left'`, `'bottom-center'`, `'top-right'`, `'top-left'`, `'top-center'`, `'middle-right'`.

```javascript
initializeLedgerProvider({
  floatingButtonPosition: "bottom-left",
  // ...
});
```

### `floatingButtonTarget`

An `HTMLElement` or CSS selector string. When provided, the floating button renders as a compact button inside the target element instead of being positioned on screen.

Use this to integrate the Ledger button into your own navigation bar, wallet panel, or sidebar.

```javascript
// CSS selector
initializeLedgerProvider({
  floatingButtonTarget: "#my-wallet-button-slot",
  // ...
});

// HTMLElement reference
initializeLedgerProvider({
  floatingButtonTarget: document.querySelector("#my-wallet-button-slot"),
  // ...
});
```

> **Note:** When `floatingButtonTarget` is set, `floatingButtonPosition` has no effect.
> The button is placed inside your target element instead.

### `walletTransactionFeatures`

An optional array of wallet transaction features to display as action buttons in the side panel.

Available features:

- `'send'` — Send crypto
- `'receive'` — Receive crypto
- `'swap'` — Swap tokens
- `'buy'` — Buy crypto
- `'earn'` — Earn rewards
- `'sell'` — Sell crypto

If not specified, the action buttons section is not displayed.

### `transactionConfirmationNotification`

Controls how transaction confirmation feedback is shown after a signing flow. Default is `'tooltip'`.

Accepted values:

- `'tooltip'` — show confirmation on the floating button (badge / tooltip)
- `'toast'` — show confirmation as a toast notification

```javascript
initializeLedgerProvider({
  transactionConfirmationNotification: "toast",
  // ...
});
```

### `dmkConfig`

Device Management Kit configuration (optional). Passes custom device policies to the underlying Device Management Kit.

### `devConfig.stub`

Toggles local stub modes so you can simulate accounts, balances, devices, and Web3 flows during development without a physical signer.

| Field                | Default | Stubs                     |
| -------------------- | ------- | ------------------------- |
| `base`               | `false` | Base stub mode            |
| `account`            | `false` | Account operations        |
| `balance`            | `false` | Account balances          |
| `device`             | `false` | Signer interactions       |
| `web3Provider`       | `false` | Web3 provider responses   |
| `solanaProvider`     | `false` | Solana provider responses |
| `transactionHistory` | `false` | Transaction history       |

```javascript
const cleanup = initializeLedgerProvider({
  devConfig: {
    stub: {
      base: true,
      account: true,
      balance: true,
      device: true,
      web3Provider: true,
      solanaProvider: true,
    },
  },
  dAppIdentifier: "my-dapp",
  apiKey: "your-api-key",
});
```

## Return value

`initializeLedgerProvider` returns a cleanup function. Call it to remove the provider and UI components from the DOM.

```typescript
const cleanup = initializeLedgerProvider({ /* options */ })

// Later, when unmounting:
cleanup()
```

The cleanup function removes the UI, deregisters any providers that were registered for your partner configuration (for example the EVM `eip6963:requestProvider` listener and/or the Solana Wallet Standard wallet), and resets internal provider state so a new configuration can be applied on the next call.

## See also

- [Get started](./get-started) — install the SDK and run your first integration
- [API reference](./api-reference) — `initializeLedgerProvider` function signature and `LedgerEIP1193Provider` (from `@ledgerhq/ledger-wallet-provider-evm`)
- [Requirements](./requirements) — browser and platform requirements

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/get-started -->

---
title: Get started with Ledger Wallet Provider
category: how-to
---

# Get started with Ledger Wallet Provider

This guide shows you how to install and initialize Ledger Wallet Provider. You install the UI package plus a family package for each chain you support, then pass those factories to one `initializeLedgerProvider` call. The SDK registers only the families that are also enabled in your partner configuration (`dAppIdentifier`). Then follow the guide for your chain.

> **Note:** **Partner program**: Ledger Wallet Provider requires enrollment in Ledger's partner program to obtain API keys. [Contact our team](https://docs.google.com/forms/d/e/1FAIpQLSdZ6eRzPxAKy6Yg8ERbnXd5CpOFX7esjvH2X3Z12MsdhvQvtw/viewform?usp=sharing\&ouid=107637591620972246516) to discuss integration.

Before you start, check the [Requirements](./requirements) to confirm your target browsers support Web HID and Web Bluetooth.

## Install the SDK

Install the UI package and a family package for each chain you support:

```bash
npm install @ledgerhq/ledger-wallet-provider
npm install @ledgerhq/ledger-wallet-provider-evm      # EVM (EIP-6963 / EIP-1193)
npm install @ledgerhq/ledger-wallet-provider-solana   # Solana (Wallet Standard)
```

You can also install with `yarn` or `pnpm`. Skip a family package if you do not support that chain.

> **Note:** The family packages declare `rxjs`, `xstate`, `purify-ts` and `@ledgerhq/device-management-kit` as peer dependencies, so they share a single instance with the UI package. npm 7+, pnpm and Yarn Berry install them for you; on Yarn 1, add them explicitly.

## Initialize the provider

```ts
import { initializeLedgerProvider } from '@ledgerhq/ledger-wallet-provider'
import { createEvmBlockchainProvider } from '@ledgerhq/ledger-wallet-provider-evm'
import { createSolanaBlockchainProvider } from '@ledgerhq/ledger-wallet-provider-solana'
import '@ledgerhq/ledger-wallet-provider/styles.css'

const cleanup = initializeLedgerProvider({
  dAppIdentifier: 'my-dapp',
  apiKey: 'your-api-key',
  loggerLevel: 'info',
  blockchainProviderFactories: [
    { family: 'ethereum', create: createEvmBlockchainProvider },
    { family: 'solana', create: createSolanaBlockchainProvider },
  ],
})

// Call cleanup() when your application unmounts
```

Pass a factory for each family you installed. `initializeLedgerProvider` mounts the Ledger UI and announces Ledger only for families that appear in **both** `blockchainProviderFactories` and your partner dApp configuration (tied to `dAppIdentifier`):

- **EVM** via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) / [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) — when you pass the EVM factory and Ethereum is enabled
- **Solana** via the [Wallet Standard](https://github.com/wallet-standard/wallet-standard) — when you pass the Solana factory and Solana is enabled

If both factories are passed and both families are enabled, both providers are registered from the same init call. Without `blockchainProviderFactories`, no chain provider is registered.

It returns a cleanup function — call it when your application unmounts to remove the UI and unregister any providers that were registered.

See [Configuration](./configuration) for the full list of options.

## SSR and dynamic imports

The SDK uses browser APIs (`window`, `document`, `CustomEvent`). In SSR frameworks (Next.js, Nuxt, SvelteKit, …), load it only on the client:

```tsx
import { useEffect } from 'react'

useEffect(() => {
  let cleanup: (() => void) | undefined

  ;(async () => {
    await import('@ledgerhq/ledger-wallet-provider/styles.css')
    const [
      { initializeLedgerProvider },
      { createEvmBlockchainProvider },
      { createSolanaBlockchainProvider },
    ] = await Promise.all([
      import('@ledgerhq/ledger-wallet-provider'),
      import('@ledgerhq/ledger-wallet-provider-evm'),
      import('@ledgerhq/ledger-wallet-provider-solana'),
    ])
    cleanup = initializeLedgerProvider({
      dAppIdentifier: 'my-dapp',
      apiKey: 'your-api-key',
      blockchainProviderFactories: [
        { family: 'ethereum', create: createEvmBlockchainProvider },
        { family: 'solana', create: createSolanaBlockchainProvider },
      ],
    })
  })()

  return () => cleanup?.()
}, [])
```

## Choose your chain

After initialization, integrate discovery and signing for each family you registered and that is enabled in your partner configuration:

[<div className="font-semibold mb-2">EVM →</div>
<div className="text-sm text-gray-400">EIP-6963 discovery, eth\_requestAccounts, message and transaction signing</div>](./blockchains/evm)

[<div className="font-semibold mb-2">Solana →</div>
<div className="text-sm text-gray-400">Wallet Standard connect, signMessage, signTransaction, signAndSendTransaction</div>](./blockchains/solana)

More blockchain families will follow the same pattern: install the family package, pass its factory, then use the chain-specific guide.

## Next steps

- [Configuration](./configuration) — UI position, stubs, environment, and other options
- [API reference](./api-reference) — `initializeLedgerProvider`, `blockchainProviderFactories`, and the EVM EIP-1193 provider surface
- [Package attestation](./package-attestation) — verify npm provenance

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/overview -->

---
title: Ledger Wallet Provider
category: explanation
---

# Ledger Wallet Provider

Give your users a first-party Ledger experience inside your application with secure signer pairing, Clear Signing, and Transaction Check built in.

## What is Ledger Wallet Provider

Ledger Wallet Provider is a web component SDK that embeds Ledger's official connect flow directly inside your application, enabling direct signer connections and ensuring full access to Ledger's security features like Clear Signing and Transaction Check.

The SDK handles USB and Bluetooth connections, automatically enables Clear Signing and Transaction Check, and exposes standards-based providers for the blockchain families you register. Install `@ledgerhq/ledger-wallet-provider-evm` and/or `@ledgerhq/ledger-wallet-provider-solana`, pass their factories to `initializeLedgerProvider`, and the SDK announces only the families also enabled in your partner configuration — an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) provider via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) for Ethereum, and a [Wallet Standard](https://github.com/wallet-standard/wallet-standard) wallet for Solana.

![Ledger connect modal with transport choices](/wallet-provider/connect-a-ledger-modal.png)

![Token balances displayed for the connected account](/wallet-provider/tokens.png)

## What you get with Ledger Wallet Provider

✓

Built-in security
Clear Signing and Transaction Check enabled automatically

✓

Complete user flow
Handles signer pairing, account selection, and connection state

✓

Standard integration
EIP-1193 provider works with any JavaScript framework

✓

Managed transports
Ledger maintains USB and Bluetooth connection layers

## Limitations

The SDK runs entirely in the browser. It does not support server-side rendering (SSR): use dynamic imports to load it only in a browser context. Mobile browsers are not supported because Web HID and Web Bluetooth APIs are not available on iOS or Android. For full environment requirements, see [Requirements](./requirements).

## Where to go next

[<div className="font-semibold mb-2">Requirements →</div>
<div className="text-sm text-gray-400">Check browser and platform requirements before you start</div>](./requirements)

[<div className="font-semibold mb-2">Get started →</div>
<div className="text-sm text-gray-400">Install the SDK and family packages, then initialize Ledger Wallet Provider</div>](./get-started)

[<div className="font-semibold mb-2">EVM →</div>
<div className="text-sm text-gray-400">Connect and sign with EIP-6963 / EIP-1193</div>](./blockchains/evm)

[<div className="font-semibold mb-2">Solana →</div>
<div className="text-sm text-gray-400">Connect and sign with Wallet Standard</div>](./blockchains/solana)

[<div className="font-semibold mb-2">Configuration →</div>
<div className="text-sm text-gray-400">Explore all initialization options</div>](./configuration)

[<div className="font-semibold mb-2">API reference →</div>
<div className="text-sm text-gray-400">Explore events, methods, and provider capabilities</div>](./api-reference)

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/package-attestation -->

---
title: NPM package attestation verification
category: how-to
---

# NPM package attestation verification

> **Key takeaway:**  ☞   Publish Attestation is enabled for our `@ledgerhq/ledger-wallet-provider` package. It links the published package to its source and build instructions, improving supply-chain transparency.

## Understanding provenance and attestation

### What is npm provenance?

npm can show two attestations:

| Provenance Attestation                                                                                                        |  Publish Attestation                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| - • Links a package to its repo and build process
- • Indicates where/how it was built
- • Lets you verify origin pre-install | * • Created by the registry at publish time by an authorized user
* • Signed via Sigstore
* • Recorded in a public transparency log |

Both are public and help verify origin.

### About Sigstore

npm’s publish attestation is implemented via Sigstore. When Ledger enables publish attestation for `@ledgerhq/ledger-wallet-provider`, the registry:

- Issues a short‑lived certificate that binds the publisher’s identity to the specific release
- Records the attestation in a public transparency log for tamper‑evidence

This proves who published the package and when, and links the artifact to its source/build instructions. It does not review or audit the package’s code.

> **Warning:** Provenance does not guarantee code safety. It only proves origin and build details so you can decide whether to trust the package.

### npm vs pnpm: When verification happens and how trust is enforced

| pnpm (recommended)                                                                  | npm                                               |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- |
| enforces trust **during** install and can block untrusted direct or transitive deps | Verifies **after** install via a separate command |

## Configure verification and trust policy

### pnpm (recommended)

### Trust policy configuration

With pnpm, verification is part of installation. If a package violates trust policy, install is blocked, thanks to the following setting:

```yaml filename="pnpm-workspace.yaml"
# Block installation if trust level decreases
trustPolicy: no-downgrade

# Optional exceptions (use sparingly)
# trustPolicyExclude:
#   - some-legacy-package
```

pnpm compares trust before extraction. If a newer publish has less evidence than earlier publishes in the same release channel, it blocks the install.

### Trust policy exceptions

Add safe, verified packages to exclusions if needed:

```yaml filename="pnpm-workspace.yaml"
# Block installation if trust level decreases
trustPolicy: no-downgrade

# Optional exceptions (use sparingly)
trustPolicyExclude:
    - some-legacy-package
```

> **Warning:** Only exclude packages you have verified are safe; exclusions bypass trust checks for that package.

### Installation

```bash
pnpm install
```

### npm

### Post-Installation Verification

With npm, attestation verification is a separate step after installation.

```bash
npm install @ledgerhq/ledger-wallet-provider
npm audit signatures  # ← Runs AFTER the package is already installed
```

## Verification outcomes

### pnpm

### What to expect from pnpm

- Enforces trust policy during install
- Based on publish date, not semver
- Applies to transitive dependencies
- Blocks the entire install if any dependency fails

### Example error

```bash
ERR_PNPM_TRUST_DOWNGRADE  High-risk trust downgrade for "package-name@version"
(possible package takeover)

Trust checks are based on publish date. If any earlier-published version had stronger trust,
this version is blocked.
```

### Transitive dependency protection example

In this example, pnpm blocked a downgrade in a transitive dep (undici-types) while installing `@ledgerhq/context-module`:

```bash
ERR_PNPM_TRUST_DOWNGRADE  High-risk trust downgrade for "undici-types@6.19.8"
(possible package takeover)

This error happened while installing the dependencies of `@ledgerhq/context-module`
    at ethers@6.14.1
    at @types/node@22.7.5
```

Dependency chain: `context-module` → `ethers` → `@types/node` → `undici-types`

### How pnpm compares prerelease and stable versions

pnpm evaluates trust within the same release channel:

- Prerelease versions (0.0.0-\*, 1.0.0-beta.1) compared against other prereleases
- Stable versions (1.0.0, 2.3.4) compared against other stable versions

> **Warning:** Prereleases are not compared to stables. Trust can only downgrade within the same channel.

#### Example

- 0.0.0-develop-20251126 (prerelease) has attestation → sets prerelease baseline
- 0.0.0-develop-20251128 (prerelease) lacks attestation → BLOCKED (trust downgrade in prerelease)
- 1.11.0 (stable) lacks attestation → NOT blocked (no prior stable had attestation)

### npm

### What to expect from npm

- Run npm audit signatures after install

### Example error

```bash
audited 1267 packages in 6s
1267 packages have verified registry signatures
74 packages have verified attestations
```

> **Warning:** Verification is reactive; install and any postinstall scripts have already run.

## pnpm vs npm: at a glance

| Aspect                    | pnpm (recommended)                 | npm                            |
| ------------------------- | ---------------------------------- | ------------------------------ |
| When verification happens | During install (pre‑install block) | After install (reactive check) |
| Blocks untrusted packages | Yes (automatic)                    | No (manual check)              |
| Requires separate command | No                                 | Yes (npm audit signatures)     |
| Policy enforcement        | trustPolicy: no-downgrade          | None                           |
| Checks transitive deps    | Yes (blocks before install)        | Yes (after install only)       |
| Comparison basis          | Publish date and trust signals     | N/A                            |

## Reference URLs

- [npm Generating Provenance Statements](https://docs.npmjs.com/generating-provenance-statements)
- [Mitigating Supply Chain Attacks with pnpm](https://pnpm.io/supply-chain-security)
- [pnpm Trust Policy Settings](https://pnpm.io/settings#trustpolicy)

---

<!-- https://developers.ledger.com/docs/ledger-wallet-provider/requirements -->

---
title: Requirements
category: reference
---

# Requirements

This page lists the environment requirements for `@ledgerhq/ledger-wallet-provider`. The SDK communicates directly with Ledger hardware signers over USB (Web HID API) and Bluetooth (Web Bluetooth API), so it requires a browser environment where those APIs are available. It cannot run in Node.js or any server-side environment.

## Platform requirements

- ES2020+ support
- Modern bundler (Vite, Webpack 5+, etc.)
- Browser environment (no Node.js server-side execution)
- Web HID API support (for USB connections)
- Web Bluetooth API support (for Bluetooth connections)

> **Note:** Mobile browsers are not supported because Web HID and Web Bluetooth APIs are not available on iOS or Android.

## Browser support

- **Desktop**: Chrome 89+, Firefox 89+, Safari 14.1+, Edge 89+
- **Mobile**: Not supported (Web HID and Web Bluetooth APIs are not available)

## See also

- [Get started](./get-started) — install the SDK and initialize the provider
- [Configuration](./configuration) — full list of initialization options

---

<!-- https://developers.ledger.com/docs/news -->

# 3rd quarter of 2026

## Breaking change: LedgerJS deprecated in September 2026

In September 2026, the Ethereum app will drop support for `signEIP712HashedMessage` (the hashed / blind-signing variant of EIP-712). This removes the last working path for `@ledgerhq/hw-app-eth`, and **all LedgerJS packages (`hw-app-*`, `hw-transport-*`) are deprecated from that date**.

Applications that have not migrated to the [Device Management Kit (DMK)](/docs/device-interaction/getting-started) by September 2026 will be unable to sign EIP-712 typed data on Ledger devices.

### What you need to do

| If you use…                       | Migrate to…                               |
| --------------------------------- | ----------------------------------------- |
| `@ledgerhq/hw-app-eth`            | `@ledgerhq/device-signer-kit-ethereum`    |
| `@ledgerhq/hw-app-btc`            | `@ledgerhq/device-signer-kit-bitcoin`     |
| `@ledgerhq/hw-app-solana`         | `@ledgerhq/device-signer-kit-solana`      |
| `@ledgerhq/hw-transport-webhid`   | `@ledgerhq/device-transport-kit-web-hid`  |
| `@ledgerhq/hw-transport-web-ble`  | `@ledgerhq/device-transport-kit-web-ble`  |
| `@ledgerhq/hw-transport-node-hid` | `@ledgerhq/device-transport-kit-node-hid` |

## Where to meet us?

Our team will be attending the following events in the coming months. We'd love to connect with you to discuss your projects and provide in-person support.

### ETH Global Lisbon

**July 24-26th 2026** | Lisbon, Portugal

---

<!-- https://developers.ledger.com/docs/nft-display/image-requirements -->

---
title: NFT image requirements
category: reference
---

# NFT image requirements

Ledger Stax and Ledger Flex have E Ink Secure Screens that display your NFT as the device's lock screen. Because E Ink renders in grayscale and at a fixed resolution, images must meet the requirements below to display correctly.

| Requirement       | Details                                                                                                                                                                                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dimensions**    | The screen resolution is 400 × 672 px (width × height). The image height must be 1.68× the width, with a minimum width of 400 px. Example: 500 × 840 px is valid; 400 × 500 px is not.                                                                                                                    |
| **File size**     | Keep the file as small as possible. Under 1 MB is strongly recommended.                                                                                                                                                                                                                                   |
| **Color profile** | Both screens support up to **16 levels of gray (4-bit grayscale)**. Work in 4-bit grayscale to guarantee the result on-device. You may work in black and white (a larger color space), but the image will be converted to 4-bit grayscale before display and the result may differ from your source file. |

## Why 4-bit grayscale?

E Ink displays do not support full-color rendering. Each pixel can be one of 16 shades, from pure black to pure white. Designing directly in 4-bit grayscale gives you full control over the dithering and tonal mapping — what you design is exactly what users see. If you supply a color or high-bit-depth image, the conversion happens automatically but without your art direction.

## Related

- [Optimized images](./optimized-images) — how to compress and optimize images before submission
- [Manifold Studio integration](./manifold-studio) — how to configure NFT display through Manifold Studio

---

<!-- https://developers.ledger.com/docs/nft-display/manifold-studio -->

# Add Metadata to new NFTs with Manifold Studio

This guide will walk you through step-by-step instructions on how to add the Ledger Stax Metadata to your NFTs with Manifold Studio.

This guide consists of four parts:

1. Load your Ledger Stax images to IPFS via Pinata.
2. Create your own smart contract on Manifold studio.
3. Mint your token on Manifold studio.
4. Add the Ledger Stax Metadata to your NFTs.

> **Note:** 

## Upload your Ledger Stax images to IPFS via Pinata

While NFT assets can be stored on a centralized (S3, Google Cloud) or decentralized (IPFS) storage systems, the latter approach is the most commonly used due to its [immutable](https://adlrocha.medium.com/ipfs-for-storage-the-blockchain-for-verified-immutability-59c1917d2141) nature (data cannot be altered unless you change the URL of the asset).

We’ll be using Pinata to upload (“pin”) the images to IPFS. Pinata is a cloud service that makes it easy to pin data to IPFS.

> **Note:** Note that [NFT.Storage](https://nft.storage/#getting-started) is another storage service option to upload data easily to IPFS.

Let’s get started:

1. First, create a free account on [pinata.cloud](https://www.pinata.cloud/)
2. Once the account is created, go to the [Pin Manager](https://app.pinata.cloud/pinmanager).
3. Click the “Upload” button, choose your Ledger Stax image, and upload the file.

![Upload a file on Pinata](/nft-display/manifold-01.png)
_Upload a file on Pinata_

When the upload is complete, you'll see your file in the grid and can copy the IPFS URL by clicking on the eye icon. You'll need this URL later, so keep it handy. You can also come back to the Pin Manage page and copy it again at any time.

![Link of your IPFS asset](/nft-display/manifold-02.png)
_Link of your IPFS asset_

> **Note:** IPFS link of your Ledger Stax image:  [[https://gateway.pinata.cloud/ipfs/QmPEZxVrRkZXapmi6sK7m8XKpxRCiFULXfTjABZZnbCt5D](https://gateway.pinata.cloud/ipfs/QmPEZxVrRkZXapmi6sK7m8XKpxRCiFULXfTjABZZnbCt5D)](https://gateway.pinata.cloud/ipfs/QmPEZxVrRkZXapmi6sK7m8XKpxRCiFULXfTjABZZnbCt5D)

Now that our Ledger Stax image is uploaded to the IPFS network, let’s move on to the Manifold studio part.

## What is Manifold studio?

Manifold is an open-source platform that allows NFT creators to write their own bespoke NFT smart contracts and mint their tokens through a seamless user interface (zero coding required).

The platform allows creators to retain true ownership of their smart contracts in contrast to the “shared contract” model that offers less customization and put creators at the mercy of NFT marketplaces (who are the ones owning and controlling the contracts used to mint and edit these tokens).

### Create your own smart contract on Manifold Studio

Let’s get started by creating your own smart contract through Manifold studio:

1. Go to [studio.manifold.xyz](https://studio.manifold.xyz/) and connect to your wallet.
2. Click the “New contract” button.
3. Fill in the contact fields including name, type (ERC721 or ERC1155), symbol, and ASCII MARK.
   ![Contract deployment flow on Manifold Studio](/nft-display/manifold-03.png)
   _Contract deployment flow on Manifold Studio_
4. Once your contract is deployed, click on “Go to dashboard”, then “Mint a token” and “Create”.
5. Select the type of token you wish to create (Single token, Edition, or Batch)
6. After filling in the token information (title, created by, description, etc), Manifold allows you to add custom metadata to your NFT called “properties”. Properties can be of different types, such as text, number, boost number, or hidden. To add your Ledger Stax Metadata, follow the below instructions:
   - Area 1: select the **“Hidden”** property from the dropdown list.
   - Area 2: enter `ledger_metadata` (name of the metadata attribute)
   - Area 3: enter the value of the metadata that points to the IPFS asset URL that we previously uploaded via Pinata:
   ```json copy
   {"ledger_stax_image": "https://gateway.pinata.cloud/ipfs/QmPEZxVrRkZXapmi6sK7m8XKpxRCiFULXfTjABZZnbCt5D"}
   ```

![Set your custom metadata on Manifold](/nft-display/manifold-04.png)
_Set your custom metadata on Manifold_

In the end, Manifold will automatically generate a metadata file (JSON) that will look like this:

```json copy
{
    "name": "Ledger Market",
    "description": "Ledger Market on Manifold", 
    "ledger_metadata": {
        "ledger_stax_image": "https://gateway.pinata.cloud/ipfs/QmPEZxVrRkZXapmi6sK7m8XKpxRCiFULXfTjABZZnbCt5D" // Location of the Ledger Stax image
     }
}
```

**You’re all set! Your NFT token (powered by Manifold studio) is now designed for an optimal display on Ledger Stax.**

---

<!-- https://developers.ledger.com/docs/nft-display/optimized-images -->

# Optimized images

This series of articles are for NFT dApp developers and NFT creators who want to allow their audience to showcase their NFTs on Ledger Stax and Ledger Flex devices.

> **Warning:** The Ledger Stax Metadata tool is no longer available. For new NFTs, we recommend using Manifold Studio. For existing NFTs with mutable metadata, you can update the metadata manually. For NFTs with immutable metadata, updates are not currently possible.

## Ledger Device Lock Screen

The Lock screen is the first thing users see when they pick up their Ledger Stax and Ledger Flex devices. The Lock Screen can be customized by choosing an image from the NFT gallery or from the user's smartphone.

The Ledger screens have specific requirements which need to be considered:

- **Dimension**: The screen's resolution is 672px (height) by 400px (width). For an optimal display of the NFT on Ledger Stax, make sure the NFT image height is 1.68x the width and the minimum width is 400px (ex: 840px \* 500px).
- **Color profile**: The Ledger Stax and Ledger Flex screens support up to 16 levels of gray (4-bit grayscale).

![CryptoPunk on Ledger Stax](/nft-display/metadata-01.png)

CryptoPunk on Ledger Stax

Ledger Wallet will give the NFT owner an option to crop the image for their NFT and the color will be converted to 4-bit grayscale, but in a lot of instances it won't look ideal.

As a creator, you can provide a dedicated secondary image that will only be used for displaying on Ledger Stax and Ledger Flex devices' lock screen. [As an example](https://metadata.ledger.com/ledger-market-pass-genesis-edition/tokens/1), for the \[ Ledger ] Market Pass - Genesis Edition NFT, you can see below the primary image against the secondary image that has been designed for Ledger devices.

|                  Primary Image                 |                  Secondary Image                 |
| :--------------------------------------------: | :----------------------------------------------: |
| ![Primary Image](/nft-display/metadata-02.png) | ![Secondary Image](/nft-display/metadata-03.png) |

## Use Dithermark To Convert Your Image

Converting your image to black and white is not enough. To ensure that your final output will look great on Ledger Stax and Ledger Flex devices, you can use Dithermark, a free tool, to apply the same dithering algorithm and color profile that your image will be converted to for display on Ledger devices.

Here's how to use it:

1. Make sure your image aspect ratio matches that of your target Ledger device (Stax or Flex)
2. Go to [app.dithermark.com](https://app.dithermark.com/) and upload your image
3. On the Color Dither tab, make the following selections:
   - a. Algorithm: Floyd-Steinberg
   - b. Color comparison: RGB
   - c. Color palette: Monochrome
   - d. Color count: 16
4. Go to the Export tab and click "Save"

Your image is now ready to be added to your NFT's metadata!

## Adding Ledger Device Metadata to Your NFTs

To add Ledger device metadata to your NFTs, you have two options:

1. For new NFTs: Use [Manifold Studio](./manifold-studio) to create your NFTs with Ledger Stax and Ledger Flex device metadata built-in
2. For existing NFTs with mutable metadata: [Update the metadata manually](./update-metadata)

> **Warning:** For NFTs with immutable metadata, updates are not currently possible. We recommend using Manifold Studio for new NFTs to ensure Ledger device compatibility from the start.

The metadata schema is open to all. As a dApp developer, you can create a flow where end-users will upload an image for Ledger Stax and Ledger Flex devices which will then trigger the metadata update.

---

<!-- https://developers.ledger.com/docs/nft-display/update-metadata -->

# Update mutable metadata manually

This guide will walk you through step-by-step instructions on how to update the JSON Metadata files of your NFTs to include the location (URL) of the Ledger Stax optimized image.

This guide consists of two parts:

1. Add the `ledger_stax_image` metadata to your JSON file.
2. Upload the JSON file on your storage service (centralized or decentralized).

> **Note:** Make sure that the dedicated secondary image of your NFT meets [the Ledger Stax’s image requirements](./image-requirements).

## 1. The ledger\_stax\_image Metadata

You can update the metadata of your NFT(s) for a single file or in batch.

### 1.1. Update your Metadata for a single file

1. Open the Metadata .JSON file of your NFT.
2. Add 2 new properties:
   - a. A wrapper `ledger_metadata` meant to include all Ledger specific metadata.
   - b. JSON attribute `ledger_stax_image` that points to the location (URL) of your Ledger Stax image:

     ```json copy
     {
     	"ledger_metadata": {
     		"ledger_stax_image": "https://mystorage.com/25.jpeg" // Location of your Ledger Stax Image
     	}
     }	
     ```

     > **Warning:** Please make sure that the image meets the [Ledger Stax requirements](./image-requirements).

3\. Your JSON Metadata file contains now a reference to the Ledger Stax image:

```json copy
{
	"name": "Sample NFT Title",
	"description": "Learn how add the Ledger Stax image URL in the metadata file.", 
	"image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/25.png", 
	"attributes": [ ... ], 
	"ledger_metadata": {
		"ledger_stax_image": "https://mystorage.com/25.jpeg"
	}
}
```

### 1.2. Update your Metadata in bulk (Javascript)

You can append the `ledger_stax_image` attribute to the metadata across the whole collection (batch update). It can be easily accomplished using JavaScript.

First, make sure to have the following settings on your local machine:

- Folder `metadata` that includes the Metadata JSON files of your collection.
- Folder `staxImages` that includes the Ledger Stax images files.
- Script “update.js” in the root folder (see below).

> **Warning:** 

![Folders organization](/nft-display/folders.png)

Below is a JS code snippet that will do the following operations:

1. Fetch locally each metadata JSON file of your token collection.
2. Verifiy if there is a Ledger Stax image available for this token.
3. If yes, append the attribute `ledger_stax_image` to the JSON.

```js copy
const fs = require('fs');
const path = require("path");
const localMetadataFolder = __dirname + '/metadata'; // folder where the JSON metadata files are stored locally
const localStaxFolder = __dirname + '/staxImages'; // folder where the Ledger Stax images are stored locally
const remoteStaxFolder = "https://collectionName.s3.amazonaws.com/" // base url (folder) where the Ledger Stax images are stored on the cloud.

const jsonsInDir = fs.readdirSync(localMetadataFolder);

// check if localStaxFolder has a Ledger Stax image for a given tokenID
function checkStaxImage(tokenId) {
	var fileNames = fs.readdirSync(localStaxFolder); // put all file names into an array
	
	for (const fileName of fileNames){
		const staxImageName =  path.parse(fileName).name; // remove file name extension
		 if(staxImageName == tokenId) {
			 return true; 
			 }
	}
	return false; 
}

   jsonsInDir.forEach(file => {
   const tokenId =  path.parse(file).name; 
   
   // "ledger_stax_image" is appended only if we found a Ledger Stax Image for a given tokenID
   if (checkStaxImage(tokenId)) { 
	const filePath = path.resolve(localMetadataFolder, file);
	const data = fs.readFileSync(filePath);
	const json = JSON.parse(data);

	json.ledger_metadata = {"ledger_stax_image": remoteStaxFolder + file};
	
	fs.writeFileSync(filePath, JSON.stringify(json, null, 4)); 
   }
   else {
	   console.log("No Ledger Stax Image found for" + tokenId);
   }
});
```

## 2. Upload the updated metadata

Once your JSON files have been updated with the `ledger_stax_image` metadata, you need to upload them on the cloud. The upload process differs whether the JSON files are stored in a centralized storage service or not.

### 2.1. Centralized storage (S3, Google Cloud..)

If the Metadata .JSON files of your NFT collection are stored in a centralized storage service (AWS, Google Cloud, etc.), simply upload the updated JSON file(s) (including the `ledger_stax_image`) to your storage service.

You’re all set!  It can take up to 24 hours for Ledger servers to process the changes.

### 2.2. Decentralized storage (IPFS)

If the Metadata .JSON files of your NFT collection are stored in a decentralized storage service like IPFS, please follow the below instructions:

1. Upload a new folder to IPFS that will include the JSON files of your `ledger_stax_image` Metadata. For the record, when you upload a folder to IPFS, it creates a [CID](https://docs.ipfs.tech/concepts/content-addressing/) that is a hash resultant from the actual contents of all of the files within your folder.
2. Copy the CID from the clipboard.
3. In your smart contract, set your `baseTokenURI` to `ipfs://<your json folder CID>/`
4. You’re all set! It can take up to 24 hours for Ledger servers to process the changes.

---

<!-- https://developers.ledger.com/docs/travel-rule/verify-destination-wallet -->

---
title: How to verify destination wallet ownership for Travel Rule compliance
category: how-to
description: Verify that a user controls their self-custodial destination wallet before allowing a withdrawal, using Reown AppKit SIWX. For any exchange (VASP) handling withdrawals to non-custodial wallets.
---

# How to verify destination wallet ownership for Travel Rule compliance

The _Travel Rule_ is a [FATF](https://www.fatf-gafi.org/en/topics/virtual-assets.html) requirement for Virtual Asset Service Providers (VASPs), established in 2019 and updated in 2021. For withdrawals to self-custodial wallets, it requires you to verify the user controls the destination address before the transfer proceeds.

This guide shows you how to verify that a user controls their self-custodial destination wallet before allowing a withdrawal from your exchange, using Reown AppKit.

> **Key takeaway:** **Reown's support for Ledger Wallet via WalletConnect covers EVM, BTC, and SOL.**

## Implementation

Follow the [Reown AppKit Travel Rule guide](https://docs.reown.com/appkit/recipes/travel-rule#travel-rule-using-appkit) to implement SIWX, a two-step flow where the user connects their wallet and signs a message to prove they control the destination address.

## User flow

When using a Ledger signer through WalletConnect:

1. The user is redirected to Ledger Wallet to sign the message.
2. Once signing is complete, they are returned to the exchange via WalletConnect.

## Verify your integration

After completing the AppKit Travel Rule guide, confirm that:

- Withdrawals above the applicable threshold require a successful SIWX signature before the transfer is allowed
- Transfers are blocked if the user rejects the wallet connection or the sign-message prompt
- Your implementation stores a compliance record (wallet address, signature, verification timestamp, transaction hash) for each verified withdrawal