81625d35d2
- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT) - Add human-blocked section with 3 precise next steps for owner - Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria
3.4 KiB
title, tags
| title | tags | ||||
|---|---|---|---|---|---|
| Trezor API |
|
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
registrationAddressto equal xpub-derivedm/44'/60'/0'/0/0. - Requires
proofSignatureto recoverregistrationAddress.
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.
Auth: bearer JWT
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
Verifies a signed operation intent against the admin's registered Trezor safekeeping address.
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.