Comprehensive documentation for Trezor Bridge, covering installation, configuration, API integration, and advanced usage scenarios. This guide is designed for both end users and developers who want to integrate Trezor Bridge into their applications.
Getting Started
Trezor Bridge serves as a communication layer between web applications and your Trezor hardware wallet. Before diving into advanced features, ensure you have downloaded and installed the latest version from our download page.
Prerequisites
Before using Trezor Bridge, ensure you have a compatible Trezor device, a supported operating system, and a modern web browser.
Basic Usage
Once installed, Trezor Bridge runs automatically in the background. When you visit a web application that needs to communicate with your Trezor device, the Bridge facilitates this connection seamlessly.
Connecting Your Device
- Connect your Trezor device to an available USB port
- Ensure Trezor Bridge is running (check your system tray)
- Open your web browser and navigate to a Trezor-compatible application
- The application will automatically detect your device through the Bridge
- Follow on-screen instructions to complete authentication
API Integration
Developers can integrate Trezor Bridge into their web applications using our JavaScript API. The Bridge exposes a RESTful interface running on localhost that applications can communicate with.
// Check if Trezor Bridge is running
fetch('http://localhost:21325')
.then(response => response.json())
.then(data => {
console.log('Bridge version:', data.version);
})
.catch(error => {
console.error('Bridge not running:', error);
});Communication Protocol
The Bridge uses HTTP for communication with web applications and USB HID protocol for device communication. All messages are encrypted and signed to ensure security.
Endpoint: /enumerate
Returns a list of all connected Trezor devices with their current status and session information.
Endpoint: /acquire
Acquires a session with a specific device, allowing the application to send commands and receive responses.
Endpoint: /call
Sends a command to the device and returns the response. Used for all device operations including signing transactions.
Endpoint: /release
Releases a previously acquired session, freeing the device for use by other applications.
Configuration Options
Advanced users can customize Trezor Bridge behavior through configuration files. These files are located in platform-specific directories and use JSON format.
Configuration File Locations
- Windows: %APPDATA%\Trezor\Bridge\config.json
- macOS: ~/Library/Application Support/Trezor/Bridge/config.json
- Linux: ~/.config/trezor-bridge/config.json
Configuration Parameters
port (integer, default: 21325)
The TCP port on which the Bridge listens for HTTP requests. Change this if the default port is already in use.
logLevel (string, default: "error")
Controls the verbosity of logging. Options: "error", "warn", "info", "debug". Higher levels provide more detailed output.
allowOrigin (array, default: ["*"])
List of allowed origins for CORS. Restrict this to specific domains for enhanced security in enterprise environments.
Security Best Practices
When developing applications that integrate with Trezor Bridge, follow these security best practices to ensure the safety of user funds:
- Always verify transaction details on the device screen before signing
- Never cache or store private keys or sensitive data in browser storage
- Implement proper error handling for all Bridge communication
- Use HTTPS for all web applications that integrate with Trezor Bridge
- Validate all data received from the Bridge before processing
- Implement session timeouts to prevent unauthorized access
- Keep Trezor Bridge updated to the latest version
Troubleshooting
Common issues and their solutions:
Bridge not responding
Check that the Bridge service is running. On Windows, look in the system tray. On macOS/Linux, use the activity monitor or process manager. Restart the service if necessary.
Device not detected
Verify USB connection, try a different port or cable. On Linux, ensure proper udev rules are installed. Check device permissions if running Bridge as non-root user.
CORS errors in browser console
This usually indicates a configuration issue. Ensure your web application's origin is allowed in the Bridge configuration, or check that the application is using the correct protocol (HTTP vs HTTPS).
Advanced Topics
Multi-Device Support
Trezor Bridge supports multiple devices connected simultaneously. Applications can enumerate all connected devices and acquire sessions with specific devices based on user selection or device path.
Proxy Configuration
In enterprise environments with HTTP proxies, Trezor Bridge can be configured to route traffic through proxy servers. Configure proxy settings in the configuration file using standard proxy URL format.
Logging and Debugging
Enable debug logging by setting logLevel to "debug" in the configuration file. Logs are written to platform-specific locations and can help diagnose communication issues between applications and devices.
Version History
Trezor Bridge has evolved significantly since its first release. Each version brings improvements in security, stability, and compatibility. Always use the latest version for the best experience and security.
Version 2.0.x
Major rewrite with improved performance, enhanced security features, and better cross-platform compatibility.
Version 1.x
Initial stable release with core functionality for device communication and transaction signing.