Documentation

Getting Started with Trezor Bridge

Trezor Bridge is the essential communication layer between your Trezor hardware wallet and your web browser. This documentation will guide you through installation, configuration, and troubleshooting to ensure you have a seamless experience with your Trezor device.

System Requirements

Before installing Trezor Bridge, ensure your system meets the following requirements:

Windows: Windows 10 or later (64-bit)
macOS: macOS 10.15 Catalina or later
Linux: Most modern distributions with kernel 4.0 or later
RAM: Minimum 50MB available memory
Disk Space: 100MB available storage
USB: USB 2.0 or higher port

How Trezor Bridge Works

Understanding the architecture of Trezor Bridge helps you appreciate its security model and troubleshoot issues effectively. The Bridge operates as a lightweight HTTP server running locally on your machine, listening on port 21325.

Communication Protocol

When you access Trezor Wallet through your browser, the web application sends HTTP requests to the Bridge running on localhost. The Bridge then translates these requests into the USB protocol that your Trezor device understands. This architecture provides several benefits:

Browser Independence: Works with any modern web browser without requiring extensions
Security: All communication is local; no data is sent to external servers
Compatibility: Uniform interface across different operating systems
Isolation: Separates web content from hardware access for enhanced security

API Endpoints

Trezor Bridge exposes several HTTP endpoints for different purposes. Here are the most important ones:

GET http://127.0.0.1:21325/

Returns basic information about Bridge

GET http://127.0.0.1:21325/status

Returns the current status and version

POST http://127.0.0.1:21325/enumerate

Lists all connected Trezor devices

POST http://127.0.0.1:21325/acquire/[session]

Acquires a device session for communication

Configuration Options

While Trezor Bridge is designed to work out of the box with minimal configuration, advanced users can customize certain aspects of its behavior.

Configuration File Location

Windows:

%APPDATA%\Trezor Bridge\config.json

macOS:

~/Library/Application Support/Trezor Bridge/config.json

Linux:

~/.config/trezor-bridge/config.json

Available Configuration Parameters

{
  "port": 21325,
  "allowedOrigins": [
    "https://wallet.trezor.io",
    "https://suite.trezor.io"
  ],
  "logLevel": "info",
  "updateCheckInterval": 86400,
  "debugMode": false
}

Note: Modifying the configuration file is generally not necessary. The default settings are optimized for security and performance. Only change these values if you have specific requirements and understand the implications.

Troubleshooting Common Issues

Device Not Detected

If your Trezor device is not being detected, try the following steps in order:

Verify that Trezor Bridge is running by checking your system tray or menu bar
Try a different USB cable or USB port
Restart Trezor Bridge from the system tray menu
On Linux, verify that udev rules are properly installed
Temporarily disable any security software that might be blocking USB access
Restart your computer and try again

Bridge Not Starting

If Trezor Bridge fails to start after installation:

Check if another program is using port 21325
Verify that you have the necessary permissions to run the application
On macOS, check System Preferences → Security & Privacy for blocked applications
Review the Bridge log files for error messages
Try reinstalling Bridge with administrative privileges

Connection Timeouts

Occasional connection timeouts can occur due to various reasons. If you experience frequent timeouts:

Ensure your Trezor device firmware is up to date
Check for Bridge updates and install if available
Avoid using USB hubs; connect directly to your computer
Close other applications that might be accessing the USB ports
If on a laptop, ensure it's plugged into power (some laptops reduce USB power on battery)

Advanced Topics

Using Bridge with Custom Applications

Developers can integrate Trezor Bridge into their own applications. The Bridge API is open and documented, allowing third-party applications to communicate with Trezor devices securely.

To use Bridge in your application, you'll need to send HTTP requests to the Bridge endpoints. All requests must originate from allowed origins, which by default includes localhost for development purposes.

Example: Enumerating devices

fetch('http://127.0.0.1:21325/enumerate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }
})
.then(response => response.json())
.then(devices => console.log(devices));

Security Considerations

When developing applications that use Trezor Bridge, keep these security best practices in mind:

Always use HTTPS for your web application in production
Never store private keys or sensitive data in your application
Implement proper user confirmations for all transactions
Validate all data received from the Bridge before processing
Keep your application and Bridge updated to the latest versions
Follow Trezor's official integration guidelines

Linux udev Rules

On Linux systems, udev rules are necessary to grant proper permissions for USB access. The Bridge installation package should install these automatically, but if needed, you can install them manually:

sudo wget -O /etc/udev/rules.d/51-trezor.rules https://data.trezor.io/udev/51-trezor.rulessudo udevadm control --reload-rules && sudo udevadm trigger

After applying the udev rules, you may need to unplug and replug your Trezor device for the changes to take effect.

Logs and Debugging

When troubleshooting issues, Bridge log files can provide valuable diagnostic information.

Log File Locations

Windows:

%LOCALAPPDATA%\Trezor Bridge\logs\