UX recommendations
The page provides UI recommendations for wallets and venues that support AMP2-managed assets, including error messages, confirmation states, terminology, and fee awareness.
Guidelines for building wallet and venue UIs that interact with AMP2 managed assets. These recommendations help translate AMP2's technical concepts into clear user experiences.
Error message mapping
When AMP2 operations fail, translate technical errors into user friendly messages:
| Technical cause | User facing message | Severity |
|---|---|---|
| Cosign refused (whitelist) | "Transfer not allowed. The destination is not an approved wallet." | Error |
| Cosign refused (burn) | "Burn not permitted for this wallet." | Error |
| Asset locked | "This asset is temporarily frozen. Try again later." | Warning |
| Wallet locked | "Your wallet is temporarily frozen. Contact support." | Warning |
| Insufficient asset balance | "Not enough tokens for this transfer." | Error |
| Insufficient LBTC | "Transaction fees unavailable. The wallet needs LBTC." | Error |
| PSET broadcast rejected | "Transaction could not be submitted. Please try again." | Error |
| Network timeout | "Connection issue. Please check your connection and retry." | Warning |
Pending state handling
Liquid transactions confirm in approximately 1 minute. Design the UI to handle this delay:
After sending
- Show a "Transaction submitted" confirmation with the txid immediately.
- Display the transfer as "Pending" in the transaction list.
- Poll for confirmation every 60 seconds (Liquid produces one block per minute).
- Update to "Confirmed" when the transaction appears in a confirmed block.
After receiving
- When a new unconfirmed transaction is detected, show it as "Incoming (pending)".
- Update the balance display after block confirmation.
- Avoid showing unconfirmed incoming transfers as spendable balance.
Confirmation polling
Broadcast → Wait 60s → Check status → Confirmed? → Update UI
↑ │
└── No ──── Wait 60s ────┘Liquid produces one block per minute, so polling more frequently than every 60 seconds provides no benefit. After 5 minutes without confirmation, show a warning: "Transaction is taking longer than expected." After 10 minutes, suggest contacting support.
Terminology guidance
Use wallet native language. Avoid AMP2 internal terms unless building advanced tooling:
| AMP2 term | User facing term |
|---|---|
| WID | Wallet ID (or just "wallet") |
| PSET | Transaction (users don't need to know about PSETs) |
| Cosign | Transaction processing |
| Restriction group | Transfer policy / approval list |
| Whitelist | Approved destinations |
| Satoshi | Amount (display with appropriate precision) |
| LBTC | Network fee balance |
| Descriptor | Wallet address (simplify for non technical users) |
Amount display
Use the asset's precision field to format amounts correctly:
| Precision | Raw (satoshi) | Display |
|---|---|---|
| 8 | 100000000 | 1.00000000 |
| 2 | 100000 | 1,000.00 |
| 0 | 1000 | 1,000 |
Always show the asset ticker alongside the amount (e.g., "1,000.00 MST").
Restricted asset indicators
If an asset has transfer restrictions:
- Show a visual indicator (e.g., a lock icon or "Restricted" badge) on the asset card.
- When the user attempts a transfer, pre check the destination against known restrictions if possible.
- If a transfer fails due to restrictions, explain clearly: "This asset can only be sent to approved wallets."
Network fee awareness
Since LBTC is required for Liquid transaction fees:
- Show the LBTC balance alongside asset balances.
- Warn users if LBTC balance is low before they attempt a transfer.
- Provide guidance on how to acquire LBTC (peg in from Bitcoin, or receive from the issuer).
Next steps
- Proxy Integration: wallet registration and PSET cosigning
- Receiving Assets: balance refresh patterns
- Restrictions: understand transfer policies
Proxy integration
A proxy service translates plain JSON requests into COSE-wrapped AMP2 calls. The page explains proxy purpose, operations, authentication, deployment models, and security guidance.
JS SDK reference
The AMP2 SDK uses three packages. The page explains core classes, request patterns, endpoint domains, pagination, and related guide pages.