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.
A proxy service sits between wallet clients and AMP2, translating plain JSON requests into COSE wrapped AMP2 calls. This lets wallet apps interact with AMP2 without implementing the COSE protocol directly.
Why use a proxy
- COSE complexity hidden: wallet clients send and receive plain JSON. The proxy handles COSE encryption, signing, CBOR encoding, and key management.
- Session management: the proxy manages AMP2 bearer tokens and device sessions.
Architecture
Wallet Client ──── Plain JSON ────► Proxy Service ──── COSE ────► AMP2 Server
│
├── Authenticates to AMP2 as issuer
└── Translates JSON → COSE → JSONThe proxy authenticates to AMP2 using an issuer account. It is the issuer's responsibility to operate the proxy securely.
Available proxy operations
The proxy exposes two operations to wallet clients:
Register wallet
Register a wallet descriptor with AMP2 and receive a wallet ID (WID).
POST /register
Request: { "descriptor": "ct(elip151,elwsh(multi(2,...)))" }
Response: { "wid": "wallet_id" }Cosign PSET
Submit a partially signed transaction for AMP2 cosigning. The HSM validates restrictions and adds the server signature.
POST /cosign
Request: { "pset": "base64_encoded_pset" }
Response: { "pset": "base64_cosigned_pset" }Authentication model
The proxy authenticates to AMP2 as an issuer account. It holds:
- RSA and ECDSA key pairs for COSE
- Bearer token management
- Device UUID from the invite
Wallet clients authenticate to the proxy using the proxy's own auth mechanism (API keys, OAuth, session tokens). The proxy does not expose AMP2 credentials to clients.
Deployment models
| Model | Description | Best for |
|---|---|---|
| Sidecar | Runs alongside the wallet backend | Single tenant, tight integration |
| Standalone service | Independent deployment | Multi tenant, shared infrastructure |
| Hosted | Operated by Blockstream | Lowest integration effort |
Security considerations
- Never expose AMP2 keys to wallet clients. All COSE operations happen inside the proxy.
- Validate all inputs at the proxy level before forwarding to AMP2.
- Rate limit aggressively: restrict per client request rates to prevent abuse.
- Log all proxy requests for audit and debugging.
- Use TLS between wallet clients and the proxy.
Next steps
- UX Recommendations: display guidance for wallet clients
- Receiving Assets: detecting incoming transfers via LWK
- Architecture: COSE flow and system overview
PSET signature
PSET signature supports outgoing asset transfers. The page explains transaction construction, AMP2 cosigning, local signing, broadcast, errors, and serialization helpers.
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.