Trezor Bridge — Secure & Smooth Crypto Access

Your gateway between web apps and hardware wallets

Overview

The Trezor Bridge is a secure and lightweight communication layer between client applications (web, desktop, or mobile) and Trezor hardware wallets. It enables seamless, encrypted communication over USB (or WebUSB) and abstracts away underlying OS-level details.

As a developer, you can leverage Bridge to access wallet operations — key management, signing, address derivation, device enumeration, and more — in a cross-platform, user‑friendly manner. This developer portal guides you through all aspects of using and integrating Trezor Bridge into your crypto app ecosystem.

Architecture & Workflow

At a high level, the architecture includes:

  • Client-side library (JavaScript / desktop SDK) — sends JSON‐RPC commands.
  • Trezor Bridge process — runs on the user’s machine, listens for client requests, routes traffic to USB or WebUSB interfaces.
  • Hardware device — executes commands, asks for user confirmation, returns result.

The workflow:

  1. Your application loads the Trezor client library.
  2. The library connects (via WebSocket or HTTP to localhost) to Trezor Bridge.
  3. The Bridge forwards the request to the hardware wallet.
  4. User confirms the operation on the device.
  5. The result returns back along the chain.

Why use Bridge?

  • Cross-platform support (Windows, macOS, Linux).
  • Standardizes USB access across browsers & OSes.
  • Ensures encrypted, authenticated communication.
  • Facilitates auto-updates & version control.

Integration Guide

Here’s a step‑by‑step guide to get started integrating Trezor Bridge into your application:

1. Install the Bridge

Provide a link for users to download and install the Trezor Bridge for their OS. Once installed, it runs as a local service (e.g. at http://127.0.0.1:21325/).

2. Include the Trezor client library

In your web or node-based project, install the official client library. For example: 

npm install @trezor/connect

Then import in your code: 

import TrezorConnect from "@trezor/connect";

3. Initialize the connection

Use the library to connect and request features: 


TrezorConnect.init({
  manifest: {
    email: "developer@yourdomain.com",
    appUrl: "https://yourapp.com"
  }
});

4. Request an operation

Example: get Bitcoin address: 


TrezorConnect.getAddress({
  path: "m/44'/0'/0'/0/0",
  coin: "Bitcoin"
})
  .then(response => {
    if (response.success) {
      console.log("Address:", response.payload.address);
    } else {
      console.error("Error:", response.payload.error);
    }
  });

5. Handle errors & user cancellations

Always design your UI to handle cancellations, device disconnection, or version mismatch. The library returns structured errors to assist you.

Tip: Use `TrezorConnect.on(event, callback)` to listen for state changes (e.g. “DEVICE_EVENT”, “UI_EVENT”). Example: 

TrezorConnect.on("DEVICE_EVENT", event => {
  console.log("Device event:", event);
});

API & Protocols

The client library communicates using a JSON‐RPC 2.0–style protocol. Commands to the Bridge include methods such as:

Under the hood, the Bridge translates these calls to proper USB (or WebUSB) commands, ensuring correct framing, version control, and error mapping.

Sample JSON‑RPC Request


{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "getFeatures",
  "params": {}
}

Sample JSON‑RPC Response


{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "vendor": "SatoshiLabs",
    "model": "T",
    "firmware_version": "2.3.4",
    "features": { ... }
  }
}

If an error occurs: 


{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": 500,
    "message": "Device disconnected"
  }
}

Versioning & Upgrades

The Bridge supports backward-compatible changes, but major version bumps may require updating your integration. Monitor Bridge release notes and enforce a minimum version in your app.

Security Considerations

Security is the foundation of any crypto interface. The Bridge and the client library put strong safeguards in place. Below are guidelines and best practices you should follow.

Encryption & Authentication

All communication between the client library and Bridge is encrypted and authenticated. The Bridge uses TLS or secure channels (depending on implementation) to prevent man-in-the-middle attacks.

User Confirmation & PINs

Any critical operation (e.g. signing, exporting keys) must be confirmed by the user on the hardware device. The device uses PIN, passphrase, or security checks as configured.

Version & Integrity Checks

The Bridge verifies firmware versions, checks signatures, and ensures integrity of commands. As a developer, you should always validate that the returned data matches expected schemas.

Failure & Recovery

Plan for scenarios like device disconnects, user cancellations, or firmware upgrades mid-session. Your UI should guide users to reinitialize sessions gracefully.

Security checklist for integrators:
  • Validate all responses against JSON schemas.
  • Ensure minimal required permissions (don’t request unnecessary coins/methods).
  • Warn users if the Bridge version is outdated or unsupported.
  • Provide fallback flows or messaging if the Bridge is not installed.

FAQ

Q: Can browser-based apps use Trezor Bridge directly?

Yes — browsers supporting WebUSB can communicate with the installed Bridge. If WebUSB is unavailable, the Bridge provides a fallback via local HTTP/WebSocket endpoints.

Q: What happens if the Bridge is not installed?

Your app should detect this and prompt the user to download & install the Bridge. Provide links for Windows, macOS, and Linux, with guidance for reboot or relaunch.

Q: Is Bridge open source?

Yes. Its source is publicly maintained under repositories on GitHub. Developers can audit the code, propose changes, or fork as needed.

Q: How do I debug communication issues?

Use logging in the client library (if enabled), monitor network/USB traffic, inspect JSON‐RPC flows, and check Bridge logs (if accessible). Also, ensure correct manifest values and origins.

Q: How do I support multiple coins or blockchains?

The client library supports many built‑in coin modules — Bitcoin, Ethereum, DOT, etc. For new blockchains, you may implement custom transaction serialization and request signatures via generic `signTransaction` calls.