Trezor Suite® – Getting Started™ Developer Portal

Welcome to the Trezor Suite® – Getting Started™ Developer Portal, your comprehensive guide designed to empower developers integrating or extending the Trezor Suite ecosystem.

Introduction

This portal helps developers navigate the practical steps, best practices, and workflows required to create secure and efficient tools ranging from small plugins to full production-grade integrations.

Prerequisites

Hardware & Accounts

You will need a Trezor device (Model T or Model One) and a verified developer account for access to the developer portal. While emulators and testnets can simulate many flows, hardware testing on an actual device is strongly recommended for production-ready apps.

Software & Tools

Ensure Node.js (LTS), a modern browser (such as Chrome, Firefox, or Brave), and Git are installed. Familiarity with terminal commands will streamline your setup process.

Setting up Your Environment

1. Create the Project

mkdir trezor-dev-portal
cd trezor-dev-portal
npm init -y
npm install axios express dotenv

2. Configuration

Create a .env file to securely store environment variables and API keys. Never commit your secrets to version control.

PORT=3000
TREZOR_API_URL=https://developer.trezor.io/api
TREZOR_CLIENT_ID=your-client-id
TREZOR_CLIENT_SECRET=your-secret

Notes on Local Development

Use a dedicated local profile or Docker container for isolation and enhanced security. Tools like ngrok can expose your local server through a secure public URL, useful for webhooks.

Authentication & Keys

OAuth 2.0 Flow (Recommended for Web Apps)

The OAuth 2.0 authorization code flow with PKCE is the most secure option for browser-based apps, minimizing client secret exposure risks.

Service Keys and Rotating Secrets

Backend services should utilize short-lived service keys, storing them securely with secrets managers such as HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault, and implement automatic rotation.

API Reference Overview

Accessible API endpoints provide structured interactions for device management, transactions, user profiles, webhooks, and emulators:

/v1/devices — Query device metadata and capabilities
/v1/transactions — Create, sign, and broadcast wallet transactions
/v1/users — Access user profiles and developer account information
/v1/webhooks — Register callbacks for device and transaction events
/v1/simulators — Manage emulated devices for automated testing

Request & Response Patterns

All API communication uses JSON over HTTPS, with these headers:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <token> (when required)

Examples & Workflows

Quick Example: Fetch Connected Devices

const axios = require('axios');

async function fetchDevices(token) {
  const res = await axios.get(process.env.TREZOR_API_URL + '/v1/devices', {
    headers: { Authorization: `Bearer ${token}` }
  });
  return res.data;
}

Signing a Transaction (High-level)

Construct the unsigned transaction payload on your server.
Send the payload to the device via API or USB bridge for signing.
Receive and broadcast the signed transaction to the network.

Security Tip

Never expose the full unsigned payload to untrusted clients. Keep sensitive operations server-side, and use the device as the final trusted signing step.

Best Practices

Minimize Attack Surface: Restrict API scopes, use Content Security Policy (CSP), and avoid inline scripts in production.
Robust Error Handling & Observability: Implement exponential backoff for retries, instrument tracing, and translate errors into user-friendly messages.
Test Extensively with Emulators: Automate tests covering firmware mismatch, device disconnections, and operation refusals.

Troubleshooting

Connection Problems

Check USB permissions, update firmware, verify USB cable and ports, and ensure firewall or bridge process isn’t blocking communication.

Authentication Failures

Verify client ID and secret, check server clock synchronization, and confirm tokens are valid and not revoked.

Office Links (Placeholders)

Below are placeholder links to internal documents that you may customize:

FAQ

What is the purpose of the Trezor Suite Developer Portal?

The portal provides APIs and developer tools to build integrations and interact securely with Trezor hardware wallets and the Trezor Suite ecosystem.

Do I need a physical Trezor device to start development?

While emulators allow simulated testing, it is strongly recommended to test on a physical device before production deployment.

How do I secure my API keys?

Store keys securely using secrets management systems and rotate them regularly to minimize risk.

Can I use the Developer Portal for both web and server applications?

Yes. OAuth 2.0 with PKCE is recommended for web apps, while API key/secret pairs are suitable for server-to-server communication.

How can I troubleshoot connection issues with my Trezor device?

Check USB permissions, firmware versions, try different cables or ports, and ensure no firewall or bridge issues block communication.