This comprehensive documentation provides detailed technical information for developers integrating Trezor Bridge into their applications. Whether you're building a cryptocurrency wallet, DeFi platform, or any application requiring secure hardware wallet interaction, this guide covers everything you need to know about implementing Trezor Bridge communication protocols.
Getting Started with Integration
Trezor Bridge operates as a background service that exposes a local HTTP API on port 21325. Your web application communicates with this local server to send commands to the connected Trezor device. The communication protocol uses JSON-RPC 2.0 format, providing a standardized and well-documented interface for all device operations.
Before beginning development, ensure that Trezor Bridge is installed on your development machine. The service must be running for your application to detect and communicate with Trezor devices. You can verify Bridge is running by making a GET request to http://localhost:21325/status, which should return version information and the current status of connected devices.
API Communication Protocol
The Bridge API follows a request-response pattern where your application sends JSON-formatted commands and receives JSON responses. Each request must include a unique session identifier to maintain state across multiple operations. Session management is crucial for security, as it prevents unauthorized applications from intercepting ongoing communication with the device.
POST http://localhost:21325/
{
"jsonrpc": "2.0",
"method": "enumerate",
"params": {},
"id": 1
}The enumerate method is typically your first API call, returning a list of all connected Trezor devices with their respective paths and session identifiers. This information is essential for establishing communication channels with specific devices when multiple units are connected simultaneously.
Device Detection and Session Management
Proper device detection requires polling the Bridge API at regular intervals to monitor for newly connected or disconnected devices. A recommended polling interval is 1-2 seconds, providing responsive device detection without overwhelming the system with requests. Implement exponential backoff if Bridge is not running to prevent excessive failed connection attempts.
When a device is detected, acquire a session by calling the acquire method with the device path. Sessions are exclusive—only one application can hold a session with a device at any given time. This exclusivity prevents conflicts and ensures that sensitive operations like transaction signing cannot be intercepted by malicious software. Always release sessions using the release method when your operations are complete.
Transaction Signing Workflow
Signing cryptocurrency transactions involves a multi-step process that maintains security while providing a smooth user experience. First, prepare the transaction data according to the specific blockchain's requirements—Bitcoin transactions differ structurally from Ethereum transactions, and Bridge supports the unique requirements of each supported cryptocurrency.
Send the prepared transaction to the device using the appropriate signing method (SignTx for Bitcoin, SignMessage for message signing, etc.). The device will display transaction details on its screen, requiring explicit user confirmation via physical button press. This on-device verification is crucial—it ensures users can verify transaction details independently of potentially compromised computer systems.
After user confirmation, the device returns the signed transaction to your application through Bridge. Your application can then broadcast this signed transaction to the respective blockchain network. The private keys used for signing never leave the Trezor device, maintaining the fundamental security guarantee of hardware wallet systems.
Error Handling and Recovery
Robust error handling is essential for production applications. Bridge returns detailed error codes and messages for various failure scenarios including device disconnection, user rejection of transactions, PIN entry failures, and communication timeouts. Your application should handle each error type appropriately, providing clear user feedback and recovery options.
Common error scenarios include the device being locked (requiring PIN entry), the device being in bootloader mode (requiring firmware update), or session conflicts (another application holds the session). Implement retry logic with appropriate delays for transient errors, but always inform users when manual intervention is required. Never automatically retry operations that users explicitly canceled—respect user intent and provide clear options for retrying canceled operations.
Security Best Practices
When integrating Trezor Bridge, follow security best practices to protect your users. Always verify the integrity of transaction data before sending it to the device—validate addresses, amounts, and other critical fields in your application layer. Display transaction details in your UI so users can cross-reference with the device screen, catching any discrepancies that might indicate malware or UI spoofing attacks.
Implement content security policies that restrict communication to localhost:21325, preventing malicious scripts from redirecting Bridge communication to attacker-controlled servers. Use HTTPS for your web application to prevent man-in-the-middle attacks on the application layer, even though Bridge communication itself occurs locally. Regularly update to the latest Bridge version to benefit from security patches and protocol improvements.
Advanced Features
Beyond basic transaction signing, Bridge supports advanced features including multi-signature wallet operations, message verification for proof of ownership, firmware updates through your application, and recovery seed verification. These features enable building sophisticated wallet applications that leverage the full capabilities of Trezor devices while maintaining security and ease of use.
The PassphraseProtection feature allows users to add an additional security layer through BIP39 passphrases, creating hidden wallets accessible only with specific passphrases. When implementing passphrase support, carefully design your UI to explain the implications—lost passphrases mean permanently lost access to funds. Consider implementing passphrase strength indicators and confirmation steps to prevent user errors.
Testing and Debugging
Thorough testing is crucial before deploying Bridge integration to production. Use Trezor's emulator for automated testing without requiring physical devices. The emulator supports all device operations and can be scripted for continuous integration testing. Test edge cases including device disconnection during operations, concurrent session requests, and various error conditions to ensure your application handles all scenarios gracefully.
Enable Bridge logging during development by running it with verbose flags. Logs provide detailed information about communication between your application and the device, helping diagnose protocol issues and timing problems. Remember to disable verbose logging in production as it may expose sensitive operation details. Use browser developer tools to monitor network requests to the Bridge API, verifying correct request formatting and response handling.