LeoYeAI/agent-master-skills / skills/archon-lightning
archon-lightning
VerifiedLightning Network payments via Archon DIDs - create wallets, send/receive sats, verify payments, Lightning Address zaps
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 8.6 KB |
| SKILL.md | skill md | 16.0 KB |
| _meta.json | config | 286 B |
| scripts/lightning/add-lightning.shexecutable | script | 191 B |
| scripts/lightning/lightning-balance.shexecutable | script | 200 B |
| scripts/lightning/lightning-check.shexecutable | script | 236 B |
| scripts/lightning/lightning-decode.shexecutable | script | 200 B |
| scripts/lightning/lightning-invoice.shexecutable | script | 223 B |
| scripts/lightning/lightning-pay.shexecutable | script | 583 B |
| scripts/lightning/lightning-payments.shexecutable | script | 193 B |
| scripts/lightning/lightning-zap.shexecutable | script | 618 B |
| scripts/lightning/publish-lightning.shexecutable | script | 212 B |
| scripts/lightning/unpublish-lightning.shexecutable | script | 219 B |
README.md
View on GitHub# archon-lightning
> Lightning Network payments powered by Archon DIDs
Send and receive Bitcoin over Lightning. No custody. No permission. Just your DID and the Lightning Network.
## What is this?
`archon-lightning` integrates the Lightning Network with [Archon](https://github.com/archetech/archon) decentralized identities (DIDs). Your DID becomes your Lightning identity - no separate wallet app, no custodian, no KYC.
- β‘ **Lightning wallets for DIDs** - Each DID can have its own Lightning wallet
- πΈ **Send/receive sats** - Pay BOLT11 invoices or create invoices to receive payments
- β‘ **Lightning Address zaps** - Send to `user@domain.com` Lightning Addresses, DIDs, or aliases
- β
**Payment verification** - Cryptographic proof that payments settled
- π **Payment history** - Track all Lightning transactions
- π **DID integration** - Publish your Lightning endpoint to your DID document
All powered by your Archon DID - same cryptographic identity across protocols.
## Why does this matter?
**The problem:** AI agents need to pay for services (APIs, compute, data). Traditional payment rails require:
- Bank accounts (agents can't open them)
- Credit cards (same problem)
- Custodial services (trust someone else with your funds)
- Complex integrations (OAuth, API keys, rate limits)
**The solution:** Lightning Network provides:
- Instant payments (sub-second settlement)
- Micropayments (pay per API call, not monthly subscriptions)
- Global reach (no borders, no intermediaries)
- Privacy (no personal information required)
- Non-custodial (your keys, your coins)
Archon DIDs + Lightning = **financial autonomy for AI agents**.
## Quick Examples
### Create a Lightning Wallet
```bash
./scripts/lightning/add-lightning.sh
```
Your DID now has a Lightning wallet. That's it.
### Check Balance
```bash
./scripts/lightning/lightning-balance.sh
```
### Receive Sats (Create Invoice)
```bash
./scripts/lightning/lightning-invoice.sh 1000 "Coffee payment"
# Returns: {"paymentRequest": "lnbc10u1...", "paymentHash": "..."}
```
Extract the `paymentRequest` value and share it. When paid, sats arrive in your wallet instantly.
### Pay an Invoice
```bash
./scripts/lightning/lightning-pay.sh lnbc10u1...
# β
Payment confirmed
# (or "β Payment failed or pending" if payment didn't settle)
```
Payment verification is built-in - the script automatically verifies before outputting success.
### Zap via Lightning Address
```bash
./scripts/lightning/lightning-zap.sh user@getalby.com 1000 "Great post!"
# β
Payment confirmed
```
Send to Lightning Addresses, DIDs, or aliases - all in one command. Payment verification is automatic.
### Payment History
```bash
./scripts/lightning/lightning-payments.sh
```
## What Can You Build?
**AI-to-AI Payments:**
- Agent pays another agent for API access
- Skill marketplace with Lightning payments
- Bounties paid in sats for completed tasks
- Subscription services charged per-use
**Content Monetization:**
- Pay-per-article (unlock with Lightning payment)
- Streaming sats for video/audio
- Microtips for social media posts
- Paywalled APIs
**Decentralized Services:**
- Pay for compute/storage in real-time
- Lightning-gated access control
- Atomic payments for data feeds
- Cross-agent value transfer
**Value-4-Value:**
- Podcast boosts/streaming sats
- Creator tips via Lightning Address
- P2P payments without intermediaries
## How It Works
### Lightning Wallet Creation
When you run `add-lightning`, your DID creates a Lightning wallet using your DID's cryptographic identity:
```
DID private key β Lightning node seed β Lightning wallet
```
The wallet is non-custodial - you control the keys, you control the funds.
### Payment Flow
**Receiving:**
1. Create invoice (`lightning-invoice`) β BOLT11 string
2. Share invoice (QR code, copy/paste, etc.)
3. Payer pays β sats arrive in your wallet
4. Check invoice status (`lightning-check`)
**Sending:**
1. Get BOLT11 invoice (from recipient)
2. Decode (optional: `lightning-decode` to verify amount/recipient)
3. Pay (`lightning-pay`) β returns payment hash
4. **Verify payment settled** (`lightning-check`)
### Payment Verification Pattern
**β οΈ Critical Security Pattern:**
A payment hash does NOT mean the payment succeeded. Lightning payments can:
- Be pending (not yet routed)
- Fail (no route, insufficient balance)
- Time out (invoice expired)
**Our `lightning-pay.sh` script handles this automatically:**
```bash
./scripts/lightning/lightning-pay.sh lnbc10u1...
# β
Payment confirmed
# (or exits with error if payment failed)
```
The script verifies the payment settled and outputs a clear success/failure message. No manual checking needed.
### Lightning Address
Lightning Addresses (`user@domain.com`) are human-readable payment endpoints. They resolve to BOLT11 invoices via LNURL.
```bash
./scripts/lightning/lightning-zap.sh user@getalby.com 1000
```
Behind the scenes:
1. Query `https://domain.com/.well-known/lnurlp/user`
2. Get invoice endpoint
3. Request invoice for amount
4. Pay BOLT11 invoice
5. Verify payment
### DID Integration
Publish your Lightning endpoint to your DID document so others can pay you:
```bash
./scripts/lightning/publish-lightning.sh
```
Your DID document now includes a Lightning service entry:
```json
{
"didDocument": {
"id": "did:cid:bagaaiera...",
"service": [
{
"id": "did:cid:bagaaiera...#lightning",
"type": "Lightning",
"serviceEndpoint": "http://...onion:4222/invoice/bagaaiera..."
}
]
}
}
```
Anyone can look up your DID and pay you via Lightning.
## Installation
```bash
# Clone the agent-skills repo
git clone https://github.com/archetech/agent-skills
cd agent-skills/archon-lightning
# Prerequisites: Archon identity configured
# (If not, see archon-keymaster first)
# Create Lightning wallet
./scripts/lightning/add-lightning.sh
# Verify it worked
./scripts/lightning/lightning-balance.sh
# {"balance": 0}
```
See [SKILL.md](./SKILL.md) for complete documentation.
## Architecture
```
archon-lightning/
βββ scripts/
β βββ lightning/
β βββ add-lightning.sh # Create wallet
β βββ lightning-balance.sh # Check balance
β βββ lightning-invoice.sh # Create invoice
β βββ lightning-pay.sh # Pay invoice
β βββ lightning-check.sh # Verify payment
β βββ lightning-zap.sh # Lightning Address payment
β βββ lightning-payments.sh # Payment history
β βββ publish-lightning.sh # Publish to DID
β βββ unpublish-lightning.sh # Remove from DID
β βββ lightning-decode.sh # Decode invoice
βββ README.md # This file
βββ SKILL.md # Complete technical docs
```
All scripts wrap the [@didcid/keymaster](https://github.com/archetech/archon/tree/main/keymaster) CLI with environment setup and error handling.
## Real-World Usage
**Morningstar (AI agent):**
- DID: `did:cid:bagaaieranxnl4gmwyw2nv4imoo5fuwvsa4ihba4clp5l22twztuwevjrevha`
- Lightning wallet for paid API access
- Receives tips via Lightning Address
- Pays for compute resources in real-time
**Use cases already working:**
- Agent-to-agent service payments
- Micropayments for API calls
- Value-4-value content tipping
- Lightning-gated access control
## Security Model
**What you trust:**
- Your hardware (runs the Lightning node)
- Lightning Network (routing and settlement)
- Mathematics (cryptographic proofs)
- Open source code (audit everything)
**What you DON'T trust:**
- Central servers (Lightning is peer-to-peer)
- Custodians (you control your keys)
- Banks (no traditional finance involved)
- Payment processors (direct payments)
## Roadmap
**Current capabilities:**
- β
Wallet creation and management
- β
Invoice generation and payment
- β
Lightning Address zapping
- β
Payment verification
- β
Balance checking and history
- β
DID document integration
## Contributing
Found a bug? Want a feature? Have a use case?
- **Issues:** https://github.com/archetech/agent-skills/issues
- **Discussions:** https://github.com/archetech/archon/discussions
- **Archon core:** https://github.com/archetech/archon
## License
Same as parent repo: [agent-skills license](https://github.com/archetech/agent-skills)
## Learn More
- **Lightning Network:** https://lightning.network
- **BOLT specs:** https://github.com/lightning/bolts
- **Lightning Address:** https://lightningaddress.com
- **Archon documentation:** https://github.com/archetech/archon
- **Complete skill documentation:** [SKILL.md](./SKILL.md)
---
**β‘ Powered by Lightning. Secured by Archon. Built for agents.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |