Skip to main content

​
Basic Initialization

Before using any Trezor Connect methods, you must initialize the SDK with your application manifest: 
import TrezorConnect from '@trezor/connect';

await TrezorConnect.init({
  manifest: {
    appName: 'My Application',
    appUrl: 'https://myapp.example.com',
    email: '[email protected]',
  },
});
The manifest object is required. Initialization will fail if the manifest is not provided or is incomplete.

​
Manifest Configuration

The manifest identifies your application to Trezor devices and users: 
const manifest = {
  // Required: Display name of your application
  appName: 'My Crypto Wallet',
  
  // Required: Your application's URL
  appUrl: 'https://wallet.example.com',
  
  // Required: Developer contact email
  email: '[email protected]',
  
  // Optional: Icon URL (displayed in Trezor Suite)
  appIcon: 'https://wallet.example.com/icon.png',
};

await TrezorConnect.init({ manifest });
The manifest information is displayed to users during certain operations and helps them identify which application is requesting access to their device.

​
Complete Example

Here’s a full example with proper error handling and event listeners:
index.ts
import TrezorConnect, { DEVICE_EVENT, TRANSPORT_EVENT } from '@trezor/connect';

const initializeTrezor = async () => {
  try {
    // Initialize Trezor Connect
    await TrezorConnect.init({
      manifest: {
        appName: 'My Crypto Wallet',
        appUrl: 'https://wallet.example.com',
        email: '[email protected]',
      },
      // Optional: Enable debug logging
      debug: false,
      // Optional: Configure lazy loading
      lazyLoad: false,
    });

    console.log('Trezor Connect initialized successfully');

    // Listen for device events
    TrezorConnect.on(DEVICE_EVENT, event => {
      console.log('Device event:', event.type, event.payload);
      
      if (event.type === 'device-connect') {
        console.log('Device connected:', event.payload);
      } else if (event.type === 'device-disconnect') {
        console.log('Device disconnected:', event.payload);
      }
    });

    // Listen for transport events
    TrezorConnect.on(TRANSPORT_EVENT, event => {
      console.log('Transport event:', event.type, event.payload);
    });

  } catch (error) {
    console.error('Failed to initialize Trezor Connect:', error);
  }
};

initializeTrezor();

​
Configuration Options

Trezor Connect accepts various configuration options during initialization:

​
Debug Mode

Enable detailed logging for development: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  debug: true,
});
Enable debug mode during development to see detailed logs of device communication, method calls, and events. Disable it in production to reduce console noise.

​
Lazy Loading

Control when the core Connect engine initializes: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  lazyLoad: true,
});
When lazyLoad is true, the Connect core engine won’t initialize until the first API method is called. This can improve initial load time for applications that don’t immediately need device access.Default: false

​
Transport Configuration

Specify which transport methods to use for device communication: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  transports: ['BridgeTransport'],
});
Available transports:
  • 'BridgeTransport': Trezor Bridge (default for Node.js)
  • 'WebUsbTransport': Direct WebUSB connection (web only)
In Node.js environments, if no transports are specified, BridgeTransport is used by default.

​
Transport Reconnect

Automatically reconnect to transport when connection is lost: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  transportReconnect: true, // default: true
});

​
Binary Files Configuration

Configure the location of firmware and binary files: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  binFilesBaseUrl: 'https://data.trezor.io',
  enableFirmwareHashCheck: true,
});
Setting binFilesBaseUrl is required if you want to use firmware update features or enable automatic firmware hash verification.

​
THP (Trezor Host Protocol) Settings

Configure THP protocol for enhanced device communication: 
await TrezorConnect.init({
  manifest: { /* ... */ },
  thp: {
    hostName: 'My Application',
    appName: 'Crypto Wallet',
    pairingMethods: ['CodeEntry', 'QrCode'],
  },
});

​
Event Handling

Trezor Connect uses an event-driven architecture. Subscribe to events to react to device and transport changes:

​
Device Events

import { DEVICE_EVENT } from '@trezor/connect';

TrezorConnect.on(DEVICE_EVENT, event => {
  switch (event.type) {
    case 'device-connect':
      console.log('Device connected:', event.payload);
      break;
    case 'device-disconnect':
      console.log('Device disconnected:', event.payload);
      break;
    case 'device-changed':
      console.log('Device state changed:', event.payload);
      break;
  }
});

​
Transport Events

import { TRANSPORT_EVENT } from '@trezor/connect';

TrezorConnect.on(TRANSPORT_EVENT, event => {
  switch (event.type) {
    case 'transport-start':
      console.log('Transport started:', event.payload);
      break;
    case 'transport-error':
      console.log('Transport error:', event.payload);
      break;
  }
});

​
Blockchain Events

import { BLOCKCHAIN_EVENT } from '@trezor/connect';

TrezorConnect.on(BLOCKCHAIN_EVENT, event => {
  console.log('Blockchain event:', event.type, event.payload);
});

