Lightning Network payments via Archon DIDs - create wallets, send/receive sats, verify payments, Lightning Address zaps
Lightning Network integration for Archon decentralized identities. Send and receive Bitcoin over Lightning using your DID.
Related skills:
archon-keymaster — Core DID identity managementarchon-vault — Encrypted backups[email protected])npx @didcid/keymaster)~/.archon.env with ARCHON_WALLET_PATH, ARCHON_PASSPHRASE)jq recommended for JSON parsingAll created by archon-keymaster setup. If you don't have Archon configured yet, see the archon-keymaster skill first.
This skill handles Lightning Network payments:
lightning-pay.sh automatically verifies payments; if using keymaster directly, you must verify manually with lightning-check (see Payment Verification Pattern below)~/.archon.env for wallet access./scripts/lightning/add-lightning.sh [id]
Creates a Lightning wallet for your current DID (or specified DID alias).
Examples:
./scripts/lightning/add-lightning.sh # Current DID
./scripts/lightning/add-lightning.sh work # Specific DID alias
./scripts/lightning/lightning-balance.sh [id]
Returns current balance in satoshis.
Example output:
2257 sats
./scripts/lightning/lightning-invoice.sh <amount> <memo> [id]
Creates a BOLT11 invoice to receive payment.
Arguments:
amount - Amount in satoshis (1000 = 0.00001 BTC)memo - Description/memo for the invoiceid - (optional) DID alias, defaults to current identityExample:
./scripts/lightning/lightning-invoice.sh 1000 "Coffee payment"
Output:
{
"paymentRequest": "lnbc10u1p...",
"paymentHash": "a3f7b8c9..."
}
Share this invoice with the payer. They can:
./scripts/lightning/lightning-pay.sh <bolt11> [id]
Pay a BOLT11 invoice with automatic payment verification.
Arguments:
bolt11 - BOLT11 invoice stringid - (optional) DID alias to pay fromOutput: Success or failure message with exit code
Example:
./scripts/lightning/lightning-pay.sh lnbc10u1p...
# ✅ Payment confirmed
# (exits 0 on success, 1 on failure)
The script automatically verifies the payment settled before outputting success.
The payment hash is NOT proof of payment! Lightning payments can fail, time out, or remain pending.
Our lightning-pay.sh script handles verification automatically:
./scripts/lightning/lightning-pay.sh lnbc10u1p...
# ✅ Payment confirmed
# (or "❌ Payment failed or pending" + exit 1)
The script verifies the payment settled and outputs a clear success/failure message. No manual checking needed.
Why verification matters:
./scripts/lightning/lightning-check.sh <paymentHash> [id]
Check whether a payment settled.
Arguments:
paymentHash - Payment hash from lightning-payid - (optional) DID aliasReturns:
{
"paid": true,
"preimage": "...",
"amount": 1000
}
"paid": true — Payment settled successfully"paid": false — Payment failed or still pending./scripts/lightning/lightning-zap.sh <recipient> <amount> [memo] [id]
Send sats to a Lightning Address, DID, or alias.
Arguments:
recipient - Lightning Address ([email protected]), DID, or aliasamount - Amount in satoshismemo - (optional) Message/memoid - (optional) DID alias to send fromExamples:
# Zap to Lightning Address
./scripts/lightning/lightning-zap.sh [email protected] 1000 "Great post!"
# Zap to DID
./scripts/lightning/lightning-zap.sh did:cid:bagaaiera... 5000
# Zap to alias
./scripts/lightning/lightning-zap.sh alice 2000 "Coffee"
Output: Success or failure message with exit code
Example:
./scripts/lightning/lightning-zap.sh [email protected] 1000 "Great post!"
# ✅ Payment confirmed
# (exits 0 on success, 1 on failure)
The script automatically verifies the payment settled before outputting success.
What it does:
./scripts/lightning/lightning-payments.sh [id]
Show all Lightning payments (sent and received).
Example output:
2026/03/05 11:17:38 -100 sats "Payment memo"
2026/03/04 17:08:14 +20 sats "Received payment"
2026/03/03 17:16:31 +25 sats "Test invoice"
Format: YYYY/MM/DD HH:MM:SS [+/-]amount sats ["memo"]
./scripts/lightning/publish-lightning.sh [id]
Add your Lightning endpoint to your DID document.
What it does:
Example:
./scripts/lightning/publish-lightning.sh
# Your DID document now includes:
# {
# "didDocument": {
# "id": "did:cid:bagaaiera...",
# "service": [{
# "id": "did:cid:bagaaiera...#lightning",
# "type": "Lightning",
# "serviceEndpoint": "http://...onion:4222/invoice/bagaaiera..."
# }]
# }
# }
./scripts/lightning/unpublish-lightning.sh [id]
Remove Lightning endpoint from your DID document.
./scripts/lightning/lightning-decode.sh <bolt11>
Inspect BOLT11 invoice details before paying.
Example output:
{
"amount": 1000,
"description": "Coffee payment",
"paymentHash": "a3f7b8c9...",
"timestamp": 1709635800,
"expiry": 3600,
"destination": "03..."
}
Use cases:
# Alice creates invoice
INVOICE=$(./scripts/lightning/lightning-invoice.sh 1000 "Coffee")
echo "Invoice: $INVOICE"
# Bob pays invoice
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE")
HASH=$(echo "$RESULT" | jq -r .paymentHash)
# Bob verifies payment
STATUS=$(./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid)
if [ "$STATUS" = "true" ]; then
echo "✅ Payment confirmed!"
fi
# Alice checks balance
./scripts/lightning/lightning-balance.sh
# Zap creator via Lightning Address
./scripts/lightning/lightning-zap.sh [email protected] 5000 "Love your content!"
# ✅ Payment confirmed
# Payment verification is automatic - no manual checking needed
# Receive a BOLT11 invoice from someone
INVOICE="lnbc10u1p..."
# Decode to verify amount and recipient
./scripts/lightning/lightning-decode.sh "$INVOICE"
# Check amount, description, expiry
# If looks good, pay it
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE")
HASH=$(echo "$RESULT" | jq -r .paymentHash)
# CRITICAL: Verify payment settled
./scripts/lightning/lightning-check.sh "$HASH"
# Create wallets for different personas
./scripts/lightning/add-lightning.sh personal
./scripts/lightning/add-lightning.sh work
./scripts/lightning/add-lightning.sh project
# Check balances
./scripts/lightning/lightning-balance.sh personal
./scripts/lightning/lightning-balance.sh work
./scripts/lightning/lightning-balance.sh project
# Pay from specific wallet
./scripts/lightning/lightning-pay.sh lnbc10u1p... work
# Create Lightning wallet
./scripts/lightning/add-lightning.sh
# Publish to DID document
./scripts/lightning/publish-lightning.sh
# Others can now discover your Lightning endpoint
# They look up your DID and see your Lightning service
# Later, if you want to unpublish:
./scripts/lightning/unpublish-lightning.sh
# Alice creates an invoice for 5000 sats
INVOICE_JSON=$(npx @didcid/keymaster lightning-invoice 5000 "Consulting fee")
INVOICE=$(echo "$INVOICE_JSON" | jq -r .paymentRequest)
# Alice sends the invoice to Bob via dmail
npx @didcid/keymaster send-dmail \
"did:cid:bob..." \
"Invoice for consulting work" \
"Please pay this invoice: $INVOICE"
# Bob receives the dmail, extracts the invoice, and pays
npx @didcid/keymaster lightning-pay "$INVOICE"
# ✅ Payment confirmed
# Alice checks her payment history
npx @didcid/keymaster lightning-payments
# Shows the received payment
Why this matters: Agents can request payment without needing email, phone numbers, or centralized messaging platforms. Just DIDs + Lightning + dmail.
All scripts require:
source ~/.archon.env # Load wallet path and passphrase
This is automatically sourced by the wrapper scripts. npx is used to run keymaster, so no nvm sourcing is needed.
Environment variables (~/.archon.env):
ARCHON_WALLET_PATH - Path to your wallet fileARCHON_PASSPHRASE - Wallet encryption passphraseARCHON_GATEKEEPER_URL - (optional) Gatekeeper endpointArchon Lightning wallets are:
The wallet is managed by @didcid/keymaster which interfaces with Lightning infrastructure.
Lightning amounts are in satoshis:
Minimum payment typically 1 sat, maximum depends on channel capacity.
BOLT11 invoices typically expire after 1 hour. Check expiry with:
./scripts/lightning/lightning-decode.sh lnbc10u1p... | jq .expiry
Lightning Addresses resolve via LNURL:
[email protected]
→ Query: https://domain.com/.well-known/lnurlp/user
→ Get invoice endpoint
→ Request invoice for amount
→ Pay invoice
The lightning-zap.sh script handles this automatically.
"No route found":
"Insufficient balance":
./scripts/lightning/lightning-balance.sh"Invoice expired":
./scripts/lightning/lightning-decode.sh"Payment failed":
lightning-check# 1. Attempt payment
RESULT=$(./scripts/lightning/lightning-pay.sh "$INVOICE" 2>&1)
# 2. Check for errors
if ! echo "$RESULT" | jq -e .paymentHash > /dev/null 2>&1; then
echo "Payment failed: $RESULT"
exit 1
fi
# 3. Extract payment hash
HASH=$(echo "$RESULT" | jq -r .paymentHash)
# 4. Verify payment settled
for i in {1..5}; do
STATUS=$(./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid)
if [ "$STATUS" = "true" ]; then
echo "✅ Payment confirmed"
exit 0
fi
sleep 2
done
echo "⏳ Payment still pending or failed"
exit 1
Always verify payments settled:
# ❌ WRONG
./scripts/lightning/lightning-pay.sh lnbc10u1p...
echo "Paid!" # NO!
# ✅ CORRECT
HASH=$(./scripts/lightning/lightning-pay.sh lnbc10u1p... | jq -r .paymentHash)
./scripts/lightning/lightning-check.sh "$HASH" | jq -r .paid
Before paying, verify:
./scripts/lightning/lightning-decode.sh lnbc10u1p...
# Check output before paying
ARCHON_PASSPHRASE securearchon-vault skill)Ensure Node.js is installed and in your PATH:
node --version # Should show v16 or newer
npx --version # Should show npm version
If not installed, install Node.js via your package manager or from https://nodejs.org
source ~/.archon.env
ls -la "$ARCHON_WALLET_PATH"
# Ensure wallet file exists and is readable
Payment may still be pending or failed. Wait 5-10 seconds and try lightning-check again.
./scripts/lightning/add-lightning.sh
# Creates wallet for current DID
If Archon gatekeeper is unreachable:
echo $ARCHON_GATEKEEPER_URL
# Verify URL is correct
# Try default gatekeeper
unset ARCHON_GATEKEEPER_URL
./scripts/lightning/lightning-balance.sh
Lightning payment data is stored:
~/.archon.wallet.jsonNo payment history or balances are exposed publicly unless you explicitly publish them.
Agent-to-Agent Payments:
Content Monetization:
Real-Time Payments:
Value-4-Value:
⚡ Powered by Lightning. Secured by Archon. Built for agents.