The built-in payments feature is experimental and currently unmaintained. The gRPC APIs exist but require a Lightning wallet backend (like LND or NWC) that may not be configured in most deployments.

This documentation covers both the native APIs (for when they're fully supported) and workarounds using SHM's core primitives.

SHM payments leverage the cryptographic identity system. Your DID (Decentralized Identifier) serves as your payment identity. The vision:

• Wallets linked to your SHM account
• Invoices cryptographically signed by the recipient
• Payment proofs verifiable through the identity system
• No centralized payment processor required

The Wallets service manages Lightning wallet connections:

# Available gRPC methods
Wallets/CreateWallet      # Create new wallet
Wallets/GetWallet         # Get wallet details
Wallets/ListWallets       # List all wallets
Wallets/GetWalletBalance  # Check balance
Wallets/SetDefaultWallet  # Set default for account
Wallets/ImportWallet      # Import existing wallet
Wallets/ExportWallet      # Export wallet credentials
Wallets/RemoveWallet      # Delete wallet

Creating a wallet (when backend is configured):

grpcurl -plaintext -d '{
  "account": "z6Mk...",
  "name": "my-lightning-wallet"
}' localhost:55002 \
  com.seed.payments.v1alpha.Wallets/CreateWallet

Response includes:

{
  "id": "wallet-uuid",
  "account": "z6Mk...",
  "address": "lnbc1...",  // Lightning address
  "name": "my-lightning-wallet",
  "type": "lnd"  // Backend type
}

Create and pay Lightning invoices:

# Invoice methods
Invoices/CreateInvoice        # Generate invoice to receive
Invoices/PayInvoice           # Pay someone's invoice
Invoices/DecodeInvoice        # Parse invoice details
Invoices/ListPaidInvoices     # Invoices you've paid
Invoices/ListReceivedInvoices # Invoices paid to you

Creating an invoice:

grpcurl -plaintext -d '{
  "account": "z6Mk...",
  "amount": 1000,
  "memo": "Thanks for the coffee!"
}' localhost:55002 \
  com.seed.payments.v1alpha.Invoices/CreateInvoice

Decoding an invoice to verify before paying:

grpcurl -plaintext -d '{
  "payment_request": "lnbc1000n1..."
}' localhost:55002 \
  com.seed.payments.v1alpha.Invoices/DecodeInvoice

# Returns
{
  "payment_hash": "abc123...",
  "description": "Thanks for the coffee!",
  "amount": 1000,
  "expires_at": "2026-02-05T00:00:00Z"
}

Since the native payment APIs require backend configuration, here's a practical alternative using SHM's core features:

You can embed payment information directly in your profile metadata. Because profiles are cryptographically signed, others can verify this payment info belongs to you.

// Profile metadata approach
{
  "displayName": "IonBobcat",
  "bio": "Building documentation",
  "lightning_address": "ionbobcat@getalby.com",
  "bitcoin_address": "bc1q...",
  "tip_jar": "https://buymeacoffee.com/ionbobcat"
}

Advantages of this approach:

• Works today without special backend
• Use any payment provider you like (Alby, Strike, etc.)
• Cryptographically tied to your identity
• Verifiable across platforms
• No lock-in to SHM payment infrastructure

When you see payment info on someone's SHM profile, you can verify it's authentic:

# Fetch and verify a profile
grpcurl -plaintext -d '{
  "account": "z6MkTargetAccount..."
}' localhost:55002 \
  com.seed.documents.v3alpha.Documents/GetProfileDocument

# The response includes:
# - Signed blob with metadata
# - Account's public key
# - Timestamp of last update

# You can verify the signature matches the account's key
# Payment info in metadata is authenticated

This solves a real problem: how do you know a Lightning address actually belongs to someone? With SHM, the cryptographic identity proves ownership.

The architecture enables interesting payment patterns:

• Pay-per-document: Unlock content with Lightning
• Tipping authors: One-click tips on any document
• Subscription feeds: Pay for ongoing access
• Permissionless monetization: No platform cut
• Cross-platform identity: Same payment info everywhere

These features aren't implemented yet, but the cryptographic foundations make them possible. The identity + signing infrastructure is the hard part, and SHM has that.

Payment support in SHM is early-stage. The APIs exist but require configuration that isn't standard. For now, embedding payment info in your profile is the practical approach.

The important insight: cryptographic identity is the foundation payments need. SHM provides that, making future payment integrations much cleaner than building identity from scratch.

• /cli-guide - Working with the gRPC API
• /signing - How cryptographic signing works
• /identity-verification - Verifying accounts across platforms