nick-doc/03 - API Reference/Trezor API.md

title, tags

title	tags
Trezor API	api payments trezor safekeeping

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

Trezor API

The Trezor API is mounted at /api/trezor. It is optional support for hardware-backed safekeeping and does not replace Request Network checkout, the funds ledger, or the broader Safe/multisig custody roadmap.

Enforcement is controlled by:

TREZOR_SAFEKEEPING_REQUIRED=false

Only the literal value true makes Trezor proof mandatory during release/refund confirmation. When unset or false, release/refund flows continue without Trezor proof.

GET /api/trezor/registration-message

Builds the exact message the user must sign to register a Trezor xpub.

Auth: bearer JWT

Query:

xpub=<extended public key>
registrationAddress=<first derived address>

Response:

{
  "success": true,
  "data": {
    "message": "Amanat escrow Trezor registration\n..."
  }
}

POST /api/trezor/register

Registers a Trezor xpub after the first derived address signs the registration challenge.

Auth: bearer JWT

Body:

{
  "xpub": "xpub...",
  "registrationAddress": "0x...",
  "proofMessage": "Amanat escrow Trezor registration\n...",
  "proofSignature": "0x...",
  "basePath": "m/44'/60'/0'",
  "deviceLabel": "Office Trezor"
}

Validation:

• Rejects private extended keys (xprv, tprv).
• Requires registrationAddress to equal xpub-derived m/44'/60'/0'/0/0.
• Requires proofSignature to recover registrationAddress.

Response:

{
  "success": true,
  "data": {
    "xpubFingerprint": "0x...",
    "registrationAddress": "0x...",
    "basePath": "m/44'/60'/0'",
    "nextAddressIndex": 1
  }
}

GET /api/trezor/account

Returns the caller's active Trezor registration summary. If no Trezor has been registered for the authenticated user, returns { registered: false } without an error.

Auth: bearer JWT

Response when registered:

{
  "success": true,
  "data": {
    "registered": true,
    "xpubFingerprint": "0x...",
    "registrationAddress": "0x...",
    "basePath": "m/44'/60'/0'",
    "deviceLabel": "Office Trezor",
    "nextAddressIndex": 3
  }
}

Response when absent:

{
  "success": true,
  "data": {
    "registered": false
  }
}

POST /api/trezor/addresses/next

Allocates or returns a deterministic receive address from the registered xpub.

Auth: bearer JWT

Body:

{
  "purpose": "deposit",
  "paymentId": "..."
}

If paymentId already has an assigned address, the same address is returned. Otherwise the backend derives:

m/44'/60'/0'/0/{nextAddressIndex}

POST /api/trezor/operation-message

Builds the exact transaction-intent message an admin must sign when Trezor safekeeping is enabled.

Auth: bearer JWT, admin

Body:

{
  "operation": "release",
  "paymentId": "...",
  "transactionHash": "0x...",
  "amount": 100,
  "currency": "USDT",
  "provider": "request.network"
}

Response:

{
  "success": true,
  "data": {
    "message": "Amanat escrow Trezor transaction approval\n..."
  }
}

POST /api/trezor/verify-operation

Admin-only standalone signature verification endpoint. Verifies a signed operation intent against the admin's registered Trezor safekeeping address without performing any release or refund. Use this to validate a Trezor proof before submitting it to the release/refund flow.

Auth: bearer JWT, admin

Body:

{
  "payload": {
    "operation": "release",
    "paymentId": "...",
    "transactionHash": "0x...",
    "amount": 100,
    "currency": "USDT",
    "provider": "request.network"
  },
  "message": "Amanat escrow Trezor transaction approval\n...",
  "signature": "0x..."
}

Release / Refund Integration

When TREZOR_SAFEKEEPING_REQUIRED=true, release/refund confirmation bodies must include the Trezor proof:

{
  "txHash": "0x...",
  "amount": 100,
  "trezor": {
    "message": "Amanat escrow Trezor transaction approval\n...",
    "signature": "0x..."
  }
}

This proof is optional when enforcement is disabled.