​
Removing Event Listeners

Clean up event listeners when they’re no longer needed: 
const handleDeviceEvent = event => {
  console.log('Device event:', event);
};

// Add listener
TrezorConnect.on(DEVICE_EVENT, handleDeviceEvent);

// Remove specific listener
TrezorConnect.off(DEVICE_EVENT, handleDeviceEvent);

// Remove all listeners
TrezorConnect.removeAllListeners();

​
Environment-Specific Configuration

​
Node.js

import TrezorConnect from '@trezor/connect';

await TrezorConnect.init({
  manifest: {
    appName: 'My Node App',
    appUrl: 'http://localhost:3000',
    email: '[email protected]',
  },
  transports: ['BridgeTransport'],
});

// Use the API
const result = await TrezorConnect.getFeatures();
if (result.success) {
  console.log('Device features:', result.payload);
}
Prerequisites for Node.js:
  • Trezor Bridge must be installed and running
  • Device must be connected via USB

​
Web Application

web-app.ts
import TrezorConnect from '@trezor/connect-web';

await TrezorConnect.init({
  manifest: {
    appName: 'My Web Wallet',
    appUrl: 'https://wallet.example.com',
    email: '[email protected]',
  },
  // Web-specific: popup will handle user interactions
  lazyLoad: false,
});

// The popup will automatically appear for user interactions
const result = await TrezorConnect.getAddress({
  path: "m/49'/0'/0'/0/0",
  coin: 'btc',
  showOnTrezor: true,
});

​
React Integration

use-trezor.ts
import { useEffect, useState } from 'react';
import TrezorConnect, { DEVICE_EVENT } from '@trezor/connect-web';

export const useTrezor = () => {
  const [initialized, setInitialized] = useState(false);
  const [device, setDevice] = useState(null);

  useEffect(() => {
    const initTrezor = async () => {
      try {
        await TrezorConnect.init({
          manifest: {
            appName: 'My React App',
            appUrl: window.location.origin,
            email: '[email protected]',
          },
        });
        setInitialized(true);
      } catch (error) {
        console.error('Failed to initialize:', error);
      }
    };

    initTrezor();

    const handleDeviceEvent = event => {
      if (event.type === 'device-connect') {
        setDevice(event.payload);
      } else if (event.type === 'device-disconnect') {
        setDevice(null);
      }
    };

    TrezorConnect.on(DEVICE_EVENT, handleDeviceEvent);

    return () => {
      TrezorConnect.off(DEVICE_EVENT, handleDeviceEvent);
    };
  }, []);

  return { initialized, device };
};

​
Error Handling

Always handle initialization errors: 
try {
  await TrezorConnect.init({
    manifest: {
      appName: 'My App',
      appUrl: 'https://myapp.com',
      email: '[email protected]',
    },
  });
} catch (error) {
  if (error.code === 'Init_ManifestMissing') {
    console.error('Manifest is required for initialization');
  } else if (error.code === 'Init_AlreadyInitialized') {
    console.warn('Trezor Connect is already initialized');
  } else {
    console.error('Initialization failed:', error);
  }
}
Calling init() multiple times will throw an Init_AlreadyInitialized error. Initialize only once in your application lifecycle.

​
Cleanup

Properly dispose of Trezor Connect when your application unmounts: 
// Clean up resources
TrezorConnect.dispose();
Call dispose() when:
  • Your application is shutting down
  • You need to reinitialize with different settings
  • You want to clean up all event listeners and connections

​
Complete Working Example

Here’s a complete Node.js example that you can run:
example.ts
import TrezorConnect, { DEVICE_EVENT, TRANSPORT_EVENT } from '@trezor/connect';

/**
 * Complete example of Trezor Connect initialization
 * 
 * Prerequisites:
 * - Trezor Bridge running
 * - Device connected via USB
 */
const main = async () => {
  try {
    // Initialize with manifest
    await TrezorConnect.init({
      manifest: {
        appName: 'Trezor Connect Example',
        appUrl: 'http://localhost:3000',
        email: '[email protected]',
      },
      debug: true,
    });

    console.log('✓ Trezor Connect initialized');

    // Set up event listeners
    TrezorConnect.on(TRANSPORT_EVENT, event => {
      console.log('Transport:', event.type);
    });

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

    // Get device features
    const features = await TrezorConnect.getFeatures();
    
    if (features.success) {
      console.log('Device model:', features.payload.model);
      console.log('Firmware version:', features.payload.fw_version);
      console.log('Device ID:', features.payload.device_id);
    } else {
      console.error('Failed to get features:', features.error);
    }

  } catch (error) {
    console.error('Error:', error);
    process.exit(1);
  }
};

main();

​
Next Steps

API Methods

Explore available API methods for blockchain operations

Supported Coins

View all supported cryptocurrencies and networks

Examples

Browse complete example implementations

Events

Learn more about event handling

Build docs developers (and LLMs) love

Get started for freeTalk to us