Skip to main content

​
Overview

The libwallet address module provides comprehensive Bitcoin address generation and payment URI parsing functionality. It supports multiple address versions, BIP70/BIP72 payment requests, and unified QR codes with both on-chain and Lightning Network payments.

​
Address Versions

The library supports multiple address scheme versions: 
const (
    AddressVersionV1      = addresses.V1
    AddressVersionV2      = addresses.V2
    AddressVersionV3      = addresses.V3
    AddressVersionV4      = addresses.V4
    AddressVersionV5      = addresses.V5
    AddressVersionSwapsV1 = addresses.SubmarineSwapV1
    AddressVersionSwapsV2 = addresses.SubmarineSwapV2
)

​
MuunPaymentURI Structure

Represents a parsed payment URI containing on-chain and/or Lightning payment information. 
type MuunPaymentURI struct {
    Address      string
    Label        string
    Message      string
    Amount       string
    Uri          string
    Bip70Url     string
    CreationTime string
    ExpiresTime  string
    Invoice      *Invoice
}
​
Address
string
The Bitcoin address (bech32, P2PKH, P2SH, etc.)
​
Label
string
Optional label for the payment
​
Message
string
Optional message describing the payment
​
Amount
string
Payment amount in BTC (decimal notation)
​
Uri
string
The original URI string
​
Bip70Url
string
BIP70 payment request URL (if present)
​
Invoice
*Invoice
Lightning invoice (for unified QR codes)

​
GetPaymentURI

Parses a Bitcoin URI, address, or unified QR code into a MuunPaymentURI structure. 
func GetPaymentURI(rawInput string, network *Network) (*MuunPaymentURI, error)
​
rawInput
string
required
Bitcoin URI (bitcoin:), plain address, or unified QR code
​
network
*Network
required
Network configuration (mainnet, testnet, regtest)
Returns: *MuunPaymentURI - Parsed payment URI structure
Errors: ErrInvalidURI, ErrInvalidInvoice

​
Examples

network := Mainnet()
uri, err := GetPaymentURI("bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", network)
if err != nil {
    log.Fatal(err)
}
fmt.Println(uri.Address) // bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

​
DoPaymentRequestCall

Fetches and parses a BIP70/BIP72 payment request from a URL. 
func DoPaymentRequestCall(url string, network *Network) (*MuunPaymentURI, error)
​
url
string
required
BIP70 payment request URL
​
network
*Network
required
Network configuration
Returns: *MuunPaymentURI - Parsed payment request
Errors: ErrNetwork - Network error or invalid response

​
Example

network := Mainnet()
uri, err := DoPaymentRequestCall("https://example.com/payment?r=xyz", network)
if err != nil {
    log.Fatal(err)
}
fmt.Println(uri.Address)
fmt.Println(uri.Amount)
fmt.Println(uri.Message)

​
MuunAddress Interface

Defines the interface for Muun-generated addresses with derivation path information. 
type MuunAddress interface {
    Version() int
    DerivationPath() string
    Address() string
}
​
Version
int
Address scheme version (V1-V5, SubmarineSwapV1/V2)
​
DerivationPath
string
HD wallet derivation path (e.g., “m/schema:1’/recovery:1’/external:0/42”)
​
Address
string
The actual Bitcoin address string

​
URI Scheme Support

The library handles multiple URI schemes:
  • bitcoin: - Standard Bitcoin URI (BIP21)
  • bitcoin:// - Alternative format (iOS compatibility)
  • muun: - Muun-specific scheme (converted to bitcoin:)

​
Error Handling

const (
    ErrInvalidURI     = "invalid_uri"
    ErrInvalidInvoice = "invalid_invoice"
    ErrNetwork        = "network_error"
)
Common error scenarios:
  • Invalid address encoding
  • Network mismatch (testnet address on mainnet)
  • Amount mismatch in unified QR codes
  • Invalid BIP70 response
  • Malformed URI parameters

​
Validation

The library performs comprehensive validation:
  • Address validation: Checks address format and network compatibility
  • Amount validation: Handles scientific notation, validates numeric values
  • Unified QR validation: Ensures on-chain and Lightning amounts match
  • BIP70 validation: Verifies payment request structure and scripts
When both on-chain and Lightning amounts are present in a unified QR code, they must match exactly or an ErrInvalidURI error is returned.

​
Advanced Features

​
Amount Parsing

The library handles flexible amount formats:
  • Standard decimal notation (“0.001”)
  • Scientific notation (converted to decimal)
  • Automatic validation for NaN/Inf values

​
BIP70 Support

Full support for BIP70 payment protocol:
  • Payment request fetching with proper Accept headers
  • Payment details parsing (protobuf)
  • Multiple outputs handling
  • Expiration time tracking

​
Legacy Compatibility

Supports legacy Muun P2P/contacts URIs for backward compatibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us